mandrel 2.111.0 → 2.112.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (178) hide show
  1. package/.agents/agents/acceptance-critic.md +14 -0
  2. package/.agents/agents/auditor.md +14 -0
  3. package/.agents/agents/plan-critic.md +5 -0
  4. package/.agents/agents/story-worker.md +4 -1
  5. package/.agents/docs/agentrc-reference.json +22 -10
  6. package/.agents/docs/configuration.md +351 -37
  7. package/.agents/docs/execution-reference.md +11 -0
  8. package/.agents/rules/git-conventions-reference.md +7 -0
  9. package/.agents/schemas/agentrc.schema.json +174 -14
  10. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  11. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  12. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  13. package/.agents/schemas/baselines/crap.schema.json +37 -10
  14. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  15. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  16. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  17. package/.agents/schemas/crap-report.schema.json +6 -5
  18. package/.agents/schemas/story-deliver-terminal.schema.json +41 -2
  19. package/.agents/schemas/story-progress.schema.json +1 -1
  20. package/.agents/schemas/validation-evidence.schema.json +2 -2
  21. package/.agents/scripts/boot-sweep.js +41 -3
  22. package/.agents/scripts/coverage-capture.js +37 -3
  23. package/.agents/scripts/coverage-ratchet.js +106 -0
  24. package/.agents/scripts/evidence-gate.js +84 -21
  25. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  26. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  27. package/.agents/scripts/lib/baseline-loader.js +4 -2
  28. package/.agents/scripts/lib/baselines/codec.js +57 -0
  29. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  32. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  33. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  34. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  35. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  36. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  37. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  38. package/.agents/scripts/lib/baselines/reader.js +36 -9
  39. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  40. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  41. package/.agents/scripts/lib/baselines/writer.js +36 -21
  42. package/.agents/scripts/lib/changed-files.js +70 -6
  43. package/.agents/scripts/lib/child-exec.js +10 -0
  44. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  45. package/.agents/scripts/lib/close-lock-events.js +8 -3
  46. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  47. package/.agents/scripts/lib/close-validation/gates.js +111 -35
  48. package/.agents/scripts/lib/close-validation/process.js +16 -7
  49. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  50. package/.agents/scripts/lib/close-validation/runner.js +55 -23
  51. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  52. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  53. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  54. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  55. package/.agents/scripts/lib/config/explain.js +5 -2
  56. package/.agents/scripts/lib/config/gates/coverage.schema.js +45 -1
  57. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  58. package/.agents/scripts/lib/config/git-roots.js +38 -4
  59. package/.agents/scripts/lib/config/handoff.js +24 -0
  60. package/.agents/scripts/lib/config/quality.js +26 -13
  61. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  62. package/.agents/scripts/lib/config-resolver.js +22 -2
  63. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  64. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  65. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  67. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  68. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  69. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  70. package/.agents/scripts/lib/coverage-capture.js +15 -0
  71. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  72. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  73. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  74. package/.agents/scripts/lib/crap-engine.js +3 -3
  75. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  76. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  77. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  78. package/.agents/scripts/lib/failure-rows.js +121 -0
  79. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  80. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  81. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  82. package/.agents/scripts/lib/gh-env.js +3 -6
  83. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  84. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  85. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  86. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  87. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  88. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  89. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  90. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  91. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  92. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  93. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  94. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  95. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  96. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  97. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  98. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  99. package/.agents/scripts/lib/orchestration/handoff-gates.js +129 -62
  100. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  101. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  102. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  103. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  104. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  105. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  106. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  107. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  108. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  109. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  110. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  111. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  112. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  113. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  114. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  115. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  116. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  117. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  118. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  119. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +15 -3
  120. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  121. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +6 -0
  122. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  123. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  124. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +9 -12
  125. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +26 -12
  126. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  127. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -2
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +50 -17
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  135. package/.agents/scripts/lib/orchestration/single-story-close/result.js +30 -13
  136. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  137. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -3
  138. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  139. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  140. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  141. package/.agents/scripts/lib/orchestration/story-handoff.js +774 -196
  142. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  143. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  144. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  145. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  146. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  147. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  148. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  149. package/.agents/scripts/lib/suite-admission.js +20 -8
  150. package/.agents/scripts/lib/suite-sizing.js +146 -0
  151. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  152. package/.agents/scripts/merge-baseline.js +14 -3
  153. package/.agents/scripts/providers/github/comments.js +19 -3
  154. package/.agents/scripts/providers/github.js +1 -0
  155. package/.agents/scripts/review-dispositions-report.js +1 -1
  156. package/.agents/scripts/role-scope-guard.js +267 -0
  157. package/.agents/scripts/single-story-close.js +4 -4
  158. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  159. package/.agents/scripts/single-story-init.js +24 -4
  160. package/.agents/scripts/story-handoff.js +3 -3
  161. package/.agents/scripts/story-outcomes-report.js +231 -0
  162. package/.agents/scripts/story-review-compute.js +9 -5
  163. package/.agents/scripts/update-coverage-baseline.js +12 -2
  164. package/.agents/scripts/update-crap-baseline.js +9 -1
  165. package/.agents/workflows/helpers/code-review.md +63 -9
  166. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  167. package/.agents/workflows/helpers/deliver-reference.md +233 -67
  168. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  169. package/.agents/workflows/helpers/deliver-story.md +7 -2
  170. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  171. package/docs/CHANGELOG.md +46 -0
  172. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  173. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  174. package/lib/cli/doctor-checks/llm-review.js +2 -11
  175. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  176. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  177. package/lib/cli/registry.js +5 -0
  178. package/package.json +1 -1
