mandrel 2.60.0 → 2.62.0

package/.agents/workflows/helpers/plan-reference.md

@@ -53,10 +53,7 @@ the first `createIssue`, and refuses any pair of same-wave siblings that both
 declare a path (or one of which declares a covering glob) — naming the pair,
 the paths and the two remedies (merge them, or order them with `depends_on`).
 Such a pair cannot be co-dispatched, so the split buys no parallelism and
-costs a delivery session per Story. It replaced the acceptance partition,
-which refused only byte-identical acceptance text across siblings — a shape
-model output does not produce — so it never fired on the fragmentation it was
-meant to catch. **N=1 can never trip the refusal.**
+costs a delivery session per Story. **N=1 can never trip the refusal.**
 
 A draft of more than one Story also stops at **Gate #2** for operator
 approval, `--force-review` or not: a split always earns eyes. `--yes`
@@ -65,8 +62,7 @@ auto-proceeds, as at every other gate.
 ## Unknown triage — AFK vs HITL
 
 Every open question interrogation surfaces is triaged by **who can resolve
-it**, not parked in one bucket (a shape borrowed from the Wayfinder skill's
-HITL/AFK ticket typing):
+it**, not parked in one bucket:
 
 - **AFK** (away from keyboard — the agent resolves it alone): the answer is a
   fact something already records — third-party docs, a dependency's API
@@ -106,7 +102,7 @@ not re-deriving which assumptions were really the agent's to make.
 
 Gate #1 stops for exactly two things — the sharpened plan intent and any HITL
 unknown — and everything else the envelope surfaced collapses to **one
