mandrel 2.59.0 → 2.61.0

package/.agents/workflows/mandrel-deliver.md

@@ -33,7 +33,7 @@ you read:
 | --- | --- | --- |
 | `/mandrel-deliver` | bare | List the open `agent::ready` Stories and ask which to deliver. Deliver nothing until answered. |
 | `/mandrel-deliver 4712` | ids | One Story via `helpers/deliver-story.md`, **inline in this session** — no `story-worker` spawn. |
-| `/mandrel-deliver 4712 4713 …` | ids | Resolve the set, sequence by the discovered graph via `stories-wave-tick.js`, dispatch sub-agents. |
+| `/mandrel-deliver 4712 4713 …` | ids | Resolve the set, then beat `deliver-run.js` — it sequences by the discovered graph and hands back the spawns and closes. |
 | `/mandrel-deliver 4712 - 4716` | ids | A **range** — every id in the inclusive span. |
 | `/mandrel-deliver 4700` (a `type::epic`) | ids | The Epic's **open** child Stories. Mixes with Story ids. |
 | `/mandrel-deliver add a --json flag to doctor` | prompt | Unplanned work: gate, author a receipt Story, land it — [`helpers/deliver-light.md`](helpers/deliver-light.md). |
@@ -42,10 +42,10 @@ you read:
 id, and `^#?\d+\s*[-–—]\s*#?\d+$` an inclusive **range** — pass one on as a
 single unspaced token, never hand-expanded (reference). Either shape
 means ids; anything else means a prompt. A **mixed** invocation (ids *and*
-prose) is a **hard error** — refuse it and ask which was meant. A ticket that
-is neither `type::story` nor `type::epic`, or that carries an `Epic: #N`
-footer, is a hard error too — container Epics link parent→child only, so that
-footer stays refused.
+prose) is **ambiguous, not fatal** — disambiguate it rather than refusing:
+ask which was meant, or, when the reading is obvious, name the one you
+inferred before acting on it. A ticket that is neither `type::story` nor
+`type::epic` is a **hard error**.
 
 ## Saying what you want
 
@@ -67,41 +67,51 @@ to an attended run.
 1. **Resolve the set.** One command, one Story or many:
    `node .agents/scripts/resolve-stories.js --ids <id,id,...>`. It validates the
    set and shows what will run: read `stories[]`, `dag[]` and `done[]` to
-   present the order in step 2, but do **not** thread them into step 3 — the
-   tick re-resolves the graph every beat. An Epic id expands to its open child
+   present the order in step 2, but do **not** thread them into step 3 — every
+   beat re-resolves the graph. A one-id run comes back `dispatchMode: "inline"`
+   and runs [`helpers/deliver-story.md`](helpers/deliver-story.md) in this
+   session; step 3 is the multi-Story path. An Epic id expands to its open child
    Stories first — **announce it**. It hard-errors (exit 1) on an id that is
-   neither a Story nor an Epic, on an `Epic: #N` footer, on an Epic with no
-   open children, or on edges it cannot read — a missing gate would co-dispatch
-   against an unlanded blocker.
+   neither a Story nor an Epic, on an Epic with no open children, or on edges
+   it cannot read — a missing gate would co-dispatch against an unlanded
+   blocker.
 
 2. **Confirm (N>1).** Present the order; wait unless `--yes`.
 
-3. **Sequence.** Loop until the tick reports `epilogueDue: true`:
+3. **Run the beat.** One command per beat, repeated until the envelope reports
+   the run `done`:
 
    ```bash
-   node .agents/scripts/stories-wave-tick.js \
-     --stories <id,id,...> --probe-live \
-     --dispatched <every id you have dispatched so far>
+   node .agents/scripts/deliver-run.js \
+     --stories <id,id,...> [--handoff <id>]...
    ```
 
    **Do not add `--concurrency` unless the operator explicitly asked for a
    per-run cap** — an explicit value wins over config, so a literal defeats a
    `.agentrc.local.json` override.
 
