feat(neckbeard): position-assessment entry mode and tracker-neutral intake

Two contained amendments to the delivery lifecycle bundle:

- references/position-assessment.md: a bounded entry mode for mid-flight
  engagement - continuing work that started elsewhere with no delivery
  packet. Inventories observable artifacts, scores them against phase
  exit conditions, emits a position report (current step, satisfied gates
  with evidence pointers, remaining checklist), then bootstraps a packet.
  Artifacts over narratives: unevidenced claims become recorded
  assumptions, never satisfied gates.

- references/tracker-discovery.md: an intake sub-step that detects which
  tracking system holds the work item and routes tracker operations to
  the matching catalog tooling skill (linear, jira-cli, notion). Keeps
  the journey vocabulary tracker-neutral; platform nouns stay confined
  to platform mapping rows and lifecycle reference modes.

Wiring: SKILL.md gains the conditional mid-flight section and file-map
rows; journey.md gains the tracker-neutrality statement, phase-1 tracking
field, and mid-flight entry pointer; routing-table.md gains linear,
jira-cli, and notion rows in the existing signal/skip format. README
triggers extended. Two eval cases added to keep the coverage ratchet
green.

Closes #371

Signed-off-by: Magnus Hedemark <magnus919@users.noreply.github.com>
This commit is contained in:
Magnus Hedemark
2026-08-21 22:56:43 -04:00
parent 1291f9576e
commit 2db3bd072c
7 changed files with 287 additions and 3 deletions
+4
View File
@@ -43,6 +43,8 @@ ordinary bug-fix reproduction requirements.
| `references/journey.md` | Canonical 9-phase change-request journey — intake, discovery, design, spec, test plan, implementation, review, readiness, authorized release — with four delivery paths |
| `references/lifecycle.md` | Platform mechanics for GitHub (reference mode) and enterprise contexts — intake snapshots, CI/review monitoring, terminal states, and post-merge release authority |
| `references/delivery-packet.md` | Durable cross-phase handoff: provenance, resumability, gate verdicts, exact-head binding, lifecycle states, and an artifact ownership map |
| `references/position-assessment.md` | Entry mode for picking up delivery work that started elsewhere: artifact inventory, phase exit-condition scoring, a position report, and packet bootstrap |
| `references/tracker-discovery.md` | Intake sub-step that detects which tracking system holds the work item and routes tracker operations to the matching tooling skill (`linear`, `jira-cli`, `notion`) |
| `references/evaluation.md` | Evaluation methodology: fixtures, baselines, rubrics, multi-run reporting, claims policy |
| `templates/` | Change contract, decision record, evidence ledger, verification plan, evaluation report |
| `templates/delivery-packet.md` | Fillable delivery packet template mirroring the nine field groups defined in the reference |
@@ -72,6 +74,8 @@ python3 eval/run_eval.py --suite eval/fixtures --report out/report.md
- You need to evaluate whether a delivery skill actually improves outcomes.
- You are delivering a **change request** — an issue, ticket, or tracked request — from intake through planning, gates, implementation, and review to a verified PR (or equivalent reviewable deliverable).
- You need to carry work from an **issue to a PR to an authorized post-merge release** with resumable, exact-head-bound state across phases.
- You are asked to **continue work someone else started** — a half-implemented branch or adopted spec with no delivery packet — and need an evidence-based answer to "what step are we on and what remains?"
- Your product tracks work in **Linear, Jira, or Notion**, and the lifecycle should operate that system through its own tooling skill instead of assuming GitHub.
Do not trigger for single factual questions, fully-specified one-line edits, or
tasks already owned end-to-end by a more specific skill. The change-request
+18
View File
@@ -118,6 +118,22 @@ or create a second orchestrator.
issue/ticket trajectory. That work uses the core loop and the stage references
below without the journey's phases, packet, or gates.
### Mid-flight engagement (conditional)
When the request is to **continue delivery work that started elsewhere** — a
half-implemented branch, an adopted spec, a change request another contributor
began — and no delivery packet exists, do not restart at phase 1 and do not
trust narrative summaries of what was done. Run position assessment first:
inventory observable artifacts, score them against phase exit conditions, emit
a position report (current step, satisfied gates with evidence pointers,
remaining checklist), then bootstrap a packet and continue under the normal
journey.
Procedure: [references/position-assessment.md](references/position-assessment.md).
Load it only for mid-flight engagement; fresh change requests start at phase 1,
and existing packets govern resumability through
[references/delivery-packet.md](references/delivery-packet.md).
## Path selection before ceremony
Select the delivery path immediately after current-state discovery and before
@@ -215,6 +231,8 @@ metadata, never as a success proxy.
| [references/lightweight-test-hardening.md](references/lightweight-test-hardening.md) | Test-only regression guards for already-correct production behavior: baseline-pass / mutant-fail evidence, hermeticity, finality-before-push, bounded review, and escalation triggers. |
| [references/lifecycle.md](references/lifecycle.md) | **Change-request work only** — platform mechanics (GitHub reference mode or enterprise mode) for intake, submission, CI/review monitoring, and authorized release. **Not loaded** for a simple fix, refactor, or review without an issue/ticket trajectory. |
| [references/delivery-packet.md](references/delivery-packet.md) | **Change-request work only** — carrying state across phases of a change-request run, or resuming after a context boundary; defines packet fields, artifact ownership, lifecycle states, and resumability. **Not loaded** for a simple fix, refactor, or review without an issue/ticket trajectory. |
| [references/position-assessment.md](references/position-assessment.md) | **Mid-flight engagement only** — continuing delivery work that started elsewhere with no delivery packet: artifact inventory, exit-condition scoring, position report, packet bootstrap. |
| [references/tracker-discovery.md](references/tracker-discovery.md) | **Change-request intake** — detecting which tracking system holds the work item and routing tracker operations to the matching catalog tooling skill; keeps the journey vocabulary tracker-neutral. |
| [references/evaluation.md](references/evaluation.md) | Designing, running, or reporting an evaluation |
| [templates/](templates/) | Change contract, decision record, evidence ledger, verification plan, eval report; plus [templates/delivery-packet.md](templates/delivery-packet.md) — the fillable packet, **for change-request work only** (not for a simple fix/refactor/review without an issue trajectory) |
| [eval/](eval/) | Task schema, rubric, baseline protocol, fixtures, runner |
File diff suppressed because one or more lines are too long
+16 -2
View File
@@ -19,6 +19,20 @@ named packet field groups. Gate verdicts are recorded in packet group (h).
Skipped phases and skills are recorded in packet group (e) with concrete reasons;
silent omission is prohibited.
This journey is tracker-neutral: it speaks of *work items*, *state
transitions*, *review submissions*, and *merge or acceptance into the protected
target*, never of one platform's nouns. Which tracking system holds the work
item is established during phase 1 intake by
[tracker-discovery.md](tracker-discovery.md), and tracker operations route to
the matching catalog tooling skill; platform mechanics live in the platform
mapping rows below and in [lifecycle.md](lifecycle.md).
Entry normally begins at phase 1. When the work being requested **already
started elsewhere** — no delivery packet exists because the earlier run happened
outside this bundle — do not restart intake blindly: enter through
[position-assessment.md](position-assessment.md) first, then continue from the
assessed position under this journey's rules.
---
## The nine phases
@@ -29,8 +43,8 @@ silent omission is prohibited.
|---|---|
| **Owner** | neckbeard framing step (core loop step 1) |
| **Input** | A change request: issue URL/number, ticket ID, email thread, or verbal request. |
| **Output** | Packet groups (a) provenance and (b) authority/mode/path populated: change-request URL/number and source type, repository, base ref, issue/comment snapshot including **repository conventions** (`CONTRIBUTING.md`, `AGENTS.md`, or equivalent) and **linked/referenced work** (related issues, PRs, commits); granted authority class; selected workflow mode (GitHub or enterprise); selected path. A change contract ([../templates/change-contract.md](../templates/change-contract.md)) exists. |
| **Gate** | The intake gate: provenance, authority, repository conventions, and linked work are captured. No planning phase may begin until these fields are populated. |
| **Output** | Packet groups (a) provenance and (b) authority/mode/path populated: change-request URL/number and source type, repository, base ref, issue/comment snapshot including **repository conventions** (`CONTRIBUTING.md`, `AGENTS.md`, or equivalent) and **linked/referenced work** (related issues, PRs, commits); **tracking system** identified per [tracker-discovery.md](tracker-discovery.md) (detected or requester-confirmed, with the evidence basis recorded); granted authority class; selected workflow mode (GitHub or enterprise); selected path. A change contract ([../templates/change-contract.md](../templates/change-contract.md)) exists. |
| **Gate** | The intake gate: provenance, authority, repository conventions, linked work, and the identified tracking system are captured. No planning phase may begin until these fields are populated. |
| **Escalation** | Authority is ambiguous between explore and modify; or the stated goal conflicts with a hard constraint (security, data safety, policy, license); or maintainer direction conflicts with proceeding (see [risk-authority-gates.md](risk-authority-gates.md) stop rules). |
| **Platform mapping** | **GitHub mode:** issue body + comments + labels captured via `gh`; `CONTRIBUTING.md` and `.github/` conventions discovered per repository. **Enterprise mode:** ticket-tracker snapshot (ticket ID, description, comments); internal contribution governance or change-governance docs captured. |
+156
View File
@@ -0,0 +1,156 @@
# Position Assessment — Mid-Flight Engagement Entry Mode
Some engagements begin mid-flight: the agent is asked to continue software
delivery work that started elsewhere — a half-implemented branch, an adopted
specification, a change request another contributor began — and no delivery
packet exists because the earlier work did not run inside this bundle. The
nine-phase journey ([journey.md](journey.md)) describes the canonical forward
path from intake; it does not describe how to enter that path honestly when the
first six phases may already be partly done.
This reference defines that entry mode. It is loaded by [../SKILL.md](../SKILL.md)
only for mid-flight engagement. It is **not** loaded when a fresh change request
starts the journey at phase 1, and **not** loaded when the run's own delivery
packet exists — packet resumability
([delivery-packet.md](delivery-packet.md)) governs that case, and the packet is
authoritative there.
The procedure answers three questions before any execution continues:
1. What step is the work actually on?
2. Which gates have evidence behind them, and which remain?
3. What is the next justified action?
## The core rule: artifacts, not narratives
Position is established from observable artifacts — files, commits, CI runs,
review states — scored against the exit conditions the phases define. It is
never established from summaries, however confident. "The spec was approved"
is not a satisfied gate; an approved `SPEC.md` artifact with a recorded gate
verdict is. A claim with no inspectable artifact behind it becomes a recorded
**unverified assumption**, never a satisfied gate.
This is the same doctrine the rest of the bundle applies to verification:
assertions are not evidence. Assessment inherits it.
## Procedure
### Step 1 — Trigger check
Enter this mode only when all three hold:
| Condition | How to check |
|---|---|
| The request is to continue existing delivery work | The request references ongoing work (a branch, spec, partial implementation) rather than a fresh change |
| No delivery packet exists for that work | No packet artifact accompanies the work; the prior run, if any, was outside this bundle |
| The work is non-trivial enough to warrant the journey | Same threshold [../SKILL.md](../SKILL.md) applies before loading the journey |
If a packet exists, use [delivery-packet.md](delivery-packet.md) resumability
instead. If no artifacts exist at all, the honest position is **phase 1**: say
so plainly and let the normal journey take over. An empty inventory is a
finding, not a failure.
### Step 2 — Inventory the observable artifacts
Search the working repository and tracker for the artifacts the phases would
have produced:
| Observable artifact | Produced by | Typical locations |
|---|---|---|
| Change contract (problem, constraints, authority) | Phase 1 | Issue/ticket body, PR description, [../templates/change-contract.md](../templates/change-contract.md) instance |
| Repository conventions captured | Phase 1 | Evidence that `CONTRIBUTING.md` / `AGENTS.md` were consulted |
| Baseline and reproduction evidence | Phase 2 | Repro steps in the issue, failing-test transcripts, benchmark notes |
| Architecture delta, ADR, C4 diagrams, or a documented no-delta determination | Phase 3 | `docs/adr/`, design docs, decision-record instances |
| `SPEC.md`, `TASK-PLAN.md` | Phase 4 | Repository root or working branch |
| `VERIFICATION-PLAN.md` | Phase 5 | Working branch |
| Implementation commits on a working branch | Phase 6 | `git log <base>..HEAD` |
| `VERIFICATION.md`, independent review verdicts | Phase 7 | Working branch, PR review states |
| Green CI and approved review at a known head SHA | Phase 8 | CI checks, review approvals bound to a specific SHA |
| Merge commit, release tag, deploy confirmation | Phase 9 | Protected-target history, tags, deploy logs |
Inventory reads are read-only discovery; they need no confirmation. Record
where each artifact was found (path, SHA, URL) — pointers become the evidence
references in the report.
### Step 3 — Score against phase exit conditions
Compare each inventoried artifact with the exit condition and gate definition
of its phase ([journey.md](journey.md); gate semantics in
[stages.md](stages.md)). Assign exactly one verdict per phase:
| Verdict | Meaning |
|---|---|
| **Satisfied** | The artifact exists and meets the phase exit condition. Record the evidence pointer. |
| **Partial** | The artifact exists but is incomplete or unapproved. Name exactly what remains. |
| **Absent** | No artifact found. The gate is not passed. |
| **Contradicted** | An artifact exists but observable evidence conflicts with it (for example, readiness claimed while CI is red at the recorded head). Contradiction blocks progression until resolved. |
Scoring constraints:
- Score the selected delivery path's mandatory phases; conditional phases are
scored only if their artifacts exist (an absent conditional phase with a
legitimate skip reason is recorded as such, not penalized).
- Verified-complete work is **not** re-executed, mirroring packet-resume
semantics. Assessment establishes position; it does not redo accepted work.
- Never upgrade a verdict to fill a gap. A missing gate verdict is `absent`,
even when the underlying work looks done.
- Two contradictory sources (artifact says approved, tracker says changes
requested) yield `contradicted`, and the conflict itself is reported.
### Step 4 — Emit the position report
Produce the report and deliver it to the requester **before** continuing
execution. Format:
```
current phase: <n>-<phase-name>
selected path: <lightweight|full|refactor|high-risk> (re-selected, see below)
satisfied gates: <gate> @ <evidence pointer>; ...
partial: <gate/artifact> — <what remains>
absent: <gates with no evidence>
contradicted: <gate/artifact> — <conflicting evidence>
remaining checklist: [ ] <next gate/action>; [ ] ...
unverified assumptions: <claims accepted provisionally, with owner of the proof>
recommended next action: <single bounded step>
```
The remaining checklist is the contract for continuation: work proceeds
against it in journey order, respecting the five-gate sequence and every stop
rule in [risk-authority-gates.md](risk-authority-gates.md).
### Step 5 — Bootstrap the packet
Create a fresh delivery packet so subsequent operation has normal resumability:
- Group (a) provenance records: engaged mid-flight, artifacts assessed, with
the inventory pointers.
- Group (b) records the re-selected delivery path (path selection per
[../SKILL.md](../SKILL.md) § Path selection — re-run it here; do not inherit
a path assumption from the prior work).
- Group (c) initializes from the position report: current phase, current gate,
and the head SHA at assessment time.
- Unverified assumptions go to the evidence ledger
([evidence-ledger.md](evidence-ledger.md)), not into gate fields.
Do **not** retroactively mark gates as passed in group (h) without artifacts.
Gates with genuine evidence pointers may be recorded as passed with those
pointers; everything else remains open.
## Completion and exit conditions
Assessment is complete when the position report has been delivered and the
packet bootstrapped. The mode then ends: execution continues under the normal
journey and core loop. If the inventory is empty, completion is the honest
statement "no artifacts found — starting at phase 1" plus the same bootstrap.
## Non-goals
- This is not a quality audit of the existing work. It establishes position;
phase 7 review still judges quality.
- It does not bypass gates. Only gates with real evidence may be marked
satisfied; the rest must actually run.
- It does not replace packet resumability. Where a packet exists, the packet
wins.
- It does not guess at intent behind ambiguous prior work. When the change
contract cannot be reconstructed from artifacts, that is a phase-1 gap, and
intake happens properly.
+3
View File
@@ -53,6 +53,9 @@ defaults without qualification.
| `data-architect` | Change requires a data-model design artifact, storage-platform evaluation, data-governance definition (ownership, lineage, cataloging), or cross-system data-flow diagram before implementation | No data-model artifact, storage-platform evaluation, data-governance definition, or cross-system data-flow design is required; schema changes are mechanical | Contract, ledger |
| `agent-evals-and-observability` | Change modifies AI/agent behavior: eval definitions, agent task contracts, grader bindings, trajectory fixtures, prompt templates, or agent observability/telemetry | No agent eval, task contract, grader, trajectory fixture, prompt template, or agent telemetry is created or modified | Contract, ledger |
| `opensource-contributions` | **Conditional — public/OSS repos only.** Repository remote is public, an open-source license is present, and a `CONTRIBUTING.md` or equivalent contribution governance file exists (verify via repo remote or `gh api`); contribution norms, agent disclosure, or fork etiquette apply | Repository is private or enterprise-internal (non-public remote, no open-source license); record skip as "non-public repository." Also skip when no contribution-norm question arises even in a public repo | Contract, ledger |
| `linear` | The product's tracking system was identified as Linear by [tracker-discovery.md](tracker-discovery.md) during intake, and tracker operations are needed (read/update work items, transitions, comments) | Tracking system is not Linear; or the change needs no tracker operation beyond reading provenance already captured | Contract, ledger |
| `jira-cli` | The tracking system was identified as Jira by [tracker-discovery.md](tracker-discovery.md), and tracker operations are needed | Tracking system is not Jira; or no tracker operation is needed beyond captured provenance | Contract, ledger |
| `notion` | The tracking system was identified as Notion by [tracker-discovery.md](tracker-discovery.md), and tracker operations are needed | Tracking system is not Notion; or no tracker operation is needed beyond captured provenance | Contract, ledger |
## Test-hardening evidence
+89
View File
@@ -0,0 +1,89 @@
# Tracker Discovery — Tracker-Neutral Intake
The change-request journey is defined in tracker-neutral terms: *work item*,
*state transition*, *review submission*, *merge or acceptance into the protected
target*, *release authorization*. Platform mechanics belong to the layer that
operates the platform — the routing rows in
[routing-table.md](routing-table.md) and the platform reference modes
([lifecycle.md](lifecycle.md)) — not to the spine itself.
That separation only works if intake actually establishes which tracking system
the product uses. This reference defines that sub-step of phase 1
([journey.md](journey.md), Intake and provenance). It exists because
improvisation under ambiguity defaults to whatever platform the agent knows
best, and the correct answer is detection plus an explicit question, not a
default.
## The rule
**Never assume the tracking system.** Detect it from repository evidence where
possible; ask the requester when evidence is absent or contradictory; record
the finding and its basis in delivery packet group (a) before any tracker
operation runs.
Read-only identification is discovery and needs no confirmation. The first
mutation against the detected system still passes the normal state-change gate
([risk-authority-gates.md](risk-authority-gates.md)).
## Detection procedure
Run during phase 1 alongside provenance capture:
1. **Inspect remotes and configuration** for tracking-system fingerprints:
| Signal | Points to |
|---|---|
| Issue/ticket URLs referenced by the change request (`…/issues/N`, `…/TICKET-123`, Linear `…/issue/TEAM-N`) | GitHub Issues / Jira / Linear respectively |
| `.jira-url`, Jira config files in the repository | Jira |
| Team keys in ticket identifiers (`ENG-42` shape) with a non-GitHub tracker configured | Jira or Linear |
| Project-management config directories (for example `.linear/`) or documented integrations in `CONTRIBUTING.md`, `AGENTS.md`, README | Whatever they name |
2. **Check what the request itself references.** A change request arriving as a
Linear issue URL, a Jira ticket ID, or a GitHub issue number is direct
evidence for its own system.
3. **Ask when ambiguous or absent.** If signals conflict (repo mirrors to
GitHub but issues live in Jira) or none exist, ask one bounded question:
which system holds this work item? Record the answer as requester-provided
provenance. Do not silently pick the system whose CLI happens to be installed.
4. **Record in packet group (a):** detected/requested system, the evidence or
source of the answer, and the routing decision below. Silent omission is
prohibited like every other intake field.
## Routing tracker operations
Operate the detected system through its catalog tooling skill rather than
improvising API calls:
| Detected system | Route operations to |
|---|---|
| GitHub (issues, PRs, releases) | Native mechanics per [lifecycle.md](lifecycle.md) — the documented reference mode |
| Linear | `linear` |
| Jira | `jira-cli` |
| Notion | `notion` |
| Other / none of the above | No specialist route: operate through the system's own documented interface with bounded reads, and note the absent specialist in the ledger |
Routing constraints:
- Every named routing target must be a real skill in this catalog; dead links
are a defect. If a target is missing from an installation, proceed on the
fallback and record the absence — same convention as
[routing-table.md](routing-table.md) § When no specialist is installed.
- Tooling skills are mechanical layers. They own commands and API contracts;
the journey owns sequencing, and discipline specialists own judgment. No
tracker skill becomes a second orchestrator.
- Vocabulary crossing the boundary stays neutral: a "state transition" maps to
whichever transition the target system defines (workflow state move, label
change, status update); the packet records outcomes by neutral name.
## Non-goals
- This step does not migrate content between systems or reconcile divergent
trackers. If work items exist on two systems, surface the conflict at intake
and ask which is authoritative.
- It does not change credential handling. Each tooling skill's own setup rules
apply.
- It does not make the journey depend on any single vendor. Absence of a
tracker, or use of an unrouted system, degrades gracefully to the fallback
path.