@@ -86,7 +86,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
86
86
  | `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
87
87
  | `commands` | No | `object` | — | Shell commands the close-validation chain spawns, each run from the repo root. One tri-state per key: absent uses the default shown; an explicit `null` disables an optional gate (`typecheck`, `lint`, `formatCheck`) — close reports it as skipped (`<gate>-disabled`) and runs nothing; a string is that command. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-tool pair in one script and name that. |
88
88
  | `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`). Mandatory: `null` is rejected. |
89
- | `commands.testChanged` | No | `string` \| `null` | — | Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files, or no incoming path is a suite input. The overlap rule ignores baseline (`baselines/`) and coverage-directory paths. Absent or `null` keeps the full re-run. |
89
+ | `commands.testChanged` | No | `string` \| `null` | — | Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files, or no incoming path is a suite input. The overlap rule ignores baseline (`baselines/`) and coverage-directory paths, and paths matching `delivery.quality.gates.coverage.nonInputGlobs`; those globs never change the incoming count or the emptiness rule, and a config file refuses under either value of `captureHandlesConfigChanges`. It is also the skip-branch first-credit depositor: when coverage-capture is active but takes its incremental skip (no changed file under `crap.targetDirs`), handoff and close run it keyed on the `origin/<baseBranch>` merge-base, credited as the full suite. It MUST therefore select any test that reads a non-module input by path (a docs registry, a fixture file) — `--changed` cannot see that edge, so a break only such a test catches surfaces only where the full suite runs later. Prefer reading `MANDREL_CHANGED_SINCE` from the env over the argv token, so the spawned argv stays constant and declarable in `delivery.execution.workloads[]`. Absent or `null` keeps the full re-run and the full skip-branch suite. |
90
90
  | `commands.typecheck` | No | `string` \| `null` | `"npm run typecheck"` | Static type-check command run as a close-validation gate. An explicit `null` disables the gate for projects with no type layer (skip reason `typecheck-disabled`). The empty string is rejected so a typo cannot silently disable it. |
91
91
  | `commands.lint` | No | `string` \| `null` | `"npm run lint"` | Lint command run as a close-validation gate and by the handoff preflight. An explicit `null` disables both (skip reason `lint-disabled`). Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. |
92
92
  | `commands.formatCheck` | No | `string` \| `null` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. An explicit `null` disables the gate (skip reason `format-disabled`). |
@@ -144,8 +144,9 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
144
144
  | --- | --- | --- | --- | --- |
145
145
  | `execution` | No | `object` | — | Serialization and capacity admission of the suite spawns delivery drives. |
146
146
  | `execution.fullSuiteLock` | No | `boolean` | `true` | Serialize full-suite spawns (`npm test` / the coverage gate's `captureScript`) behind a repository-level advisory lock shared by every worktree, so two concurrent deliveries do not run two suites against the same cores (see `capacity` / `workloads` for declared runs that may overlap). The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable. |
147
- | `execution.capacity` | No | `integer` | — | Story #5668. The admission budget, in weight units (CPU workers), shared by every suite spawn across this repository's worktrees and sessions — runs in other repositories on the host are not counted. Unset → the host's `os.availableParallelism()`. A declared workload is admitted while the live weights plus its own fit, strictly first-in-first-out: nothing overtakes an earlier live waiter, so a queued full suite is never starved. |
148
- | `execution.workloads[]` | No | `array<object>` | `[]` | Story #5668. Suite commands declared safe to run alongside others. A spawn whose argv (whitespace-normalized) EXACTLY equals `command` takes that `weight` and `resources`; anything else — and every spawn when this list is empty, the default — runs exclusively (full capacity, today's serialization). Isolation is never inferred from a flag, prefix or diff size. `weight` must count the run's nested worker pool (`--workers 4` → 4), and a full suite needs its own entry before anything can overlap it. Two runs naming a common `resources` entry (a database fixture, a shared coverage file) never overlap; worktree-local outputs need none. A weight above `capacity` refuses the run with exit 78 — nothing spawns, no credit is recorded. An expired wait still exits 75, resumably. Scheduling never changes a run's credit identity. `MANDREL_FULL_SUITE_LOCK=0` (one invocation) or `fullSuiteLock: false` turns admission off entirely; reach for the env hatch only when you have checked the runs share nothing. Each item has: command, weight, resources. |
147
+ | `execution.capacity` | No | `integer` | — | Story #5668. The admission budget, in weight units (CPU workers), shared by every suite spawn across this repository's worktrees and sessions — runs in other repositories on the host are not counted. Unset → the host's `os.availableParallelism()`. A declared workload is admitted while the live weights plus its own fit, first-in-first-out: nothing overtakes an earlier live waiter, so a queued full suite is never starved — except a `workloads[].backfill` run, which may pass earlier declared waiters it fits beside, only while the oldest has waited under 300 s. |
148
+ | `execution.workloads[]` | No | `array<object>` | `[]` | Story #5668. Suite commands declared safe to run alongside others. A spawn whose argv (whitespace-normalized) EXACTLY equals `command` takes that `weight` and `resources`; anything else — and every spawn when this list is empty, the default — runs exclusively (full capacity, today's serialization). Isolation is never inferred from a flag or prefix; a weight comes from the entry, or from its `tiers` as sized by its own `sizeCommand`. `weight` must count the run's nested worker pool (`--workers 4` → 4), and a full suite needs its own entry before anything can overlap it. Two runs naming a common `resources` entry (a database fixture, a shared coverage file) never overlap; worktree-local outputs need none. A weight above `capacity` refuses the run with exit 78 — nothing spawns, no credit is recorded. An expired wait still exits 75, resumably. Scheduling never changes a run's credit identity. `MANDREL_FULL_SUITE_LOCK=0` (one invocation) or `fullSuiteLock: false` turns admission off entirely; reach for the env hatch only when you have checked the runs share nothing. Each item has: command, weight, resources, tiers, sizeCommand, backfill. |
149
+ | `execution.preflightConcurrency` | No | `integer` | `1` | Story #5997. The most handoff preflight checks that may run at once. `1` (the default) is the serial preflight. Above 1, typecheck, lint and format (close's independent gates) may also run in up to N − 1 extra lanes, each admitted through suite admission with no wait under close's argv for that gate; a miss hands the check back to the serial lane. Set it per host in `.agentrc.local.json`: whether a host can afford a second CPU-heavy check is a per-host fact. |
149
150
  | `docsFreshness` | No | `object` | — | Documentation-freshness scope: the files a change of consequence is expected to touch. Read by the audit-documentation lens to seed its target set; no delivery gate enforces it. |
150
151
  | `docsFreshness.paths` | No | `array<string>` | `["README.md"]` | Repo-relative documentation paths the audit-documentation lens adds to its target set. |
151
152
  | `tempRetention` | No | `object` | — | Story #4794. Auto-purge of spent temp artifacts once their Story lands. Classification is an allowlist: only the declared classes below are ever deleted, so unrecognized files under tempRoot are reported with their size and left alone (`/clean-temp` is the operator path for them). signals.ndjson is never purged by any path. |
@@ -166,7 +167,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
166
167
  | `worktreeIsolation.primeFromPath` | No | `string` \| `null` | `null` | Absolute path to an existing `node_modules` tree to prime new worktrees from, instead of the main checkout. `null` uses the main checkout. |
167
168
  | `worktreeIsolation.allowSymlinkOnWindows` | No | `boolean` | `false` | Permit the `symlink` strategy on win32, where it needs Developer Mode or elevation. Off by default so a Windows consumer fails over to a strategy that works. |
168
169
  | `worktreeIsolation.reapOnSuccess` | No | `boolean` | `true` | Remove the Story's worktree once its PR merges. False keeps it for post-mortem inspection. |
169
- | `worktreeIsolation.bootstrapFiles` | No | `array<string>` | `[".env",".mcp.json",".agentrc.local.json",".agents/instructions.local.md"]` | Gitignored files copied from the main checkout into every new worktree. A worktree checks out tracked files only, so local secrets and overrides would otherwise be missing. |
170
+ | `worktreeIsolation.bootstrapFiles` | No | `array<string>` | `[".env",".mcp.json",".agents/instructions.local.md"]` | Gitignored files copied from the main checkout into every new worktree. A worktree checks out tracked files only, so local secrets would otherwise be missing. `.agentrc.local.json` is not copied by default: a worktree reads the main checkout's live overlay. |
170
171
  | `quality` | No | `object` | — | Quality-gate configuration. Every gate lives under `gates.<tier>` and shares the same `{ enabled, baselinePath, tolerance, floors, components }` base. |
171
172
  | `quality.gates` | No | `object` | — | The six quality gates, each sharing the `{ enabled, baselinePath, tolerance, floors, components }` base. |
172
173
  | `quality.gates.coverage` | No | `object` | — | Line/branch/function coverage ratchet, read from the Istanbul JSON summary the project test run emits. |
@@ -181,7 +182,12 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
181
182
  | `quality.gates.coverage.captureScript` | No | `string` | `"test:coverage"` | `package.json` script (never a shell command) the coverage gate's capture runs, spawned as `<pm> run <script>` under the detected package manager (npm, pnpm, yarn or bun). Close registers the coverage-capture gate when the coverage or CRAP gate is enabled and this script exists; the full-suite lock's workload identity and `mandrel doctor`'s `test-credit-path` check follow it. Default `test:coverage`. |
182
183
  | `quality.gates.coverage.captureScope` | No | `"full"` \| `"affected"` | `"full"` | What coverage-capture runs. `full` (default) runs `captureScript`. `affected` runs the consumer-owned `test:coverage:affected` script with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite. |
183
184
  | `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure. |
