mandrel 2.40.0 → 2.42.0

package/.agents/workflows/helpers/deliver-story.md

@@ -40,7 +40,7 @@ that dispatched the work**, never to a spawned worker.
 
 **A worker returning no terminal envelope is expected, not a failure** — only
 Step 3 mints one. Never re-dispatch the Story on it; resume per § Recovery
-(reference § Idempotence and the standing constraints).
+(reference § Idempotence).
 
 ## Step 0 — Initialize (`single-story-init.js`)
 
@@ -73,12 +73,8 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
    digest-first; read a caller-provided `checklistPath` first, and walk any
    `## Slicing` rows as **intra-session checkpoints** (reference § Step 1).
 2. Implement and commit on the Story branch, iterating with quick advisory
-   gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3.
-3. Run the full suite once in the worktree **before Step 1a**: repo-invariant
-   guards outside the Story's scoped greps are the failure class that bounces
-   deliveries. Fix and commit first, then run the self-eval loop. Run it **so
-   Step 3 credits it** — a bare `npm test` records nothing, so close re-runs
-   the identical suite (reference § Step 1, "Pre-eval full-suite discipline").
+   gates (`typecheck`, `lint`, scoped tests) — the full chain runs in Step 3,
+   and the **one** creditable full-suite run at Step 2.5.
 
 ### Step 1a — Bounded acceptance self-eval loop (**required**)
 
@@ -94,14 +90,21 @@ Ceremony is `delivery.routing.ceremonyProfile` × the **derived change level**,
 never a planner-authored verdict. **Digest § 3** is the incantation (change set
 once, derive the level, resolve critics with `ceremony-routing.js`); edge cases
 are reference § Step 2. Hard gates always run in Step 3 — the derived level
-never disables them; do **not** pre-run the chain here.
+never disables them; do **not** pre-run the chain here — Step 2.5's credited
+suite run is the sole exception.
 
-### Step 2.5 — Push and hand off (sub-agent dispatch only)
+### Step 2.5 — The creditable full-suite run, then push and hand off
 
-Push `story-<storyId>` to `origin` and confirm the remote ref moved. Return the
-hand-off — Story id, `workCwd`, branch, pushed head SHA, self-eval verdict,
-`verify[]` evidence — then stop. Do not open the PR; do not compose a terminal
-envelope. An inline run skips this.
+Run the full suite **once**, after the self-eval loop's last fix commit and
+immediately **before** the push, in the shape close credits (**digest § 5**):
+the credit is keyed on the tree, so any later commit invalidates it, and a bare
+`npm test` deposits none. Red → fix, commit, re-run. An inline run makes the
+same run before Step 3.
+
+Then (sub-agent dispatch only) push `story-<storyId>` to `origin`, confirm the
+remote ref moved, and return the hand-off — Story id, `workCwd`, branch, pushed
+head SHA, self-eval verdict, `verify[]` evidence — then stop. Do not open the
+PR; do not compose a terminal envelope.
 
 ## Step 3 — Close and land (`single-story-close.js`)
 
@@ -115,7 +118,7 @@ node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <
 **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
 post-land tail in one process. Never background it, never delegate it to a
 child, and never end your turn while it is still running: "close is running"
