mandrel 2.13.0 → 2.15.0

package/.agents/audit-checklists/navigability.md

@@ -6,7 +6,7 @@
 
 # Navigability Audit — authoring checklist
 
-> Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens (Epic #4131, F2/F3) exempt from the cross-epic-leak guard and routed onto route-adding change sets.
+> Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens exempt from the cross-epic-leak guard and routed onto route-adding change sets.
 
 Self-check your change against this lens's concerns before you ship:
 

package/.agents/docs/workflows.md

@@ -32,7 +32,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (25)
+## Commands (24)
 
 | Command | Description |
 | --- | --- |
@@ -43,7 +43,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |
 | `/audit-devops` | Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps. |
 | `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
-| `/audit-navigability` | Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens (Epic #4131, F2/F3) exempt from the cross-epic-leak guard and routed onto route-adding change sets. |
+| `/audit-navigability` | Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens exempt from the cross-epic-leak guard and routed onto route-adding change sets. |
 | `/audit-performance` | Audit performance by measuring first — profile hot paths, I/O, memory, and payload against the repo's own numbers — and audit interleaving/partial-failure correctness (TOCTOU, unawaited promises, non-atomic writes) as a first-class dimension. |
 | `/audit-privacy` | Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps. |
 | `/audit-quality` | Audit test coverage gaps, flaky tests, missing assertions, and test-pyramid balance; recommend a remediation batch. |
@@ -52,11 +52,10 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
 | `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --seed-file or opens standalone Stories. |
 | `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
-| `/deliver` | Unified delivery entry point. Takes a list of Story ids, resolves their dependency graph from live state, and delivers each via the single deliver-story engine — story-<id> → PR → main. |
-| `/deliver-light` | Single-session delivery for genuinely small work. Judges a prompt's predicted footprint, authors a receipt Story, then lands it through the same single-story-init / single-story-close engine — every close gate unchanged. |
+| `/deliver` | Unified delivery entry point. Takes Story ids or a plain-language prompt, derives which path the work belongs on, and lands it via the single deliver-story engine — story-<id> → PR → main. |
 | `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
 | `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
-| `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
+| `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the stabilized quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
 | `/plan` | Unified planning entry point. Interrogate → author → persist. Emits one Story by default; splits into N>1 only under the default-single split policy. |
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-deliver-terminal.schema.json",
   "title": "story-deliver-terminal",
-  "description": "The single terminal envelope every Story close-and-land invocation emits (Story #4543). Before this schema, the delivery tail had two divergent prose return contracts — one in .agents/workflows/helpers/deliver-story.md, a different one in .agents/agents/story-worker.md — and neither was validated by anything, so a caller could not tell a landed Story from a parked one without re-probing GitHub. This is the SSOT both now reference rather than restate. status is exactly one of landed | pending | blocked | failed; phase names where the run ended; tail carries per-step booleans so a partial-tail degradation is visible without failing an otherwise-landed merge; nextCommand names the single command that resumes or remediates the run, drawn from the same vocabulary deliver-recover.js prints.",
+  "description": "The single terminal envelope a Story delivery invocation emits (Story #4543). Before this schema, the delivery tail had two divergent prose return contracts — one in .agents/workflows/helpers/deliver-story.md, a different one in .agents/agents/story-worker.md — and neither was validated by anything, so a caller could not tell a landed Story from a parked one without re-probing GitHub. This is the SSOT both now reference rather than restate. status is exactly one of landed | pending | blocked | failed | escalated; phase names where the run ended; tail carries per-step booleans so a partial-tail degradation is visible without failing an otherwise-landed merge; nextCommand names the single command that resumes or remediates the run, drawn from the same vocabulary deliver-recover.js prints. escalated (Story #4746) is the one status emitted BEFORE a Story exists — /deliver-light's suitability gate refusing an over-scope prompt — which is why storyId is null exactly there and non-null everywhere else.",
   "type": "object",
   "required": [
     "kind",
@@ -14,16 +14,21 @@
   ],
   "properties": {
     "kind": { "type": "string", "const": "story-deliver-terminal" },
-    "storyId": { "type": "integer", "minimum": 1 },
+    "storyId": {
+      "type": ["integer", "null"],
+      "minimum": 1,
+      "description": "The Story this envelope reports on. null ONLY for status escalated, where the run refused before authoring a receipt Story — the allOf below pins that correspondence in both directions, so an escalated envelope cannot name a Story it did not create and a landed one cannot omit the Story it landed."
+    },
     "status": {
       "type": "string",
-      "description": "landed — the PR merged, the Story is agent::done, and the post-land tail was attempted. pending — a bounded wait expired with the PR still in flight; NO label was mutated and no merge.unlanded event was emitted, so the run is resumable via nextCommand. blocked — a classified hard block; the Story carries agent::blocked and blocked.blockClass names the class. failed — a phase crashed; phase names which one.",
-      "enum": ["landed", "pending", "blocked", "failed"]
+      "description": "landed — the PR merged, the Story is agent::done, and the post-land tail was attempted. pending — a bounded wait expired with the PR still in flight; NO label was mutated and no merge.unlanded event was emitted, so the run is resumable via nextCommand. blocked — a classified hard block; the Story carries agent::blocked and blocked.blockClass names the class. failed — a phase crashed; phase names which one. escalated — the /deliver-light suitability gate refused an over-scope prompt under --yes; nothing was created and the session ENDS here, nextCommand naming the /plan invocation that owns the work instead.",
+      "enum": ["landed", "pending", "blocked", "failed", "escalated"]
     },
     "phase": {
       "type": "string",
-      "description": "The pipeline phase the run ended in. Mirrors the close pipeline's phase names so a terminal envelope is attributable to one step.",
+      "description": "The pipeline phase the run ended in. Mirrors the close pipeline's phase names so a terminal envelope is attributable to one step. suitability-gate precedes them all — it is the /deliver-light gate, the only phase that runs before a Story exists.",
       "enum": [
+        "suitability-gate",
         "init",
         "wrong-tree-guard",
         "close-validation",
@@ -130,9 +135,35 @@
       },
       "additionalProperties": false
     },
+    "escalation": {
+      "type": ["object", "null"],
+      "description": "Present iff status === \"escalated\" (Story #4746). The suitability gate's decision was already correct before this block existed — what was missing was an outcome a session could not walk past. reasons carries the gate's own words; created records, per artifact, that the run started nothing.",
+      "required": ["reasons", "created"],
+      "properties": {
+        "reasons": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 },
+          "description": "The gate's reasons verbatim — the same strings the ask-operator path prints, so attended and unattended over-scope explain themselves identically."
+        },
+        "created": {
+          "type": "object",
+          "description": "Per-artifact proof that an escalated run left nothing half-started for a later run to trip over. Deliberately three const-false booleans rather than one aggregate flag or a bare omission: an omitted field reads as \"not checked\", and an aggregate is exactly the shape that let the post-land tail once report an outcome it never verified. Every value is pinned false by the schema, so an escalated envelope claiming it authored a receipt Story, cut a branch, or materialized a worktree cannot be built at all.",
+          "required": ["receiptStory", "storyBranch", "worktree"],
+          "properties": {
+            "receiptStory": { "const": false },
+            "storyBranch": { "const": false },
+            "worktree": { "const": false }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "nextCommand": {
       "type": ["string", "null"],
-      "description": "The single command that advances this Story from where it stopped, or null when status === \"landed\" and nothing remains. Shares its vocabulary with deliver-recover.js so recovery and normal resumption speak one language."
+      "description": "The single command that advances this work from where it stopped, or null when status === \"landed\" and nothing remains. Shares its vocabulary with deliver-recover.js so recovery and normal resumption speak one language. For status escalated it is the /plan invocation the operator runs in a FRESH session — the one case where the command is a slash command rather than a script, because the work needs planning, not resumption.",
+      "minLength": 1
     },
     "elapsedSeconds": { "type": "number", "minimum": 0 },
     "waitBudget": {
@@ -148,5 +179,28 @@
     },
     "timestamp": { "type": "string", "format": "date-time" }
   },
+  "allOf": [
+    {
+      "description": "escalated is the pre-Story terminal, and the correspondence is pinned in BOTH directions. An escalated envelope MUST carry the escalation block, MUST have a null storyId (it created none), and MUST name the next command that owns the work — so a run cannot report escalation while pointing at a Story it started. Every other status MUST carry an integer storyId and MUST NOT carry an escalation block, so the new status cannot leak into the close path.",
+      "if": {
+        "properties": { "status": { "const": "escalated" } },
+        "required": ["status"]
+      },
+      "then": {
+        "required": ["escalation"],
+        "properties": {
+          "storyId": { "type": "null" },
+          "escalation": { "type": "object" },
+          "nextCommand": { "type": "string", "minLength": 1 }
+        }
+      },
+      "else": {
+        "properties": {
+          "storyId": { "type": "integer", "minimum": 1 },
+          "escalation": { "type": "null" }
+        }
+      }
+    }
+  ],
   "additionalProperties": false
 }

package/.agents/scripts/acceptance-eval.js

@@ -302,4 +302,21 @@ export async function main(argv = process.argv.slice(2)) {
   return envelope;
 }
 
-runAsCli(import.meta.url, main, { source: 'acceptance-eval' });
+runAsCli(import.meta.url, main, {
+  source: 'acceptance-eval',
+  usage: {
+    invocation:
+      'node .agents/scripts/acceptance-eval.js --story <id> --verdict <path> [--no-signal]',
+    summary:
+      "Score an authored acceptance verdict against the Story's acceptance[] criteria and emit the bounded loop's proceed / redraft / block decision.",
+    flags: [
+      ['--story <id>', 'GitHub issue number of the Story (required).'],
+      ['--verdict <path>', 'Path to the authored verdict JSON (required).'],
+      [
+        '--no-signal',
+        "Skip appending the per-criterion signal to the Story's signals ledger.",
+      ],
+    ],
+    notes: ['Exit codes:\n  0  proceed or redraft\n  1  block'],
+  },
+});

package/.agents/scripts/agents-bootstrap-github.js

@@ -526,4 +526,25 @@ export {
   verifyApiAccess,
 };
 
-runAsCli(import.meta.url, main, { source: 'Bootstrap' });
+runAsCli(import.meta.url, main, {
+  source: 'Bootstrap',
+  usage: {
+    invocation:
+      'node .agents/scripts/agents-bootstrap-github.js [--assume-yes|--assume-no] [--approve-github-admin] [--with-project-board] [--reap-conflicting-workflows]',
+    summary:
+      'Bootstrap the GitHub side of a consumer repo: label taxonomy, issue forms, workflows, and the optional project board.',
+    flags: [
+      ['--assume-yes', 'Answer yes to every prompt (non-interactive run).'],
+      ['--assume-no', 'Answer no to every prompt (probe only).'],
+      [
+        '--approve-github-admin',
+        'Consent to admin-scoped GitHub mutations (implied by --assume-yes).',
+      ],
+      ['--with-project-board', 'Also provision the GitHub Project board.'],
+      [
+        '--reap-conflicting-workflows',
+        'Remove pre-existing workflow files that clash with the framework set.',
+      ],
+    ],
+  },
+});

package/.agents/scripts/apply-quality-bootstrap.js

@@ -76,4 +76,10 @@ async function main() {
 runAsCli(import.meta.url, main, {
   source: 'apply-quality-bootstrap',
   propagateExitCode: true,
+  usage: {
+    invocation: 'node .agents/scripts/apply-quality-bootstrap.js',
+    summary:
+      'Install the quality-gate surface into the consumer repo (guardrails helper, pre-commit line, npm scripts, config defaults) and migrate the baselines layout. Idempotent; prints { quality, baselines } JSON to stdout.',
+    flags: [],
+  },
 });

package/.agents/scripts/audit-labels-bootstrap.js

@@ -272,4 +272,18 @@ async function main() {
   }
 }
 
-runAsCli(import.meta.url, main, { source: 'audit-labels-bootstrap' });
+runAsCli(import.meta.url, main, {
+  source: 'audit-labels-bootstrap',
+  usage: {
+    invocation:
+      'node .agents/scripts/audit-labels-bootstrap.js [--owner <owner>] [--repo <repo>] [--force] [--dry-run]',
+    summary:
+      'Create the audit-finding label taxonomy in the target repository. Idempotent.',
+    flags: [
+      ['--owner <owner>', 'Repository owner (default: github.owner).'],
+      ['--repo <repo>', 'Repository name (default: github.repo).'],
+      ['--force', 'Update colour/description of labels that already exist.'],
+      ['--dry-run', 'Report what would be created; mutate nothing.'],
+    ],
+  },
+});

package/.agents/scripts/audit-to-stories.js

@@ -626,4 +626,29 @@ async function main() {
   );
 }
 
-runAsCli(import.meta.url, main, { source: 'audit-to-stories' });
+runAsCli(import.meta.url, main, {
+  source: 'audit-to-stories',
+  usage: {
+    invocation:
+      'node .agents/scripts/audit-to-stories.js (--scan | --auto | --emit-plan-seed | --emit-stories) [options]',
+    summary:
+      'Turn audit-lens findings under temp/audits/ into a dedup-checked plan seed or standalone Stories.',
+    flags: [
+      ['--scan', 'Print the grouped, deduplicated plan as JSON.'],
+      ['--auto', 'Run the full scan → file pipeline and print the summary.'],
+      ['--emit-plan-seed', 'Emit a /plan --seed-file document.'],
+      ['--emit-stories', 'Emit the Story drafts as JSON.'],
+      ['--glob <pattern>', 'Override the audit-results glob.'],
+      ['--severity <level>', 'Lowest severity to include (high|medium|low).'],
+      ['--ledger <path>', 'Path to the dedup ledger.'],
+      [
+        '--plan <path>',
+        'Read a previously emitted plan instead of re-scanning.',
+      ],
+      ['--out <path>', 'Write output to a file instead of stdout.'],
+      ['--no-provider', 'Skip live GitHub dedup lookups (offline).'],
+      ['--json', 'Force JSON output.'],
+      ['--dry-run', 'Report what would be filed; create nothing.'],
+    ],
+  },
+});

package/.agents/scripts/boot-sweep.js

@@ -212,4 +212,7 @@ async function main() {
   }
 }
 
-runAsCli(import.meta.url, main, { source: 'boot-sweep' });
+runAsCli(import.meta.url, main, {
+  source: 'boot-sweep',
+  usage: HELP,
+});

package/.agents/scripts/bootstrap.js

@@ -1467,4 +1467,5 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
 runAsCli(import.meta.url, main, {
   source: 'Bootstrap',
   propagateExitCode: true,
+  usage: HELP,
 });

package/.agents/scripts/check-arch-cycles.js

@@ -381,4 +381,24 @@ runAsCli(import.meta.url, main, {
   source: 'arch-cycles',
   propagateExitCode: true,
   errorPrefix: '[arch-cycles] ❌ Fatal error',
+  usage: {
+    invocation:
+      'node .agents/scripts/check-arch-cycles.js [--baseline <path>] [--root <dir>] [--json]',
+    summary:
+      'Ratchet on module-dependency cycles: compare the live import graph against the recorded baseline and fail on any newly added cycle.',
+    flags: [
+      [
+        '--baseline <path>',
+        'Baseline file (default: baselines/arch-cycles.json).',
+      ],
+      [
+        '--root <dir>',
+        'Scan a single root instead of the distributed surface.',
+      ],
+      ['--json', 'Emit the comparison envelope as JSON.'],
+    ],
+    notes: [
+      'Exit codes:\n  0  clean, or removals only\n  1  a new cycle was detected',
+    ],
+  },
 });

package/.agents/scripts/check-baselines.js

@@ -43,7 +43,10 @@ import {
   assertFloorAxesExist,
   compareToFloor,
 } from './lib/orchestration/check-baselines/phases/floors.js';
-import { parseArgs } from './lib/orchestration/check-baselines/phases/parse-args.js';
+import {
+  HELP_TEXT,
+  parseArgs,
+} from './lib/orchestration/check-baselines/phases/parse-args.js';
 import {
   runCheckBaselines,
   selectEnabledGates,
@@ -78,4 +81,7 @@ async function main() {
   process.exit(result.exitCode);
 }
 
-runAsCli(import.meta.url, main, { source: 'check-baselines' });
+runAsCli(import.meta.url, main, {
+  source: 'check-baselines',
+  usage: HELP_TEXT,
+});

package/.agents/scripts/check-context-budget.js

@@ -11,6 +11,13 @@
  *   - `alwaysLoaded`  — the `CLAUDE.md` `@`-import closure re-paid on every
  *                       session and every subagent spawn (instructions.md § 4).
  *   - `mandatoryRead` — the resolved `project.docsContextFiles` set.
+ *   - `workflow`      — the workflow **mandatory closure** (Story #4752): every
+ *                       `.agents/workflows/**` entry point plus the transitive
+ *                       closure of its `mandatoryReads:` frontmatter edges. The
+ *                       companion **reachable** closure (per entry point) is
+ *                       recorded under the top-level `workflowClosure` key as a
+ *                       drift signal and never gates — growth there is a
+ *                       reading-cost signal, not a contract violation.
  *
  * It additionally enforces a **per-file** ceiling on the role-scoped agent-boot
  * tier (`.agents/agents/*.md`, #4478): no single boot context may exceed
@@ -52,12 +59,12 @@ import { resolveConfig } from './lib/config-resolver.js';
 import { resolveDocTiers, tierTotalBytes } from './lib/doc-tiers.js';
 
 /**
- * The tiers this ratchet gates (in report order). `digestVisible` and
- * `onDemand` are resolved by the tier map for the lens, but the byte budget
- * intentionally gates only the two tiers the Epic AC names.
- * @type {Array<'alwaysLoaded' | 'mandatoryRead'>}
+ * The tiers this ratchet gates (in report order). `digestVisible`, `onDemand`
+ * and `workflowOnDemand` are resolved by the tier map for the lens, but the
+ * byte budget intentionally gates only the tiers a session is *forced* to read.
+ * @type {Array<'alwaysLoaded' | 'mandatoryRead' | 'workflow'>}
  */
-export const GATED_TIERS = ['alwaysLoaded', 'mandatoryRead'];
+export const GATED_TIERS = ['alwaysLoaded', 'mandatoryRead', 'workflow'];
 
 /**
  * Default tolerance (bytes) seeded into a fresh baseline by `--update` when the
@@ -171,6 +178,12 @@ export function buildBaseline(tierMap, toleranceBytes) {
       ceilingBytes: AGENT_BOOT_CEILING_BYTES,
       files: agentBootFiles,
     },
+    // Recorded, never gated (#4752): the total reachable closure per workflow
+    // entry point. It is a drift signal — the gate is `tiers.workflow`.
+    workflowClosure: {
+      reachableTotalBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
+      entryPoints: tierMap.workflowClosure?.entryPoints ?? [],
+    },
   };
 }
 
@@ -249,6 +262,25 @@ export function renderDiff(diff) {
   return lines.join('\n');
 }
 
+/**
+ * Render the workflow **reachable** closure line — recorded, never gated
+ * (Story #4752). Returns `''` when there is no workflow tier to report, so the
+ * caller can stay a one-liner.
+ *
+ * @param {{ workflowClosure?: { reachableTotalBytes?: number, entryPoints?: unknown[] } }} tierMap
+ * @param {{ workflowClosure?: { reachableTotalBytes?: number } } | null} [baseline]
+ * @returns {string}
+ */
+export function renderReachable(tierMap, baseline) {
+  const closure = tierMap?.workflowClosure;
+  const current = closure?.reachableTotalBytes ?? 0;
+  if (current <= 0) return '';
+  const recorded = baseline?.workflowClosure?.reachableTotalBytes;
+  const against = Number.isFinite(recorded) ? ` (recorded ${recorded})` : '';
+  const entries = closure.entryPoints?.length ?? 0;
+  return `  workflow reachable closure: ${current} bytes across ${entries} entry points${against} — drift signal, never gated`;
+}
+
 /**
  * Top-level CLI entry. Exported so tests can drive the full pipeline against a
  * tmpdir fixture with an injected config and sinks.
@@ -338,12 +370,15 @@ export async function runCli({
       skipped: diff.skipped,
       agentBootCeilingBytes: ceiling,
       agentBootOverflow: bootOverflow,
+      workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
       exitCode,
     };
     stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
   } else {
     stdout.write(`\n--- context-budget preview ---\n`);
     stdout.write(`${renderDiff(diff)}\n`);
+    const reachable = renderReachable(tierMap, baseline);
+    if (reachable) stdout.write(`${reachable}\n`);
     for (const o of bootOverflow) {
       stdout.write(
         `+ agentBoot: ${o.path} is ${o.bytes} bytes, over the ${o.ceiling}-byte per-agent ceiling\n`,

package/.agents/scripts/check-dead-exports.js

@@ -247,4 +247,25 @@ runAsCli(import.meta.url, main, {
   source: 'dead-exports',
   propagateExitCode: true,
   errorPrefix: '[dead-exports] ❌ Fatal error',
+  usage: {
+    invocation:
+      'node .agents/scripts/check-dead-exports.js [--production] [--baseline <path>] [--knip-output <path>] [--json]',
+    summary:
+      'Ratchet on unused exports reported by knip: fail when an export is added above the recorded baseline.',
+    flags: [
+      [
+        '--production',
+        'Score the production-only surface (separate baseline).',
+      ],
+      ['--baseline <path>', 'Baseline file (default: mode-specific).'],
+      [
+        '--knip-output <path>',
+        'Read a saved knip JSON envelope instead of running knip.',
+      ],
+      ['--json', 'Emit the comparison envelope as JSON.'],
+    ],
+    notes: [
+      'Exit codes:\n  0  clean, or removals only\n  1  newly added unused exports',
+    ],
+  },
 });

package/.agents/scripts/check-doc-links.js

@@ -423,4 +423,15 @@ async function main() {
   process.exit(1);
 }
 
-runAsCli(import.meta.url, main, { source: 'check-doc-links' });
+runAsCli(import.meta.url, main, {
+  source: 'check-doc-links',
+  usage: {
+    invocation: 'node .agents/scripts/check-doc-links.js',
+    summary:
+      'Validate every relative Markdown link and /slash-command token across docs/ and .agents/, and reject mentions of retired commands.',
+    flags: [],
+    notes: [
+      'Exit codes:\n  0  every link and command token resolves\n  1  at least one violation (file:line on stderr)',
+    ],
+  },
+});

package/.agents/scripts/check-lifecycle-doc-drift.js

@@ -399,4 +399,13 @@ async function main() {
 await runAsCli(import.meta.url, main, {
   source: 'check-lifecycle-doc-drift',
   propagateExitCode: true,
+  usage: {
+    invocation: 'node .agents/scripts/check-lifecycle-doc-drift.js',
+    summary:
+      "Fail when the listener-model table in docs/LIFECYCLE.md drifts from the lifecycle listeners' declared subscriptions.",
+    flags: [],
+    notes: [
+      'Exit codes:\n  0  doc and code agree\n  1  drift in either direction',
+    ],
+  },
 });