184
- | `quality.gates.coverage.onOverBudget` | No | `"block"` \| `"defer-to-ci"` | `"block"` | What handoff and close do when the capture script exits 76 — the consumer-declared signal that the selected slice is over this host's budget and no test ran. `block` (default) stops the handoff (`blocked`) and fails close, naming this key. `defer-to-ci` settles the coverage gate as deferred to CI: no artifact is written or stamped and no credit is recorded, the coverage-reading gates (CRAP preview, coverage and CRAP baselines) are skipped, and handoff and close proceed — the terminal envelope and the PR body say coverage was deferred. Set it only when the consumer's CI runs the deferred suite with a coverage floor. A timeout (124) is never deferred, under either value. |
185
+ | `quality.gates.coverage.onOverBudget` | No | `"block"` \| `"defer-to-ci"` | `"block"` | What handoff and close do when the capture script — or the `test` command (`project.commands.test`, or `testChanged` on the skip branch and the delta re-credit) — exits 76: the consumer-declared signal that the selected slice is over this host's budget and no test ran. `block` (default) stops the handoff (`blocked`) and fails close, naming this key. `defer-to-ci` settles the coverage gate as deferred to CI: no artifact is written or stamped and no credit is recorded, the coverage-reading gates (CRAP preview, coverage and CRAP baselines) are skipped, and handoff and close proceed — the terminal envelope and the PR body say coverage was deferred. Set it only when the consumer's CI runs the deferred suite with a coverage floor. A timeout (124) is never deferred, under either value. |
186
+ | `quality.gates.coverage.suiteOfRecord` | No | `"local"` \| `"ci"` | `"local"` | Where the coverage capture runs. `local` (default) changes nothing. `ci` — meant for a small host's `.agentrc.local.json` — makes CI the coverage and CRAP ratchet of record: handoff and close settle the coverage gate as deferred (reason `suite-of-record-ci`) without spawning the capture, the PR body carries the `Coverage-deferred:` key line, and confirm-merge waits for `ciRatchetCheck` to go green. Requires `ciRatchetCheck`; without it handoff blocks and close fails. |
187
+ | `quality.gates.coverage.ciRatchetCheck` | No | `string` \| `null` | `null` | Name of the consumer's CI check (check-run or status context) that runs `coverage-ratchet.js` on a deferred PR. Required by `suiteOfRecord: ci`; when set, confirm-merge holds `agent::done` on a PR carrying the `Coverage-deferred:` key line until this check is green on the PR head. Default `null`. |
188
+ | `quality.gates.coverage.nonInputGlobs` | No | `array<string>` | `[]` | Repo-relative picomatch globs naming paths no test reads. A matching path is dropped from both sides of the coverage delta-refresh overlap check and from the re-measured set — a delta of only matching, baseline and coverage-directory paths restamps without a run — and from the overlap check of close's `test` delta re-credit (its incoming count and emptiness test are unchanged). It never changes the suite-input filter, the tree digest or stamp freshness. Default `[]`: nothing is built in, so Markdown counts as an input unless declared here. |
189
+ | `quality.gates.coverage.captureHandlesConfigChanges` | No | `boolean` | `false` | Declares that the affected capture script, given `MANDREL_COVERAGE_BASE_REF`, widens its own selection when a coverage-determining config file (`package.json`, a lockfile, `tsconfig*.json`, a test-runner config) changes. When `true`, such a file in the coverage delta no longer refuses the delta refresh. Close's `test` delta re-credit refuses on a config file under either value. Default `false`. |
190
+ | `quality.gates.coverage.ownFixDeltaMaxFiles` | No | `integer` | `0` | Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no net line removal in a test file. Rows outside the delta can go stale high; validate against full captures before raising it. `10` is a reasonable start. |
185
191
  | `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
186
192
  | `quality.gates.crap.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
187
193
  | `quality.gates.crap.baselinePath` | No | `string` | `"baselines/crap.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
@@ -198,7 +204,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
198
204
  | `quality.gates.crap.incrementalCoverage` | No | `object` | — | The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full run of the coverage gate's `captureScript` (Story #5065). |
199
205
  | `quality.gates.crap.incrementalCoverage.skipWhenUnchanged` | No | `boolean` | `true` | Skip the capture entirely when no changed file under `crap.targetDirs` versus `baseRef` was touched. The only measured saving, and gate-semantics-neutral. Defaults to true. |
200
206
  | `quality.gates.crap.incrementalCoverage.baselineJoin` | No | `boolean` | `false` | Let the CRAP join resolve a method in a file the diff did not touch from its committed baseline row instead of requiring fresh coverage for it. A gate loosening, not a saving — defaults to false. |
201
- | `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | Default git ref the changed-file set is computed against, for a caller that passes no `--ref`. A `--ref` the caller named wins over this value, so a caller that anchors another gate on the same ref — `.husky/pre-push`, which passes `--ref origin/main` and then previews `--changed-since origin/main` — resolves ONE scope for both steps (Story #5365). Omitted and unpassed, the gate’s own default `main` applies. |
207
+ | `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | Default git ref the changed-file set is computed against, for a caller that passes no `--ref`. A `--ref` the caller named wins over this value, so a caller that anchors another gate on the same ref — `.husky/pre-push`, which passes `--ref origin/main` and then previews `--changed-since origin/main` — resolves ONE scope for both steps (Story #5365). Omitted and unpassed, the default is `origin/<project.baseBranch>` (`origin/main` by default), so a local base branch that trails the remote cannot widen the set; a clone where that remote ref does not resolve falls back to the local base branch with a warning. |
202
208
  | `quality.gates.crap.coveragePath` | No | `string` \| `null` | `null` | Repo-relative Istanbul `coverage-final.json` the CRAP gate joins against (Story #5717). `null` or unset falls back to `delivery.quality.gates.coverage.coveragePath`. When it differs from that path the CRAP gate has its OWN coverage source: `coverage-capture.js` refreshes it full-scope via `captureScript`, and the handoff seat, close preview and `update-crap-baseline.js` read it. Its capture stamp sits beside it, so it may share a directory with the coverage gate's artifact. |
203
209
  | `quality.gates.crap.captureScript` | No | `string` | — | `package.json` script (never a shell command) that writes the CRAP gate's OWN coverage artifact, spawned as `<pm> run <script>`. Valid only beside an own `coveragePath`: without one the CRAP gate reads the coverage gate's artifact, so this key is refused and `delivery.quality.gates.coverage.captureScript` runs. Unset beside an own `coveragePath`, it is the coverage gate's `captureScript`. |
204
210
  | `quality.gates.maintainability` | No | `object` | — | Maintainability-index ratchet. Scores per file as the average over its methods, so deleting a small high-MI method can legitimately lower a file’s score. |
@@ -241,23 +247,30 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
241
247
  | `quality.gates.duplication.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664). This is the lever for scanning fewer files. |
242
248
  | `quality.autoRefresh` | No | `object` | — | Baseline-attribution auto-refresh: when a gate can prove a regression is a legitimate consequence of the diff, it rewrites the baseline instead of blocking. The single-row CRAP jump cap (5) and the rescore scope (`diff`) are fixed. |
243
249
  | `quality.autoRefresh.enabled` | No | `boolean` | `true` | Master switch for the auto-refresh path. When false, every baseline refresh is a deliberate operator action. |
250
+ | `quality.ratchets` | No | `object` | — | CI's standalone ratchets as the handoff preflight runs them. |
251
+ | `quality.ratchets.coveredByLint` | No | `array<enum>` | `[]` | Standalone ratchets the handoff preflight skips once the same pass's whole-tree `lint` check exited 0. Each listed ratchet MUST be run, with the same arguments and over the whole repository, by the command `project.commands.lint` resolves to; mandrel cannot inspect that command, so this is the consumer's declaration. A lint that is absent, disabled, failing or narrowed to changed files covers nothing, and CI stays the backstop. Default `[]` runs every ratchet whose baseline is committed. |
244
252
  | `quality.requireBaselines` | No | `boolean` | `false` | Story #4495. Fail-closed baseline-enforcement policy for the unified check-baselines close-validation gate. When false (default), a consumer that enables baseline gates (crap/maintainability/…) but has not committed the corresponding baseline artifacts under baselines/ gets a clean skip-with-reason instead of a deterministic first-try close failure. Set true to keep the gate registered so an absent baseline artifact fails close-validation with a preflight hint naming the fix (the fail-closed posture). |