-is not a return value. Branch on the envelope's `status` per **digest § 5**
+is not a return value. Branch on the envelope's `status` per **digest § 6**
 (`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
 → Step 4; `failed` → diagnose, re-run). Gate output is captured.
 
@@ -126,7 +129,7 @@ Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
 
 Relay the validated envelope close emits between its
 `--- STORY DELIVER TERMINAL ---` markers — never free-form prose, never a
-hand-composed object. Statuses, exits and fields: **digest § 5** (SSOT: the
+hand-composed object. Statuses, exits and fields: **digest § 6** (SSOT: the
 shipped [schema](../../schemas/story-deliver-terminal.schema.json)).
 `pending` is the only sanctioned no-merge ending.
 
@@ -139,15 +142,14 @@ so only a green on a NEW head SHA re-arms it — a re-run is refused; fix at sou
 and push ([`rules/ci-remediation.md`](../../rules/ci-remediation.md)). And a
 `tail.*: false` degrades the report, never the land.
 
-**Watch exit codes** — `pr-watch-with-update.js` exits 0 green, 1 only when a
-required check genuinely failed (or the PR is unreadable), 2 slow-but-not-red:
-still-running, unresolved, **or** `notYetStarted` — no required context attached
-inside `attachWindowMs`. Never route a 2 onto the red path; nothing is broken
-and no digest exists to read.
+**Watch exit codes** — `pr-watch-with-update.js` exits 0 green, 1 on a genuine
+red, 2 slow-but-not-red (still-running, unresolved, or `notYetStarted`). Never
+route a 2 onto the red path: nothing is broken and no digest exists to read.
+Which slow condition, and what to do: reference § Step 4.
 
 **Lost envelope first: read it off disk.** Close persists each to
 `temp/orchestration/story-deliver-terminal-<storyId>.json`; branch on it per
-digest § 5. Otherwise do not guess — probe **read-only** with
+digest § 6. Otherwise do not guess — probe **read-only** with
 `node .agents/scripts/deliver-recover.js --story <storyId>`; it prints the
 **one** next command with its evidence, never a menu. A live close answers
 `close-in-flight`: wait, never re-init underneath it.

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

@@ -234,7 +234,7 @@ Each `stories.json` entry: `slug` (`^[a-z0-9][a-z0-9-]*$`), `type: "story"`,
 `title`, `body` (`goal`, optional `spec`, `changes[{path, assumption}]` —
 `creates|refactors-existing|deletes`, `non_goals`, `reason_to_exist`),
 top-level `acceptance[]`, `verify[]` (`… (unit|contract|e2e|validate)`), and
-`depends_on[]` (N>1 only).
+`depends_on[]` (a sibling slug, or `#<id>` for an existing open Story).
 
 Nothing in that shape inventories the repo for the author. `changes[]` arrives
 pre-resolved against the working tree, and Phase 8's
@@ -414,7 +414,53 @@ That is the whole point of running it first: a dry run that comes back clean
 has already paid for every deterministic refusal, so the real persist has
 nothing left to discover except network failure.
 
-## The container Epic (Gate #3, N>2)
+## The container Epic (Gate #3)
+
+Gate #3 has two branches, in this order: **adopt** an Epic that already exists,
+else **create** a new one.
+
+### Adopting an open Epic (any N)
+
+`epicCandidates[]` in the plan-context envelope lists **every open `type::epic`
+issue**, each `{ id, title, url, score, childIds }`, ranked by token overlap
+between the seed and the Epic's title, `## Goal` and its children's titles. The
+list is deliberately **complete rather than thresholded**: a low score is
+evidence for the operator to weigh, and hiding a candidate is exactly how a
+plan opens its second container for one body of work.
+
+This branch fires at **any N, N=1 included** — "add this to the Epic we started
+last week" is the single-Story case, and refusing it below three Stories would
+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.
+
+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.
+
+**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
+re-scope a completed plan. Open a new container, or reopen the old one by hand.
+
+`--epic` and `--epic-title`/`--epic-goal` are **mutually exclusive** — a run
+either joins a container or opens one — and supplying both is a usage error
+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
@@ -442,6 +488,40 @@ 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.
 
+## Cross-plan `depends_on` (`#<id>`)
+
+A `depends_on[]` entry is read **lexically**: `some-slug` is a sibling inside
+this plan, `#<id>` an **external** blocker already live on the tracker. The
+second form is what lets a plan authored today wait on a Story an earlier plan
+opened and never had to name.
+
+`dependencyCandidates[]` in the envelope is the advisory prompt for it: open
+`type::story` issues whose declared `changes[]` footprint intersects the seed's
+`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.
+
+It stays advisory: two Stories can touch a shared barrel file with no real
+ordering between them, and only the operator knows.
+
+External refs are **excluded from sibling ordering and cycle detection** —
+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.
+
+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
+sibling edge produces. `/mandrel-deliver` therefore gates on it with no engine
+change: `resolve-stories.js` has always resolved foreign blockers from live
+state.
+
 ## Ready means fully persisted
 
 `agent::ready` is the **terminal** step, not part of the creating POST.

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

@@ -1,8 +1,7 @@
 ---
 description:
   Unified planning entry point. Interrogate → author → persist. Emits one
-  Story by default; splits into N>1 only under the default-single split
-  policy.
+  Story by default; splits into N>1 only under the default-single split policy.
 ---
 
 # /mandrel-plan
@@ -19,20 +18,20 @@ mode from what the operator typed, announce it, act**:
 | Invocation | Mode | Behavior |
 | --- | --- | --- |
 | `/mandrel-plan` | ask | Ask what to plan; nothing runs first. |
-| `/mandrel-plan add a --json flag to doctor` | seed | Ideation from prose: interrogate → author **one Story by default** → persist. |
+| `/mandrel-plan add a --json flag to doctor` | seed | Ideation from prose → **one Story by default** → persist. |
 | `/mandrel-plan temp/notes/idea.md` | seed-file | Same, from notes. An existing file is a path, not prose. |
 | `/mandrel-plan 4712[,4713…]` | tickets | Fetch issue(s), analyze into proper Stories (prefer N=1 rewrite). |
-| `/mandrel-plan 4712`, already delivered | amends | Amend a shipped Story from a **delta envelope**, not a re-interrogation. |
+| `/mandrel-plan 4712`, already delivered | amends | Amend a shipped Story from a **delta envelope**. |
 
 **Resolving a bare id.** Read live state rather than asking: `agent::done` can
-only be amended, an open unplanned issue only planned. **Announce the derivation** —
-"4712 is `agent::done` → amending". Ask **only** for an open Story already at
-`agent::ready`.
+only be amended, an open unplanned issue only planned. **Announce the
+derivation** — "4712 is `agent::done` → amending". Ask **only** for an open
+Story already at `agent::ready`.
 
 ## Saying what you want
 
 No flags to remember — state intent; the workflow fills in the CLI
-([reference](helpers/plan-reference.md)). Run scripts with `--help`.
+([ref](helpers/plan-reference.md)). Run scripts with `--help`.
 
 `--yes` is **runner-set, never operator-typed** — cron, `/loop`, and headless
 dispatch set it to mean *nobody is at the keyboard*, which auto-proceeds the
@@ -42,8 +41,7 @@ gates below (#1 and #2) and skips #3. Never offer it to an operator.
 
 Author **one Story** unless the pieces have **near-zero overlap** or sit across
 an **architectural seam**. Coupled work stays one Story — `## Slicing`
-checkpoints, not sibling tickets
-([detail](helpers/plan-reference.md)). **N=1 is lean.**
+checkpoints, not sibling tickets ([ref](helpers/plan-reference.md)).
 
 ## Procedure
 
@@ -52,19 +50,21 @@ checkpoints, not sibling tickets
 ```bash
 node .agents/scripts/plan-context.js --seed "<seed>" \
   --out temp/plan-<slug>/plan-context.json
-# or: --seed-file <path>  |  --tickets 123,456  |  --amends #<id>
+# 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[]`; the CLI also writes
+and derives source ids from its `sourceTickets[]`; it also writes
 **`stories.template.json`**, step 2's skeleton.
 
 The envelope carries docs context, the story-author prompt, `sourceTickets[]`,
-`duplicates[]` (open **Stories**, never Epics) and advisory `complexitySignals`
-(**no routing authority**). A trivial scope can claim the lite route at
-persist — shape-validated, failing closed to `full` ([detail](helpers/plan-reference.md)).
+`duplicates[]` (open **Stories**, never Epics), `epicCandidates[]` +
+`dependencyCandidates[]` (Gate #3; path collisions) and advisory
+`complexitySignals` (**no routing authority**). A trivial scope can claim the
+lite route at persist — shape-validated, failing closed to `full`
+([ref](helpers/plan-reference.md)).
 
-**Triage each unknown by resolver** ([detail](helpers/plan-reference.md)): an
+**Triage each unknown by resolver** ([ref](helpers/plan-reference.md)): an
 **AFK** unknown (research settles it) is resolved before authoring, never
 assumed; a **HITL** unknown goes to Gate #1. Under `--yes` do not ask free-form
 operator questions — AFK unknowns are still researched; only HITL unknowns land
@@ -74,26 +74,26 @@ in Key Assumptions, each a decision-made-by-default.
 duplicate-candidate review. Under `--yes`, auto-proceed.
 
 On a truthy `memoryPoolAdvisory.recommend`, name
-[`/memory-consolidate`](memory-consolidate.md) quoting its `reasons[]` —
-advisory, never invoked here.
+[`/memory-consolidate`](memory-consolidate.md) quoting its `reasons[]`;
+advisory.
 
 On a truthy `deliverLightSuggestion.suggested`, offer — advisory, never an
 automatic reroute — to deliver the seed instead; on confirm route **in this
 session** into [`helpers/deliver-light.md`](helpers/deliver-light.md), its gate
 filled from this envelope. A truthy `complexitySignals.uiSurface` names
-[`/prototype`](prototype.md) as an option; never invoke it here.
-[Both offers](helpers/plan-reference.md).
+[`/prototype`](prototype.md); never invoke it here.
+[Both](helpers/plan-reference.md).
 
 ### 2. Author
 
-**One-shot authoring.** Start from `stories.template.json`; author
-`stories.json` in one pass. `body` is markdown **or** a structured object;
+**One-shot authoring.** From `stories.template.json`, author `stories.json`
+in one pass. `body` is markdown **or** a structured object;
 persist parses either, serializes canonical markdown and syncs top-level
-`acceptance[]` / `verify[]` in — never dual-author those lists.
+`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. Fields: [reference](helpers/plan-reference.md).
+file you cite; persist hard-errors on any `{path, assumption}` absent from the
+tree. Fields: [ref](helpers/plan-reference.md).
 
 Artifacts under `temp/plan-<slug>/`: `stories.json` (**length 1 by default**;
 over-budget Specs fail closed — split or tighten, never under `docs/`); optional
@@ -112,10 +112,10 @@ node .agents/scripts/plan-critics.js \
   [--tech-spec temp/plan-<slug>/techspec.md]
 ```
 
-Run **before** persist — the last point a finding folds into a re-author.
-It exits 0 on **any** verdict (verdicts route work, they do not gate) and
-exits **1** only on a usage/IO error — no critic ran: **do not proceed to
-Persist**, fix and re-run.
+Run **before** persist — the last point a finding folds into a re-author. It
+exits 0 on **any** verdict (verdicts route work, they do not gate) and exits
+**1** only on a usage/IO error — no critic ran: **do not proceed to Persist**,
+fix and re-run.
 
 - **Both `dispatch: false`** — proceed to Persist (each skip is ledgered).
 - **Either `dispatch: true`** — dispatch **one fresh-context, maker-blind
@@ -130,12 +130,12 @@ Persist**, fix and re-run.
 **Gate #2** — STOP for approval before persist **only** when the operator asked
 to review (`--force-review`). Under `--yes`, auto-proceed.
 
-**Gate #3 (N>2 only)** — offer a **container Epic**; on a yes add
-`--epic-title` / `--epic-goal` below. It carries nothing a child does not
-([shape](helpers/plan-reference.md)). Never below 3 Stories, never unasked.
+**Gate #3 — adopt, else create.** Offer the top `epicCandidates[]` Epic at
+**any N** (`--epic <id>`); else, at **N>2**, a new container (`--epic-title` /
+`--epic-goal`). Never unasked ([ref](helpers/plan-reference.md)).
 
-Run persist with `--dry-run` **first** — same command, writes suppressed; every
-gate runs before the first `createIssue` ([list](helpers/plan-reference.md)):
+Run persist `--dry-run` **first** — same command, writes suppressed; every gate
+runs before the first `createIssue` ([list](helpers/plan-reference.md)):
 
 ```bash
 node .agents/scripts/plan-persist.js \
@@ -144,28 +144,28 @@ node .agents/scripts/plan-persist.js \
   [--plan-acceptance temp/plan-<slug>/acceptance-manifest.json] \
   [--tech-spec temp/plan-<slug>/techspec.md] \
   [--source-tickets 123,456] \
-  [--epic-title "<name>" --epic-goal "<one paragraph>"]
+  [--epic <id> | --epic-title "<name>" --epic-goal "<one paragraph>"]
 ```
 
-At lite shape `--chain-on-clean` folds a clean dry-run into the real persist;
-a full plan keeps its review trip.
+At lite shape `--chain-on-clean` folds a clean dry-run into the persist; a full
+plan keeps its review trip.
 
 Persist creates `type::story` issue(s), a **metadata-only** `plan-run::<id>`
-label, `blocked by #<id>` footers for N>1 `depends_on` edges, and on a confirmed
-Gate #3 a `type::epic` container linking every created Story.
-`agent::ready` is the **terminal** flip after receipts land; stdout is pure
-JSON. Tickets mode also comments on and closes each source id
-([detail](helpers/plan-reference.md)).
+label, `blocked by #<id>` footers for every `depends_on` edge, and on a Gate #3
+yes links them under a `type::epic` container (adopted or new). `agent::ready`
+is the **terminal** flip after receipts land; stdout is pure JSON. Tickets mode
+also comments on and closes each source id ([ref](helpers/plan-reference.md)).
 
 ## Constraints
 
 - `/mandrel-plan` starts delivery **only** through a confirmed Gate #1 light
-  route — never off its own authored Stories, which land via
+  route — never off its Stories, which land via
   [`/mandrel-deliver`](mandrel-deliver.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 no Story body gains an `Epic: #N`
-  footer: linkage is parent→child only.
+- 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).
+- `depends_on` takes a sibling slug or `#<id>` (open Story).
 
 ## See also
 

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

@@ -42,7 +42,8 @@ Constraints delta.
 > triage-ready finding without breaking stride — then, when the testing pass is
 > done, turned into a plan in one batch.
 >
-> **Skills**: `core/qa-coverage-mapping`
+> **Rules**: [`testing-standards.md`](../rules/testing-standards.md)
+> (§ The Three Tiers — the tier-classification rules enrichment applies)
 
 ## Role framing
 
@@ -106,7 +107,8 @@ ledger is hard-gated.**
 
 Goal: become the operator's QA assistant before any observation arrives.
 
-1. Re-read the QA role framing and `core/qa-coverage-mapping` skill.
+1. Re-read the QA role framing and the tier-classification rules in
+   [`testing-standards.md`](../rules/testing-standards.md) (§ The Three Tiers).
 2. **Load codebase context.** Read the files in `project.docsContextFiles`
    (architecture, decisions, patterns) and, when the testing touches UI/routing,
    `docs/style-guide.md` / `docs/web-routes.md`. This is the context you will
@@ -176,17 +178,16 @@ 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. **Compute the coverage verdict** for the surface the observation points at,
-   via [`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js) — the
-   deterministic seam behind the
-   [`core/qa-coverage-mapping`](../skills/core/qa-coverage-mapping/SKILL.md)
-   skill. Read that skill for how to assemble the `surface` input and read the
-   per-tier `{present|absent}` verdict.
-5. **Name the missing test** (if any) from that verdict: take the lowest tier
-   the verdict marks `absent` (unit → contract → acceptance) and write one
-   concrete sentence describing the test that would close it. Every tier
-   `present` means no missing test. Record that sentence as the ledger item's
-   `missingTest`.
+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
    [`classify-finding.js`](../scripts/lib/findings/classify-finding.js) so the
    tentative `class` resolves to the correct focus/meta label set. The helper
@@ -267,10 +268,12 @@ the `/qa-assist`-specific deltas are:
 - **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 coverage verdict and
-  the finding classification come from their deterministic helpers, never from
-  prose. 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
+- **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.
 
 ## See also

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

@@ -34,7 +34,7 @@ Constraints delta.
 > or Feature, a regression sweep over a risky surface before `/mandrel-deliver`, or a
 > structured agent-driven bug-hunt captured into a triageable ledger.
 >
-> **Skills**: `core/qa-coverage-mapping`, `stack/qa/qa-explore-driving`
+> **Skills**: `stack/qa/qa-harness`
 
 ## Role framing
 
@@ -45,15 +45,16 @@ the surface shows. Apply the QA skills below; there is no separate persona pack.
 ## Driving conventions
 
 Before you drive a surface, read the
-[`stack/qa/qa-explore-driving`](../skills/stack/qa/qa-explore-driving/SKILL.md)
-skill — the **one** conventions reference for the *how* of agent-driven
-exploration (navigation-first driving as the default; static driving as the
-documented interim chosen at Plan time only where no seam resolves;
-authenticated driving through the resolved environment's `signInSeam`; broken
-navigation is a finding, not a workaround). The driving method (drive vs.
-static) is a **Plan-phase decision recorded in the ledger**; do not switch
-methods mid-surface without a new Plan note. Do not restate these conventions
-inline — the skill owns them.
+[`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)
+skill — the **one** conventions reference for the *how* of agent-driven driving,
+shared with the known-scenario sweep (navigation-first driving as the default;
+static driving as the documented interim chosen at Plan time only where no seam
+resolves; authenticated driving through the resolved environment's
+`signInSeam`; broken navigation is a finding, not a workaround). Its § 5 carries
+the exploratory-mode deltas. The driving method (drive vs. static) is a
+**Plan-phase decision recorded in the ledger**; do not switch methods
+mid-surface without a new Plan note. Do not restate these conventions inline —
+the skill owns them.
 
 ## Slash Command
 
@@ -110,7 +111,7 @@ then the captured ledger), and wait. If the operator does not confirm, hold.
 Goal: agree on **what** will be explored and **how the agent will drive it**
 before touching the surface.
 
-1. Re-read the `stack/qa/qa-explore-driving` skill and resolve the contract and
+1. Re-read the `stack/qa/qa-harness` skill and resolve the contract and
    session (above).
 2. **Resolve the target environment** via
    [`resolveQaEnvironment`](../scripts/lib/qa/resolve-qa-contract.js) — it keys
@@ -149,8 +150,8 @@ Goal: **the agent drives the confirmed surface itself** and records its
 observations. **This phase is strictly read-only.**
 
 > **Read-only invariant.** The agent observes; it never mutates. Per
-> [`stack/qa/qa-explore-driving`](../skills/stack/qa/qa-explore-driving/SKILL.md)
-> § 3 (inviolable per [`security-baseline.md`](../rules/security-baseline.md)),
+> [`stack/qa/qa-harness`](../skills/stack/qa/qa-harness/SKILL.md)
+> § 2 (inviolable per [`security-baseline.md`](../rules/security-baseline.md)),
 > do **not** edit source, run write commands, file or label GitHub issues,
 > change tickets, submit destructive forms, or alter the product under test. The
 > only write Capture performs is **appending ledger lines to
@@ -170,17 +171,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. **Compute the coverage verdict** for the surface the observation points at,
-   via [`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js) — the
-   deterministic seam behind the
-   [`core/qa-coverage-mapping`](../skills/core/qa-coverage-mapping/SKILL.md)
-   skill. Read that skill for how to assemble the `surface` input and read the
-   per-tier `{present|absent}` verdict.
-3. **Name the missing test** (if any) from that verdict: take the lowest tier
-   the verdict marks `absent` (unit → contract → acceptance) and write one
-   concrete sentence describing the test that would close it. Every tier
-   `present` means no missing test. Record that sentence as the ledger item's
-   `missingTest` (or `null`).
+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
    [`helpers/qa-core.md`](helpers/qa-core.md)): a stable `id`, the redacted
    `evidence`, the `coverage` label (the `surface`, or `unknown`), a tentative
@@ -215,7 +215,7 @@ resumed session will pick up.
 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-explore-driving`](../skills/stack/qa/qa-explore-driving/SKILL.md)),
