mandrel 2.36.0 → 2.38.0

package/.agents/rules/changelog-style.md

@@ -3,7 +3,7 @@
 This rule governs the shape of per-release entries in the project CHANGELOG
 (typically `docs/CHANGELOG.md` or `CHANGELOG.md`). It applies whenever a
 release entry is authored or edited — most commonly inside Story #N's
-docs sweep before `/deliver` opens the release PR.
+docs sweep before `/mandrel-deliver` opens the release PR.
 
 The contract is **guidance-tier**: no automated gate fails a close when an
 entry drifts off-template. It still binds every author.
@@ -152,12 +152,12 @@ worktree cleanup.
 - **Shared-store worktrees.** Per-story worktrees link a shared
   `node_modules` store, so parallel waves no longer duplicate installs
   or leave residue that blocks reap.
-- **`/deliver` auto-invokes pre-merge gates** (code review, retro)
+- **`/mandrel-deliver` auto-invokes pre-merge gates** (code review, retro)
   inline. `--skip-code-review` is available as an override.
 - **Closure sweep covers Epic Health tickets** in addition to PRD and
   Tech Spec tickets.
 - **Stale-lock sweep** on the shared `.git/` directory runs at
-  `/deliver` start, clearing lock files left behind by interrupted
+  `/mandrel-deliver` start, clearing lock files left behind by interrupted
   operations.
 ```
 

package/.agents/rules/ci-remediation.md

@@ -31,7 +31,7 @@ exactly one of two ways, and no others:
    delivery's scope — a pre-existing flaky test, a runner/infra weakness, a
    framework-level environment gap. Open the issue with the `meta::framework-gap`
    label (see [`git-conventions.md`](git-conventions.md)) carrying **the run
-   link and the failure signature** so a later `/plan` Phase 0 sweep can act on
+   link and the failure signature** so a later `/mandrel-plan` Phase 0 sweep can act on
    it. Remediate this delivery only if the pre-existing defect is genuinely
    blocking it.
 

package/.agents/rules/git-conventions-reference.md

@@ -95,7 +95,7 @@ signature is worth naming:
 **Invariant (stated in the core): the delivering flow owns tidying the local
 checkout — reaping its own merged refs and fast-forwarding the base branch.
 `/git-cleanup` is a recovery tool, not a routine chore.** The outcome every
-delivering flow (`/deliver`, `/git-deliver`) guarantees, with the mechanics
+delivering flow (`/mandrel-deliver`, `/git-deliver`) guarantees, with the mechanics
 owned by `boot-sweep.js` / `git-cleanup.js`:
 
 - **`main` is fast-forwarded** by the flow itself in its cleanup phase, so the
@@ -104,7 +104,7 @@ owned by `boot-sweep.js` / `git-cleanup.js`:
 - **Merged local refs are reaped** at the next workflow boot's protected sweep
   (`boot-sweep.js`) — every local branch whose PR is already merged, skipping
   any candidate with unpushed work, a dirty worktree, or a still-open parent
-  ticket. `/plan` and `/git-deliver` widen the sweep's `--include` scope beyond
+  ticket. `/mandrel-plan` and `/git-deliver` widen the sweep's `--include` scope beyond
   the default `story-*` to their own branch namespaces at their boot call site.
 - **Content-merged branches are report-only.** A branch detected only via the
   weaker content-equivalence signal (`detectedBy: 'content-merged'` — content
@@ -149,13 +149,13 @@ different hazards:
 - **Recognition signature**: close aborts naming stray files in the main
   checkout that intersect the Story's diff. **Resolution**: relocate those
   edits under the worktree, restore the main checkout
-  (`git -C <main-repo> checkout -- <files>`), then re-run `/deliver <storyId>`.
+  (`git -C <main-repo> checkout -- <files>`), then re-run `/mandrel-deliver <storyId>`.
   Never `git reset --hard` or `git checkout --force` to clear the way.
 
 ## Meta Labels (Retrospective Signal Routing)
 
 Two `meta::*` labels route retrospective signals into durable substrates so
-the `/plan` Phase 0 fetcher (see
+the `/mandrel-plan` Phase 0 fetcher (see
 [`prior-feedback-fetcher.js`](../scripts/lib/feedback-loop/prior-feedback-fetcher.js))
 can surface open feedback issues to the planner. Both labels live in
 [`label-constants.js`](../scripts/lib/label-constants.js) under the

package/.agents/rules/testing-standards.md

@@ -79,6 +79,13 @@ of the pyramid.
 - **Location.** `tests/features/**/*.feature` with step definitions in
   `tests/steps/**` (or the project's equivalent). The companion skill is
   [`stack/qa/playwright-bdd`](../skills/stack/qa/playwright-bdd/SKILL.md).
+- **Run tier.** This tier MUST NOT ride inside the default suite. It is slow
+  by construction — real installs, real browsers, real stacks — and the
+  default suite is what a pre-push hook and every local iteration pay for.
+  Give it its own runner tier and its own CI job, so its cost is charged to
+  the surface whose signal it is. In this repository that is `tests/e2e/**`,
+  the `e2e` tier (`npm run test:e2e`), and the per-PR `e2e` job; the coverage
+  run still measures those files, so nothing leaves the measured surface.
 
 ## Assertion Placement Rule {#assertion-placement}
 
@@ -236,3 +243,52 @@ Hypothesis keeps a failure DB, proptest writes `proptest-regressions/` — pin o
 commit whichever the stack provides. Once shrinking surfaces a minimal
 counterexample, **add it as an example-based regression test** alongside the
 property: the property guards the domain, the pinned example guards the bug.
+
+## The suite's child-process budget
+
+`npm test` forks one process per test file, and the spawns those leaves make
+dominate the suite's system time. Two instruments and one rule keep that
+budget visible and honest (Story #5121).
+
+### Measure it with `npm run test:census`
+
+```bash
+npm run test:census            # writes temp/census.json
+```
+
+`tests/fixtures/spawn-census.cjs` is a `--require` preload that counts every
+`child_process` call per binary, aggregates across all ~700 processes, and
+reports `nodeInSuite` (node children spawned *by test files*, excluding the
+runner's own fan-out), `git`, `gh`, `npm`, and any standalone
+`git config user.*` spawns. Read the numbers from the census rather than
+re-deriving them; two audits hand-rolled this measurement and lost it both
+times with the gitignored temp tree.
+
+The script interpolates `$PWD` deliberately. A **relative** `--require` path is
+inherited by children that run with a different `cwd`, where it fails to
+resolve and kills the child before it runs a line — measured as 15 spurious
+failures in one file.
+
+### Build a fixture repo once, then copy it
+
+A multi-commit fixture repo rebuilt in `beforeEach` is the costly shape. Build
+it once in `before()` and hand each test an `fs` copy via
+`copyGitRepo(pristine)` from `tests/fixtures/git-fixture.js`: each test still
+gets a private directory it may freely mutate, for **no subprocess at all**.
+One file went from 92 `git` spawns to 27 this way.
+
+`copyGitRepo` is safe only for a locally-`git init`ed repo, whose
+`.git/config` holds no absolute paths. Do **not** copy a **clone** (its
+`remote.origin.url` is absolute, so the copy would fetch from the original) or a
+linked worktree (its `gitdir:` / `commondir` pointers would dangle).
+
+### Never trade coverage for a spawn count
+
+Most of the suite's remaining `git` spawns are integration tests exercising
+real git against git-manipulating production code — the spawn **is** the
+subject under test, and so is a CLI's exit code in an exit-code contract test.
+Those are not fixture waste and must not be converted to in-process calls or
+mocks to make a number smaller. Hoist shared setup; leave the assertions alone.
+A spawn census also records argv, not what the binary resolved to: a
+`gh pr view 4890` line may well be a fake `gh` the test put on `PATH`, so
+verify resolution before calling a spawn a network call.

package/.agents/schemas/agentrc.schema.json

@@ -298,7 +298,7 @@
     },
     "planning": {
       "type": "object",
-      "description": "Inputs to `/plan`: risk escalation heuristics, ceremony-lite routing, and the cross-Story conflict-finding severity gates.",
+      "description": "Inputs to `/mandrel-plan`: risk escalation heuristics, ceremony-lite routing, and the cross-Story conflict-finding severity gates.",
       "properties": {
         "riskHeuristics": {
           "oneOf": [
@@ -440,7 +440,7 @@
     },
     "delivery": {
       "type": "object",
-      "description": "Everything `/deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, signals, quality gates, merge/CI watch, review ceremony, and the feedback loop.",
+      "description": "Everything `/mandrel-deliver` and `single-story-close` consume: execution timeouts, worktree isolation, runner concurrency, docs freshness, signals, quality gates, merge/CI watch, review ceremony, and the feedback loop.",
       "properties": {
         "execution": {
           "type": "object",
@@ -521,12 +521,12 @@
         },
         "deliverRunner": {
           "type": "object",
-          "description": "Bounded-concurrency knob for the /deliver fan-out.",
+          "description": "Bounded-concurrency knob for the /mandrel-deliver fan-out.",
           "properties": {
             "concurrencyCap": {
               "type": "integer",
               "minimum": 1,
-              "description": "Maximum ready Stories dispatched by /deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff.",
+              "description": "Maximum ready Stories dispatched by /mandrel-deliver at once. Default 3. Moderate by design — keeps host-quota consumption predictable while allowing a small ready-set fan-out. Set 1 for strictly sequential delivery; raise further on hosts with adequate parallel-agent quota. See deliver.md for the sequencing model and throughput tradeoff.",
               "default": 3
             },
             "footprintGuard": {
@@ -1628,7 +1628,7 @@
             },
             "navigability": {
               "type": "object",
-              "description": "Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /deliver's per-Story ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op.",
+              "description": "Navigability lens + journey-suite config (Epic #4131, F2/F3/F1/F4). Read by audit-suite/selector.js (route globs) and /mandrel-deliver's per-Story ceremony (journey suite). Opt-in: absent or empty routeGlobs degrades to a silent no-op.",
               "properties": {
                 "routeGlobs": {
                   "type": "array",
@@ -1648,7 +1648,7 @@
                 },
                 "journeySuite": {
                   "type": "string",
-                  "description": "Path or command for the per-persona journey suite /deliver's per-Story ceremony runs."
+                  "description": "Path or command for the per-persona journey suite /mandrel-deliver's per-Story ceremony runs."
                 }
               },
               "additionalProperties": false
@@ -1692,7 +1692,7 @@
         },
         "codeReview": {
           "type": "object",
-          "description": "Review-provider chain plus bounded-retry knobs for the /deliver code-review ceremony.",
+          "description": "Review-provider chain plus bounded-retry knobs for the /mandrel-deliver code-review ceremony.",
           "properties": {
             "providers": {
               "type": "array",
@@ -1780,7 +1780,7 @@
             "maxFixAttempts": {
               "type": "integer",
               "minimum": 0,
-              "description": "Maximum auto-fix retry attempts per finding in /deliver Phase 5 (code-review). 0 disables auto-fix. Default 3.",
+              "description": "Maximum auto-fix retry attempts per finding in /mandrel-deliver Phase 5 (code-review). 0 disables auto-fix. Default 3.",
               "default": 3
             },
             "maxFixScopeFiles": {
@@ -1792,7 +1792,7 @@
             "autoFixSeverity": {
               "type": "string",
               "enum": ["high", "medium"],
-              "description": "Severity threshold for on-branch remediation in /deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag.",
+              "description": "Severity threshold for on-branch remediation in /mandrel-deliver Phase 5 (code-review). `medium` (default) routes 🔴/🟠/🟡 findings into the host-LLM focused-fix routing (Mediums batched per lens: one commit per lens, a single validation + rescan at the end) while 🟢 suggestions still graduate to follow-up issues; `high` reproduces the pre-4399 Critical/High-only routing. Hard cutover — no back-compat flag.",
               "default": "medium"
             }
           },

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

@@ -21,7 +21,7 @@
     },
     "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. 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.",
+      "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 /mandrel-plan invocation that owns the work instead.",
       "enum": ["landed", "pending", "blocked", "failed", "escalated"]
     },
     "phase": {
@@ -173,7 +173,7 @@
     },
     "nextCommand": {
       "type": ["string", "null"],
-      "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.",
+      "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 /mandrel-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 },

package/.agents/schemas/validation-evidence.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "validation-evidence",
   "title": "Validation Evidence",
-  "description": "Per-scope record of which validation gates have passed against which commit SHA. Written by lib/validation-evidence.js under the per-Epic temp tree at temp/run-<id>/validation-evidence.json (Epic-scoped) or temp/run-<id>/stories/story-<storyId>/validation-evidence.json (Story-scoped). Standalone Stories (no parent Epic) use a storyId-anchored keyspace at temp/standalone/stories/story-<storyId>/validation-evidence.json. All paths are gitignored via temp/. Consumed by close-validation, epic-code-review, the acceptance self-eval critic, and /deliver Phase 3 (close-validation) to skip identical re-runs against an already-validated tree. The `storyId` field carries the scope id and equals the epic id for Epic-scoped records.",
+  "description": "Per-scope record of which validation gates have passed against which commit SHA. Written by lib/validation-evidence.js under the per-Epic temp tree at temp/run-<id>/validation-evidence.json (Epic-scoped) or temp/run-<id>/stories/story-<storyId>/validation-evidence.json (Story-scoped). Standalone Stories (no parent Epic) use a storyId-anchored keyspace at temp/standalone/stories/story-<storyId>/validation-evidence.json. All paths are gitignored via temp/. Consumed by close-validation, epic-code-review, the acceptance self-eval critic, and /mandrel-deliver Phase 3 (close-validation) to skip identical re-runs against an already-validated tree. The `storyId` field carries the scope id and equals the epic id for Epic-scoped records.",
   "type": "object",
   "required": ["storyId", "schemaVersion", "records"],
   "properties": {

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

@@ -20,7 +20,7 @@
  *      and the resolved, undisableable round cap
  *      (`delivery.acceptanceEval.maxRounds`, clamped to `[1, ceiling]`).
  *   3. Emit one per-criterion `acceptance-eval` signal into the retro /
- *      feedback substrate so the retro and `/plan` Phase 0 feedback
+ *      feedback substrate so the retro and `/mandrel-plan` Phase 0 feedback
  *      fetch can see which acceptance items needed rework and the round
  *      count.
  *   4. Print a single JSON envelope and exit:

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

@@ -20,7 +20,7 @@
  *
  * Story #5007 retired the second step. `migrateBaselinesLayout` relocated
  * per-Epic ratchet snapshots into `temp/epic/<id>/baselines/` on the contract
- * that `/deliver` reaps that namespace on merge — a mechanism the Story-only
+ * that `/mandrel-deliver` reaps that namespace on merge — a mechanism the Story-only
  * v2 model deleted, so the migration moved dead data into a namespace no code
  * path writes, reads, or reaps. Its one residual hygiene value (getting the
  * committed `baselines/epic/` tree out of version control) survives as

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

@@ -13,7 +13,7 @@
  *     stdout when --json is set).
  *
  *   --emit-plan-seed --plan <plan.json> --out <path>
- *     Read the plan envelope from disk, render the `/plan --seed`
+ *     Read the plan envelope from disk, render the `/mandrel-plan --seed`
  *     seed markdown, persist to --out.
  *
  *   --emit-stories --plan <plan.json>
@@ -844,7 +844,7 @@ runAsCli(import.meta.url, main, {
     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-plan-seed', 'Emit a /mandrel-plan --seed-file document.'],
       ['--emit-stories', 'Emit the Story drafts as JSON.'],
       [
         '--wire-edges',

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

@@ -45,6 +45,7 @@ import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 import { createProvider } from './lib/provider-factory.js';
 import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
+import { resolveSweepLockPath } from './lib/single-story-sweep/sweep-lock.js';
 import { sweepMergedBranches } from './lib/single-story-sweep.js';
 import { sweepTempRetention } from './lib/temp-retention.js';
 
@@ -141,8 +142,13 @@ export async function runBootSweep({
       excludeGlobs.push(current);
     }
 
+    // Story #5112 — one critical section, one lock. `single-story-init.js`
+    // reaps the same merged `story-*` branches through the same engine; when
+    // the two surfaces held differently named lockfiles they could run
+    // concurrently, each deleting branches the other had already planned.
+    // Both now resolve the path through `resolveSweepLockPath`.
     const tempRoot = config?.project?.paths?.tempRoot ?? 'temp';
-    const lockPath = path.resolve(root, tempRoot, 'boot-sweep.lock');
+    const lockPath = resolveSweepLockPath({ cwd: root, tempRoot });
     const lockTimeoutMs =
       config.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
 

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

@@ -481,6 +481,179 @@ export function renderReachable(tierMap, baseline) {
  * @returns {Promise<number>} 0 = clean / within tolerance / shrink-only / no-op;
  *   1 = a gated tier grew beyond tolerance
  */