245
253
  | `mergeWatch` | No | `object` | — | Knobs consumed by the close-and-land merge wait (Story #4543). `mode` (Story #4698) selects the close-time merge posture. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the later of the PR's createdAt and its latest auto-merge arm, so a `--wait` resume does not restart the clock while a re-close that re-arms gets a fresh budget) and exhausting it is the genuine give-up that classifies and blocks. The poll cadence is internal (at most 30s while checks run, at most 10s once they are green and the PR is unmerged); it and the cap of 3 behind-the-base updates are not configurable. |
246
254
  | `mergeWatch.mode` | No | `"sync"` \| `"async"` | — | Close-time merge-wait posture (Story #4698). `sync` (default) keeps the in-close foreground merge wait unchanged. `async` caps the per-invocation wait to a short ~60s probe window — long enough to catch an instant merge and, via the head-anchored required-check predicate, an instantly-red required check — then returns the resumable `pending` terminal (exit 3) with a `nextCommand`. Opt in when slow CI makes the foreground wait routinely expire: the worker launches `nextCommand` in the background instead of burning the host tool slot polling. `maxBudgetSeconds` (the cumulative give-up) is unchanged. |
247
255
  | `mergeWatch.maxWaitSeconds` | No | `integer` | — | Per-invocation merge-wait bound (seconds). Default 300 (5 minutes) — chosen to fit inside a single host tool invocation (~10 min ceiling) alongside the close gates that precede the wait. Expiry yields `pending` (exit 3), never a block. Headless callers with no host ceiling raise this to land in one block. |
248
256
  | `mergeWatch.maxBudgetSeconds` | No | `integer` | `3600` | Cumulative wall-clock budget (seconds) across merge-wait resumes, anchored at the later of the PR's createdAt and its latest auto-merge arm (`autoMergeRequest.enabledAt`), so a re-close that re-arms starts a fresh budget; without an arm time it falls back to createdAt, then to the invocation start. Default 3600 (60 minutes). Exhausting this classifies the block and transitions the Story to agent::blocked. |
257
+ | `close` | No | `object` | — | Close-time posture (Story #5954). `baseSync` decides whether close and a handoff re-run merge `origin/<baseBranch>` before validating. |
258
+ | `close.baseSync` | No | `"always"` \| `"on-conflict"` | `"always"` | `always` (default) merges `origin/<baseBranch>` on every close, as before. `on-conflict` first runs a conflict-only probe and skips the merge when it is conflict-free (`git merge-tree --write-tree`) and the incoming and Story paths are disjoint (raw paths, `baselines/` and renames included); `check-baselines` then compares against the merge-base and the terminal envelope's `baseSync` says why. Any other probe answer merges as today. A handoff applies the probe only on a re-run. Opt in only behind a merge queue that re-tests the merged tree and with no up-to-date-branch requirement: a semantic conflict the probe cannot see surfaces in CI, and coverage is measured on the pre-merge tree. |
249
259
  | `codeReview` | No | `object` | — | Review-provider chain and on-branch remediation threshold for the /mandrel-deliver code-review ceremony. |
250
- | `codeReview.providers[]` | No | `array<object>` | `[{"name":"native"},{"name":"llm-review","scopes":["story"],"optional":true}]` | Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (maintainability scoring of the changed files) then an optional story-scoped `llm-review` — the first available of `code-review` (a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge) and `codex` (`codex exec`), so a host with both CLIs runs one LLM review and a host with neither skips it. Pin `code-review` or `codex` to choose the CLI. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. Each item has: name, scopes, optional, manualPrompt, when. |
260
+ | `codeReview.providers[]` | No | `array<object>` | `[{"name":"native"},{"name":"llm-review","scopes":["story"],"optional":true}]` | Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (maintainability scoring of the changed files) then an optional story-scoped `llm-review` — the first available of `code-review` (a `claude --print` bug review, at the effort `effortByDepth` maps its depth to, whose every finding is critical and halts close before auto-merge) and `codex` (`codex exec`), so a host with both CLIs runs one LLM review and a host with neither skips it. Pin `code-review` or `codex` to choose the CLI. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. Each item has: name, scopes, optional, manualPrompt, when. |
251
261
  | `codeReview.autoFixSeverity` | No | `"high"` \| `"medium"` | `"medium"` | 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. |
252
262
  | `codeReview.sensitivePaths` | No | `object<map>` | — | The project's own sensitive-path classes, merged additively over the shipped `audit-rules.json` `sensitivePaths`: a class named like a shipped one appends its patterns to it, a new name adds a class, and no shipped class or pattern can be removed or narrowed. A changed file matching any class derives a `high` change level, which drives both code-review depth (`deep`, never `light`) and plan-time routing. Patterns are picomatch globs matched with `dot: true`. |
263
+ | `codeReview.effortByDepth` | No | `object<map>` | — | The `claude --effort` level the `code-review` provider runs at for each review depth. An entry overrides the shipped default for that depth only: `light: low`, `standard: low`, `deep: high`. |
253
264
  | `codeReview.guidanceFile` | No | `string` | — | Project review guidance, a path relative to the project root. Unset, a root `REVIEW.md` is used when present; an absent file is a no-op. Its text is rendered into every LLM review provider's prompt after the framework's severity and anti-gaming rules, and over 8,000 characters is truncated with a degradation. Guidance may add failure classes and paths worth skipping but cannot lower a severity rule, excuse a `shortcut:`, or change the output shape. |
265
+ | `codeReview.onNoVerdict` | No | `"report"` \| `"block"` | `"report"` | What a Story-scope review that left part or all of the diff without a verdict does. `report` (default) records it (`gates.codeReview: unreviewed` or `partial`) and does not halt. `block` halts handoff and close on any `verdict-missing` or `coverage-partial` degradation, naming the cause, its fix and the `story-review-compute.js` re-run command; `--override-review-block` stays the escape. Reduced context (`degraded`) never halts. Set `block` when this review is the only pre-merge review. |
254
266
  | `codeReview.skipPaths` | No | `array<string>` | — | Picomatch globs (`dot: true`) whose findings are dropped after grounding and before severity is counted; the report states how many were dropped. A finding is dropped when its file, or every instance file, matches. Only config sets skip paths: guidance prose cannot silence a finding. |
255
267
  | `refactorStage` | No | `object` | — | Opt-in, config-gated post-green refactor checkpoint wired into story-deliver (Story #3430, Epic #3418). Strictly additive and default-OFF: when disabled, story-deliver behaves exactly as before. Advisory only — never changes existing close-validation gate semantics. |
256
268
  | `refactorStage.enabled` | No | `boolean` | `false` | When true, story-deliver runs an advisory post-green refactor stage (core/code-review-and-quality skill, Post-Green Refactor Pass) after the suite is green. Default false — when unset the stage is skipped and close-validation gate semantics are unchanged. |
257
269
  | `acceptanceEval` | No | `object` | — | Story #3819. Bounded per-Story acceptance self-eval loop. After the implementation commits land and before the Story-implementation phase flips to `closing`, an independent (fresh-context) critic pass scores the caller-injected change set against each inline `acceptance[]` item, redrafts the unmet items, and re-evaluates — capped at `maxRounds` redraft rounds (0 = scored once, no redraft), then escalates to `agent::blocked` when criteria remain unmet. There is no `enabled` flag: the scoring pass is a hard cutover (always on). |
258
270
  | `acceptanceEval.maxRounds` | No | `integer` | `2` | Maximum number of redraft rounds before escalation. Default 2; 0 means the verdict is scored once with no redraft round (Story #5313 dropped the hard ceiling and the floor-of-one clamp). |
259
- | `feedbackLoop` | No | `object` | — | Opt-in toggle for the close-time retro auto-file graduator. Auto-filing defaults to OFF (Story #5341). |
271
+ | `feedbackLoop` | No | `object` | — | Opt-in toggles for anything posted to the tracker unasked: the retro auto-file graduator and the per-Story outcome record. Both default to OFF (Story #5341). |
260
272
  | `feedbackLoop.retroProposals` | No | `boolean` | `false` | When true, the retro auto-files its actionable routed proposals as meta::<framework-gap\|consumer-improvement> + friction::<category> issues via the graduator pre-parsed-findings seam, and the rendered retro sections list the filed issue numbers instead of paste-ready gh command stanzas. Defaults to false (Story #5341), which renders the command stanzas instead. |
273
+ | `feedbackLoop.outcomeRecord` | No | `boolean` | `false` | When true, every close and confirm-merge attempt upserts one `story-outcome` structured comment on the Story issue: a JSON record of each attempt (status, cause, failed gates, mandrel version) plus a carried-forward summary, read back by story-outcomes-report.js. Defaults to false, which makes no extra GitHub call. |
261
274
  | `ci` | No | `object` | — | CI-aware delivery namespace (Story #4356, Epic #4355): the merge posture and the advisory-check policy. |
262
275
  | `ci.autoMerge` | No | `"trust-ci"` \| `"strict"` | `"trust-ci"` | Story #4356 (Epic #4355). Merge posture. 'trust-ci' (default) merges once required checks pass; 'strict' skips arming auto-merge, so the operator owns the merge; it adds no review gate. |
263
276
  | `ci.blockOnAdvisoryFailure` | No | `boolean` | `true` | Story #5096. When true (default), delivery refuses to arm — and disarms — GitHub native auto-merge while a non-required (advisory) check is genuinely red on the PR head and GitHub reports the PR mergeable anyway (mergeStateStatus=UNSTABLE). `--auto` waits on REQUIRED contexts only, so without this a red advisory quality gate merges unattended. Set false to restore the pre-#5096 behaviour verbatim. |
@@ -265,6 +278,8 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
265
278
  | `ci.rerunAdvisory` | No | `integer` | `0` | Story #5266. How many times close may re-run a failed advisory workflow run before blocking on it, per close invocation. Default 0: close spends no CI minutes and issues no GitHub mutation on an advisory red unless asked. At n > 0 the failed run(s) are re-run within that allowance and the merge wait re-polls inside its existing budget, landing or blocking on the re-run verdict. Overridden per invocation by --rerun-advisory <n>. |
266
279
  | `pullRequest` | No | `object` | — | Story #5875. What close writes into the pull request it opens, beyond the title and the `Closes #<id>` line. |
267
280
  | `pullRequest.bodyTrailers` | No | `array<string>` | `[]` | Story #5875. Git-trailer keys close lifts from the Story branch commits into the PR body, for a consumer whose required check reads a body line (e.g. `Policy-impact`). For each key the last branch commit carrying `<Key>: <value>` as a trailer wins, and the line is appended after the auto-opened marker and before any `BREAKING CHANGE:` footer. A key no commit carries appends nothing and logs one info line. Workers record the value with `git commit --trailer`. Default [] leaves the body unchanged. |
281
+ | `handoff` | No | `object` | — | Story #5960. What `story-handoff.js` runs beyond close's own gates. |
282
+ | `handoff.postSeatChecks[]` | No | `array<object>` | `[]` | Story #5960. Consumer checks the handoff re-runs in its post-capture step, after the seat commits the Story's new baseline rows: each `{ cmd, args? }` runs in the worktree without a shell, with `MANDREL_HANDOFF_STEP=post-capture`, and a non-zero exit settles `fix-required`. Declare the check a consumer downgrades during `preflight` (keyed on `MANDREL_HANDOFF_STEP`) here, so a row the seat did not write still fails the handoff; while any is declared the preflight `lint` credit is withheld until they pass at HEAD. Skipped under a coverage deferral. Default [] runs nothing extra. Each item has: cmd, args. |
268
283
  | `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313 and the derived-level ceremony routing in Story #5343. |
269
284
  | `routing.roleScopedAgents` | No | `boolean` | `true` | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full entry-doc (AGENTS.md or CLAUDE.md) @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
270
285
  | `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | `"standard"` | Acceptance-ceremony depth — who authors the Story acceptance verdict. minimal and standard (default) = the inline self-eval, whatever the diff touches; strict = a fresh-context maker-blind critic. Review depth is a separate decision and still derives `deep` for any sensitive path (review-depth.js). |
@@ -433,6 +448,30 @@ A config still carrying the retired key is a hard validation failure; the
433
448
  the callback's result, `75` when the wait expires, or `78` when the
434
449
  declared weight exceeds `capacity`. With `MANDREL_FULL_SUITE_LOCK=0` or
435
450
  `fullSuiteLock: false` it calls the callback directly with an empty `env`.
451
+ - **Sized workloads and backfill.** A `workloads[]` entry may declare
452
+ `tiers` (`[{ maxFiles, weight }]`) together with `sizeCommand`, an argv run
453
+ without a shell, in the spawn's cwd and environment (a coverage capture's
454
+ includes `MANDREL_COVERAGE_BASE_REF`), just before Mandrel reserves. Its
455
+ last stdout line must be the slice's test-file count. The run books the
456
+ weight of the first tier, by ascending `maxFiles`, that covers the count.
457
+ A count above every tier, a non-zero exit, a spawn error, the fixed 60 s
458
+ timeout or an unparseable line books the entry's full `weight` and logs
459
+ why, and so does a tier whose weight exceeds the entry's `weight`. Sizing
460
+ never runs for a refused, inherited or lock-disabled spawn, and a weight
461
+ above `capacity` is still refused with exit 78 first. Every declared
462
+ reservation's child also gets `MANDREL_SUITE_WEIGHT`, the weight it
463
+ booked (inherited runs read it from the parent's reservation). **Capping
464
+ the runner's worker pool at it (`--maxWorkers`, `--workers`) is the
465
+ consumer's obligation**: a booked weight below the real pool moves
466
+ contention from the queue onto the CPU. An entry marked `backfill: true`
467
+ may be admitted ahead of earlier waiters only when every one of them is
468
+ declared (an exclusive, empty or unreadable queue ticket is never
469
+ overtaken), fits beside it within `capacity`, shares no resource with it,
470
+ and the oldest has waited under 300 s. After that window nothing passes
471
+ the head waiter, so its remaining wait is bounded by the runs already
472
+ live, each bounded by its own kill bound. With no entry marked, admission
473
+ stays strictly first-in-first-out. Neither sizing nor backfill changes a
474
+ run's credit identity or capture stamp.
436
475
  - **Duplication needs jscpd.** The duplication gate scans with `jscpd` 4, an
437
476
  **optional peer dependency** of `mandrel`: a project that enables
438
477
  `quality.gates.duplication` installs it itself — `npm i -D jscpd@^4`.
@@ -464,48 +503,301 @@ suite when the script is absent):
464
503
  - `captureScope` is `affected` and the `test:coverage:affected` script
465
504
  exists;
466
505
  - the worktree is clean, and the delta (`git diff --name-only <commit> HEAD`)
467
- is non-empty and shares no path with the Story's change set;
506
+ is non-empty;
507
+ - the delta shares no path with the Story's change set, **or** every commit
508
+ since the stamp came from the base: `git rev-list --no-merges
509
+ <commit>..HEAD ^origin/<baseBranch>` is empty. A shared file is then in the
510
+ delta, so its prior row is dropped and re-measured keyed on the stamped
511
+ commit. A Story commit since the stamp, or an unresolvable base ref, keeps
512
+ the refusal, and the reason names the Story's own commits;
468
513
  - the delta touches no coverage-determining config: `package.json`, a
469
- lockfile, `tsconfig*.json`, or a vitest / jest / c8 / nyc config;
514
+ lockfile, `tsconfig*.json`, or a vitest / jest / c8 / nyc config — unless
515
+ `captureHandlesConfigChanges` is `true`;
470
516
  - a prior artifact exists to merge over.
471
517
 
518
+ Baseline and coverage-directory paths never count, and neither do paths
519
+ matching **`nonInputGlobs`** (repo-relative picomatch globs, default `[]`).
520
+ Those globs are dropped from both sides of the overlap check and from the
521
+ re-measured set, so a delta made only of matching, baseline and
522
+ coverage-directory paths restamps without running a test. Nothing is built
523
+ in: a consumer test may read a doc by path, so Markdown counts as an input
524
+ until a consumer declares it. The globs never change the suite-input filter,
525
+ the tree digest or stamp freshness. Close's `test` delta re-credit
526
+ (`commands.testChanged`) drops them from its overlap comparison only; its
527
+ incoming count and emptiness rule are unchanged, and it refuses a config file
528
+ under either value of **`captureHandlesConfigChanges`**. That key declares
529
+ that the affected capture script, given `MANDREL_COVERAGE_BASE_REF`, widens
530
+ its own selection when a config file changes; it covers only the capture
531
+ script.
532
+
533
+ **Own-fix delta refresh (`ownFixDeltaMaxFiles`, opt-in).** A small fix to
534
+ the Story's own code after the credited capture (a review fix, a CRAP
535
+ extraction, a pre-push fix) is normally refused above: the delta shares a
536
+ path with the Story and a Story commit landed since the stamp. With
537
+ `ownFixDeltaMaxFiles` at `N >= 1`, a delta that the rules above refuse for a
538
+ Story overlap or a config file is re-judged; a delta they accept takes the
539
+ same path as before, and at `0` (the default) no extra git command runs.
540
+ The re-judge walks `git rev-list --first-parent --parents <commit>..HEAD`,
541
+ whose oldest step must have the stamped commit as its first parent. Each
542
+ merge step's paths (`git diff --name-only <M>^1 <M>`) form the **base part**,
543
+ and each non-merge commit's paths form the **own part**. Both parts are
544
+ counted after the same suite-input and `nonInputGlobs` filter. The delta is
545
+ re-measured, keyed on the stamped commit and merged with the prior rows kept,
546
+ only when **every** guard holds:
547
+
548
+ - the base part shares no suite-input path with the Story's change set and
549
+ holds no coverage-determining config (unless `captureHandlesConfigChanges`);
550
+ - the own part holds no coverage-determining config file;
551
+ - the own part touches at most `N` suite-input paths in the delta;
552
+ - no own commit deletes or renames a suite-input path;
553
+ - no own-part test file (`*.test.*` / `*.spec.*`, or under a `tests`, `test`,
554
+ `__tests__`, `spec` or `e2e` directory) has net line removals across
555
+ `<commit>..HEAD`;
556
+ - no own commit is reachable from `origin/<baseBranch>` (that would be a
557
+ fast-forwarded base commit).
558
+
559
+ An eligible plan logs `needs an own-fix delta refresh — re-measuring <k>
560
+ file(s) changed since <sha> (<n> own file(s), <m> base file(s))` with
561
+ verdict `own-fix-delta-refresh`. A refusal logs the ordinary `delta refresh
562
+ not eligible (…)` line with a reason starting `own-fix:` that names the
563
+ guard and the offending path or count, so the hit rate can be counted from
564
+ logs. Any git error while splitting refuses. The consumer's
565
+ `test:coverage:affected` script still selects the tests; mandrel only names
566
+ the base ref and the rows to replace.
567
+
568
+ **Risk.** Rows outside the delta are kept, so one can go stale high: a fix
569
+ that weakens a test covering another Story file, or a changed source that
570
+ stops calling another Story file, leaves that file's prior row in place. The
571
+ base-delta refresh already accepts this hazard class; the guards close the
572
+ obvious routes. Before raising the cap (a reasonable start is `10`),
573
+ validate on a sample of Stories by diffing a delta-merged artifact against a
574
+ full capture. A consumer whose CI does not measure coverage on the full
575
+ suite should leave the key at `0`.
576
+
472
577
  Any git error or unresolvable input fails closed to the ordinary capture.
473
578
  Every freshness log line names the stamp's scope, the required scope and the
474
- verdict (`fresh`, `stale`, `scope-mismatch`, `missing`, or `delta-refresh`
475
- with the delta's file count), so an unexpected full re-run is explainable
476
- from the log alone. `captureScope: "full"` is unaffected.
477
-
478
- #### `delivery.quality.gates.coverage.onOverBudget` — deferring to CI
579
+ verdict (`fresh`, `stale`, `scope-mismatch`, `missing`, or `delta-refresh` /
580
+ `own-fix-delta-refresh` with the delta's file count), so an unexpected full re-run is explainable
581
+ from the log alone. Every delta-refresh and not-eligible line also names the
582
+ rule that decided (`disjoint`, `overlap`, `own-commits`, `config`, `empty`,
583
+ `restamp`, or `precondition` before any delta was read), the delta's file
584
+ count, the paths dropped as baseline/coverage-directory and as
585
+ `nonInputGlobs`, and, for an overlap, how many Story files overlapped.
586
+ `captureScope: "full"` is unaffected.
587
+
588
+ #### `delivery.close.baseSync` — conflict-only base sync
589
+
590
+ `always` (the default) merges `origin/<baseBranch>` into the Story branch on
591
+ every close, as before. `on-conflict` first asks a probe whether the merge is
592
+ needed, and skips it only when all of these hold:
593
+
594
+ - `origin/<baseBranch>` was fetched and is not already an ancestor of `HEAD`;
595
+ - `git merge-tree --write-tree --no-messages origin/<baseBranch> HEAD` exits
596
+ 0 (exit 1 is a conflict; any other exit, such as git older than 2.38, is
597
+ unsupported);
598
+ - the paths the base changed since the merge-base and the paths the Story
599
+ changed are disjoint — raw lists with `--no-renames`, so `baselines/`, the
600
+ coverage directory and a rename's old path all count.
601
+
602
+ Any other answer, or any git failure, merges exactly as `always` does. With
603
+ no path changed on both sides, git never runs a merge driver, so a skip cannot
604
+ depend on the `mandrel-baseline` driver.
605
+
606
+ After a skip, close validates and pushes the tree it has: no merge commit, no
607
+ spent credit, so the handoff's lint, format, typecheck and coverage credit
608
+ holds. `check-baselines` compares against the **merge-base** instead of
609
+ `origin/<baseBranch>`, so a row the base improved since is not a phantom
610
+ regression. Close logs one `SYNC` line naming the decision, and the terminal
611
+ envelope carries `baseSync: { mode, outcome, reason, incoming }` (`null`
612
+ when no sync ran). A handoff applies the same probe on a **re-run** only;
613
+ its first invocation always merges, and a skip records `baseMerge: {
614
+ skipped: "conflict-free", incoming }` in its envelope. The merge-wait
615
+ recovery and the DIRTY-PR sync always merge.
616
+
617
+ **The trade-off, and why it is opt-in.** A semantic conflict `merge-tree`
618
+ cannot see — a sibling's API change, a dead-export or dependency-graph rule
619
+ over the combined tree — surfaces only in PR CI or as a merge-queue ejection,
620
+ and coverage rows are measured on the pre-merge tree. Nothing local checks
621
+ coverage baselines on the merged tree before landing. Set `on-conflict` only
622
+ when the repository **requires a merge queue** (or an equivalent) that
623
+ re-tests the merged tree, and does **not** require PR branches to be up to
624
+ date — otherwise the PR shows BEHIND and confirm-merge's `gh pr update-branch`
625
+ merges the base anyway.
626
+
627
+ #### Deferring coverage to CI — `onOverBudget`, `suiteOfRecord` and the ratchet
479
628
 
480
629
  A hub change on a small host (a 4-core cloud VM, say) can select a capture
481
630
  slice that cannot finish inside `timeoutMs`, and the handoff then ends in
482
631
  exit 124. When the consumer's CI already runs that suite, a local run is a
483
- duplicate the host cannot finish. Exit `76` and this key let the consumer
484
- say so.
485
-
486
- - **The signal is the consumer's.** Its `captureScript`,
487
- `affectedCaptureScript` or `crap.captureScript` exits **76** to mean "the
488
- selected slice is over this host's budget; no test ran". Mandrel never
632
+ duplicate the host cannot finish. Two settings defer the capture to CI, and
633
+ `ciRatchetCheck` names the CI check that ratchets coverage and CRAP in its
634
+ place.
635
+
636
+ - **Exit `76` is the consumer's signal.** Its `captureScript`,
637
+ `affectedCaptureScript` or `crap.captureScript` — or the `test` command
638
+ (`project.commands.test`, or `testChanged` as the skip-branch depositor
639
+ or delta re-credit) — exits **76** to mean "the selected slice is over
640
+ this host's budget; no test ran". `onOverBudget` settles a `test` exit 76
641
+ exactly as it settles the capture's. Mandrel never
489
642
  sizes a slice or predicts its runtime. `coverage-capture.js` passes 76
490
643
  through unchanged: it writes and stamps no artifact, and runs no later
491
644
  capture pass.
492
- - **`block` (default).** The handoff settles `blocked` and close fails, each
493
- naming this key. Nothing changes for a consumer that never emits 76.
494
- - **`defer-to-ci`.** The handoff settles `ready` with
495
- `coverage: { status: "deferred", reason: "over-budget", policy:
496
- "defer-to-ci" }` and records no credit. It skips the CRAP `--seat-missing`
497
- pass and the gates that read the artifact (`quality-preview-crap`,
498
- `check-baselines-coverage`). Close re-runs the capture, reports
645
+ - **`onOverBudget: "block"` (default).** The handoff settles `blocked` and
646
+ close fails, each naming this key. Nothing changes for a consumer that
647
+ never emits 76.
648
+ - **`onOverBudget: "defer-to-ci"`.** An exit 76 settles the coverage gate as
649
+ deferred, reason `over-budget`.
650
+ - **`suiteOfRecord: "ci"`.** Set it in a small host's `.agentrc.local.json`.
651
+ The handoff and close defer the capture before anything spawns, reason
652
+ `suite-of-record-ci`: no full-suite lock is taken and `coverage-capture.js`
653
+ never runs. It applies only when `coverage-capture` is the credited
654
+ depositor; under the `test` depositor it changes nothing. It needs
655
+ `ciRatchetCheck`. Without one the handoff settles `blocked`
656
+ (`ci-ratchet-undeclared`) and close fails, both naming the two keys.
657
+ - **What a deferral does.** The handoff settles `ready` with
658
+ `coverage: { status: "deferred", reason, policy }` (`policy` is
659
+ `defer-to-ci` or `suite-of-record`) and records no credit. It skips the CRAP
660
+ `--seat-missing` pass and the gates that read the artifact
661
+ (`quality-preview-crap`, `check-baselines-coverage`). Close reports
499
662
  `coverage-capture: "deferred"` and those gates as `skipped`
500
- (`coverage-deferred-ci`), and opens the PR with a line saying coverage was
501
- deferred to CI. Every other gate still runs.
502
- - **CI owns the deferred run.** Set `defer-to-ci` only when the consumer's
503
- CI runs the suite with a coverage floor. Nothing local checks coverage or
504
- CRAP for a deferred Story, and CRAP rows for its new methods stay unseated.
663
+ (`coverage-deferred-ci`), then opens the PR and arms auto-merge. Every other
664
+ gate still runs.
665
+ - **The marker.** A deferred PR's body carries the prose line and, directly
666
+ beneath it, the key line `Coverage-deferred: <reason>` (`over-budget` or
667
+ `suite-of-record-ci`). Both tokens are a stable contract that CI workflows
668
+ and confirm-merge route on.
669
+ - **The hand-back: `coverage-ratchet.js`.** The CI job named by
670
+ `ciRatchetCheck` runs it on the merge ref, after CI has produced and merged
671
+ its artifact:
672
+ `node .agents/scripts/coverage-ratchet.js --artifact <path> --head <sha>
673
+ [--scope affected|full] [--base <ref>] [--adopt-only]`. It refuses (exit 1)
674
+ when `--head` is not the checked-out HEAD, a tracked file is dirty, or the
675
+ artifact is missing or unparseable. Otherwise it places the artifact at
676
+ `coveragePath` and writes the standard capture stamp for that tree, so
677
+ `update-crap-baseline.js --seat-missing`, `quality-preview.js --only crap`
678
+ and `update-coverage-baseline.js` read it as a green capture at that head.
679
+ It then runs the value ratchet against `--base` (default
680
+ `origin/<baseBranch>`): `update-coverage-baseline.js --diff-scope`, which
681
+ only re-scores the working copy, then `quality-preview.js --only crap`, then
682
+ `check-baselines.js --gate coverage,crap`. It exits non-zero at the first
683
+ failing step and names it. `--adopt-only` stops after the stamp, for a host
684
+ that seats rows from the artifact. CI never commits seated rows: a later run
685
+ on any host checked out at the same head seats them, or a full-scope
686
+ refresh does. Sharding and merging shard artifacts stay CI's job.
687
+ - **Confirm-merge holds on it.** With `ciRatchetCheck` set, a merged PR
688
+ carrying the key line flips `agent::done` only once that check is green on
689
+ the PR head. While the check is absent or in flight the Story stays at
690
+ `agent::closing` (`pending`, `ci-ratchet-pending`) and a re-run resolves
691
+ it. A red check (completed without success: failed, errored, timed out,
692
+ cancelled, startup failure or action required) flips `agent::blocked` and
693
+ posts a friction comment naming the check and the PR. The deferred code
694
+ landed without its ratchet, so an operator must decide. Making the check required in branch protection
695
+ remains the consumer's setting.
696
+ - **Doctor.** `mandrel doctor`'s `coverage-ratchet` check reads
697
+ `.agentrc.json` with `.agentrc.local.json` over it. It fails when
698
+ `suiteOfRecord` is `ci`, or `onOverBudget` is `defer-to-ci`, and
699
+ `ciRatchetCheck` is unset.
505
700
  - **Nothing sticks.** A deferral writes no artifact, stamp or credit, so a
506
701
  later run on a bigger host captures, seats and scores as usual.
507
702
  - **A timeout is not a deferral.** Exit 124 can hide a hang, so it keeps its
508
- current handling under either value.
703
+ current handling under every setting.
704
+
705
+ A CI job, as an example. Shards, artifact merging and the ratchet must all
706
+ check out the same ref:
707
+
708
+ ```yaml
709
+ coverage-ratchet:
710
+ needs: coverage-shards # produced and merged coverage/merged.json
711
+ runs-on: ubuntu-latest
712
+ steps:
713
+ - uses: actions/checkout@v4
714
+ with: { fetch-depth: 0 }
715
+ - uses: actions/download-artifact@v4
716
+ with: { name: coverage-merged, path: ci-coverage }
717
+ - run: npm ci
718
+ - run: >
719
+ node .agents/scripts/coverage-ratchet.js
720
+ --artifact ci-coverage/merged.json
721
+ --head "$(git rev-parse HEAD)"
722
+ ```
723
+
724
+ On a `pull_request` event the checkout is the merge ref, so pass
725
+ `--head "$(git rev-parse HEAD)"` from the job that produced the artifact.
726
+
727
+ #### Exit `77` — a suite that lost workers to host memory
728
+
729
+ A small host's OOM killer can take test workers mid-run, leaving a red
730
+ suite with no failing assertion. Exit `77` lets the consumer say so, and it
731
+ always blocks — `onOverBudget` never governs it and it is never deferred.
732
+
733
+ - **The signal is the consumer's.** The `captureScript`,
734
+ `affectedCaptureScript`, `crap.captureScript` or `project.commands.test`
735
+ wrapper exits **77** only when all hold: the runner reports lost workers,
736
+ zero assertions failed, and OOM is confirmed — a worker ended by
737
+ `SIGKILL` **plus** an `oom_kill` delta in the cgroup's `memory.events` (or
738
+ an OOM line in `dmesg`). Otherwise it exits `1`; a non-OOM worker crash is
739
+ the consumer's to retry once. Mandrel never inspects runner output,
740
+ `dmesg` or cgroups.
741
+ - **coverage-capture** passes 77 through: no artifact, no stamp, no later
742
+ pass, and a host-memory line instead of the failing-tests line.
743
+ - **Handoff** settles `blocked` (`failedStep: credited-run`, `reason:
744
+ host-resources`), records no credit, posts the `friction` comment, flips
745
+ `agent::blocked` and appends a `host-resources` runtime-friction record.
746
+ The detail names the remedies: fewer workers, a larger host, or — when CI
747
+ runs the suite with a coverage floor — an exit-76 declaration under
748
+ `onOverBudget: "defer-to-ci"`.
749
+ - **Counts (optional).** One stdout line such as
750
+ `{"hostResources":{"testsPassed":812,"testsFailed":0,"workersLost":2,"filesAffected":["a.test.js"],"peakWorkerRssMb":1900}}`
751
+ — the last such line wins — is copied unchanged into the envelope as
752
+ `hostResources`; its numeric counts join the step detail. A missing or
753
+ malformed line is ignored.
754
+ - **Close** reports a `test` or `coverage-capture` gate's 77 as outcome
755
+ `host-resources` with its own hint; a 77 from any other gate is an
756
+ ordinary failure.
757
+
758
+ #### `delivery.handoff.postSeatChecks` — the seat order and the step env
759
+
760
+ `story-handoff.js` seats the baseline rows a Story's own diff needs before
761
+ any check refuses the change for missing them. MI is static, so its
762
+ `--seat-missing` pass runs in `seat-static`, after the base merge and before
763
+ preflight. CRAP and coverage need a fresh capture, so theirs run in `seat`,
764
+ after the credited capture (coverage only on the capture path with the
765
+ coverage gate on, never under a coverage deferral). Each seat writes only
766
+ absent rows for files changed since the `origin/<baseBranch>` merge-base and
767
+ commits them as a `baseline-refresh:`.
768
+
769
+ Every child the handoff spawns gets `MANDREL_HANDOFF_STEP` set to the running
770
+ step (`seat-static`, `preflight`, `credited-run`, `seat`, `post-capture`, …),
771
+ over any inherited value. A consumer check that refuses a missing row may key
772
+ on `MANDREL_HANDOFF_STEP=preflight` to downgrade that direction for change-set
773
+ files, since the seat has not run yet; stale and extra rows stay fatal.
774
+
775
+ That downgrade is sound only with `postSeatChecks` declared: list the check
776
+ (`{ "cmd": "node", "args": ["scripts/check-rows.js"] }`) so the handoff
777
+ re-runs it in `post-capture`, after the seat, and a row the seat did not
778
+ write still settles `fix-required`. While any check is declared, preflight
779
+ runs `lint` without depositing close's credit and records the one `lint` pass
780
+ only after every post-seat check passed at that HEAD; under a coverage
781
+ deferral the checks are skipped and close runs lint itself.
782
+
783
+ #### `delivery.quality.ratchets.coveredByLint` — ratchets your lint already runs
784
+
785
+ The handoff preflight runs each standalone ratchet whose baseline is committed
786
+ (`dead-exports`, `dead-exports-production`, `arch-cycles`, `cyclomatic`). A
787
+ consumer whose `project.commands.lint` already runs some of them over the whole
788
+ tree lists those keys here, and the preflight skips each one, printing
789
+ `⏭ <key> covered by lint (delivery.quality.ratchets.coveredByLint)`.
790
+
791
+ The list is a declaration mandrel cannot check: each listed ratchet MUST be run
792
+ by the `project.commands.lint` command with the same arguments and over the
793
+ whole repository. A ratchet is skipped only when the same preflight pass
794
+ contains a whole-tree `lint` check (close's lint gate with no changed-file
795
+ scoping) and that check exited 0, whether it ran or `evidence-gate.js` credited
796
+ it from fresh evidence for the same HEAD and tree. A failing lint settles
797
+ `fix-required` with its own finding and no covered ratchet spawns; an absent,
798
+ disabled or narrowed lint covers nothing, so every ratchet runs. CI's ratchet
799
+ jobs stay the backstop. The preflight step's detail lists covered keys apart
800
+ from the checks that ran clean.
509
801
 
510
802
  #### `delivery.worktreeIsolation` — node_modules strategies
511
803
 
@@ -530,8 +822,11 @@ then skips `npm ci` and junctions/symlinks the donor's `node_modules`.
530
822
  #### `delivery.codeReview` — provider chain
531
823
 
532
824
  `providers[]` is iterated in declaration order (unset/empty → `native` plus
533
- an optional story-scoped `code-review`, the low-effort `claude --print` bug
534
- review whose every finding is critical and halts close). Beyond the field list in the generated table: `scopes`
825
+ an optional story-scoped `code-review`, the `claude --print` bug review whose
826
+ every finding is critical and halts close). `code-review` runs at the
827
+ `--effort` that `effortByDepth` maps the review depth to; the shipped mapping
828
+ is `light: low`, `standard: low`, `deep: high`, and an entry overrides only its
829
+ own depth. Beyond the field list in the generated table: `scopes`
535
830
  defaults to both `story` and `epic`; `when` is a label predicate (`when.label`
536
831
  / `when.labelAny`) that silently skips the entry when false; `manualPrompt`
537
832
  entries contribute a one-line suggestion and do **not** affect severity counts
@@ -543,7 +838,7 @@ non-Claude consumers can pin the same `.agents/` version unmodified. The fix
543
838
  budget (`maxFixAttempts` / `maxFixScopeFiles`) uses the same values for every
544
839
  Story in a run — there is no per-Story override.
545
840
 
546
- #### `delivery.feedbackLoop` — retro auto-graduation
841
+ #### `delivery.feedbackLoop` — retro auto-graduation and the outcome record
547
842
 
548
843
  `retroProposals` auto-graduates the retro's actionable routed proposals into
549
844
  follow-up issues; the graduator embeds a content-derived idempotency marker so
@@ -551,6 +846,17 @@ re-runs skip proposals that already have an issue (re-enabling after a
551
846
  manual-triage window is safe). It defaults to `false` (Story #5341) — set it
552
847
  to `true` to opt in.
553
848
 
849
+ `outcomeRecord` (default `false`) makes every close and confirm-merge attempt
850
+ upsert one `story-outcome` structured comment on the Story issue: a fenced JSON
851
+ record of each attempt (status, cause, failed gates, PR, mandrel version,
852
+ worker figures) and a summary whose counters carry across machines and across
853
+ the 100-attempt / comment-size cap. Recording is best-effort and never changes the terminal
854
+ envelope or exit code. `node .agents/scripts/story-outcomes-report.js
855
+ [--since <YYYY-MM-DD>] [--json]` reads those comments back in one paginated
856
+ call and reports first-pass rate, mean attempts to land, failed gates by count
857
+ and the same rates by landing mandrel version. Off, close makes no extra
858
+ GitHub call.
859
+
554
860
  Two sibling keys were retired and a config carrying either fails validation;
555
861
  delete it. `codeReviewAutoFile` went when Story #4411 unified the pass.
556
862
  `auditResultsAutoFile` went in Story #5366: its graduator had already been
@@ -671,6 +977,14 @@ it for machine-specific tuning (e.g. lower
671
977
  `delivery.deliverRunner.concurrencyCap` on a laptop) that should never reach
672
978
  git.
673
979
 
980
+ **One overlay per machine.** The main checkout's `.agentrc.local.json` governs
981
+ every worktree of that checkout: a linked worktree reads the main checkout's
982
+ file live, so an edit there reaches running Story worktrees, and Story init no
983
+ longer copies it in. A worktree's own copy is read only when the main checkout
984
+ has none. When a worktree holds a copy that differs from the main checkout's,
985
+ resolving config there prints one stderr warning naming both paths: the main
986
+ checkout's overlay is in force and the worktree copy can be deleted.
987
+
674
988
  **Per-contributor identity (required).** `github.operatorHandle` is a personal,
675
989
  per-contributor value with two jobs: the `@`-handle the framework @mentions on
676
990
  friction comments, **and** the lease owner the workflow guards
@@ -34,6 +34,17 @@ about **where** a friction record lands and **how** it is validated.
34
34
 
35
35
  ---
36
36
 
37
+ ## Story outcome record
38
+
39
+ With `delivery.feedbackLoop.outcomeRecord: true`, every close and
40
+ confirm-merge terminal upserts one `story-outcome` comment on the Story, so
41
+ attempts from any machine add to one record (a re-run confirm-merge on a
42
+ landed Story adds nothing). `story-outcomes-report.js [--since <YYYY-MM-DD>]
43
+ [--json]` rolls the records up by gate and mandrel version; details in
44
+ [`configuration.md`](configuration.md). Off by default.
45
+
46
+ ---
47
+
37
48
  ## Anti-thrashing: attack the premise
38
49
 
39
50
  Procedure behind the Re-Plan step of
@@ -114,6 +114,13 @@ owned by `boot-sweep.js` / `clean-git.js`:
114
114
  ancestry of its own) is **never** reaped by the boot sweep; it is surfaced
115
115
  under `contentMerged` for the operator to send to `/clean-git` for a
116
116
  confirmed, eyeballed reap.
117
+ - **Stalled deliveries are reported, never touched.** The same boot sweep
118
+ (`boot-sweep.js` and `single-story-init.js`) automatically lists every open
119
+ `agent::executing` Story whose `story-<id>` origin head has not moved (no
120
+ commit and no push) for 6 hours (`--stalled-after-hours <n>`) and that has no open PR — a session
121
+ that died silently. It reads origin over the REST API, writes nothing, and
122
+ is advisory: each row names `deliver-recover.js --story <id>`, which owns
123
+ the verdict.
117
124
  - **`/clean-git` is recovery, not routine.** Run it by hand only for a state
118
125
  the automated hygiene does not cover — triaging stashes, reaping across
119
126
  non-standard namespaces, or `--remote` pruning after a force-push. Reaching