+([`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
@@ -231,10 +231,11 @@ the `/qa-explore`-specific deltas are:
   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.
-- **Delegate the coverage verdict to the helper.** Tier placement comes from
-  [`coverage-verdict.js`](../scripts/lib/qa/coverage-verdict.js) — deterministic,
-  never re-derived in prose. The missing-test sentence is yours to write from
-  that verdict's lowest `absent` tier.
+- **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.
 
 ## See also
 

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

@@ -29,7 +29,8 @@ the agent never invents those decisions in prose.
 > passes before `/mandrel-deliver`, or on demand while debugging a Story's
 > user-visible behavior in a live browser.
 >
-> **Skills**: `stack/qa/gherkin-authoring`, `stack/qa/playwright-bdd`
+> **Skills**: `stack/qa/qa-harness` (driving and instrumentation
+> conventions), `stack/qa/gherkin-authoring` and `stack/qa/playwright-bdd`
 > (authoring reference; this harness owns execution)
 
 ## Slash Command

package/docs/CHANGELOG.md

@@ -15,6 +15,38 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.42.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.41.0...mandrel-v2.42.0) (2026-09-06)
+
+
+### Added
+
+* full-suite capture economy: default the coverage-independent skip on, and serialize concurrent captures behind a host lock ([#5173](https://github.com/dsj1984/mandrel/issues/5173)) ([#5178](https://github.com/dsj1984/mandrel/issues/5178)) ([ed79751](https://github.com/dsj1984/mandrel/commit/ed7975199b6e2a3279a5d0d02b50e3068509987f))
+* story-worker digest carries the creditable full-suite invocation, runs it after self-eval, and the critic reuses its stamp ([#5174](https://github.com/dsj1984/mandrel/issues/5174)) ([#5175](https://github.com/dsj1984/mandrel/issues/5175)) ([1e46457](https://github.com/dsj1984/mandrel/commit/1e464574aa6305dcc8f1ff8522015ae0f9a5301a))
+
+
+### Fixed
+
+* scope the baseline refresh acknowledgment to the rows the refresh commit actually refreshed ([#5179](https://github.com/dsj1984/mandrel/issues/5179)) ([#5180](https://github.com/dsj1984/mandrel/issues/5180)) ([e8758b9](https://github.com/dsj1984/mandrel/commit/e8758b909ec19ed55c0678c05f481d515937f978))
+
+
+### Changed
+
+* close fails fast: base-sync before validation, and coverage-independent baseline kinds in the parallel gate phase ([#5172](https://github.com/dsj1984/mandrel/issues/5172)) ([#5177](https://github.com/dsj1984/mandrel/issues/5177)) ([dff33d5](https://github.com/dsj1984/mandrel/commit/dff33d530965ef7da8ee3dd4f1f218d11805273f))
+
+## [2.41.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.40.0...mandrel-v2.41.0) (2026-09-06)
+
+
+### Added
+
+* /mandrel-plan adopts an existing open Epic and declares depends_on edges on existing open Stories ([#5155](https://github.com/dsj1984/mandrel/issues/5155)) ([#5156](https://github.com/dsj1984/mandrel/issues/5156)) ([9119f31](https://github.com/dsj1984/mandrel/commit/9119f313146ab08ed676909f9b0a61671c4d6069))
+
+
+### Changed
+
+* **agents:** retire four frontier-known rules/skills, fold two more into rules (refs [#5158](https://github.com/dsj1984/mandrel/issues/5158)) ([#5162](https://github.com/dsj1984/mandrel/issues/5162)) ([065f883](https://github.com/dsj1984/mandrel/commit/065f8839fafcc7064e4ad6d2ea30f2bfebbd5c0c))
+* **qa:** fold qa-explore-driving into qa-harness (refs [#5159](https://github.com/dsj1984/mandrel/issues/5159)) ([#5163](https://github.com/dsj1984/mandrel/issues/5163)) ([2fbc8db](https://github.com/dsj1984/mandrel/commit/2fbc8db5a420450414cfd046bb6418e0c210bf7f))
+* **rules:** trim surviving rules and core skills to their contracts (refs [#5160](https://github.com/dsj1984/mandrel/issues/5160)) ([#5164](https://github.com/dsj1984/mandrel/issues/5164)) ([f0e6a62](https://github.com/dsj1984/mandrel/commit/f0e6a62feaba275377c9cc435f03ea6089008148))
+
 ## [2.40.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.39.0...mandrel-v2.40.0) (2026-09-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.40.0",
+  "version": "2.42.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",