mandrel 2.38.0 → 2.40.0

package/.agents/workflows/helpers/audit-lens-core.md

@@ -51,7 +51,8 @@ path). The report MUST include every section its lens template mandates — writ
 `_No findings._` rather than omitting a section — and always an
 `## Executive Summary` and a `## Detailed Findings` section. The Executive
 Summary carries the self-cross-check `kept <k> / dropped <d>` line
-([below](#self-cross-check)).
+([below](#self-cross-check)) and, beside it, the machine-readable severity
+tally ([below](#severity-tally)).
 
 Every finding under `## Detailed Findings` uses the shared 7-field skeleton
 below. A lens may **add** fields (e.g. a WCAG success criterion, a CWE ID, a
@@ -64,9 +65,11 @@ drops or renames a shared field.
 ```markdown
 ## Executive Summary
 
-[The lens's headline read plus the self-cross-check `kept <k> / dropped <d>`
-line. A lens may mandate additional report sections between here and the
-findings — its own body names them.]
+[The lens's headline read, the self-cross-check `kept <k> / dropped <d>` line,
+and the severity tally line below. A lens may mandate additional report
+sections between here and the findings — its own body names them.]
+
+Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
 
 ## Detailed Findings
 
@@ -188,6 +191,23 @@ that rests on one of them:
 A lens that keeps every finding still records `dropped 0` — the line's absence
 is itself a defect (it means the pass did not run).
 
+## Severity tally (mandatory, machine-readable) {#severity-tally}
+
+The Executive Summary MUST also carry exactly one tally line, counting the
+findings you kept:
+
+```text
+Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
+```
+
+Write every bucket, zeros included, and never count `Info` — the scale already
+excludes it from scheduled work. This line is the report's own checksum:
+`audit-to-stories --scan` cross-checks it against the findings its parser
+extracted and names any disagreement as a **report failure**
+(`summary.reportFailures[]`), and `--auto` refuses to file anything from a
+report whose line is missing or wrong. A parse that silently drops findings is
+otherwise indistinguishable from a clean audit.
+
 ## Execution strategy {#execution-strategy}
 
 A lens is a self-contained, read-only unit of work — exactly the shape a

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

@@ -292,6 +292,14 @@ This executes, in order:
   (files issues when auto-file is on; posts `follow-ups`).
 - `sibling-coherence` — Spec/Acceptance coherence check across sibling bodies
   (`plan-run-sibling-coherence`).
+- `epic-close` — closes a container Epic once **every** child Story is
+  `agent::done`, as `completed`. This is the only completion cascade v2 has:
+  it closes the container and nothing else — no child status roll-up, no label
+  inheritance, no reopening. Because linkage is parent→child only, the parent
+  is found by scanning open `type::epic` issues, and only an Epic containing
+  one of *this run's* Stories is considered, so an unrelated container is
+  never swept. An Epic with an outstanding child is reported `pending` and
+  left open.
 
 A single-Story run skips the epilogue — follow-ups are captured on merge
 confirm instead (`captureStoryFollowUps`).

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

@@ -414,6 +414,34 @@ 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)
+
+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.
+
+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
+body lint), a `## Spec`, an `acceptance[]` / `verify[]`, or any path, finding
+or rationale a child does not already hold. It is a container; unique content
+here is content no delivering agent reads.
+
+What the **Stories** never gain is an `Epic: #N` footer. Linkage is
+parent→child only, which is exactly why every existing refusal of that footer
+still stands and 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.
+
 ## Ready means fully persisted
 
 `agent::ready` is the **terminal** step, not part of the creating POST.

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

@@ -7,8 +7,8 @@ description:
 
 # /mandrel-deliver
 
-> **Lean spine.** Happy path + gate list. Sequencing, dispatch mechanics,
-> intent phrases, ceremony and the epilogue live in on-demand
+> **Lean spine.** Happy path + gate list. Sequencing, dispatch mechanics, intent
+> phrases, ceremony and the epilogue live in on-demand
 > [`helpers/deliver-reference.md`](helpers/deliver-reference.md) ("reference"
 > below); the unplanned path in
 > [`helpers/deliver-light.md`](helpers/deliver-light.md). Every delivery reads
@@ -21,9 +21,8 @@ close-and-land tail; Stories are implemented via
 [`helpers/deliver-story.md`](helpers/deliver-story.md).
 
 The dependency graph is **discovered, not declared** — `resolve-stories.js`
-reads it from live state, so you can deliver Stories **across plan runs and
-over time**. `plan-run::<id>` is filter metadata, never a resolution input;
-`route::lite` a body-derived hint only.
+reads it from live state, so you can deliver Stories **across plan runs and over
+time**. `plan-run::<id>` is filter metadata, never a resolution input.
 
 ## Inputs
 
@@ -36,25 +35,28 @@ you read:
 | `/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 - 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). |
 
 **The discriminator is lexical and total.** An argument matching `^#?\d+$` is an
 id, and `^#?\d+\s*[-–—]\s*#?\d+$` an inclusive **range** — pass one on as a
-single unspaced token, never hand-expanded (reference § Ranges). Either shape
+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 not
-`type::story`, or carrying an `Epic: #N` footer, is a hard error too.
+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.
 
 ## Saying what you want
 
-No flags to remember: state intent — *"…but I'll merge it myself"*, *"…one at
-a time"* — and announce what you read. Phrasings and the flags they fill in:
+No flags to remember: state intent — *"…but I'll merge it myself"*, *"…one at a
+time"* — and announce what you read. Phrasings and the flags they fill in:
 reference § Intent phrases.
 
 `--yes` is **runner-set, never operator-typed**: cron, `/loop` and headless
 dispatch set it to mean *nobody is at the keyboard*, which fails the unplanned
-path's over-scope stop closed to an envelope instead of a question. Never offer
-it to an operator or add it to an attended run.
+path's over-scope stop closed to an envelope instead of a question. Never add it
+to an attended run.
 
 ## Procedure
 
@@ -66,9 +68,11 @@ it to an operator or add it to an attended run.
    `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. It hard-errors (exit 1) on an id that
-   is not a Story, carries an `Epic: #N` footer, or whose edges cannot be
-   read — a missing gate would co-dispatch against an unlanded blocker.
+   tick re-resolves the graph every beat. 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.
 
 2. **Confirm (N>1).** Present the order; wait unless `--yes`.
 
@@ -87,62 +91,62 @@ it to an operator or add it to an attended run.
    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 (reference §§ Sequencing edge cases,
-   Dispatch mechanics). Branch on the exit code:
+   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.
    - **2 / 3 / 4** — `cycleError` / `wedged` / `blocked`: stop the loop and
-     route per reference § Sequencing edge cases. **4** is the protocol's HITL
-     pause ([`instructions.md` § 1.J](../instructions.md)) — surface it and
-     wait for the operator; never poll.
+     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)**:
-   `node .agents/scripts/plan-run-epilogue.js --stories 101,102`. N=1 skips it
-   ([reference § Per-run epilogue](helpers/deliver-reference.md)).
+   `node .agents/scripts/plan-run-epilogue.js --stories 101,102`, which also
+   closes a container Epic whose children all landed. N=1 skips it
+   ([reference](helpers/deliver-reference.md)).
 
 5. **Correct what the change invalidated.** If a memory you recalled this
-   session is now wrong — a trap this landed, a budget it moved — fix that
-   entry now, while both the old belief and the new fact are in context, and
-   say so when you report. No memory substrate → skip silently. Sweeping the
-   whole pool is [`/memory-consolidate`](memory-consolidate.md), not this step.
+   session is now wrong — a trap this landed, a budget it moved — fix that entry
+   now, while both the old belief and the new fact are in context, and say so
+   when you report. No memory substrate → skip silently. Sweeping the whole pool
+   is [`/memory-consolidate`](memory-consolidate.md), not this step.
 
 ## Closing what the workers hand back {#tail}
 
 **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 the envelope.
+(`single-story-close.js`) for it, foreground, and relay its envelope.
 
-**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 and
-the checkout. A worker handing back mid-close waits its turn.
+**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
+and the checkout. A worker handing back mid-close waits its turn.
 
-**A worker returning no terminal envelope is the expected shape**, not a failure
-to answer with a re-dispatch: only close mints one. Close the pushed branch, or
-probe read-only with `node .agents/scripts/deliver-recover.js --story <storyId>`
-and resume the worker or close it names.
+**A worker returning no terminal envelope is expected**, not a failure to answer
+with a re-dispatch: only close mints one. Close the pushed branch, or probe
+read-only with `node .agents/scripts/deliver-recover.js --story <storyId>` and
+resume what it names.
 
 **Reading the outcome.** Each close ends the Story in one schema-validated
 envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
-fields are digest § 5. `pending` is **not** a failure — `nextCommand` resumes
-it; run that, do not re-dispatch.
+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 + derived level via `ceremony-routing.js`, review depth reading
-it): reference § Ceremony.
+depth (profiles + the derived level via `ceremony-routing.js`, which review
+depth reads): reference § Ceremony.
 
 ## Constraints
 
 - **Land or block — never a silent local build** (digest § 2). Attended delivers
   default to close-and-land (`delivery.routing.closeAndLand: true`); rest at
-  `agent::closing` only when a human owns it.
-- **`/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).
+  `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).
 
 ## See also
 

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

@@ -7,14 +7,14 @@ description:
 
 # /mandrel-plan
 
-> **Lean spine.** Happy path + gate list; edge-case detail lives on demand in
+> **Lean spine.** Happy path + gate list; edge-case detail is on demand in
 > [`helpers/plan-reference.md`](helpers/plan-reference.md).
 
 ## Inputs
 
 Single planning path — there is no Epic/Story router, no scope-triage
-`epic|story` verdict. **Derive the mode from what the operator typed, announce
-it, act**:
+`epic|story` verdict (Gate #3's container groups, never routes). **Derive the
+mode from what the operator typed, announce it, act**:
 
 | Invocation | Mode | Behavior |
 | --- | --- | --- |
@@ -25,9 +25,9 @@ it, act**:
 | `/mandrel-plan 4712`, already delivered | amends | Amend a shipped Story from a **delta envelope**, not a re-interrogation. |
 
 **Resolving a bare id.** Read live state rather than asking: `agent::done` can
-only be amended, an open unplanned issue can only be 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
 
@@ -36,7 +36,7 @@ No flags to remember — state intent; the workflow fills in the CLI
 
 `--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
-gates below (#1 and #2). Never offer it to an operator or an attended run.
+gates below (#1 and #2) and skips #3. Never offer it to an operator.
 
 ## Default-single split policy
 
@@ -62,46 +62,44 @@ and derives source ids from its `sourceTickets[]`; the CLI also writes
 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)).
+persist — shape-validated, failing closed to `full` ([detail](helpers/plan-reference.md)).
 
 **Triage each unknown by resolver** ([detail](helpers/plan-reference.md)): an
 **AFK** unknown (research settles it) is resolved before authoring, never
-assumed; a **HITL** unknown (an operator call) goes to Gate #1 as "needs your
-decision". Under `--yes` do not ask free-form operator questions — AFK unknowns
-are still researched; only HITL unknowns land in Key Assumptions, each marked a
-decision-made-by-default.
+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
+in Key Assumptions, each a decision-made-by-default.
 
 **Gate #1** — STOP to confirm the sharpened plan intent and any
 duplicate-candidate review. Under `--yes`, auto-proceed.
 
-On a truthy `memoryPoolAdvisory.recommend`, name [`/memory-consolidate`](memory-consolidate.md)
-as an operator option, quoting its `reasons[]` — advisory, never invoked here.
+On a truthy `memoryPoolAdvisory.recommend`, name
+[`/memory-consolidate`](memory-consolidate.md) quoting its `reasons[]` —
+advisory, never invoked here.
 
 On a truthy `deliverLightSuggestion.suggested`, offer — advisory, never an
-automatic reroute — to deliver the seed instead; on confirm, route **in this
+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` marks a
-UI-touching plan: name [`/prototype`](prototype.md) as an operator option,
-never invoke it here. [Both offers](helpers/plan-reference.md).
+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).
 
 ### 2. Author
 
 **One-shot authoring.** Start 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[]` into it — never dual-author those lists.
+`acceptance[]` / `verify[]` in — never dual-author those lists.
 
 **Grounding = your reads + Phase 8.** Nothing inventories the repo: read each
-file you cite; persist's file-assumption gate hard-errors on any
-`{path, assumption}` absent from the tree. Entry fields:
-[reference](helpers/plan-reference.md).
+file you cite; persist hard-errors on any `{path, assumption}` absent from
+the tree. Fields: [reference](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
-`techspec.md` (**N===1 only** — folded into `## Spec`); optional
-`acceptance-manifest.json` (N>1 partition — `--plan-acceptance`). For N=1 use
-the envelope `systemPrompts.story`; split only under the policy above.
+`techspec.md` (**N===1 only**, folded into `## Spec`) and
+`acceptance-manifest.json` (N>1 — `--plan-acceptance`). Use the envelope
+`systemPrompts.story`; split only under the policy above.
 
 **Tickets mode:** every Story authors a top-level `supersedes[]`; persist
 refuses a partial map ([shape](helpers/plan-reference.md)).
@@ -115,9 +113,9 @@ node .agents/scripts/plan-critics.js \
 ```
 
 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, no skip ledgered: **do not
-proceed to Persist**, fix and re-run.
+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
@@ -125,16 +123,19 @@ proceed to Persist**, fix and re-run.
   authoring transcript), fold findings into Gate #2 or a re-author round, re-run
   this step. Pre-mortem triggers (incl. the external-dependency probe), the
   advisory-only `textHygiene.findings[]` lints and dispatch shape:
-  [reference § Critic dispatch detail](helpers/plan-reference.md).
+  [reference](helpers/plan-reference.md).
 
 ### 3. Persist
 
 **Gate #2** — STOP for approval before persist **only** when the operator asked
 to review (`--force-review`). Under `--yes`, auto-proceed.
 
-Run persist with `--dry-run` **first** — same command, writes suppressed;
-every gate runs before the first `createIssue`
-([the list](helpers/plan-reference.md)):
+**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.
+
+Run persist with `--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 \
@@ -142,24 +143,29 @@ node .agents/scripts/plan-persist.js \
   --plan-dir temp/plan-<slug> \
   [--plan-acceptance temp/plan-<slug>/acceptance-manifest.json] \
   [--tech-spec temp/plan-<slug>/techspec.md] \
-  [--source-tickets 123,456]
+  [--source-tickets 123,456] \
+  [--epic-title "<name>" --epic-goal "<one paragraph>"]
 ```
 
-At lite shape, `--chain-on-clean` folds a clean dry-run into the real persist;
+At lite shape `--chain-on-clean` folds a clean dry-run into the real persist;
 a full plan keeps its review trip.
 
 Persist creates `type::story` issue(s), a **metadata-only** `plan-run::<id>`
-label, and `blocked by #<id>` footers for N>1 `depends_on` edges.
+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)).
 
 ## Constraints
 
-- `/mandrel-plan` starts delivery **only** through a confirmed Gate #1 light route —
-  never off its own authored Stories, which land via [`/mandrel-deliver`](mandrel-deliver.md).
+- `/mandrel-plan` starts delivery **only** through a confirmed Gate #1 light
+  route — never off its own authored 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.
 
 ## See also
 

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

@@ -106,7 +106,11 @@ browser surface") and stop. Never attempt a headless fallback.
 runs against via
 [`resolveQaEnvironment`](../scripts/lib/qa/resolve-qa-contract.js), yielding
 `{ name, baseUrl, signInSeam, allowWrites }` (`allowWrites` defaults to an
-explicit boolean — `true` only for the conventional `local` environment). When
+explicit boolean — `true` only for the conventional `local` environment;
+`signInSeam` is `null` when the environment declares none). A `{ skill }` seam
+is resolved here too: the resolver throws when the id resolves to no
+`SKILL.md`, so a dangling seam fails before the browser is driven, never
+mid-sweep. When
 `<env>` is supplied, pass it straight through (an exact name wins; a raw URL
 matches by origin). When it is omitted (bare `/qa-run`), **prompt** the
 operator, enumerating every environment as `name → baseUrl` (marking
@@ -152,10 +156,14 @@ resolved environment's discriminated-union seam (anchored on `baseUrl`):
   input; under a `urlTemplate` seam the contract is authored as a plain name
   array and no per-persona auth material is read.
 - **`kind: 'skill'`** — invoke the named consumer sign-in skill (procedural /
-  non-URL sign-in). Real auth uses **only `credentialRef`-indirected material**
-  the skill dereferences; raw passwords, tokens, or API keys are never inlined
-  into the contract, the workflow, or chat, and captured evidence is redacted
-  per [`helpers/qa-core.md`](helpers/qa-core.md) before persistence.
+  non-URL sign-in), reading the `SKILL.md` at the seam's resolved `skillPath`.
+  Real auth uses **only `credentialRef`-indirected material** the skill
+  dereferences; raw passwords, tokens, or API keys are never inlined into the
+  contract, the workflow, or chat, and captured evidence is redacted per
+  [`helpers/qa-core.md`](helpers/qa-core.md) before persistence.
+- **No seam (`signInSeam` absent → `null`)** — a declarable state, not a
+  defect. Drive only the unauthenticated surface and record the gap in the
+  envelope; never fabricate a session or enter real credentials by hand.
 
 **Verification (the envelope's proof).** After sign-in, confirm the
 authenticated state with a `take_snapshot` showing the persona badge (the user

package/docs/CHANGELOG.md

@@ -15,6 +15,34 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.40.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.39.0...mandrel-v2.40.0) (2026-09-06)
+
+
+### Added
+
+* audit-to-stories --auto: persist the cross-run ledger via a `--ledger-commit` PR and ship the audit-sweep runbook template ([#5145](https://github.com/dsj1984/mandrel/issues/5145)) ([#5151](https://github.com/dsj1984/mandrel/issues/5151)) ([7274e6a](https://github.com/dsj1984/mandrel/commit/7274e6abe1bbf4fca6e1ed09abc8b4ebc9598d89))
+* audit-to-stories: parse `####` findings under grouping headers and fail closed on a missing or mismatched `Severity tally:` line ([#5144](https://github.com/dsj1984/mandrel/issues/5144)) ([#5149](https://github.com/dsj1984/mandrel/issues/5149)) ([d9d8275](https://github.com/dsj1984/mandrel/commit/d9d827584989406e85d3e22110e6b741dab837e9))
+* container Epic: /mandrel-plan offers one above 2 Stories, /mandrel-deliver expands an Epic id, /audit-to-stories requests one by default ([#5139](https://github.com/dsj1984/mandrel/issues/5139)) ([#5147](https://github.com/dsj1984/mandrel/issues/5147)) ([60dd912](https://github.com/dsj1984/mandrel/commit/60dd912f9d00dbf2fb7c17f8c98639b4008b5892))
+
+
+### Fixed
+
+* audit-to-stories --wire-edges: carry the live provider's write ports through the dedup adapter ([#5143](https://github.com/dsj1984/mandrel/issues/5143)) ([#5146](https://github.com/dsj1984/mandrel/issues/5146)) ([380577e](https://github.com/dsj1984/mandrel/commit/380577e5e8f215bf28bb15ef8f2ac03c5958f0b8))
+* **tests:** assert the report path separator-agnostically for Windows ([#5153](https://github.com/dsj1984/mandrel/issues/5153)) ([afe7fda](https://github.com/dsj1984/mandrel/commit/afe7fda7aa257bfb5e0745160363189ed84c2ad1))
+* **tests:** import the provider fixture as a file URL for Windows ([#5150](https://github.com/dsj1984/mandrel/issues/5150)) ([797af46](https://github.com/dsj1984/mandrel/commit/797af46269e22e878fbd13293e5e5df6a044a1d3))
+
+## [2.39.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.38.0...mandrel-v2.39.0) (2026-09-05)
+
+
+### Added
+
+* qa: make the `signInSeam` `{ skill }` arm authorable via a consumer-writable `.agents/local/skills/` root, and declarable-absent ([#5135](https://github.com/dsj1984/mandrel/issues/5135)) ([#5136](https://github.com/dsj1984/mandrel/issues/5136)) ([4a7c89e](https://github.com/dsj1984/mandrel/commit/4a7c89e55b83c20637c518950e3cdee5620a4442))
+
+
+### Fixed
+
+* quality-preview --staged: re-base the staged scope to MERGE_HEAD so a base-sync merge commit is not scored for the base branch's work ([#5131](https://github.com/dsj1984/mandrel/issues/5131)) ([#5132](https://github.com/dsj1984/mandrel/issues/5132)) ([d6fccc1](https://github.com/dsj1984/mandrel/commit/d6fccc15738fe22965ff8e9c819a55fe69b39815))
+
 ## [2.38.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.37.0...mandrel-v2.38.0) (2026-09-04)
 
 

package/package.json

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