+/**
+ * Write a fresh budget, preserving the recorded tolerance so `--update` never
+ * silently widens the gate it is refreshing.
+ *
+ * @param {object} params
+ * @returns {0}
+ */
+function writeUpdatedBaseline({ tierMap, resolvedBaselinePath, json, stdout }) {
+  const existing = loadBaseline(resolvedBaselinePath);
+  const tolerance = Number.isFinite(existing?.toleranceBytes)
+    ? existing.toleranceBytes
+    : DEFAULT_TOLERANCE_BYTES;
+  const envelope = buildBaseline(tierMap, tolerance);
+  fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
+  fs.writeFileSync(
+    resolvedBaselinePath,
+    `${JSON.stringify(envelope, null, 2)}\n`,
+  );
+  if (!json) {
+    stdout.write(
+      `[context-budget] wrote baseline ${resolvedBaselinePath} (tolerance ${tolerance} bytes)\n`,
+    );
+  } else {
+    stdout.write(
+      `${JSON.stringify({ kind: 'context-budget-update', baselinePath: resolvedBaselinePath, envelope }, null, 2)}\n`,
+    );
+  }
+  return 0;
+}
+
+/**
+ * An absent budget is a no-op, not a failure: a consumer that has never
+ * recorded one has nothing to regress against.
+ *
+ * @param {object} params
+ * @returns {0}
+ */
+function reportMissingBaseline({
+  tierMap,
+  resolvedBaselinePath,
+  json,
+  stdout,
+  stderr,
+}) {
+  if (json) {
+    stdout.write(
+      `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], absent: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
+    );
+  } else {
+    stderr.write(
+      `[context-budget] ⚠ budget not found at ${resolvedBaselinePath} — skipping (no-op)\n`,
+    );
+  }
+  return 0;
+}
+
+/**
+ * Score the tree against the recorded budget. Pure — every verdict the two
+ * renderers below present is decided here, so they cannot disagree about what
+ * failed or drift apart in which fields they surface.
+ *
+ * @param {{ tierMap: object, baseline: object }} params
+ * @returns {{ diff: object, ceiling: number, bootOverflow: object[], bootDrift: object[], permissiveDrift: object[], exitCode: 0 | 1 }}
+ */
+function evaluateBudget({ tierMap, baseline }) {
+  const diff = diffBudget(tierMap, baseline);
+  const ceiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
+    ? baseline.agentBoot.ceilingBytes
+    : AGENT_BOOT_CEILING_BYTES;
+  const bootOverflow = agentBootOverflow(tierMap, ceiling);
+  const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
+  const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
+  const exitCode =
+    budgetFailureCount(diff) > 0 ||
+    bootOverflow.length > 0 ||
+    permissiveDrift.length > 0
+      ? 1
+      : 0;
+  return { diff, ceiling, bootOverflow, bootDrift, permissiveDrift, exitCode };
+}
+
+/**
+ * @param {object} params
+ * @returns {void}
+ */
+function renderJsonReport({
+  tierMap,
+  baseline,
+  resolvedBaselinePath,
+  report,
+  stdout,
+}) {
+  const { diff, ceiling, bootOverflow, bootDrift, exitCode } = report;
+  const envelope = {
+    kind: 'context-budget-report',
+    baselinePath: resolvedBaselinePath,
+    toleranceBytes: Number.isFinite(baseline.toleranceBytes)
+      ? baseline.toleranceBytes
+      : 0,
+    current: Object.fromEntries(
+      GATED_TIERS.map((t) => [t, tierTotalBytes(tierMap.tiers[t] ?? [])]),
+    ),
+    grown: diff.grown,
+    shrunk: diff.shrunk,
+    absent: diff.absent,
+    skipped: diff.skipped,
+    agentBootCeilingBytes: ceiling,
+    agentBootOverflow: bootOverflow,
+    agentBootDrift: bootDrift,
+    workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
+    exitCode,
+  };
+  stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+}
+
+/**
+ * Each failing condition gets its own remediation line: they are fixed
+ * differently (trim a role def vs refresh the budget), so a single generic
+ * message would leave the author guessing which applies.
+ *
+ * @param {object} params
+ * @returns {void}
+ */
+function renderFailureDiagnostics({ report, stderr }) {
+  const { diff, ceiling, bootOverflow, permissiveDrift } = report;
+  if (permissiveDrift.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a recorded agentBoot row understates the file it describes, so it overstates the headroom an author would size an edit against — refresh it with \`node .agents/scripts/check-context-budget.js --update\` (the ceiling is unchanged)\n`,
+    );
+  }
+  if (bootOverflow.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,
+    );
+  }
+  if (diff.grown.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
+    );
+  }
+  if (diff.shrunk.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+    );
+  }
+  if (diff.absent.length > 0) {
+    stderr.write(
+      `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+    );
+  }
+}
+
+/**
+ * @param {object} params
+ * @returns {void}
+ */
+function renderTextReport({ tierMap, baseline, report, stdout, stderr }) {
+  const { diff, bootOverflow, bootDrift, exitCode } = report;
+  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`,
+    );
+  }
+  for (const line of renderBootDrift(bootDrift)) {
+    stdout.write(`${line}\n`);
+  }
+  if (exitCode === 1) renderFailureDiagnostics({ report, stderr });
+}
+
 export async function runCli({
   argv = process.argv.slice(2),
   cwd = process.cwd(),
@@ -498,120 +671,39 @@ export async function runCli({
   const tierMap = resolveDocTiers(resolvedConfig, { root });
 
   if (update) {
-    const existing = loadBaseline(resolvedBaselinePath);
-    const tolerance = Number.isFinite(existing?.toleranceBytes)
-      ? existing.toleranceBytes
-      : DEFAULT_TOLERANCE_BYTES;
-    const envelope = buildBaseline(tierMap, tolerance);
-    fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
-    fs.writeFileSync(
+    return writeUpdatedBaseline({
+      tierMap,
       resolvedBaselinePath,
-      `${JSON.stringify(envelope, null, 2)}\n`,
-    );
-    if (!json) {
-      stdout.write(
-        `[context-budget] wrote baseline ${resolvedBaselinePath} (tolerance ${tolerance} bytes)\n`,
-      );
-    } else {
-      stdout.write(
-        `${JSON.stringify({ kind: 'context-budget-update', baselinePath: resolvedBaselinePath, envelope }, null, 2)}\n`,
-      );
-    }
-    return 0;
+      json,
+      stdout,
+    });
   }
 
   const baseline = loadBaseline(resolvedBaselinePath);
   if (!baseline) {
-    if (json) {
-      stdout.write(
-        `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], absent: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
-      );
-    } else {
-      stderr.write(
-        `[context-budget] ⚠ budget not found at ${resolvedBaselinePath} — skipping (no-op)\n`,
-      );
-    }
-    return 0;
+    return reportMissingBaseline({
+      tierMap,
+      resolvedBaselinePath,
+      json,
+      stdout,
+      stderr,
+    });
   }
 
-  const diff = diffBudget(tierMap, baseline);
-  const ceiling = Number.isFinite(baseline?.agentBoot?.ceilingBytes)
-    ? baseline.agentBoot.ceilingBytes
-    : AGENT_BOOT_CEILING_BYTES;
-  const bootOverflow = agentBootOverflow(tierMap, ceiling);
-  const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
-  const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
-  const exitCode =
-    budgetFailureCount(diff) > 0 ||
-    bootOverflow.length > 0 ||
-    permissiveDrift.length > 0
-      ? 1
-      : 0;
-
+  const report = evaluateBudget({ tierMap, baseline });
   if (json) {
-    const envelope = {
-      kind: 'context-budget-report',
-      baselinePath: resolvedBaselinePath,
-      toleranceBytes: Number.isFinite(baseline.toleranceBytes)
-        ? baseline.toleranceBytes
-        : 0,
-      current: Object.fromEntries(
-        GATED_TIERS.map((t) => [t, tierTotalBytes(tierMap.tiers[t] ?? [])]),
-      ),
-      grown: diff.grown,
-      shrunk: diff.shrunk,
-      absent: diff.absent,
-      skipped: diff.skipped,
-      agentBootCeilingBytes: ceiling,
-      agentBootOverflow: bootOverflow,
-      agentBootDrift: bootDrift,
-      workflowReachableBytes: tierMap.workflowClosure?.reachableTotalBytes ?? 0,
-      exitCode,
-    };
-    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+    renderJsonReport({
+      tierMap,
+      baseline,
+      resolvedBaselinePath,
+      report,
+      stdout,
+    });
   } 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`,
-      );
-    }
-    for (const line of renderBootDrift(bootDrift)) {
-      stdout.write(`${line}\n`);
-    }
-    if (exitCode === 1) {
-      if (permissiveDrift.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a recorded agentBoot row understates the file it describes, so it overstates the headroom an author would size an edit against — refresh it with \`node .agents/scripts/check-context-budget.js --update\` (the ceiling is unchanged)\n`,
-        );
-      }
-      if (bootOverflow.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a role-agent boot context exceeds the ${ceiling}-byte per-agent ceiling — trim the role def (the ceiling is a hard cap, not a starve target)\n`,
-        );
-      }
-      if (diff.grown.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
-        );
-      }
-      if (diff.shrunk.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
-        );
-      }
-      if (diff.absent.length > 0) {
-        stderr.write(
-          `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,
-        );
-      }
-    }
+    renderTextReport({ tierMap, baseline, report, stdout, stderr });
   }
 
-  return exitCode;
+  return report.exitCode;
 }
 
 async function main() {