-advisory line** beneath it (Story #5312). Nothing on that line stops the run,
+advisory line** beneath it. Nothing on that line stops the run,
 reroutes it, or is invoked by `/mandrel-plan`; each item names something the
 operator may prefer to do instead, and the run proceeds either way. Under
 `--yes` the line is recorded and planning continues — an unattended run has
@@ -128,8 +124,7 @@ The line names, in order, whichever of these the envelope carries:
   the same shape with a different owner.
 - **`memoryPoolAdvisory.recommend`** — name
   [`/memory-consolidate`](../memory-consolidate.md), quoting its
-  `reasons[]`. The one arm left measures the `MEMORY.md` index against the
-  harness's byte cap; a stale pool degrades recall, it does not make the plan
+  `reasons[]`. A stale pool degrades recall, it does not make the plan
   wrong.
 - **`complexitySignals.uiSurface`** — name [`/prototype`](../prototype.md)
   and stop there. The signal carries **no routing authority and adds no
@@ -138,8 +133,8 @@ The line names, in order, whichever of these the envelope carries:
   lenses gate on, and whether any predicted path matches a web lens
   `filePattern` in `audit-rules.json`; a project with no rendered frontend
   resolves falsey and the offer never fires. `/mandrel-plan` must never invoke
-  it — operator invocation is the entire design, because the value is a human
-  looking at a layout before its UI acceptance criteria are frozen. Under
+  it — the value is a human looking at a layout before its UI acceptance
+  criteria are frozen. Under
   `--yes` the offer is recorded and planning proceeds — no reroute, no
   prototype written, no gate raised.
 
@@ -149,12 +144,10 @@ The envelope's `complexitySignals` field carries the paths the seed predicts,
 their repo state (existing paths predict refactors; missing predict creates)
 and the `audit-rules.json` sensitive-path classes the footprint intersects —
 `routingAuthority: false`, no `route` field. They ground the authoring
-template's pre-resolved `changes[]` and the `/prototype` offer, nothing else.
-Story #5312 deleted the plan-side lite claim that used to read them
-(`--route-downgrade-reason`, the persist shape backstop, the `route::lite`
-hint): every Story lands through the same engine and the same close gates,
-and the acceptance verdict owner follows the operator's ceremony profile —
-never anything a plan authored.
+template's pre-resolved `changes[]` and the `/prototype` offer, nothing else:
+every Story lands through the same engine and the same close gates, and the
+acceptance verdict owner follows the operator's ceremony profile — never
+anything a plan authored.
 
 ## Correct-by-construction authoring template
 
@@ -163,7 +156,7 @@ never anything a plan authored.
 `complexitySignals` ran:
 
 - **`verify[]` entries are commands.** There is no tier suffix and no
-  `manual:<reason>` escape (Story #5312): write the exact command or test
+  `manual:<reason>` escape: write the exact command or test
   path the deliverer runs and the acceptance critic reads as evidence.
 - **`changes[]` names what the deliverer authors.** Generated artifacts —
   quality baselines, generated test indexes, migration journals, lockfiles —
@@ -201,12 +194,10 @@ numbers each checkbox from its array position, so a carried handle renders
 doubled. Persist normalises one off rather than refusing, and names the strip
 on the dry-run's repair list.
 
-Nothing in that shape inventories the repo for the author. `changes[]` arrives
-filled in from the working-tree probe, and Phase 8's
-`validateStoryFileAssumptions` re-probes every resolved `{path, assumption}`
-at persist — so the grounding contract is the author's own targeted reads plus
-that gate. There is no pre-computed codebase snapshot to fall back on, and no
-manifest-derived replacement to build.
+Nothing in that shape inventories the repo for the author: the grounding
+contract is the author's own targeted reads plus Phase 8's
+`validateStoryFileAssumptions`, which re-probes every resolved
+`{path, assumption}` at persist.
 
 ### Per-Story audit provenance (`provenance`)
 
@@ -234,20 +225,16 @@ work this plan already tracked.
 | Present but empty (`{}`) | Nothing. "Owns no findings" is a real answer. |
 | **Absent** | The **whole seed's** footers (the union) — the recall-safe default. |
 
-**The union fallback is load-bearing, not legacy.** Leaving the authoring agent
-to hand-carry provenance out of the seed's HTML comments was measured to fail —
-a remembered step is no step at all — and the mechanical union carry is what
-closed it. Attribution is additive: it sharpens a plan that opts in and changes
-nothing for one that does not. Never remove the fallback to "finish the
-migration".
-
-Attribution is what makes the next sweep's dedup answerable rather than
-arbitrary. Under the union every sibling carried every key, so a finding
-confirming against several open Stories could only pick one at random, and a
-key whose owning Story had since **closed** was masked by any open neighbour —
-a genuine regression filed as a routine update. With ownership stamped, the
-issue carrying a finding's own fingerprint decides both the match and its
-state (`lib/findings/route-finding.js`).
+**The union fallback is load-bearing, not legacy** — hand-carrying provenance
+out of the seed's HTML comments is a step an author forgets. Attribution is
+additive: it sharpens a plan that opts in and changes nothing for one that
+does not. Never remove the fallback to "finish the migration".
+
+Attribution makes the next sweep's dedup answerable: under the union a finding
+confirming against several open Stories can only pick one, and a key whose
+owning Story has **closed** is masked by an open neighbour. With ownership
+stamped, the issue carrying a finding's own fingerprint decides both the match
+and its state (`lib/findings/route-finding.js`).
 
 The audit path authors this mechanically from the per-group footers the seed
 already carries — see [`audit-to-stories`](../audit-to-stories.md). A `--seed`
@@ -257,24 +244,17 @@ or `--tickets` plan has nothing to attribute and omits the field.
 
 The conflict passes run **twice**: once over the raw `stories.json` payload
 (alongside the freshness, file-assumption and sizing gates), and again over the
-**assembled, footer-stamped bodies** — the artifact persist actually posts.
-The second pass is not belt-and-braces. The canonical authoring shape carries
-`acceptance[]` / `verify[]` at the ticket's top level and assembly folds them
-into the body, so the passes that scan `body.acceptance` / `body.verify`
-saw two empty arrays on the real payload and emitted nothing; the two
-substring-match advisories that depended on it are retired, leaving
-`shared-editor` as the one conflict kind. Both passes complete before the first
-`createIssue`, so a refusal still costs no writes.
+**assembled, footer-stamped bodies** — the artifact persist actually posts,
+where top-level `acceptance[]` / `verify[]` have been folded in. `shared-editor`
+is the one conflict kind. Both passes complete before the first `createIssue`,
+so a refusal still costs no writes.
 
 `shared-editor` findings are rendered into the plan-summary section of every
-Story's posted `story-plan-state` comment, directly beneath the wave table: the table promises which Stories can run
-together, and a path two same-wave Stories both write is exactly where that
-promise breaks. Promise and caveat belong on one durable surface — previously
-the caveat was a stderr warning nobody kept.
-
-Every conflict class is advisory (Story #5312 retired the
-`planning.failOn*` / `requireExplicitCrossStoryDeps` upgrade knobs with the
-registry and fan-out findings): co-editing one file is routine and often
+Story's posted `story-plan-state` comment, directly beneath the wave table: the
+table promises which Stories can run together, and a path two same-wave Stories
+both write is exactly where that promise breaks.
+
+Every conflict class is advisory: co-editing one file is routine and often
 correct — the delivery scheduler already serializes file-overlapping Stories —
 and a path reference matched by substring can read as a dependency a prose
 mention never meant. A finding names the Stories and the fix (a `depends_on`
@@ -284,10 +264,10 @@ edge, or folding the shared edit into one Story) for the operator to weigh.
 
 A `--tickets` envelope carries a third author prompt beside
 `systemPrompts.story` and `systemPrompts.storySplitRules`:
-**`systemPrompts.storyTicketsRules`**. It exists because a
-source ticket arrives already in Story shape — rendered `AC-<n>:` checkboxes,
-a `## Verify` list, a `## Changes` footprint — and an author reading it as a
-template carries that shape forward instead of re-deriving it. The addendum
+**`systemPrompts.storyTicketsRules`**. A source ticket arrives already in
+Story shape — rendered `AC-<n>:` checkboxes, a `## Verify` list, a
+`## Changes` footprint — and an author reading it as a template carries that
+shape forward instead of re-deriving it. The addendum
 binds the author to re-derive `acceptance[]` from the goal, to express
 mechanical checks (a refreshed baseline, a lint exiting 0, a regenerated
 index) as `verify[]` commands rather than acceptance items, and to take the
@@ -332,9 +312,7 @@ the default is not what you mean.
 
 ## The pre-mortem critic — operator-invoked
 
-The maker-blind **pre-mortem** critic is not a step of the spine (Story #5312
-retired step 2.5 with the consolidation critic, whose one deterministic input
-was a `## Delivery Slicing` table no Story carries). Run it when the operator
+The maker-blind **pre-mortem** critic is not a step of the spine. Run it when the operator
 asks for it, after Author and before Persist — the last point a finding folds
 into a re-author:
 
@@ -374,18 +352,17 @@ a re-author round.
 ## What `--dry-run` actually gates
 
 A bare `plan-persist.js` runs the whole gate list write-free and then, on a
-clean list, persists in the same invocation (Story #5342); `--dry-run` is that
-same first half with the second suppressed. Either way every gate runs before
-the first `createIssue` would fire. Since Story #5312 the gates split two
-ways, and the dry-run output is where the second half is read:
+clean list, persists in the same invocation; `--dry-run` is that same first
+half with the second suppressed. Either way every gate runs before the first
+`createIssue` would fire. The gates split two ways, and the dry-run output is
+where the second half is read:
 
 **Hard — the run refuses:** a body that does not parse, a ticket that is not
 a Story, an empty `acceptance[]`, an unknown or cyclic `depends_on`, the
 same-wave collision refusal at N>1, a supersede claim on a non-source id or
 one claimed twice, and a `deletes` entry naming a path absent at base.
-Story #5342 retired two: the commit-subject-prefix scan is gone entirely —
-the `commit-msg` hook and `normalize-pr-title.js` enforce subjects — and an
-empty `verify[]` is now a warning.
+Commit subjects are not scanned — the `commit-msg` hook and
+`normalize-pr-title.js` enforce them.
 
 **Warnings — listed, then the persist proceeds:** a `creates` on a path that
 exists at base or a `refactors-existing` on one that does not (including a
@@ -399,15 +376,11 @@ advisory `changes[]` is free to reshape out from under the criterion. The
 list also names every **repair** the run applied — a plain-string bullet or a
 trailing parenthetical rewritten into `{ path, assumption }` by probing base,
 and an `AC-<n>:` handle normalised off an acceptance item. The same list rides
-the result envelope as `warnings[]` and `repairs[]` — and because the repairs
-are applied in the write-free pass, the chained run carries that pass's
-`repairs[]` and `warnings[]` onto the envelope it returns, so the evidence
-survives the hand-off rather than being re-derived from an already-repaired
-draft.
+the result envelope as `warnings[]` and `repairs[]`, carried from the
+write-free pass onto the chained run's envelope.
 
 A dry run that comes back clean has paid for every deterministic refusal, so
-the real persist has nothing left to discover except network failure — which
-is why the clean case no longer waits for a second operator invocation.
+the real persist has nothing left to discover except network failure.
 
 ## The container Epic (Gate #3)
 
@@ -429,23 +402,17 @@ leave the common follow-up plan with nowhere to file itself. The three-Story
 threshold governs **creation** only, where it still holds: at two Stories a
 pair of ids is as easy to carry as one container id.
 
-On a yes, pass `--epic <id>`. Persist then:
-
-1. resolves the id **before the first create** (dry run included) — it must be
-   **open** and carry `type::epic`, or the run hard-errors having written
-   nothing;
-2. after the Stories exist, appends one `- [ ] #N` row per new Story to the
-   Epic's checklist via `appendEpicChildIds`, which is idempotent and preserves
-   existing rows' **checked state**, their order, and the fingerprint marker;
-3. mirrors a native sub-issue edge per child.
+On a yes, pass `--epic <id>`. Persist resolves it **before the first create**
+(dry run included) — it must be **open** and carry `type::epic`, or the run
+hard-errors having written nothing — then appends a `- [ ] #N` checklist row
+and a native sub-issue edge per new Story.
 
 The refusal posture is the **opposite** of creation's, deliberately. Creation
 degrades (an unensurable label just skips the container) because the operator
-never named one. Adoption cannot: the operator named a specific id, so silently
-not adopting it would leave them believing their Stories were filed somewhere
-they were not. Hence a hard error, raised while nothing has been written and
-the fix is free. Once the Stories are live the posture flips back — a failed
-checklist write or sub-issue edge only warns.
+never named one; adoption names a specific id, so silently not adopting it
+would misfile the Stories. Hence a hard error, raised while nothing has been
+written. Once the Stories are live the posture flips back — a failed checklist
+write or sub-issue edge only warns.
 
 **Only open Epics are adoptable.** A closed Epic is a finished body of work;
 joining one would reopen a container the epilogue deliberately closed and
@@ -458,11 +425,9 @@ raised before any I/O.
 ### Creating a new container (N>2)
 
 Above two Stories, `/mandrel-plan` offers to group them under one `type::epic`
-container. Confirmed, persist opens it **after** the Stories — its body embeds
-their issue numbers and its sub-issue edges need their database ids — and
-links every created Story both ways it can: a `- [ ] #N` body checklist and a
-native GitHub sub-issue edge. Both are written because each survives what the
-other does not; the delivery-side reader unions them.
+container. Confirmed, persist opens it **after** the Stories and links every
+created Story both ways: a `- [ ] #N` body checklist and a native GitHub
+sub-issue edge, which the delivery-side reader unions.
 
 What the Epic must never carry: an `agent::*` label (that absence keeps it out
 of the bare `/mandrel-deliver` ready list and outside the `type::story`-scoped
@@ -474,12 +439,9 @@ Linkage runs parent→child only, which is why each Story stays independently
 deliverable (ADR `20260905-5139`).
 
 Degradation is deliberate: an unensurable `type::epic` label skips the Epic
-entirely (an unlabelled container is not a container), while a failed
-sub-issue edge only warns — the checklist still lists every child. Either way
-the Stories are untouched and deliver by id. A resumed persist adopts an
-existing Epic carrying the same fingerprint, which is keyed on the title **and
-the exact child set**, so a run grouping different Stories never adopts the
-wrong container.
+entirely, while a failed sub-issue edge only warns. Either way the Stories are
+untouched and deliver by id. A resumed persist adopts an existing Epic whose
+fingerprint matches the title **and the exact child set**.
 
 ## Cross-plan `depends_on` (`#<id>`)
 
@@ -493,9 +455,8 @@ opened and never had to name.
 `complexitySignals.predictedPaths`, each carrying the `overlappingPaths[]` that
 matched. Overlap is computed on **declared footprints** and not on prose, using
 the same `storyFootprint` the wave runner uses to withhold colliding Stories at
-dispatch — so the planner sees the collision the runtime would later enforce,
-one layer earlier and while it is still cheap to order around. A seed naming no
-paths short-circuits to `[]` with no provider call at all.
+dispatch — the collision the runtime would later enforce, seen while it is
+still cheap to order around. A seed naming no paths short-circuits to `[]`.
 
 It stays advisory: two Stories can touch a shared barrel file with no real
 ordering between them, and only the operator knows.
@@ -505,9 +466,9 @@ a Story already open is not scheduled by this run, so it has no position in the
 topological sort and cannot close a cycle back into a Story that does not exist
 yet. They are validated **before any create** (dry run included): each must
 resolve to an **open `type::story`**, and a closed issue, a container Epic, a
-missing id or a non-Story hard-errors with every bad ref named in one pass. The
-strictness is the point — a blocker that can never be satisfied reads to the
-delivery engine as a permanent wedge rather than as an error worth reporting.
+missing id or a non-Story hard-errors with every bad ref named in one pass — a
+blocker that can never be satisfied would read to the delivery engine as a
+permanent wedge.
 
 Persist renders the entry unchanged as a `blocked by #<id>` footer line and
 mirrors the native `blocked_by` edge, which is the same pair of surfaces a
@@ -518,10 +479,9 @@ state.
 ## Ready means fully persisted
 
 `agent::ready` is the **terminal** step, not part of the creating POST.
-The order is: create unlabelled → upsert `story-plan-state` on every Story —
-since Story #5343 one comment, carrying the plan summary (story set, delivery
-order, deliver command) and nothing else, since Story #5367 deleted the machine
-checkpoint no reader consumed — → flip every Story to `agent::ready`.
+The order is: create unlabelled → upsert `story-plan-state` on every Story (one
+comment carrying the plan summary: story set, delivery order, deliver command)
+→ flip every Story to `agent::ready`.
 
 This is what lets `/mandrel-deliver` trust the label: a Story carrying
 `agent::ready` always has the operator's delivery instructions on the ticket,
@@ -561,43 +521,30 @@ them **envelope-first**:
 | `--source-tickets <ids>` | Explicit **override** for hand-driven runs (no captured envelope, or deliberately narrowing the set). Wins over the envelope; a disagreement is warned about, not silently reconciled. |
 
 The result envelope's `supersede.sourceTicketOrigin` reports which channel was
-used (`envelope` \| `flag` \| `none`).
-
-Every path with no envelope is **audible** — persist cannot tell a legitimate
-`--seed` run from a `--tickets` run whose envelope was never captured, so it
-says so rather than deciding silently:
-
-| Situation | Behaviour |
-| --- | --- |
-| Neither `--plan-dir` nor `--plan-context` | **Warn** — nothing was read; only `--source-tickets` can supply ids. |
-| Auto-discovered `<plan-dir>/plan-context.json` absent | **Warn** — degrade to `--source-tickets`; a `--seed` run legitimately has none. |
-| Explicit `--plan-context` missing | **Fatal** — the operator named a file and meant it. |
-| Envelope present but unparseable | **Fatal** — a corrupt envelope is not "no source tickets"; treating it as such is how a `--tickets` run used to report success having superseded nothing. |
+used (`envelope` \| `flag` \| `none`). Every path with no envelope is
+**audible**: an absent envelope warns and degrades to `--source-tickets` (a
+`--seed` run legitimately has none), while an explicitly named but missing
+`--plan-context`, or an unparseable envelope, is **fatal**.
 
 Whichever channel supplies them, the supersede-map partition above still
-fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is now
-**caught** (`source ticket #N is not claimed by any Story`) instead of
-partitioning an empty set and passing vacuously.
+fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is
+**caught** (`source ticket #N is not claimed by any Story`).
 
 ## Closing superseded source tickets
 
 **Default on.** After the Stories exist, persist comments on each source
 issue naming the specific Story that claims it — plus that Story's optional
 per-supersede `note` — and closes it with reason **`not_planned`**
-(`state_reason`). Nothing has shipped at persist time and the issue will not
-be actioned in its own right, so `not_planned` is the honest reason;
-`completed` would be a lie. This is what keeps the tracker from asserting
-that already-planned work is still unowned, and it writes down the supersede
-link that makes the history readable.
-
-| Behaviour | Contract |
-| --- | --- |
-| Default | Comment + close every source ticket as `not_planned`, **clearing its `agent::*` label** in the same write — a retired ticket has no agent state, and `agent::done` would claim a delivery that never happened. |
-| `--no-close-superseded` | Skips all commenting and closing. Story creation is unchanged. Use it for a genuinely partial supersede — when the plan folded in only *part* of an issue and the remainder must stay open. |
-| `--dry-run` | Posts no comment and closes nothing; reports what it would have done. |
-| Re-run | Idempotent — the comment is keyed off a `superseded-by` structured-comment marker, and an already-closed source is skipped. |
-| Already closed / deleted / inaccessible | Skipped and reported. Never throws. |
-| Close-phase failure | **Never fails the run.** Stories stay created; the result envelope's `supersede` report names which tickets were and were not closed so the operator can finish by hand. |
+(`state_reason`) — nothing has shipped at persist time, so `completed` would
+be a lie.
+
+The default also **clears the source's `agent::*` label** in the same write — a
+retired ticket has no agent state. Pass **`--no-close-superseded`** for a
+genuinely partial supersede — when the plan folded in only *part* of an issue
+and the remainder must stay open. The phase is idempotent (keyed off a
+`superseded-by` marker), skips already-closed or inaccessible sources, and
+**never fails the run**: its `supersede` report names which tickets were and
+were not closed so the operator can finish by hand.
 
 `--seed` / `--seed-file` modes have no source tickets, so no close phase
 runs at all.

package/.agents/workflows/helpers/qa-core.md

@@ -110,6 +110,18 @@ ledger, conforming to [`qa-ledger.schema.json`](../../schemas/qa-ledger.schema.j
 session. This is the single findings channel across all three workflows — there
 is no per-workflow finding schema.
 
+## Coverage tiers and the missing test
+
+For the surface an item points at, gather the tests that exercise it and
+classify each by path per
+[`testing-standards.md` § The Three Tiers](../../rules/testing-standards.md#the-three-tiers)
+— a `.feature` file is **acceptance**, a path containing `/contract/` or
+`.contract.test.` is **contract**, and a path containing `.test.` or
+`__tests__/` is **unit**; a skipped test leaves its tier uncovered. Then take
+the lowest tier with no live test (unit → contract → acceptance) and write one
+concrete sentence describing the test that would close it — the item's
+`missingTest` (`null` when every tier is covered).
+
 ## Triage — classify → route → disposition → promote
 
 Route the ledger through the shared classify/route/dedup/promote core. The

package/.agents/workflows/memory-consolidate.md

@@ -101,7 +101,7 @@ count the directory, never the plan. The stamp is the operator's record of
 the pass; nothing in the framework reads it back.
 
 The `/mandrel-plan` Phase 0 advisory re-arms on exactly one condition:
-`MEMORY.md` exceeding `planning.memoryPool.indexByteCeiling` (24576) bytes —
+`MEMORY.md` exceeding the fixed 24576-byte index ceiling —
 the harness cap past which the index it loads is truncated. Pool size and
 stamp age never trigger it (Story #5312 retired those arms): a pass that
 rewrites long index lines short quiets it without pruning an entry.

package/.agents/workflows/qa-assist.md

@@ -6,36 +6,21 @@ description: Human-led QA assist loop — set up, then ride a rolling multi-obse
 
 Drive a **human-led, rolling QA-assist session**. The operator tests; the agent
 rides alongside as the QA engineer and captures what they see into a
-high-quality, triage-ready ledger. The session has four movements:
-
-1. **Setup & Ready** (Phase 0) — load codebase context, resolve the contract,
-   open (or resume) the rolling ledger, then tell the operator what it will do
-   and that it is **ready for observations**.
-2. **Rolling intake** (Phases 1–3, looped) — the operator reports observations
-   **in any order and any quantity**: one at a time, or a **brain dump** of many
-   at once. The agent splits a multi-observation message into discrete items and
-   runs each through **Intake → Enrich → Record**, then **loops straight back**
-   for more. It **records and enriches only — it never plans or fixes during
-   intake.**
-3. **Done** — when the operator says they have finished testing, the agent does
-   a final review of the **entire** ledger and asks any last clarifying
-   questions.
-4. **Triage & Plan** (Phase 4) — only then does it route the full ledger through
-   [`/mandrel-plan`](mandrel-plan.md) to generate Stories.
-
-Unlike [`/qa-explore`](qa-explore.md) (where the *agent* drives open-ended
-exploration of a named surface), `/qa-assist` is **human-led**: the human owns
-the signal, the agent owns the enrichment. It is the front door for "I'm
-testing — ride along and capture everything well." Each observation is a
-`QaLedgerItem` on the same ledger `/qa-explore` produces, so a `/qa-assist` item
-flows through the identical dedup, classification, and promotion machinery in
-Phase 4.
+high-quality, triage-ready ledger: Setup (Phase 0), a rolling
+**Intake → Enrich → Record** loop over observations reported in any order and
+quantity (Phases 1–3 — record only, never plan), then Triage & Plan (Phase 4)
+once the operator says they are done.
+
+Unlike [`/qa-explore`](qa-explore.md) (where the *agent* drives exploration of
+a named surface), `/qa-assist` is **human-led**: the human owns the signal, the
+agent owns the enrichment. Each observation is a `QaLedgerItem` on the same
+ledger `/qa-explore` produces, so it flows through the identical dedup,
+classification, and promotion machinery in Phase 4.
 
 The shared machinery — contract resolution + loud failure, the session & ledger
 contract, redact-first, the `QaLedgerItem` shape, the triage procedure, and the
 HITL write gate — lives once in [`helpers/qa-core.md`](helpers/qa-core.md); this
-workflow states only the `/qa-assist`-specific phases (Intake / Enrich) plus a
-Constraints delta.
+workflow states only the `/qa-assist`-specific phases.
 
 > **When to run**: a developer or operator is about to test (or is mid-test) and
 > wants every bug and enhancement idea captured as a high-quality,
@@ -97,9 +82,8 @@ rolling loop stays fluid:
   done. Second, **every write that leaves the local ledger** — filing a ticket,
   invoking `/mandrel-plan`, or mutating a label. Present the artifact, ask, and wait.
 
-In short: appending to the rolling ledger is the natural product of intake and
-needs no gate beyond the echo-back; **planning and anything that leaves the
-ledger is hard-gated.**
+Appending to the rolling ledger needs no gate beyond the echo-back; **planning
+and anything that leaves the ledger is hard-gated.**
 
 ---
 
@@ -160,8 +144,10 @@ first, then run Intake for **each** before returning for the next message.
 
 ## Phase 2 — Enrich (per observation)
 
-Goal: turn the observation into a high-quality, triage-ready finding. Delegate
-every decision to the shared helpers; never re-derive them in prose.
+Goal: turn the observation into a high-quality, triage-ready finding. The
+classification comes from its deterministic helper and tier placement from the
+three path rules; context lookup and the missing-test sentence are your own
+judgment.
 
 1. **Redact first** (per [`helpers/qa-core.md`](helpers/qa-core.md)) — scrub the
    evidence string through `redactEvidence` before it touches disk or GitHub.
@@ -178,17 +164,10 @@ every decision to the shared helpers; never re-derive them in prose.
    `gh issue view <ticketNumber> --json title,body,labels`, and verify each
    surface-map path resolves with `git cat-file -e HEAD:<path>` — flag every
    miss rather than citing a path that does not exist.
-4. **Read the coverage tiers** for the surface the observation points at:
-   gather the tests that exercise it and classify each by path per
-   [`testing-standards.md` § The Three Tiers](../rules/testing-standards.md#the-three-tiers)
-   — a `.feature` file is **acceptance**, a path containing `/contract/` or
-   `.contract.test.` is **contract**, and a path containing `.test.` or
-   `__tests__/` is **unit**. A skipped test leaves its tier uncovered.
-5. **Name the missing test** (if any): take the lowest tier with no live test
-   (unit → contract → acceptance) and write one concrete sentence describing
-   the test that would close it. Every tier covered means no missing test.
-   Record that sentence as the ledger item's `missingTest`.
-6. **Classify** the finding via
+4. **Read the coverage tiers and name the missing test** per
+   [`helpers/qa-core.md`](helpers/qa-core.md) § Coverage tiers, recording the
+   sentence as the ledger item's `missingTest`.
+5. **Classify** the finding via
    [`classify-finding.js`](../scripts/lib/findings/classify-finding.js) so the
    tentative `class` resolves to the correct focus/meta label set. The helper
    **throws** on an absent/unknown class — fix the finding's class rather than
@@ -236,10 +215,9 @@ its transition is **explicitly operator-gated**.
    `file`-dispositioned findings through `promoteFindings` → `/mandrel-plan` (never a raw
    Issue), stamping each cluster's `fingerprintFooter(sha)` into the seed.
    `defer` carries an item forward as backlog; `dismiss` marks it non-actionable.
-3. **Gate:** the move into this phase, and every write inside it (seed write,
-   `/mandrel-plan` invocation, ticket-filing, label mutation), is **operator-gated** —
-   confirm each one. The plan→deliver hard stop is preserved; redaction has
-   already run, so nothing unredacted reaches disk or GitHub.
+3. **Gate:** every write inside this phase (seed write, `/mandrel-plan`
+   invocation, ticket-filing, label mutation) is **operator-gated** — confirm
+   each one. The plan→deliver hard stop is preserved.
 
 After planning, summarize: the findings recorded, the route/promotion decisions
 (`new`/`update-existing`/`duplicate`/`regression-of-closed`), whether each
@@ -250,31 +228,9 @@ resumed session will pick up.
 
 ## Constraints
 
-Beyond the shared core ([`helpers/qa-core.md`](helpers/qa-core.md): contract +
-loud failure, session/ledger, redact-first, QaLedgerItem, triage, HITL gate),
-the `/qa-assist`-specific deltas are:
-
-- **Human-led, rolling, multi-observation.** The operator owns the signal and
-  reports in any order and quantity — one at a time or a brain dump. The agent
-  splits a brain dump (echoing the split for correction), then enriches and
-  records each. **Never invent an observation**; ask clarifying questions only
-  when one is ambiguous, batched across the dump.
-- **Record during intake; plan only on "done".** Phases 1–3 enrich, append, and
-  loop — never triage, route, file, or invoke `/mandrel-plan`. All of that is Phase 4,
-  entered only on explicit operator confirmation that testing is done.
-- **Light intake gate, firm boundary gate.** Intake → Enrich → Record is fluid
-  (echo-back, no ceremony); the move into Phase 4 and every write that leaves the
-  ledger are hard-gated.
-- **Persistent, resumable rolling session** — `/qa-assist` defaults to resuming
-  the same session and appending; a reused session carries the untriaged backlog
-  forward and never overwrites a prior ledger.
-- **Enrichment delegates where a helper exists** — the finding classification
-  comes from its deterministic helper, never from prose; tier placement comes
-  from the three path rules in
-  [`testing-standards.md`](../rules/testing-standards.md#the-three-tiers).
-  Context lookup and the missing-test sentence are the model's own work: they
-  are judgments, not computations, and routing them through a module only
-  bought a round-trip.
+The shared core in [`helpers/qa-core.md`](helpers/qa-core.md) binds this
+workflow. The `/qa-assist` deltas are stated once, above: never invent an
+observation, record during intake, and plan only on "done" (§ Phase gates).
 
 ## See also