-   Each beat re-probes live state to derive done / in-flight itself; you never
-   compute them. `--dispatched` is the one thing you must supply — the
-   append-only list of every id you spawned this run. Cross-run de-confliction
-   via the assignee lease is automatic. Branch on the exit code:
-   - **0** — dispatch each `ready` id (already capped and overlap-free); an
-     empty `ready` with work in flight means "waiting", so keep looping;
-     `epilogueDue: true` means every Story is done — step 4.
+   Each beat re-probes live state and keeps its own accounting: the run ledger
+   under `<tempRoot>/run-<id>/` records every id it hands out, so **nothing is
+   maintained across beats by you**. Cross-run de-confliction via the assignee
+   lease is automatic. Branch on the exit code:
+   - **0** — spawn one `story-worker` per `ready[]` entry, **all in one turn**,
+     each with that entry's `promptPath` file as its prompt; run each `close[]`
+     entry's command foreground and serialized as hand-offs arrive. An empty
+     `ready` with work in flight means "waiting", so beat again — **unless
+     `stalledDispatch[]` is non-empty**: those ids were dispatched but still
+     read `agent::ready`, which is a live init window the first beats or two
+     and a spawn that never started one after that. Beating again cannot
+     clear it. Relay `stalledDispatchReason` — it carries the recovery — and
+     let the operator decide; never edit the ledger for them.
+     `done: true` means every Story is landed — step 4.
    - **2 / 3 / 4** — `cycleError` / `wedged` / `blocked`: stop the loop and
      route per reference. **4** is the protocol's HITL pause
      ([`instructions.md` § 1.J](../instructions.md)) — surface it and wait for
      the operator; never poll.
 
-4. **Close each hand-off** (§ Closing what the workers hand back), then, with
-   every Story landed, run the **per-run epilogue (N>1)**:
+4. **Land what the workers hand back** (§ Closing what the workers hand back —
+   the beat renders each command), then, with every Story landed, run the
+   **per-run epilogue (N>1)**:
    `node .agents/scripts/plan-run-epilogue.js --stories 101,102`; N=1 has none
    ([reference](helpers/deliver-reference.md)). Every close rolls its container
    Epic up from its children.
@@ -117,7 +127,10 @@ to an attended run.
 **The tail is the orchestrator's, not the worker's.** A dispatched
 `story-worker` stops at a pushed branch and returns a hand-off; **you** run
 [`helpers/deliver-story.md`](helpers/deliver-story.md) Step 3
-(`single-story-close.js`) for it, foreground, and relay its envelope.
+(`single-story-close.js`) for it, foreground, and relay its envelope. Pass the
+id as `--handoff` on the next beat and run the `close[]` command it prints
+verbatim — the beat knows the run topology, so it decides
+`--merge-watch-mode async` for you.
 
 **Serialize the tail.** Implementation runs in parallel; closing does not.
 Close one Story at a time — closes contend on the base branch, the merge queue
@@ -133,9 +146,11 @@ envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
 fields are digest § 5. `pending` is **not** a failure — run its `nextCommand`.
 
 **Branch model (authoritative).** `story-<id>` → PR → `main` (squash +
-required checks), per digest § 2; dependent Stories land sequentially. Ceremony
-depth (profiles + the derived level via `ceremony-routing.js`, which review
-depth reads): reference § Ceremony.
+required checks), per digest § 2; dependent Stories land sequentially. The
+acceptance verdict owner follows the ceremony profile alone
+(`ceremony-routing.js`); the **derived level** feeds review depth instead
+(`review-depth.js`). The rule and its one home are digest § 3; the profile
+table is reference § Ceremony.
 
 ## Constraints
 
@@ -143,10 +158,11 @@ depth reads): reference § Ceremony.
   default to close-and-land (`delivery.routing.closeAndLand: true`); rest at
   `agent::closing` only when a human owns the merge.
 - **`/mandrel-deliver` never plans.** Planned tickets come from
-  [`/mandrel-plan`](mandrel-plan.md), and an over-scope prompt **escalates and
-  ends** — never invoke `/mandrel-plan` in this session to rescue it
-  ([`helpers/deliver-light.md`](helpers/deliver-light.md) § Escalation is
-  terminal).
+  [`/mandrel-plan`](mandrel-plan.md), and a refused prompt **escalates**: the
+  light path ends, and the escalation's `nextCommand` is what owns the work —
+  seeded with `escalation.reasons`, in this session or a fresh one
+  ([`helpers/deliver-light.md`](helpers/deliver-light.md) § Continuing into
+  `/mandrel-plan`).
 
 ## See also
 

