mandrel 2.38.0 → 2.40.0

package/.agents/scripts/quality-preview.js

@@ -12,9 +12,18 @@
  *   2. `npm run quality:watch`     — chokidar wrapper re-emits on save.
  *   3. `.husky/pre-commit`         — block the commit on threshold violations.
  *
- * Story #1394 (Epic #1386) flipped the default scope of both gates to
- * diff-against-`main`, so passing `--changed-since HEAD` here mirrors what the
- * pre-commit hook actually wants: the delta the operator is about to commit.
+ * The pre-commit hook passes `--staged` and nothing else — the index is
+ * already the exact delta the operator is about to commit, and
+ * `tests/pre-commit-hook.test.js` pins that `--changed-since` stays off it.
+ * (This docblock previously claimed the hook passed `--changed-since HEAD`,
+ * describing a wiring the hook has not used for some time; the stale prose
+ * sent at least one bug report at the wrong flag — Story #5131.)
+ *
+ * `--staged` is merge-aware: while a merge is in progress the index is read
+ * against `MERGE_HEAD` rather than `HEAD`, so a base-sync merge commit is
+ * scored for the merging branch's own work and its conflict resolutions, not
+ * for everything the base branch landed. See `resolveMergeHead` in
+ * `lib/changed-files.js`.
  *
  * The CLI exits 0 when both envelopes report zero violations and the script
  * could not surface a regression. Any violation in either envelope, or any
@@ -29,6 +38,7 @@ import {
   runCrapPreview,
   runMaintainabilityPreview,
 } from './lib/baselines/preview-gates.js';
+import { resolveMergeHead } from './lib/changed-files.js';
 import { respondToHelp } from './lib/cli-usage.js';
 import { getQuality, resolveConfig } from './lib/config-resolver.js';
 import { resolveCyclomaticPolicy } from './lib/cyclomatic-ceiling.js';
@@ -39,7 +49,10 @@ const USAGE = {
   summary:
     'Preview the per-file maintainability and CRAP deltas for the change set, and exit non-zero on any threshold violation.',
   flags: [
-    ['--staged', 'Score the git index only (the pre-commit-hook scope).'],
+    [
+      '--staged',
+      'Score the git index only (the pre-commit-hook scope). During a merge the index is read against MERGE_HEAD.',
+    ],
     [
       '--changed-since <ref>',
       'Score the diff against <ref> (default: HEAD). Last occurrence wins.',
@@ -388,6 +401,35 @@ function runGateSafely(runner, args, label, stderr) {
   });
 }
 
+/**
+ * Render the scope header line.
+ *
+ * Story #5131 — when `--staged` runs during a merge the scope is re-based to
+ * `MERGE_HEAD`, and the header says so. Without that line the operator sees a
+ * table whose row count does not match `git diff --cached` with no way to tell
+ * the narrowing was deliberate.
+ *
+ * The merge state is resolved here rather than read back off a gate envelope's
+ * `summary.diffRef`: that field means "the ref this scope was resolved
+ * against" for every scope kind, so anything that populates it — a future
+ * scope mode, a test stub — would render a merge banner over a repo that is
+ * not merging. Resolving it after the `!staged` early return also keeps the
+ * probe off the `--changed-since` path, which has no use for it.
+ *
+ * @param {{ staged: boolean, ref: string|null, cwd: string }} args
+ * @returns {string}
+ */
+function stagedScopeLine({ staged, ref, cwd }) {
+  if (!staged) return `scope=diff ref=${ref}\n\n`;
+  const mergeHead = resolveMergeHead({ cwd });
+  if (!mergeHead) return 'scope=staged (git diff --cached)\n\n';
+  return (
+    `scope=staged (git diff --cached ${mergeHead.slice(0, 12)}) — merge in ` +
+    "progress: scored against MERGE_HEAD, not HEAD, so the base branch's " +
+    'incoming files are excluded\n\n'
+  );
+}
+
 /**
  * Write the run's report — the `--json` envelope, or the human-readable
  * table plus any gate diagnostics and the non-zero-exit summary.
@@ -401,6 +443,7 @@ function runGateSafely(runner, args, label, stderr) {
  *   json: boolean,
  *   staged: boolean,
  *   ref: string|null,
+ *   cwd: string,
  *   miResult: {exitCode: number, envelope: object|null},
  *   crapResult: {exitCode: number, envelope: object|null},
  *   merged: ReturnType<typeof mergeEnvelopes>,
@@ -413,6 +456,7 @@ function emitReport({
   json,
   staged,
   ref,
+  cwd,
   miResult,
   crapResult,
   merged,
@@ -438,11 +482,7 @@ function emitReport({
     return;
   }
   stdout.write('\n--- quality:preview ---\n');
-  stdout.write(
-    staged
-      ? 'scope=staged (git diff --cached)\n\n'
-      : `scope=diff ref=${ref}\n\n`,
-  );
+  stdout.write(stagedScopeLine({ staged, ref, cwd }));
   stdout.write(`${renderTable(merged)}\n`);
   const diagnostics = renderDiagnostics([miResult, crapResult]);
   if (diagnostics) stdout.write(`\n${diagnostics}\n`);
@@ -518,6 +558,7 @@ export async function runCli({
     json,
     staged,
     ref,
+    cwd,
     miResult,
     crapResult,
     merged,

package/.agents/scripts/resolve-stories.js

@@ -39,6 +39,7 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
+import { expandEpicIds } from './lib/orchestration/epic-expansion.js';
 import {
   buildStoriesEnvelope,
   isSatisfiedBlocker,
@@ -71,7 +72,9 @@ real issue state.
 Options:
   --ids <csv>    Comma-separated Story issue numbers. Required. A token may be
                  a single id (4922) or an inclusive dash range (4922-4926);
-                 ranges expand in place and dedupe against the rest.
+                 ranges expand in place and dedupe against the rest. A
+                 container Epic id expands to its open child Stories, and may
+                 be mixed with Story ids.
   --pretty       Pretty-print the JSON envelope.
   --no-native    Skip the native blocked_by read (body edges only).
   --help         Show this help.
@@ -89,17 +92,54 @@ export function resolveStoriesProvider({
   return { provider: createProviderFn(config), config };
 }
 
+/**
+ * Read an Epic's native sub-issue children as issue numbers.
+ *
+ * Injected into `expandEpicIds` so the lib layer stays provider-agnostic,
+ * exactly as `paginate` is injected into `readNativeBlockedBy`. A provider
+ * without the GraphQL surface yields `[]`, and the Epic body's checklist
+ * carries the children on its own.
+ *
+ * @param {object} provider
+ * @returns {(epic: object) => Promise<number[]>}
+ */
+export function nativeChildReader(provider) {
+  return async (epic) => {
+    if (typeof provider?._getNativeSubIssues !== 'function') return [];
+    return provider._getNativeSubIssues(epic?.nodeId, epic?.number ?? epic?.id);
+  };
+}
+
 /**
  * Fetch every requested id and map it to a Story record, failing on the first
  * id that is not a deliverable Story.
  *
+ * Container Epics are expanded to their open child Stories **first**, so
+ * everything downstream sees a plain Story-id list (Story #5139). The
+ * expansion walk is sequential because it is id-by-id conditional; the Story
+ * fetch that follows stays under the bounded concurrency.
+ *
  * @param {object} provider
  * @param {number[]} ids
  * @returns {Promise<object[]>}
  */
 export async function fetchStories(provider, ids) {
-  return concurrentMap(
+  const { ids: resolvedIds, expansions } = await expandEpicIds({
     ids,
+    getTicket: (id) => provider.getTicket(id),
+    readNativeChildIds: nativeChildReader(provider),
+    warn: (m) => Logger.warn(m),
+  });
+
+  for (const { epicId, childIds } of expansions) {
+    Logger.info(
+      `[resolve-stories] Epic #${epicId} → ${childIds.length} open Story(ies): ` +
+        childIds.map((c) => `#${c}`).join(', '),
+    );
+  }
+
+  return concurrentMap(
+    resolvedIds,
     async (id) => {
       const issue = await provider.getTicket(id);
       if (!issue) {

package/.agents/scripts/validate-skills.js

@@ -1,11 +1,16 @@
 #!/usr/bin/env node
 // .agents/scripts/validate-skills.js
 //
-// Walk `.agents/skills/{core,stack}/**/SKILL.md` via the shared parser
+// Walk `SKILL.md` under both skills roots — the package payload
+// (`.agents/skills/{core,stack}/`) and the consumer-writable local zone
+// (`.agents/local/skills/{core,stack}/`, Story #5135) — via the shared parser
 // helper, validate each frontmatter block against
 // `.agents/schemas/skill.schema.json`, enforce Policy Capsule presence
-// (5–12 bullets), and verify membership in `.agents/skills/skills.index.json`
-// when that manifest exists. All findings are batched into a single
+// (5–12 bullets), and verify membership in each root's own manifest when it
+// exists. A consumer-authored skill is held to exactly the same bar as a
+// shipped one; the roots are validated separately because each carries its
+// own index (the shipped manifest is a payload file and must stay
+// payload-only — see generate-skills-index.js). All findings are batched into a single
 // human-readable report; the process exits non-zero when any finding is
 // surfaced.
 //
@@ -30,7 +35,17 @@ import { parseStandardCliArgs } from './lib/cli/standard-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { Logger } from './lib/Logger.js';
 import { parseSkill } from './lib/skills/parse-skill.js';
-import { collectSkillFiles } from './lib/skills/walk-skill-files.js';
+import {
+  auditIndex,
+  indexPathFor,
+  readIndexPaths,
+} from './lib/skills/skills-index.js';
+import {
+  collectLocalSkillFiles,
+  collectSkillFiles,
+  LOCAL_SKILLS_SEGMENTS,
+  PAYLOAD_SKILLS_SEGMENTS,
+} from './lib/skills/walk-skill-files.js';
 
 const MIN_CAPSULE_BULLETS = 5;
 const MAX_CAPSULE_BULLETS = 12;
@@ -118,56 +133,11 @@ function buildManifestValidator(repoRoot) {
 }
 
 /**
- * Read the on-disk skills.index.json manifest, returning `{ exists, paths,
- * manifest }` where `paths` is the Set of `entry.path` values when the file
- * is present and parseable, or null otherwise.
+ * Read one root's manifest into the `{ exists, paths, manifest, indexPath }`
+ * shape the findings pass consumes.
  */
-function readIndex(repoRoot) {
-  const indexPath = path.join(
-    repoRoot,
-    '.agents',
-    'skills',
-    'skills.index.json',
-  );
-  if (!fs.existsSync(indexPath)) {
-    return { exists: false, paths: null, manifest: null, indexPath };
-  }
-  try {
-    const manifest = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
-    const paths = new Set(
-      Array.isArray(manifest.skills)
-        ? manifest.skills
-            .map((s) => s.path)
-            .filter((p) => typeof p === 'string')
-        : [],
-    );
-    return { exists: true, paths, manifest, indexPath };
-  } catch (err) {
-    return {
-      exists: true,
-      paths: null,
-      manifest: null,
-      indexPath,
-      parseError: err.message,
-    };
-  }
-}
-
-/**
- * Validate a parsed manifest against skills-index.schema.json. Returns
- * finding strings tagged with the `manifest-schema` pillar.
- */
-function validateManifestSchema(manifest, indexRelPath, validateManifest) {
-  const findings = [];
-  if (!validateManifest(manifest)) {
-    for (const err of validateManifest.errors ?? []) {
-      const where = err.instancePath || '(root)';
-      findings.push(
-        `${indexRelPath}: manifest-schema: schema violation at ${where}: ${err.message}`,
-      );
-    }
-  }
-  return findings;
+function readIndex(repoRoot, rootSegments = PAYLOAD_SKILLS_SEGMENTS) {
+  return readIndexPaths(indexPathFor(repoRoot, rootSegments));
 }
 
 /**
@@ -216,6 +186,7 @@ function rel(absPath, repoRoot) {
 /**
  * Pure entry point used by tests. Returns `{ status, output, findings }`.
  */
+
 export function run({ argv = [], repoRoot } = {}) {
   const parsed = parseArgs(argv);
   if (parsed.help) {
@@ -234,25 +205,41 @@ export function run({ argv = [], repoRoot } = {}) {
   const indexRel = rel(indexInfo.indexPath, root);
 
   const findings = [];
-  if (!indexInfo.exists) {
-    findings.push(
-      `index missing: ${indexRel} not found — run 'node .agents/scripts/generate-skills-index.js'`,
-    );
-  } else if (indexInfo.paths === null) {
-    findings.push(`index unparseable: ${indexRel} — ${indexInfo.parseError}`);
-  } else if (indexInfo.manifest !== null) {
-    findings.push(
-      ...validateManifestSchema(indexInfo.manifest, indexRel, validateManifest),
-    );
-  }
+  findings.push(
+    ...auditIndex(indexInfo, indexRel, validateManifest, { required: true }),
+  );
 
-  const skillFiles = collectSkillFiles(root);
+  const payloadFiles = collectSkillFiles(root);
   const indexPaths =
     indexInfo.exists && indexInfo.paths !== null ? indexInfo.paths : null;
-  for (const file of skillFiles) {
+  for (const file of payloadFiles) {
     findings.push(...validateOne(file, root, validateFrontmatter, indexPaths));
   }
 
+  // The local zone is optional: a repo with no consumer-authored skills has
+  // no local root and no local index, and that is a clean run, not a finding.
+  const localFiles = collectLocalSkillFiles(root);
+  if (localFiles.length > 0) {
+    const localIndexInfo = readIndex(root, LOCAL_SKILLS_SEGMENTS);
+    const localIndexRel = rel(localIndexInfo.indexPath, root);
+    findings.push(
+      ...auditIndex(localIndexInfo, localIndexRel, validateManifest, {
+        required: true,
+      }),
+    );
+    const localIndexPaths =
+      localIndexInfo.exists && localIndexInfo.paths !== null
+        ? localIndexInfo.paths
+        : null;
+    for (const file of localFiles) {
+      findings.push(
+        ...validateOne(file, root, validateFrontmatter, localIndexPaths),
+      );
+    }
+  }
+
+  const skillFiles = [...payloadFiles, ...localFiles];
+
   if (findings.length === 0) {
     Logger.info(`validate-skills: ${skillFiles.length} skill(s) passed`);
     return { status: 0, output: '', findings };

package/.agents/templates/docs/audit-sweep-runbook.md

@@ -0,0 +1,169 @@
+# Audit sweep runbook
+
+> **Template generated by Mandrel.** Copy it into your own docs tree (e.g.
+> `docs/audit-sweep-runbook.md`), then localise every bracketed placeholder:
+> the cadence, the lens list, who reviews the ledger PR, and the label
+> conventions your repository actually uses. The steps themselves are the
+> contract — the values around them are yours.
+>
+> The workflow this runbook drives is
+> [`/audit-to-stories`](../../workflows/audit-to-stories.md); the CLI it calls
+> is [`audit-to-stories.js`](../../scripts/audit-to-stories.js). Run the CLI
+> with `--help` for the authoritative flag list.
+
+## What this runbook is for
+
+A maintenance **sweep** runs the `audit-*` lenses full-scope, folds their
+findings onto the cross-run ledger, and turns what is genuinely new into
+Stories. It is the unattended sibling of an interactive `/audit-to-stories`
+run: no HITL gates, so every judgement call the interactive path asks a human
+has to be settled here instead.
+
+| Setting | Value for this repository |
+| --- | --- |
+| Cadence | _e.g. weekly, Sunday 02:00_ |
+| Lenses in scope | _e.g. security, clean-code, quality, dependencies_ |
+| Severity floor | _`delivery.auditToStories.severityFloor`, default `high`_ |
+| Ledger reviewer | _e.g. @your-handle_ |
+| Story triage owner | _e.g. the on-call maintainer_ |
+
+## Step 1 — Run the lenses full-scope
+
+Run each `audit-*` workflow with **no** `--paths` and no change-set filter, so
+the whole target-set union is audited rather than whatever a recent branch
+happened to touch. Each lens writes its report to
+`temp/audits/audit-<lens>-results.md`.
+
+A sweep scoped to a change set is not a sweep: it re-reports the same recent
+files every cycle and never reaches the code nobody has touched in a year,
+which is exactly where audit findings accumulate.
+
+## Step 2 — Cross-check the severity tally
+
+Every lens report ends its executive summary with a machine-readable line:
+
+```text
+Severity tally: Critical 0 / High 3 / Medium 7 / Low 2
+```
+
+The CLI re-counts the `### Finding` blocks it actually parsed and compares them
+to that declared tally. A mismatch — or a missing tally line — means the report
+is not trustworthy: a finding was malformed, a severity did not resolve onto the
+canonical scale, or the lens truncated its own output.
+
+`--auto` **fails closed** on any such failure. It exits non-zero having opened
+no Issue and written no ledger, and names the offending report in
+`summary.reportFailures[]`. `--allow-missing-tally` is a `--scan` affordance
+only; `--auto` ignores it by design, because an unattended run has no operator
+to read a warning.
+
+**When the sweep goes red here, re-run the lens.** Do not reach for
+`--allow-missing-tally` and do not hand-edit the report to make the numbers
+agree — the tally is the only signal that the parse saw what the lens wrote.
+
+## Step 3 — Dry-run the first cycles
+
+Start every new sweep in report-only mode, and stay there until the tallies
+stop surprising you:
+
+```bash
+node .agents/scripts/audit-to-stories.js --auto --dry-run
+```
+
+`--dry-run` performs zero GitHub writes and skips the ledger write, printing
+only the run summary. Read `totals.create` before you let the sweep file
+anything: a first full-scope run over an un-audited repository can propose more
+Stories than your team can triage in a quarter. Raise `--severity` (or
+`delivery.auditToStories.severityFloor`) until the create count is a batch you
+would actually take on, then go live.
+
+## Step 4 — Go live, and persist the ledger
+
+```bash
+node .agents/scripts/audit-to-stories.js --auto --ledger-commit
+```
+
+The cross-run ledger (`baselines/audit-ledger.json`) is **consumer state, not
+scratch output**. It is what lets the next sweep tell a re-detection from a
+fresh finding, and a deliberately-rejected finding from an unseen one. A
+scheduled job normally runs on an ephemeral checkout, so unless the ledger is
+committed back it dies with the clone and every later sweep starts amnesiac —
+re-proposing findings already filed and re-surfacing findings a human already
+rejected.
+
+`--ledger-commit` closes that loop. After the run summary has printed, and only
+when the ledger actually changed, it:
+
+1. creates `chore/audit-ledger-<YYYY-MM-DD>` from the current HEAD,
+2. commits **only** the ledger file, subject
+   `chore(audit): reconcile audit ledger <date>`,
+3. pushes the branch, and
+4. opens a PR against your base branch.
+
+**Auto-merge is never requested.** The ledger records machine-derived lifecycle
+state, so a human glance before it lands is the point — nominate that reviewer
+in the table above. Review the PR for entries flipping to `accepted-risk` or
+`regressed`; those two are the ledger telling you something about your backlog,
+not about itself.
+
+Any git or `gh` failure in that sequence is fatal and names the step it broke
+on — but it happens _after_ the summary is printed, so a broken remote never
+costs you the sweep's findings.
+
+Without the flag, a run whose ledger changed on a checkout that cannot persist
+it — no `origin` remote, or HEAD parked off the base branch — sets
+`ledger.unpersisted: true` in the summary and warns on stderr naming the file.
+Treat that warning as a red sweep: the findings are fine, but the memory is
+about to be thrown away.
+
+## Step 5 — Enrich before you deliver
+
+`--emit-stories` renders `{ title, body, labels }` payloads from audit findings.
+Those bodies are **audit prose**, not delivery-ready Specs: they describe a
+symptom and a recommendation, not a scoped change with acceptance criteria a
+worker can verify against.
+
+Do not point `/mandrel-deliver` at a freshly-filed audit Story. Route it through
+`/mandrel-plan` first — the planning pass is where the finding becomes a
+capability slice with a `## Spec`, real `acceptance[]` items and runnable
+`verify[]` lines. Planning is deliberately not automated here: deciding what a
+finding is worth, and how far the fix should reach, is the judgement the sweep
+exists to surface rather than to make.
+
+The wiring pass is the exception — it _is_ mechanical and it is **required**.
+After opening the Issues, replay their numbers through `--wire-edges` so the
+cohort's declared ordering exists as `blocked by #N` footers and native
+`blocked_by` relations. An unwired cohort is genuinely unordered, and
+`/mandrel-deliver` will co-dispatch Stories the edges say must follow one
+another.
+
+## Step 6 — Label convention
+
+Audit-sourced Stories carry a closed label set, so they can be filtered out of
+(or into) ordinary planning at a glance:
+
+| Label | Meaning |
+| --- | --- |
+| `type::story` | Every emitted Story — the sweep never opens Epics or tasks. |
+| `agent::ready` | Filed and available for pickup. |
+| `audit::<lens>` | One per lens represented in the group; a cross-audit merge carries several. |
+| `risk::high` | Added when any finding in the group is Critical. |
+
+The lens labels are a **closed taxonomy**: only the canonical `audit::<lens>`
+names are valid, and the filer refuses to emit a label the repository has never
+created. Create them once with `audit-labels-bootstrap.js` before the first live
+sweep — a generated label that does not exist makes every Issue create fail.
+
+Do not invent per-finding labels. If you need another axis (a team, a
+component), add it in triage on top of this set rather than teaching the sweep
+to mint labels no taxonomy defines.
+
+## Failure triage
+
+| Symptom | Cause | Action |
+| --- | --- | --- |
+| Non-zero exit, `summary.reportFailures[]` populated | A lens report's tally is missing or disagrees with the parse | Re-run that lens; never downgrade with `--allow-missing-tally` |
+| `ledger.unpersisted: true` in the summary | No `origin`, or HEAD off the base branch | Re-run with `--ledger-commit`, or commit the ledger by hand |
+| `--ledger-commit failed at step "..."` | git or `gh` failed at the named step | Fix the remote/auth and re-run; the summary above it is still valid |
+| Same findings re-proposed every cycle | The ledger is not being committed | Adopt Step 4 |
+| `totals.create` far larger than the team can absorb | Severity floor too low for a first full-scope run | Raise `--severity` and re-dry-run |

package/.agents/workflows/audit-to-stories.md

@@ -44,10 +44,12 @@ They remain read-only emitters of audit reports.
 ## Phase 1 — Discover & parse
 
 Run the CLI in `--scan` mode against the resolved glob. It parses every
-`### Finding` block, normalises the fields (`Severity` / `Impact` are
+finding block, normalises the fields (`Severity` / `Impact` are
 both recognised; `Dimension` / `Category` likewise), and extracts file
-paths mentioned in the body. It then stamps each finding with a stable
-sha1 fingerprint via the shared
+paths mentioned in the body. A `###` heading that carries no severity axis and
+holds `####` blocks is read as a **grouping header**: its `####` children are
+the findings, and the header itself never becomes one. It then stamps each
+finding with a stable sha1 fingerprint via the shared
 [`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)
 helper (`fingerprintFinding`) — the single dedup/route implementation
 shared with `qa-explore`. The workflow carries **no** separate inline
@@ -64,6 +66,19 @@ The emitted plan envelope carries `findings`, `groups`, `edges`,
 `classifications`, and `summary`. Subsequent phases consume the file
 rather than re-parsing the reports.
 
+**The tally cross-check is automatic.** Every report declares
+`Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>` in its
+Executive Summary; the scan compares that line with what it parsed and carries
+each disagreement on `summary.reportFailures[]` as
+`{ sourceReport, kind, reported, parsed }`. The kinds are `missing-tally` (no
+line), `tally-mismatch` (line and parse disagree), and `unresolved-severity` (a
+finding whose severity did not resolve — dropped from grouping, never filed as
+an `unknown` group). They print to stderr before `--scan` returns its plan, so
+a mis-parsed report is never read as a clean audit: re-run the lens rather than
+file from it. Over older reports predating the mandate,
+`--scan --allow-missing-tally` downgrades **only** `missing-tally` to a
+warning.
+
 ## Phase 2 — HITL: severity gate
 
 Read the plan envelope's `summary.tally`. Present the operator with the
@@ -117,6 +132,11 @@ Ask:
 >   default-single policy.
 > - **Individual standalone Stories** — opens one GitHub Issue per
 >   group directly (no plan ceremony).
+>
+> Either way, if the sweep proposes **more than 2** Stories they are grouped
+> under a **container Epic** by default — a title, a one-paragraph goal and a
+> child checklist, carrying nothing a child does not already carry. Say so if
+> you would rather file them flat.
 
 **STOP** until the operator picks.
 
@@ -133,7 +153,14 @@ node .agents/scripts/audit-to-stories.js --emit-plan-seed \
 The seed renders the canonical one-pager sections — Problem Statement,
 Recommended Direction, Key Assumptions (with links to every source
 report), MVP Scope (the M proposed Stories), Key Files (so `/mandrel-plan`'s
-authoring step has concrete anchors), Not Doing.
+authoring step has concrete anchors), Grouping, Not Doing.
+
+**Grouping is the container-Epic directive.** Above 2 proposed Stories the
+seed instructs `/mandrel-plan` to group them under one Epic — a sweep is the
+clearest case for a container, since every Story shares a provenance and an
+operator usually delivers them together. It is a directive in the text, not an
+automatic write: Phase 4 above is where an operator declines it. Below the
+threshold the section says so and asks for nothing.
 
 Chain into the existing planning entrypoint:
 
@@ -215,6 +242,14 @@ its footprint guard ignores the shared provenance footers, so an unwired cohort
 is genuinely unordered and `/mandrel-deliver` will co-dispatch Stories the edges say
 must follow one another.
 
+**Preconditions.** The pass writes through the configured provider, so it needs
+`github.owner` **and** `github.repo` in `.agentrc.json` plus working `gh` auth
+(`GH_TOKEN`/`gh auth status`) — the same two things Phase 1's dedup needs. When
+either is missing the command refuses and names which one; fix that and re-run
+the exact command above. Do not transcribe the footers by hand: `/mandrel-deliver`
+reads them, but the native `blocked_by` relations only exist if this pass wrote
+them.
+
 ## Phase 6 — Idempotency (folded into Phase 1 scan)
 
 The `--scan` step routes each group's findings through the shared
@@ -289,6 +324,8 @@ summarising the run:
 
 When the single-plan path ran, link the Story (or plan-run) the chained
 `/mandrel-plan` opened. When the Standalone-Stories path ran, list every Issue URL.
+Either way, name the container Epic if one was created — it is the single id
+that delivers the whole sweep (`/mandrel-deliver <epicId>`).
 
 ## Constraints
 
@@ -330,18 +367,59 @@ writing their `temp/audits/audit-*-results.md` reports, then (2) invokes the
 CLI's **`--auto` mode** over those results:
 
 ```bash
-node .agents/scripts/audit-to-stories.js --auto [--dry-run] \
+node .agents/scripts/audit-to-stories.js --auto [--dry-run] [--ledger-commit] \
   [--glob "temp/audits/audit-*-results.md"] [--severity <floor>]
 ```
 
+The routine shape is **lenses full-scope → dry-run → live with a ledger PR**:
+
+1. Run the `audit-*` lenses with no `--paths` and no change-set filter. A
+   sweep scoped to a change set re-reports the same recent files every cycle
+   and never reaches the untouched code where findings accumulate.
+2. `--auto --dry-run` for the first cycles — zero writes, summary only. Read
+   `totals.create` and raise the severity floor until it is a batch the team
+   would actually take on.
+3. `--auto --ledger-commit` once the tallies stop surprising you.
+
 `--auto` runs with **no interactive gates**: it resolves the severity floor
 from `delivery.auditToStories.severityFloor` (default `high`, overridable with
 `--severity`), applies the two-stage dedup, reconciles the cross-run ledger,
 and prints a run-summary JSON (create / skip-open / skip-reoccurring /
 suppressed-by-ledger tallies, plus the re-detected open Issue numbers an
 operator may want a "re-detected" comment on). `--dry-run` performs zero GitHub
-writes and skips the ledger write, emitting only the summary. The host
-scheduler owns the cadence; this workflow owns the routing.
+writes and skips the ledger write, emitting only the summary.
+
+`--auto` **fails closed on any `summary.reportFailures[]` entry** (Phase 1): an
+unattended sweep has no operator to read a warning, so a missing or mismatched
+`Severity tally:` line — or a finding whose severity did not resolve — exits
+non-zero having opened no Issue and written no ledger. `--allow-missing-tally`
+is a `--scan` affordance that `--auto` ignores. A red sweep means the report is
+untrustworthy: re-run the lens. The host scheduler owns the cadence; this
+workflow owns the routing.
+
+### The ledger is consumer state — commit it
+
+`baselines/audit-ledger.json` is **committed consumer state, not scratch
+output**. A scheduled sweep normally runs on an ephemeral checkout, so unless
+the reconciled ledger is committed back it dies with the clone: every later
+sweep starts amnesiac, re-proposing findings already filed and re-surfacing
+findings a human already rejected.
+
+`--ledger-commit` closes that loop. After the summary prints — and only when
+the ledger changed — it creates `chore/audit-ledger-<YYYY-MM-DD>` from HEAD,
+commits **only** the ledger file, pushes it, and opens a PR against
+`project.baseBranch`. **Auto-merge is never requested**: a human glance at the
+`accepted-risk` / `regressed` flips before it lands is the point. A git or `gh`
+failure is fatal and names its step, but only after the summary is printed, so
+a broken remote never costs the operator the run's findings. `--dry-run` skips
+the tail. Without the flag, a changed ledger on a checkout that cannot persist
+it — no `origin`, or HEAD off the base branch — sets `ledger.unpersisted: true`
+in the summary and warns on stderr naming the file.
+
+The full sweep procedure — tally cross-check, the ledger PR, the
+enrich-before-deliver step and the label convention — ships as a
+consumer-copyable template at
+[`templates/docs/audit-sweep-runbook.md`](../templates/docs/audit-sweep-runbook.md).
 
 ## See also