package/.agents/workflows/mandrel-plan.md

@@ -47,14 +47,14 @@ checkpoints, not sibling tickets ([ref](helpers/plan-reference.md)).
 ### 1. Interrogate
 
 ```bash
-node .agents/scripts/plan-context.js --seed "<seed>" \
-  --out temp/plan-<slug>/plan-context.json
+node .agents/scripts/plan-context.js --seed "<seed>"
 # or: --seed-file <path> | --tickets 123,456 | --amends #<id>
 ```
 
-**Always pass `--out`.** Persist auto-discovers the envelope from `--plan-dir`
-and derives source ids from its `sourceTickets[]`; it also writes
-**`stories.template.json`**, step 2's skeleton.
+It writes the envelope and **`stories.template.json`** (step 2's skeleton) to
+`<tempRoot>/plan-<slug>/` and prints a digest naming both; `--out` overrides
+the path. Persist auto-discovers the envelope from `--plan-dir` and derives
+source ids from its `sourceTickets[]`.
 
 The envelope carries docs context, the story-author prompt (`systemPrompts.story`,
 plus `systemPrompts.storySplitRules` for an N>1 draft and
@@ -87,10 +87,11 @@ persist parses either, serializes canonical markdown and syncs top-level
 `acceptance[]` / `verify[]` in — never dual-author them.
 
 **Grounding = your reads + Phase 8.** Nothing inventories the repo: read each
-file you cite; persist hard-errors on any `{path, assumption}` absent from the
-tree — a `refactors-existing` on a path the base branch **deleted or renamed**
-included. One rescue: a **never-tracked** one normalises to `creates`. Fields:
-[ref](helpers/plan-reference.md).
+file you cite. A `changes[]` entry is a **bare path** by default — persist
+derives its assumption by probing the base branch and reports the derivation;
+pin `{path, assumption}` only when the probe would get it wrong, and always
+for a `deletes`, which is the one shape still refused on an absent path.
+Fields: [ref](helpers/plan-reference.md).
 
 Artifacts under `temp/plan-<slug>/`: `stories.json` (**length 1 by default**;
 a Spec is as long as the work needs, inline, never under `docs/`) and optional
@@ -120,15 +121,11 @@ Under `--yes`, auto-proceed.
 **any N** (`--epic <id>`); else, at **N>2**, a new container (`--epic-title` /
 `--epic-goal`). Never unasked ([ref](helpers/plan-reference.md)).
 
-Run persist `--dry-run` **first** — same command, writes suppressed; every gate
-runs before the first `createIssue` — including the **same-wave collision
-refusal**, which rejects an N>1 draft whose siblings declare a common path
-(merge them, or order them with `depends_on`) — and the run **lists its
-warnings**
-(a `creates` / `refactors-existing` the base branch disagrees with, a goal or
-acceptance path absent at base, an open question in a body) and the
-`changes[]` repairs it applied ([list](helpers/plan-reference.md)). Read
-them; they never stop the persist:
+**One command.** Persist runs every gate write-free first — including the
+**same-wave collision refusal**, which rejects an N>1 draft whose siblings
+declare a common path (merge them, or order them with `depends_on`) — and,
+when the gate list comes back clean, creates the issues in the same
+invocation:
 
 ```bash
 node .agents/scripts/plan-persist.js \
@@ -139,8 +136,12 @@ node .agents/scripts/plan-persist.js \
   [--epic <id> | --epic-title "<name>" --epic-goal "<one paragraph>"]
 ```
 
-`--chain-on-clean` folds a clean dry-run into the persist for **any** plan —
-the dry-run's warning list is the review.
+The run **lists its warnings** (a `creates` / `refactors-existing` the base
+branch disagrees with, a goal or acceptance path absent at base, an empty
+`verify[]`, a source id assigned to the primary Story by default, an open
+question in a body) and the `changes[]` repairs it applied
+([list](helpers/plan-reference.md)). Read them; they never stop the persist.
+Add `--dry-run` to validate without creating anything.
 
 Persist creates `type::story` issue(s), a **metadata-only** `plan-run::<id>`
 label, `blocked by #<id>` footers for every `depends_on` edge, and on a Gate #3
@@ -155,7 +156,7 @@ also comments on and closes each source id ([ref](helpers/plan-reference.md)).
 - Duplicate search targets open Stories (`type::story`), not Epics; and
   deterministic gates still fail closed under `--yes`.
 - A container Epic is never a work item and only an **open** one is adoptable;
-  no Story body gains an `Epic: #N` footer (linkage is parent→child only).
+  linkage is parent→child only.
 - `depends_on` takes a sibling slug or `#<id>` (open Story).
 
 ## See also

package/.agents/workflows/mandrel-update.md

@@ -7,7 +7,7 @@ description: >-
   leaves unowned: reconcile `.agentrc.json`, install the stabilized
   quality-gate surface, refresh the harness permission allowlist, reconcile
   the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and
-  stage + commit the staged lockfile bump.
+  stage + commit the dependency bump the CLI's closing report describes.
 ---
 
 # /mandrel-update
@@ -19,14 +19,15 @@ description: >-
 > **distribution-agnostic judgment steps** the CLI deliberately does **not**
 > perform — config reconciliation, the quality-gate installs, the
 > permission-allowlist refresh, the consumer-side changelog reconciliation,
-> and the stage-and-commit of the staged lockfile bump.
+> and the stage-and-commit of the dependency bump.
 
 The upgrade contract, in brief: the version only moves on explicit
 invocation (no `postinstall` drift — teammates track the committed
 lockfile pin, and CI's `npm ci` honours it); majors apply like any other
 bump (Mandrel ships hard cutovers — the surfaced changelog is the
-migration guide); the CLI **never commits** (the lockfile bump is left
-staged for operator review); and the only authoritative writer of the
+migration guide); the CLI **never mutates git** — it reads the index and
+**reports** whether the bump is staged, so the operator follows that
+report rather than an assumption; and the only authoritative writer of the
 generated `.claude/commands/` tree is
 [`sync-claude-commands.js`](../scripts/sync-claude-commands.js), invoked by
 the CLI's sync step.
@@ -80,22 +81,32 @@ npx mandrel update
 The dry run resolves the newest published version and prints the ordered
 step plan (`npm-update → runSync → runMigrations → doctor → surface
 changelog`) without touching anything — read the planned target version
-before applying. The live run drives those phases in order, leaves the
-lockfile bump **staged** (never committed), and finishes by printing the
-`docs/CHANGELOG.md` sections covering the applied range `(current, target]`.
-**Capture that changelog output** — Step 4 reconciles the consumer's own
-instructions against it. Already-newest is a clean no-op (`Already up to
-date`, exit 0).
+before applying. The live run drives those phases in order, never commits,
+and finishes by printing the `docs/CHANGELOG.md` sections covering the
+applied range `(current, target]`. **Capture that changelog output** —
+Step 4 reconciles the consumer's own instructions against it.
+Already-newest is a clean no-op (`Already up to date`, exit 0).
+
+**Read the closing line — it reports the real index state.** Staging is
+package-manager-specific (`npm install` may stage; `pnpm add` / `yarn add`
+stage nothing), so the CLI probes git read-only and tells you which of three
+states you are in rather than asserting one:
+
+| Closing line | What it means | What you do |
+| --- | --- | --- |
+| `The dependency bump is staged for review (package.json, <lockfile>).` | The index already carries both. | Go to Step 2. |
+| `The dependency bump is NOT staged. … Review and stage it: git add …` | Nothing (or only half) is staged. | Run the exact `git add` the line prints — it names `.agents/` too when this consumer tracks the materialized tree. |
+| `Review the working tree and commit the bump (git not available to report staging state).` | The probe could not read git; the update still succeeded (exit 0). | Inspect `git status` yourself before Step 5. |
 
 ## Step 2.5 — Partial-upgrade recovery (**blocker — resolve before Step 5**)
 
-The install phase stages the lockfile bump *before* the later phases run,
+The install phase writes the dependency bump *before* the later phases run,
 and by deliberate design the CLI **never rolls back the install on
 failure**. So when a post-install phase (`sync` / `sync-commands` /
 `migrate` / `doctor`) exits non-zero you land in a **partially-upgraded
-state**: the bump is already staged while `.agents/` may be
-half-materialized, the command tree out of sync, or a migration partially
-applied — and the operator is one `git commit` away from recording a broken
+state**: the bump is already on disk (and possibly in the index) while
+`.agents/` may be half-materialized, the command tree out of sync, or a
+migration partially applied — and the operator is one `git commit` away from recording a broken
 half-upgrade as "done". **Treat any post-install phase failure as an
 explicit blocker: do not proceed to Step 5 until the failed phase is
 recovered and a clean re-run reports success.**
@@ -203,22 +214,25 @@ between the installed and target versions:
    workflows for renamed flags / changed exit codes / removed scripts.
 
 Do not invent updates — silence is a valid review outcome. Stage every
-consumer-side edit alongside the staged lockfile bump so the upgrade and
-the reconciliation land in one reviewable commit.
+consumer-side edit alongside the dependency bump so the upgrade and the
+reconciliation land in one reviewable commit.
 
 ## Step 5 — Commit the bump
 
-> **Blocker check before you commit.** The staged lockfile bump is only safe
+> **Blocker check before you commit.** The dependency bump is only safe
 > to commit once every post-install phase has gone green. If `npx mandrel
 > update` exited non-zero, resolve it via
 > [Step 2.5 — Partial-upgrade recovery](#step-25--partial-upgrade-recovery-blocker--resolve-before-step-5)
 > **before** the `git commit` below. Committing over a half-upgrade records
 > a broken state as "done".
 
-Stage and commit the bump plus everything the wraparound touched:
+Stage and commit the bump plus everything the wraparound touched. Start from
+the `git add` the CLI's closing report printed (it names the detected
+lockfile, and `.agents/` when this consumer tracks it), then add the
+wraparound paths:
 
 ```bash
-git add package.json package-lock.json .agentrc.json .claude/settings.json AGENTS.md  # plus any runbook files touched in Step 4
+git add package.json package-lock.json .agentrc.json .claude/settings.json AGENTS.md  # lockfile per the CLI report; plus any runbook files touched in Step 4
 git commit -m "chore: update mandrel to v<NEW_VERSION>
 
 Upgraded v<OLD_VERSION> → v<NEW_VERSION> via mandrel update.
@@ -239,8 +253,9 @@ materialized tree.
 
 - **Idempotent.** A second `mandrel update` after a successful run hits the
   no-op short-circuit — exit 0, nothing bumped.
-- **No auto-commit.** The CLI leaves the lockfile bump staged and never runs
-  git; the operator writes the commit (Step 5).
+- **No auto-commit.** The CLI never stages and never commits — it reads git
+  only to report whether the bump is staged; the operator writes the commit
+  (Step 5).
 - **No framework-side version bump.** This workflow advances the
   *consumer's* pinned version; framework releases remain the maintainer's
   call via release-please.

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
 

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

@@ -6,29 +6,18 @@ description: Agent-led exploratory-QA loop — the agent Plans a surface with an
 
 Drive a **bounded, agent-led exploratory-QA session** as a human-in-the-loop
 (HITL) loop: **Plan → Capture → Triage**. The operator names a single surface;
-the agent (acting as the QA engineer) **plans** how it will reach that surface,
-**drives** it itself — through the browser MCP by default, or statically as a
-documented interim — and records each observation as a structured ledger item
-under a strictly read-only capture invariant. Only after explicit operator
-confirmation does it triage the ledger into routed, classified, dedup'd
-follow-up dispositions.
-
-This is the **agent-led** front-end of exploratory QA: **the agent drives, the
-operator watches and gates.** Its human-led sibling is
-[`/qa-assist`](qa-assist.md) — there the *human* drives a single observation and
-the agent scribes/enriches. No human-driven flow lives in `/qa-explore`.
-
-Unlike [`/qa-run`](qa-run.md) (which steps a known set of Gherkin `.feature`
-scenarios through a browser), `/qa-explore` is **open-ended exploration**: the
-agent probes the surface for product bugs, environment-setup friction,
-tooling/DX gaps, missing tests, and enhancement ideas — each captured as a
-`QaLedgerItem`.
+the agent drives it itself — **the agent drives, the operator watches and
+gates** — and records each observation as a `QaLedgerItem` under a strictly
+read-only capture invariant. Its human-led sibling is
+[`/qa-assist`](qa-assist.md); no human-driven flow lives in `/qa-explore`.
+Unlike [`/qa-run`](qa-run.md) (a known set of Gherkin `.feature` scenarios),
+this is **open-ended exploration** for product bugs, environment-setup
+friction, tooling/DX gaps, missing tests, and enhancement ideas.
 
 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-explore`-specific phases (Plan / Capture) plus a
-Constraints delta.
+workflow states only the `/qa-explore`-specific phases (Plan / Capture).
 
 > **When to run**: ad-hoc agent-driven exploration of a freshly delivered Story
 > or Feature, a regression sweep over a risky surface before `/mandrel-deliver`, or a
@@ -69,9 +58,7 @@ the skill owns them.
 | `surface` | yes      | `feature:login`, `area:onboarding` | A human label for the single surface to explore. Recorded as each ledger item's `coverage`. |
 
 If no `surface` is supplied, **stop and ask** the operator to name one — do not
-invent scope. `/qa-explore` is **bounded to one surface per session**: explore
-exactly the named surface, do not wander into adjacent surfaces, and start a
-fresh session for a different surface.
+invent scope.
 
 ## Contract & session
 
@@ -171,23 +158,16 @@ For each observation the agent makes while driving:
 
 1. **Redact first** (per [`helpers/qa-core.md`](helpers/qa-core.md)) — scrub the
    evidence string through `redactEvidence` before it touches disk.
-2. **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.
-3. **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` (or `null`).
-4. **Append a `QaLedgerItem`** to the ledger (shape per
+2. **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` (or `null`).
+3. **Append a `QaLedgerItem`** to the ledger (shape per
    [`helpers/qa-core.md`](helpers/qa-core.md)): a stable `id`, the redacted
    `evidence`, the `coverage` label (the `surface`, or `unknown`), a tentative
    `class` and `severity`, the `missingTest`, and `disposition` left untriaged.
-5. Continue driving until the agent believes the surface is covered, then
+4. Continue driving until the agent believes the surface is covered, then
    propose that exploration is complete.
-6. **Gate:** present the captured ledger (item count, classes, the driving
+5. **Gate:** present the captured ledger (item count, classes, the driving
    method used, the rolling backlog) and ask the operator to confirm moving to
    Triage. Do **not** triage until they confirm.
 
@@ -212,30 +192,10 @@ 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)
-and the driving conventions
-([`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)),
-the `/qa-explore`-specific deltas are:
-
-- **Agent-led, bounded per surface.** The agent drives one named surface per
-  session and proposes when it is covered; the operator gates the boundary. No
-  human-driven flow lives here — that is [`/qa-assist`](qa-assist.md).
-- **Pick the driving method at Plan time** (drive default; static the documented
-  interim, chosen with a recorded reason, never a silent fallback); do not
-  switch mid-surface without a new Plan note.
-- **Capture is read-only.** The only Capture write is appending ledger lines
-  under `temp/qa/`. No source edits, ticket mutations, product writes, or
-  destructive form submissions. Reach an authenticated surface only through the
-  resolved environment's `signInSeam`; where no seam resolves, record the gap
-  and fall back to static.
-- **Broken navigation is a finding, not a workaround** — never URL-jump around a
-  missing affordance, a nav 404, or a guard redirect loop.
-- **Read tier placement from the rule, not from prose you invent.** The three
-  path rules in
-  [`testing-standards.md` § The Three Tiers](../rules/testing-standards.md#the-three-tiers)
-  decide which tier a test occupies; the missing-test sentence is yours to write
-  from the lowest uncovered tier.
+The shared core in [`helpers/qa-core.md`](helpers/qa-core.md) and the driving
+conventions in [`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)
+bind this workflow. The `/qa-explore` deltas are stated once, above: one
+surface per session, the method chosen at Plan time, and a read-only Capture.
 
 ## See also