mandrel 2.110.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 (190) 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/audit-checklists/state-machines.md +21 -0
  6. package/.agents/docs/agentrc-reference.json +23 -10
  7. package/.agents/docs/configuration.md +362 -15
  8. package/.agents/docs/execution-reference.md +11 -0
  9. package/.agents/docs/workflows.md +2 -1
  10. package/.agents/rules/ci-remediation.md +28 -4
  11. package/.agents/rules/git-conventions-reference.md +7 -0
  12. package/.agents/schemas/agentrc.schema.json +179 -13
  13. package/.agents/schemas/audit-rules.json +28 -0
  14. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  15. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  16. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  17. package/.agents/schemas/baselines/crap.schema.json +37 -10
  18. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  19. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  20. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  21. package/.agents/schemas/crap-report.schema.json +6 -5
  22. package/.agents/schemas/story-deliver-terminal.schema.json +49 -3
  23. package/.agents/schemas/story-progress.schema.json +1 -1
  24. package/.agents/schemas/validation-evidence.schema.json +2 -2
  25. package/.agents/scripts/boot-sweep.js +41 -3
  26. package/.agents/scripts/coverage-capture.js +39 -3
  27. package/.agents/scripts/coverage-ratchet.js +106 -0
  28. package/.agents/scripts/evidence-gate.js +84 -21
  29. package/.agents/scripts/file-ci-gap.js +220 -10
  30. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  31. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  32. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  33. package/.agents/scripts/lib/baseline-loader.js +4 -2
  34. package/.agents/scripts/lib/baselines/codec.js +57 -0
  35. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  36. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  37. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  38. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  39. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  40. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  41. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  42. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  43. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  44. package/.agents/scripts/lib/baselines/reader.js +36 -9
  45. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  46. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  47. package/.agents/scripts/lib/baselines/writer.js +36 -21
  48. package/.agents/scripts/lib/changed-files.js +70 -6
  49. package/.agents/scripts/lib/child-exec.js +10 -0
  50. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  51. package/.agents/scripts/lib/close-lock-events.js +8 -3
  52. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  53. package/.agents/scripts/lib/close-validation/gates.js +156 -32
  54. package/.agents/scripts/lib/close-validation/process.js +16 -7
  55. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  56. package/.agents/scripts/lib/close-validation/runner.js +160 -41
  57. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  58. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  59. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  60. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  61. package/.agents/scripts/lib/config/explain.js +5 -2
  62. package/.agents/scripts/lib/config/gates/coverage.schema.js +53 -0
  63. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  64. package/.agents/scripts/lib/config/git-roots.js +38 -4
  65. package/.agents/scripts/lib/config/handoff.js +24 -0
  66. package/.agents/scripts/lib/config/quality.js +28 -12
  67. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  68. package/.agents/scripts/lib/config-resolver.js +22 -2
  69. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  70. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  71. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  73. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  74. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  75. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  76. package/.agents/scripts/lib/coverage-capture.js +31 -0
  77. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  78. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  79. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  80. package/.agents/scripts/lib/crap-engine.js +3 -3
  81. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  82. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  83. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  84. package/.agents/scripts/lib/failure-rows.js +121 -0
  85. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  86. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  87. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  88. package/.agents/scripts/lib/gh-env.js +3 -6
  89. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  90. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  91. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  92. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  93. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  94. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  95. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  96. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  97. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  98. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  99. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  100. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  101. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  102. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  103. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  104. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +124 -23
  105. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  106. package/.agents/scripts/lib/orchestration/handoff-gates.js +217 -44
  107. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  108. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  109. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -1
  110. package/.agents/scripts/lib/orchestration/plan-persist/source-rewrite.js +76 -4
  111. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +2 -2
  112. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  113. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  114. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  115. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  116. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  117. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  118. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  119. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  120. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  121. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  122. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  123. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  124. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  125. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  126. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  127. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +17 -2
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +13 -1
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +17 -2
  135. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +42 -20
  136. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  137. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -1
  138. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +51 -15
  139. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  140. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  141. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  142. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  143. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  144. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  145. package/.agents/scripts/lib/orchestration/single-story-close/result.js +43 -13
  146. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  147. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -2
  148. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  149. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  150. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  151. package/.agents/scripts/lib/orchestration/story-handoff.js +789 -196
  152. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  153. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  154. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  155. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  156. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  157. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  158. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  159. package/.agents/scripts/lib/suite-admission.js +20 -8
  160. package/.agents/scripts/lib/suite-sizing.js +146 -0
  161. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  162. package/.agents/scripts/merge-baseline.js +14 -3
  163. package/.agents/scripts/providers/github/comments.js +19 -3
  164. package/.agents/scripts/providers/github.js +1 -0
  165. package/.agents/scripts/review-dispositions-report.js +1 -1
  166. package/.agents/scripts/role-scope-guard.js +267 -0
  167. package/.agents/scripts/single-story-close.js +4 -4
  168. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  169. package/.agents/scripts/single-story-init.js +24 -4
  170. package/.agents/scripts/story-handoff.js +3 -3
  171. package/.agents/scripts/story-outcomes-report.js +231 -0
  172. package/.agents/scripts/story-review-compute.js +9 -5
  173. package/.agents/scripts/update-coverage-baseline.js +12 -2
  174. package/.agents/scripts/update-crap-baseline.js +9 -1
  175. package/.agents/workflows/audit-state-machines.md +213 -0
  176. package/.agents/workflows/helpers/code-review.md +63 -9
  177. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  178. package/.agents/workflows/helpers/deliver-reference.md +236 -63
  179. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  180. package/.agents/workflows/helpers/deliver-story.md +7 -2
  181. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  182. package/.agents/workflows/helpers/plan-reference.md +10 -2
  183. package/docs/CHANGELOG.md +56 -0
  184. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  185. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  186. package/lib/cli/doctor-checks/llm-review.js +2 -11
  187. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  188. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  189. package/lib/cli/registry.js +5 -0
  190. package/package.json +1 -1
@@ -344,7 +344,9 @@ shapes poll on inside the ~60s window: checks already **green** (the merge is
344
344
  imminent — observed at the green cadence, it saves a whole confirm
345
345
  invocation) and a red rollup still awaiting its confirming probe. When a close returns that `pending` envelope, launch its
346
346
  `nextCommand` (`single-story-confirm-merge.js … --wait`) as a **background**
347
- invocation (host background Bash — its completion re-invokes the agent) and
347
+ invocation with the explicit timeout (`timeout: 7200000` on Claude Code —
348
+ [`parallel-tooling.md`](parallel-tooling.md) Rule 2; its completion
349
+ re-invokes the agent) and
348
350
  move on to the next Story; `single-story-confirm-merge.js` is idempotent and
349
351
  owns the whole tail, and `deliver-recover.js` recovers an orphaned confirm. Do
350
352
  not foreground-poll the merge. The cumulative `maxBudgetSeconds` give-up is
@@ -365,32 +367,74 @@ for the same reason — a foreground wait longer than the host tool ceiling
365
367
  expires `pending` anyway. Otherwise a one-Story run keeps `sync`: there is no
366
368
  sibling to unblock, and the foreground wait is the cheapest path to `landed`.
367
369
 
370
+ **Exception — a time-limited host.** On a host that limits background
371
+ commands (a cloud session, a `-p` run, an Agent SDK application, CI) a
372
+ one-Story close also runs with `--merge-watch-mode async`. Close itself stays
373
+ in the foreground, now bounded to the gates plus the ~60s probe, and the long
374
+ merge wait moves into the background confirm that carries the explicit
375
+ timeout. A local session need not pass the flag.
376
+
368
377
  ## Preflight (before close) {#preflight}
369
378
 
370
379
  Digest § 5 states the rule: `story-handoff.js` runs, after the base merge
371
- and before the credited suite run, close's own `lint` and `format` gates,
372
- `quality-preview.js --changed-since origin/<baseBranch>`, then the shipped
373
- standalone ratchets CI's `baselines` job runs — `check-dead-exports.js`
374
- (default and `--production`), `check-arch-cycles.js` and
375
- `check-cyclomatic.js` — in the worktree; a finding is `fix-required` — fix,
376
- commit, re-run it. It runs **before** the credited run because a fix commit
377
- afterwards would void that run's credit.
378
-
379
- - **Lint and format are close's credit.** The handoff takes both entries from
380
- close's `buildDefaultGates` (same config, base branch, worktree and
381
- evidence root) and runs them through `evidence-gate.js --standalone
382
- --gate <name>`, so the pass lands in close's evidence store keyed to the
383
- post-merge HEAD and tree, with close's command hash. `format` runs the argv
384
- close's runner scopes to the changed files, and deposits nothing when that
385
- scoping skips it or `project.commands.formatCheck` is `null`. Close on the
386
- handed-off HEAD skips both as `evidence-match`. A baselines-only seat commit
387
- re-keys the `lint` record to the seated HEAD; `format` is not carried (its
388
- argv names the changed files). Any other commit, or a close-time base move,
389
- re-runs them.
390
- - **Why.** Close runs lint and the maintainability half of the preview
391
- (`quality-preview-mi`) in its parallel phase, but a regression found there
392
- still costs a close round-trip. Seconds of preflight in the worktree is
393
- cheaper than any close.
380
+ and before the credited suite run, close's own `typecheck`, `lint` and
381
+ `format` gates, `quality-preview.js --changed-since origin/<baseBranch>`,
382
+ then the shipped standalone ratchets CI's `baselines` job runs —
383
+ `check-dead-exports.js` (default and `--production`), `check-arch-cycles.js`
384
+ and `check-cyclomatic.js` — in the worktree. It runs **before** the credited
385
+ run because a fix commit afterwards would void that run's credit.
386
+
387
+ - **One pass, every finding.** Every check runs, even after a finding. Any
388
+ finding settles one `fix-required` whose `detail` lists each finding on its
389
+ own line, in check order, and whose `findings[]` carries `{ check, detail,
390
+ evidencePath }` per failing check; the envelope's `evidencePath` is the
391
+ first one's in check order. No suite runs before the credited run. Only a
392
+ fully clean preflight is skipped on a re-run at the same HEAD.
393
+ - **Serial by default; admitted lanes per host.** With
394
+ `delivery.execution.preflightConcurrency` at `1` (the default) the checks
395
+ run one after another, exactly as before. A host that can afford overlap
396
+ sets a higher value in its `.agentrc.local.json` (copied into every
397
+ worktree); a host with no overlay, such as a cloud session, stays serial.
398
+ Above 1 the step runs one **base lane**, which takes every check in order
399
+ unadmitted, and up to N − 1 **admitted lanes**. An admitted lane takes only
400
+ a deposited check whose gate close runs in its independent bucket
401
+ (`isIndependentGate`: today `typecheck`, `lint` and `format`, never
402
+ `quality-preview` or a ratchet), admits it through `withSuiteAdmission`
403
+ under close's argv for that gate with no wait, and runs it inside the
404
+ reservation. A miss (exit 75 or 78) hands the check back to the base lane
405
+ in order, records no finding and retires that lane; a check that throws
406
+ once admitted is not a miss and fails the step as it would serially. No
407
+ lane aborts another. The step result gains
408
+ `concurrency: { requested, admitted }`, and each passed deposit missing
409
+ from the evidence store afterwards is re-recorded with close's command
410
+ hash. Suite admission off
411
+ (`fullSuiteLock: false`, `MANDREL_FULL_SUITE_LOCK=0`) or an inherited
412
+ suite reservation keeps the step serial, with one progress line naming
413
+ why.
414
+ - **Ratchets your lint runs.** A ratchet listed in
415
+ `delivery.quality.ratchets.coveredByLint` is skipped (`⏭ <key> covered by
416
+ lint`) only once this pass's whole-tree `lint` exited 0, run or credited
417
+ from fresh evidence; a failing lint spawns no covered ratchet, and an
418
+ absent or changed-file-scoped lint covers nothing.
419
+ - **Typecheck, lint and format are close's credit.** The handoff takes the
420
+ entries from close's `buildDefaultGates` (same config, base branch,
421
+ worktree and evidence root) and runs them through `evidence-gate.js
422
+ --standalone --gate <name>`, so each pass lands in close's evidence store
423
+ keyed to the post-merge HEAD and tree, with close's command hash. A
424
+ disabled gate (`project.commands.typecheck: null`, or `formatCheck`)
425
+ deposits nothing; `format` runs the argv close's runner scopes to the
426
+ changed files and deposits nothing when that scoping skips it. Close on
427
+ the handed-off HEAD skips each as `evidence-match`, and a consumer
428
+ `pre-push` hook running the same argv through `evidence-gate.js --gate
429
+ typecheck` replays the deposit. A baselines-only seat commit re-keys the
430
+ `lint` and `typecheck` records to the seated HEAD (handoff state
431
+ `preflightCredits`); `format` is not carried (its argv names the changed
432
+ files). Any other commit, or a close-time base move, re-runs them.
433
+ - **Why.** Close runs typecheck, lint and the maintainability half of the
434
+ preview (`quality-preview-mi`), but a regression found there still costs a
435
+ close round-trip, and a type error found after the suite costs the whole
436
+ lock-plus-suite phase. Seconds of preflight in the worktree is cheaper than
437
+ either.
394
438
  - **The CRAP half never captures.** It scores whatever coverage artifact is
395
439
  on disk — the worker's credited capture when one exists — and triggers no
396
440
  capture of its own. With no artifact its methods report unscorable; a stale
@@ -400,6 +444,12 @@ afterwards would void that run's credit.
400
444
  `arch-cycles.json`, `cyclomatic.json`) exists, and is judged by its exit
401
445
  code and `(gate fail)` line; the finding names the offending `+` / `!`
402
446
  rows. Close does not run them — CI stays their backstop.
447
+ - **Findings quote their rows.** A non-ratchet finding (lint, format,
448
+ quality-preview) quotes the failing lint, biome or guard lines it parsed —
449
+ at most 10, via `lib/failure-rows.js` — and falls back to the bare
450
+ `<key> finding` text when none parse. A baselines finding, at post-capture
451
+ or close, names its regressed rows and the kind's diff-scoped remedy
452
+ command from the `check-baselines --format text` report.
403
453
  - **Close stays authoritative.** Its `quality-preview-crap` gate scores a
404
454
  fresh capture after `coverage-capture`; a preflight pass never skips it.
405
455
  The handoff's post-capture step (§ Credited run) runs that gate early too.
@@ -420,42 +470,103 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
420
470
  JSON spends it, and close re-captures.
421
471
  - **Predicted skip.** With `incrementalCoverage.skipWhenUnchanged` on and no
422
472
  changed file under `crap.targetDirs`, the capture would run nothing, so
423
- the shared predicate (`resolveCreditedDepositor`) picks the `test`
424
- depositor for both close and the handoff. A `no changed files … —
425
- skipping capture` line is never credit.
473
+ the shared predicate (`resolveCreditedDepositor`, `skipBranch: true`)
474
+ picks the `test` depositor for both close and the handoff. A `no changed
475
+ files … — skipping capture` line is never credit. On this branch the
476
+ depositor is scoped: with `project.commands.testChanged` set, the handoff
477
+ runs `evidence-gate.js … --gate test --changed-since <merge-base> --
478
+ <testChanged>` and close registers the same run as its `test` gate, keyed
479
+ on `git merge-base origin/<baseBranch> HEAD` (substituted for a literal
480
+ `$MANDREL_CHANGED_SINCE` and set in the env). A green run credits close's
481
+ full-suite `test` identity with `scope: delta`, so close at that HEAD skips
482
+ the gate and the base-moved delta re-credit still applies. Unset
483
+ `testChanged` or an unreadable merge-base falls back to the full
484
+ `project.commands.test`, logging which reason applied. An exit 76 from any
485
+ `test` form settles by `coverage.onOverBudget`, as the capture's does.
426
486
  - **Runner shapes.** A bare `npm test` earns the `test` credit **only** where
427
487
  the project's test script routes through mandrel's own runner, which prints
428
488
  the outcome. On any other runner it deposits nothing and prints nothing, so
429
489
  silence is never evidence of credit.
490
+ - **Own-fix delta refresh.** A small fix to your own code after the credited
491
+ capture spends the stamp; by default the next capture re-runs the Story's
492
+ whole affected scope. With `coverage.ownFixDeltaMaxFiles` at `N >= 1` and
493
+ `captureScope: affected`, it re-measures only the delta when HEAD's
494
+ first-parent chain splits into base-sync merges sharing no suite input or
495
+ config with the Story and own commits touching at most `N` suite-input
496
+ files, with no config, no deleted or renamed suite input, no net line
497
+ removal in a test file and none reachable from the base. Any other shape
498
+ logs `delta refresh not eligible (own-fix: …)` and captures as before.
499
+ Rows outside the delta are kept and can go stale high, so validate against
500
+ full captures before raising the cap
501
+ ([configuration](../../docs/configuration.md)).
430
502
  - **Background dispatch.** If the handoff outruns the host's sync Bash ceiling,
431
- dispatch it in the **background** — its completion re-invokes you; never
432
- spawn a task to poll or `sleep`-loop against it
503
+ dispatch it in the **background** with an explicit timeout
504
+ (`timeout: 7200000` on Claude Code, the 2-hour maximum) — its completion
505
+ re-invokes you; never spawn a task to poll or `sleep`-loop against it. On a
506
+ host stop notice, re-run it once; a second stop is the blocked path
433
507
  ([`parallel-tooling.md`](parallel-tooling.md) Rule 2).
434
508
  - **Redraft rounds.** Run the scoped projects for the roots you changed plus
435
509
  `verify[]`, not the whole suite; only the one run needs credit.
436
- - **Seating new methods (`--seat-missing`).** Close fails a Story whose own
437
- new methods have no baseline row, so `story-handoff.js` runs, in
438
- `<workCwd>`, for each enabled gate:
439
- `node .agents/scripts/update-crap-baseline.js --seat-missing` (CRAP) and
510
+ - **Seating new rows (`--seat-missing`).** Close fails a Story whose own
511
+ new files or methods have no baseline row, so `story-handoff.js` seats them
512
+ in `<workCwd>`, in two steps. `seat-static`, after the base merge and
513
+ before preflight, runs
440
514
  `node .agents/scripts/update-maintainability-baseline.js --seat-missing`
441
- (MI). Each scores the files changed since the `origin/<baseBranch>`
442
- merge-base and writes **only** rows whose (path, method) key is absent —
515
+ (MI is static, so it voids no credit) unless the MI gate is disabled.
516
+ `seat`, after the credited capture, runs
517
+ `node .agents/scripts/update-crap-baseline.js --seat-missing` (CRAP gate
518
+ on) and `node .agents/scripts/update-coverage-baseline.js --seat-missing`
519
+ (capture depositor with the coverage gate on; never on the `test` path or
520
+ under a coverage deferral). Each scores the files changed since the
521
+ `origin/<baseBranch>` merge-base — after the base merge that is the base
522
+ tip, so a file only the merge brought in is never seated — and writes
523
+ **only** rows whose key (path, or path and method for CRAP) is absent:
443
524
  every existing row stays byte-identical, including rows whose scores moved
444
525
  (re-scoring stays close's auto-refresh). It prints `seated: N`; `seated: 0`
445
- writes nothing. The handoff commits a change as `chore(baselines):
446
- baseline-refresh: seat rows for new methods (refs #<id>)`.
447
- - **Seat refusals.** The CRAP seat exits non-zero and writes nothing unless
448
- the coverage-capture stamp is fresh for the tree **and** method resolution
449
- over the in-scope files is exactly 100% — a lower rate means the artifact's
450
- coordinates predate the tree. The refusal names the rate, the unresolved
451
- files and the fix: re-run the digest § 5 capture, then seat.
526
+ writes nothing. Each step commits its rows as `chore(baselines):
527
+ baseline-refresh: seat rows for new methods (refs #<id>)` and skips at an
528
+ unchanged HEAD on a re-run.
529
+ - **Seat refusals.** The CRAP and coverage seats exit non-zero and write
530
+ nothing unless a coverage-capture stamp is fresh for the tree; the CRAP
531
+ seat also needs method resolution over the in-scope files at exactly
532
+ 100% — a lower rate means the artifact's coordinates predate the tree. The
533
+ refusal names the fix: re-run the digest § 5 capture, then seat. A changed
534
+ file the fresh artifact did not measure is named in the coverage seat's
535
+ log and never seated at 0%.
536
+ - **Step env (`MANDREL_HANDOFF_STEP`).** Every child the handoff spawns gets
537
+ `MANDREL_HANDOFF_STEP` set to the running step (`base-merge`,
538
+ `seat-static`, `preflight`, `credited-run`, `seat`, `post-capture`,
539
+ `push`), layered over any inherited value. It is the one contract a
540
+ consumer check keys on to downgrade a missing baseline row for change-set
541
+ files during `preflight`, before the seat can write it; stale and extra
542
+ rows stay the consumer's to keep fatal.
543
+ - **Post-seat checks (`delivery.handoff.postSeatChecks`).** After close's
544
+ post-capture gates pass, the handoff runs each declared `{ cmd, args }` in
545
+ `<workCwd>` without a shell, with `MANDREL_HANDOFF_STEP=post-capture`; a
546
+ non-zero exit is `fix-required` naming the check, and nothing is pushed.
547
+ While any is declared, preflight runs close's `lint` argv bare and holds
548
+ its credit: a baselines-only seat commit re-keys it, any other commit drops
549
+ it, and the one `lint` pass record is written only once every post-seat
550
+ check passed at HEAD. Under a coverage deferral the checks are skipped and
551
+ no `lint` record is written, so close runs lint itself. A preflight
552
+ downgrade is sound only with the re-asserting check declared here.
553
+ - **Duplication re-score.** After the base merge and before preflight, the
554
+ handoff runs close's own duplication re-score (`duplication-rescore` in
555
+ `steps[]`) over the same scope close uses, and commits any moved row with
556
+ close's **untagged** subject — never `baseline-refresh:`, which would let
557
+ refresh-ack launder the rise. It precedes every credit, so its commit voids
558
+ no lint/format credit, `test` credit or capture stamp, and close's re-score
559
+ over the same tree and base reports `unchanged`. Best-effort: a failed scan
560
+ or refused commit settles `error` and the run continues; close's re-score
561
+ stays authoritative. A re-run at the HEAD it settled skips it.
452
562
  - **Post-capture checks.** After depositor and seat, the handoff runs close's
453
563
  `quality-preview-crap` entry — only when the depositor is
454
564
  `coverage-capture`, so a project with no capture keeps its CRAP behaviour —
455
565
  and every registered `check-baselines` entry (`single`, or `independent`
456
566
  plus `coverage`), each with close's argv and env (`BASELINE_REF`). A
457
567
  non-zero exit is `fix-required` naming the gate and its kinds, with the log
458
- as evidence; nothing is pushed. They are pure scoring: no lock, no suite,
568
+ as evidence (a duplication-scoring entry also lists each row raised over
569
+ `BASELINE_REF`, base → head, with the re-score's clone partners); nothing is pushed. They are pure scoring: no lock, no suite,
459
570
  no evidence, so close re-scores them. A re-run at a credited, unchanged
460
571
  HEAD skips them.
461
572
  - **Seat order vs credit.** Neither capture-stamp digest reads
@@ -467,10 +578,13 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
467
578
  ## Held review at hand-off {#held-review}
468
579
 
469
580
  The one home of this rule; the digest and the worker contract point here.
470
- `story-handoff.js` starts the Story-scope code review as the credited run
471
- starts — pinned to HEAD at that moment, after a `test`-depositor seat — and
472
- awaits it after the push, skipping the computation when a deposit already
473
- matches the diff digest. The envelope's `reviewMs` sits beside the run's
581
+ `story-handoff.js` starts the Story-scope code review once base-merge settles
582
+ HEAD — pinned to the post-merge HEAD, before preflight's first check (and
583
+ before a `test`-depositor seat, whose generated-only commit keeps the digest)
584
+ — so it runs alongside preflight, and awaits it after the push, skipping the
585
+ computation when a deposit already matches the diff digest. A precheck
586
+ refusal or a base merge that does not settle (conflict, failed fetch, missing
587
+ merge driver) starts no review. The envelope's `reviewMs` sits beside the run's
474
588
  `suiteTimings`. The same computation stands alone for a manual re-run:
475
589
 
476
590
  ```bash
@@ -481,27 +595,60 @@ node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd
481
595
  provider chain) against `origin/<baseBranch>...story-<id>`, posts nothing,
482
596
  takes no full-suite lock, and writes
483
597
  `temp/orchestration/story-review-<id>.json` beside the terminal envelope,
484
- keyed on the **diff digest** (sha256 of the three-dot diff with every
485
- `linguist-generated` section removed; a failed attribute lookup hashes it
486
- whole). It never stops the handoff on a provider throw — the step reports
598
+ keyed on the **diff digest**: sha256 of the three-dot diff with every
599
+ `linguist-generated` section removed (a failed attribute lookup keeps them),
600
+ every `index` line dropped and every hunk header reduced to a bare `@@`
601
+ (offsets and function-context trailer gone) — `git patch-id --stable`'s
602
+ sameness. Every `+`, `-`, context, path and mode line still counts, so a
603
+ change a reviewer could see moves it; the reviewer itself still gets the
604
+ raw diff. It never stops the handoff on a provider throw — the step reports
487
605
  `error` and close computes the review itself.
488
606
  - **A CRITICAL is the worker's to fix.** The handoff settles `fix-required`
489
- naming the deposit. One that lands while the credited run is in flight
490
- aborts the run (the SIGTERM a Ctrl-C sends; the child frees the full-suite
491
- lock), records no credit and pushes nothing; a CRITICAL after the run still
492
- settles after the push, as before. Any earlier stop still awaits the
493
- review, so no provider is orphaned. Fix, commit, and re-run the handoff
607
+ naming the deposit. It never cuts preflight short: every check runs to its
608
+ own result. One that has landed before the credited run would begin stops
609
+ the handoff there — no `test`-depositor seat, no run, no full-suite lock,
610
+ no credit, no push. One that lands while the run is in flight aborts it
611
+ (the SIGTERM a Ctrl-C sends; the child frees the full-suite lock), records
612
+ no credit and pushes nothing; a CRITICAL after the run still settles after
613
+ the push. Any earlier stop still awaits the review and appends its result
614
+ to `steps[]` once, so no provider is orphaned and one envelope carries both
615
+ findings, each with its own evidence path; `status` and `failedStep` stay
616
+ the first stop's, and a review `error` never blocks. Fix, commit, and re-run the handoff
494
617
  (the fix commit voided the credit, so it re-runs the suite, pushes and
495
618
  re-computes) — the acceptance loop's redraft discipline, bounded by
496
619
  `delivery.acceptanceEval.maxRounds`. Still CRITICAL at the cap → take the
497
620
  blocked path. Anything else goes in the hand-off as the severity tally.
498
- - **Close adopts, else computes.** When the deposit's digest equals the
499
- digest of the diff at close's held-review start, close starts no review and
500
- posts the deposit after PR-open. A clean base-sync merge or a seat commit
501
- that writes only generated baselines keeps the deposit; a commit that
502
- changes a reviewed path does not, and close reviews as it would without
503
- one. The CRITICAL halt and `--override-review-block` apply to an adopted
504
- result unchanged.
621
+ - **Close adopts, else computes — and deposits.** When the deposit's digest
622
+ equals the digest of the diff at close's held-review start, close starts no
623
+ review and posts the deposit after PR-open. A base-sync merge that moves
624
+ only offsets or `index` lines, or a seat commit that writes only generated
625
+ baselines, keeps the deposit; a commit that changes a reviewed line does
626
+ not, and close reviews as it would without one. Close deposits every
627
+ non-degraded review it computes, keyed on the SHA it reviewed: the held
628
+ review when it settles (posted or discarded alike) and the serial post-PR
629
+ review before it posts — so a retry on the same diff adopts it. A degraded
630
+ result is never deposited, and a failed write is one `REVIEW` warning. The
631
+ CRITICAL halt and `--override-review-block` apply to an adopted result
632
+ unchanged.
633
+ - **A deposit close never adopts is posted at land.** A Story landed without
634
+ close (push plus confirm-merge, or the boot sweep) gets the deposit matching
635
+ its merged head posted by the land tail before the temp purge, else an
636
+ `Unreviewed` marker naming `no-deposit` or `stale-deposit`, and a
637
+ `review-recorded-at-land` friction signal.
638
+
639
+ ## Handoff telemetry {#handoff-telemetry}
640
+
641
+ Every `steps[]` entry carries `durationMs` (the review's is `reviewMs`); a
642
+ skip that reuses a result already recorded for this HEAD adds
643
+ `skippedByCredit: true`. A stopped envelope names a `cause` from a closed set
644
+ beside `failedStep`, and every envelope an `attempt` (`null` on a failed
645
+ read). After the state write, each run appends one record to the Story's
646
+ `signals.ndjson` (`phase: handoff`, `emitter.tool: story-handoff`): a `retry`
647
+ when refused, a `trace` when ready. A step that throws settles
648
+ `fix-required` with cause `other`, so the run still writes both. Details
649
+ carry step names, durations and the cause — never a file path. Close telemetry counts them in its `handoff`
650
+ block, apart from close's own `retries`. Best-effort: a failed write never
651
+ changes the status or exit code.
505
652
 
506
653
  ## Gate output {#gate-output}
507
654
 
@@ -510,7 +657,28 @@ reports a one-line digest on success; a failed gate replays its tail inline.
510
657
  `AGENT_LOG_LEVEL=verbose` restores live streaming. A gate exiting `75` (its
511
658
  full-suite lock wait expired) logs a deferred line and the close settles
512
659
  `pending`; one exiting `124` (the suite outran its timeout) logs a timeout
513
- line naming host contention — neither is reported as failing tests.
660
+ line naming host contention — neither is reported as failing tests. A
661
+ coverage-capture exiting `76` (the consumer's capture script declared its
662
+ slice over this host's budget, so nothing ran) follows
663
+ `delivery.quality.gates.coverage.onOverBudget`, and under
664
+ `coverage.suiteOfRecord: "ci"` the capture is deferred before anything
665
+ spawns (no lock, no credit). A deferral reports the gate `deferred`, the
666
+ coverage-reading gates `skipped` (`coverage-deferred-ci`), settles the
667
+ handoff `ready` with a `coverage` field, and puts a `Coverage-deferred:
668
+ <reason>` key line in the PR body. CI's `ciRatchetCheck` job then runs
669
+ `node .agents/scripts/coverage-ratchet.js --artifact <path> --head <sha>`,
670
+ and confirm-merge holds `agent::done` until that check is green. Under the
671
+ default `block`, or `suiteOfRecord: "ci"` with no `ciRatchetCheck`, the
672
+ handoff settles `blocked` and close fails, naming the keys.
673
+ A credited suite exiting `77` (the consumer's `test` or capture script
674
+ confirmed it lost workers to host memory and no test failed) is never read
675
+ as failing tests: the handoff settles `blocked` with `reason:
676
+ host-resources`, records no credit, copies any consumer `hostResources`
677
+ counts line into the envelope and appends a `host-resources` friction
678
+ record; close logs the suite gate as `host-resources` with its own hint.
679
+ `onOverBudget` never governs it. A second `124` at the same HEAD stays
680
+ `fix-required` but points at `coverage.timeoutMs`, an exit-76 declaration
681
+ or a quieter host instead of a plain re-run.
514
682
 
515
683
  Every full-suite run ends on `⏲ suite timings: lockWaitMs=… hostWaitMs=…
516
684
  testRunMs=…`. The handoff envelope carries its credited run's figures as
@@ -525,6 +693,11 @@ that writes `$MANDREL_SUITE_READY_FILE` when its tests start (after a
525
693
  consumer load gate) gets a fresh bound for them, so worst-case wall is lock
526
694
  wait + 2 × `timeoutMs`.
527
695
 
696
+ The close terminal's `pushOutcome` (also on the close result) reads its
697
+ `phaseDurations.push`: `pushed`, or `skipped-already-at-head` when origin
698
+ already held the Story-branch tip, so no `git push` (and no `pre-push`) ran.
699
+ `--skip-validation` always pushes; an unreadable tip or `ls-remote` pushes.
700
+
528
701
  **Delta re-credit after a base move.** When close's base sync merged
529
702
  incoming paths (`BASE MOVED`), the `test` gate is the suite gate, the
530
703
  pre-sync head holds `test` credit and `project.commands.testChanged` is set,
@@ -277,18 +277,26 @@ judgment that help text cannot carry.
277
277
  **critical** blocker is one you have read and judged wrong (a false positive,
278
278
  or a finding the ratchet correctly exempts). It is the only sanctioned way
279
279
  past that halt: reach for it instead of merging the PR by hand, because a
280
- hand-merge bypasses the gate and records nothing. The reason is mandatory and
280
+ hand-merge bypasses the gate and records no override — the land then posts
281
+ the held deposit (a merged CRITICAL raises `review-critical-merged`) or an
282
+ `Unreviewed` marker. The reason is mandatory and
281
283
  is written to three places (Story comment, PR comment, a
282
284
  `review-block-overridden` friction signal), and the terminal envelope reports
283
285
  `gates.codeReview: "overridden"` rather than `"passed"`. If you find yourself
284
286
  reaching for it twice for the same shape of finding, the gate is
285
287
  miscalibrated — fix the gate, not the run.
286
- - `gates.codeReview: "degraded"` — not a flag but an envelope value: a
287
- review surface ran yet produced no verdict (the `claude` CLI is not logged
288
- in or out of quota, or its output did not parse). The PR comment lists it
289
- under Degraded Gates. It is reported, not blocking — close still lands —
290
- so read the diff yourself before trusting the merge. Precedence:
291
- `overridden` > `degraded` > `passed`.
288
+ - `gates.codeReview: "unreviewed" | "partial" | "degraded"` — not flags but
289
+ envelope values from the review's degradation kinds: `unreviewed` (any
290
+ `verdict-missing`: no verdict, a skipped optional reviewer, an unresolvable
291
+ base), `partial` (any `coverage-partial`: part of the diff unreviewed),
292
+ `degraded` (only `context-reduced`: reviewed with less context). The
293
+ reviewer is retried once on a transient failure first. Precedence:
294
+ `overridden` > `unreviewed` > `partial` > `degraded` > `passed`. Under the
295
+ default `delivery.codeReview.onNoVerdict: "report"` all three are reported,
296
+ not blocking — read the diff yourself before trusting the merge. Under
297
+ `"block"`, `unreviewed` and `partial` halt the close like a CRITICAL
298
+ (`haltCause: "no-verdict"`, blocker naming the fix and the
299
+ `story-review-compute.js` re-run); `--override-review-block` is the escape.
292
300
  - `--max-wait-seconds <n>` — from a headless caller with no host
293
301
  tool-invocation ceiling, to keep single-block semantics
294
302
  without editing the consumer's config.
@@ -545,7 +553,10 @@ state, flips `agent::closing → agent::done` on a confirmed merge (closing the
545
553
  issue) and runs the **same** post-land tail — so the two surfaces cannot
546
554
  diverge. It is idempotent, emits the same terminal envelope, and is safe to
547
555
  re-run while the PR is still open (returns `pending`). The issue closes exactly
548
- when the work has merged, never at PR-open.
556
+ when the work has merged, never at PR-open. It also guarantees a review record:
557
+ a PR landed without close gets the handoff deposit matching its merged head, or
558
+ an `Unreviewed` marker, as its `verification-results` comment
559
+ (`tail.reviewRecord`).
549
560
 
550
561
  ---
551
562
 
@@ -127,12 +127,17 @@ dispatch, pass it as `--worker-tokens <n>` — close records it in its
127
127
  result's local `telemetry`; omit it when the host reports none. Every close
128
128
  command deliver-run renders (a multi-Story run, or a one-Story resume) already
129
129
  carries `--worker-model`, plus `--worker-effort` when the worker ran at a
130
- resume effort.
130
+ resume effort. With `delivery.feedbackLoop.outcomeRecord` on, each close also
131
+ updates the Story's `story-outcome` comment, which
132
+ `node .agents/scripts/story-outcomes-report.js` rolls up.
131
133
 
132
134
  **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
133
135
  post-land tail in one process. Never background it, never delegate it to a
134
136
  child, and never end your turn while it is still running: "close is running"
135
- is not a return value. Branch on the envelope's `status` per **digest § 6**
137
+ is not a return value. On a host that limits background commands (cloud,
138
+ `-p`, Agent SDK, CI) a one-Story close still runs in the foreground but adds
139
+ `--merge-watch-mode async`, so its merge wait moves into the background
140
+ confirm (reference § Async merge-confirm mode). Branch on the envelope's `status` per **digest § 6**
136
141
  (`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
137
142
  → Step 4; `failed` → diagnose, re-run; a `phase: base-sync` conflict comes
138
143
  back with labels untouched — resolve it in `workCwd`, commit, run
@@ -66,6 +66,35 @@ the command exits.
66
66
  a bracketed pattern (`pgrep -f "[m]y-script.js"`) — and always bound the
67
67
  loop with a maximum iteration count so a wrong condition ends the wait
68
68
  instead of the agent.
69
+ - **Time-limited hosts: pass an explicit timeout.** A host that runs
70
+ unattended (a cloud session, a `-p` run, an Agent SDK application, CI)
71
+ limits background commands to 30 minutes by default and 2 hours at most,
72
+ then stops them. Every long command started in the background therefore
73
+ passes an explicit timeout sized to its worst case — on Claude Code,
74
+ `timeout: 7200000` (the 2-hour maximum) beside `run_in_background: true`.
75
+ Pass it on **every** host: it is harmless on a local session, and an agent
76
+ cannot reliably tell the two apart. A host whose background shell takes no
77
+ timeout parameter follows its own limit. The host limit is a safety net,
78
+ not the plan — the delivery commands are idempotent and bounded internally
79
+ (`coverage.timeoutMs`, `mergeWatch.maxBudgetSeconds`).
80
+ - **Never rely on the auto-move.** A foreground command that reaches its
81
+ foreground timeout is moved to the background and gets only 30 minutes
82
+ from the move, whatever timeout it carried — start long work in the
83
+ background instead. Close stays foreground; on a time-limited host it
84
+ runs with `--merge-watch-mode async` so its merge wait moves into the
85
+ background `single-story-confirm-merge.js … --wait`
86
+ ([`deliver-reference.md`](deliver-reference.md) § Async merge-confirm
87
+ mode).
88
+ - **Worst-case sizing.** A credited capture can reach the full-suite lock
89
+ wait plus 2 × `coverage.timeoutMs`. A consumer whose worst case exceeds
90
+ the host maximum lowers `coverage.timeoutMs` or declares the slice over
91
+ budget (exit 76, `onOverBudget`) — no timeout can exceed the maximum.
92
+ - **A stop notice is not silent.** When the host stops `story-handoff.js`,
93
+ `single-story-close.js` or `single-story-confirm-merge.js` at its
94
+ background limit, re-run the same command once with the explicit
95
+ timeout — each is idempotent and resumes. A second stop is a blocker:
96
+ post a `friction` comment naming the command and the limit, and flip
97
+ `agent::blocked`.
69
98
 
70
99
  ## Rule 3 — N parallel `Agent` calls in one turn for N independent units
71
100
 
@@ -578,12 +578,20 @@ for a source that was already `agent::ready`:
578
578
  2. One PATCH sets the new title and body (with the plan fingerprint, so a
579
579
  retried persist adopts the rewritten issue instead of duplicating it),
580
580
  adds the Story's labels and this run's `plan-run::` label, and removes
581
- every `agent::*` label and any earlier run's `plan-run::` label.
581
+ every `agent::*` label and any earlier run's `plan-run::` label. When the
582
+ original body's last non-blank line is a single HTML comment — a
583
+ consumer's machine-readable marker such as
584
+ `<!-- design-lab-ship branch=… sha=… -->` — that line is appended
585
+ verbatim after the fingerprint, so it stays the body's last line. It is
586
+ read from the preserved `plan-rewrite` original when one exists, so a
587
+ re-plan keeps exactly one copy; Mandrel's own fingerprint and
588
+ structured-comment markers are never carried.
582
589
  3. The `story-plan-state` comment, then the terminal `agent::ready` flip.
583
590
 
584
591
  The supersede phase lists the rewritten id under `supersede.rewritten` and
585
592
  neither comments on nor closes it; the result's `rewrite` field names the
586
- ticket or why there was none.
593
+ ticket or why there was none, and `rewrite.preservedMarker` says whether a
594
+ trailing marker was carried (a dry run reports the same answer).
587
595
 
588
596
  **Falls back to create-and-close** with no warning for any other shape
589
597
  (several sources, several Stories), under `--no-rewrite-source`, and under
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,62 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.112.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.111.0...mandrel-v2.112.0) (2026-11-07)
19
+
20
+
21
+ ### ⚠ BREAKING CHANGES
22
+
23
+ * gates.codeReview "degraded" now means reviewed with reduced context only. A review that produced no verdict reports "unreviewed", and one that left part of the diff unreviewed reports "partial"; a consumer reading "degraded" as "no verdict" must read "unreviewed".
24
+ * baselines/crap.json moves to the grouped `files` layout (path -> { "<method key>": crap }) with no startLine, coordinateSystem, anonymous or provenanceStamped, stamped scoringSemantics "method-identity-v5". A baseline in the previous rows[] layout or under any other stamp fails closed; re-seed it with `npm run test:coverage` then `npm run crap:update -- --full-scope` and commit the result with a `baseline-refresh:` subject.
25
+
26
+ ### Added
27
+
28
+ * a deep held code review runs the reviewer at high effort, and a consumer can set the effort for each review depth ([#5976](https://github.com/dsj1984/mandrel/issues/5976)) ([#5996](https://github.com/dsj1984/mandrel/issues/5996)) ([00a7baa](https://github.com/dsj1984/mandrel/commit/00a7baabb16a6a95996273cb3c43ec0a232a650c))
29
+ * a held review survives a base merge that only shifts hunk offsets, and close deposits every review it computes so a retry adopts it ([#5973](https://github.com/dsj1984/mandrel/issues/5973)) ([#5985](https://github.com/dsj1984/mandrel/issues/5985)) ([5d834dc](https://github.com/dsj1984/mandrel/commit/5d834dc87fb1662ea8262be8a6e12b2c543ba8ae))
30
+ * a held-review CRITICAL reaches the worker during handoff preflight, in the same envelope as preflight's findings ([#5966](https://github.com/dsj1984/mandrel/issues/5966)) ([#6008](https://github.com/dsj1984/mandrel/issues/6008)) ([fb801bd](https://github.com/dsj1984/mandrel/commit/fb801bd2a5497f1286c7727a3d81cb05b3987b4c))
31
+ * a host can make CI the coverage and CRAP ratchet of record, and a deferred PR cannot land without that ratchet green ([#5955](https://github.com/dsj1984/mandrel/issues/5955)) ([#6003](https://github.com/dsj1984/mandrel/issues/6003)) ([c67c2b3](https://github.com/dsj1984/mandrel/commit/c67c2b3072082d4b0a01abd282f567b8aa09d884))
32
+ * a Story with no change under crap.targetDirs earns its handoff and close `test` credit from `testChanged`, not the full suite ([#5961](https://github.com/dsj1984/mandrel/issues/5961)) ([#6006](https://github.com/dsj1984/mandrel/issues/6006)) ([bf76aad](https://github.com/dsj1984/mandrel/commit/bf76aad78822b84d4851a44b7b06b1bead7b886d))
33
+ * a Story worktree reads the operator's live .agentrc.local.json from the main checkout, never a stale init-time snapshot ([#5972](https://github.com/dsj1984/mandrel/issues/5972)) ([#5992](https://github.com/dsj1984/mandrel/issues/5992)) ([80f62b5](https://github.com/dsj1984/mandrel/commit/80f62b595a95425fe88eb10f446613b968a8162c))
34
+ * a Story's own small post-credit fix re-measures only the delta's tests, not the whole affected slice ([#5958](https://github.com/dsj1984/mandrel/issues/5958)) ([#6004](https://github.com/dsj1984/mandrel/issues/6004)) ([8301e84](https://github.com/dsj1984/mandrel/commit/8301e842339f3f17d1ecd48eabc8749be394459f))
35
+ * a verified review CRITICAL stays blocking on later runs until the verifier refutes it at a newer head or an operator overrides it, and the PR comment lists every earlier CRITICAL ([#5974](https://github.com/dsj1984/mandrel/issues/5974)) ([#5987](https://github.com/dsj1984/mandrel/issues/5987)) ([f44a73b](https://github.com/dsj1984/mandrel/commit/f44a73b167ebad6f8c8ec9e9e082aa6ad31e5708))
36
+ * anonymous CRAP rows keep their identity across sibling insert, remove, reorder and line re-wrap ([#5969](https://github.com/dsj1984/mandrel/issues/5969)) ([#5981](https://github.com/dsj1984/mandrel/issues/5981)) ([1ca63df](https://github.com/dsj1984/mandrel/commit/1ca63df17b07ab80d0d2cb2f82e7c7083e39eec0))
37
+ * base moves stop voiding credit: a narrower coverage delta rule and an opt-in conflict-only base sync for merge-queue consumers ([#5954](https://github.com/dsj1984/mandrel/issues/5954)) ([#5984](https://github.com/dsj1984/mandrel/issues/5984)) ([fe5c2db](https://github.com/dsj1984/mandrel/commit/fe5c2dbc68ddd7c482f0e4a392261ab0e93f3491))
38
+ * close skips the Story-branch push when origin already holds the branch tip, so pre-push does not re-run on a pushed SHA ([#5967](https://github.com/dsj1984/mandrel/issues/5967)) ([#6010](https://github.com/dsj1984/mandrel/issues/6010)) ([12f4217](https://github.com/dsj1984/mandrel/commit/12f4217e4cc7c8592845c92dc9762e961f8e25d4))
39
+ * coverage capture and the CRAP preview measure a Story's change against origin/&lt;baseBranch&gt;, so a stale local base cannot widen the slice ([#5962](https://github.com/dsj1984/mandrel/issues/5962)) ([#5988](https://github.com/dsj1984/mandrel/issues/5988)) ([650552d](https://github.com/dsj1984/mandrel/commit/650552d4db225640bce7378ce511c79f38db85b4))
40
+ * CRAP scripts leave a baseline stamped with newer scoring semantics untouched and skip the gate instead of rewriting it or failing closed ([#5991](https://github.com/dsj1984/mandrel/issues/5991)) ([#5994](https://github.com/dsj1984/mandrel/issues/5994)) ([fdc29ea](https://github.com/dsj1984/mandrel/commit/fdc29ea525f8b9cb424a1248a0a1262fc445c965))
41
+ * every landed Story PR carries a code-review record, even when it landed without close ([#5975](https://github.com/dsj1984/mandrel/issues/5975)) ([#5993](https://github.com/dsj1984/mandrel/issues/5993)) ([9f9126f](https://github.com/dsj1984/mandrel/commit/9f9126f30a12c6993524156878d5eeb56dd1b86d))
42
+ * every story-handoff run leaves one signal naming its stopping step, cause and per-step time, and close telemetry counts handoff attempts ([#5970](https://github.com/dsj1984/mandrel/issues/5970)) ([#6013](https://github.com/dsj1984/mandrel/issues/6013)) ([c889f5f](https://github.com/dsj1984/mandrel/commit/c889f5f12ff11a0d54646eec8368acc642f959f1))
43
+ * every workflow boot names the open Stories stalled at agent::executing, with the deliver-recover command for each ([#5980](https://github.com/dsj1984/mandrel/issues/5980)) ([#6001](https://github.com/dsj1984/mandrel/issues/6001)) ([8074597](https://github.com/dsj1984/mandrel/commit/8074597db5920d69325ff11c0ac066706c4c5da9))
44
+ * handoff and close failure findings quote the offending rows and the diff-scoped remedy command ([#5968](https://github.com/dsj1984/mandrel/issues/5968)) ([#6011](https://github.com/dsj1984/mandrel/issues/6011)) ([bd297a9](https://github.com/dsj1984/mandrel/commit/bd297a925217fa2e5ac97c5bc86ba43d32976850))
45
+ * handoff and close settle a suite that lost workers to host memory (consumer exit 77) as blocked host-resources, not failing tests ([#5959](https://github.com/dsj1984/mandrel/issues/5959)) ([#6000](https://github.com/dsj1984/mandrel/issues/6000)) ([4f219fa](https://github.com/dsj1984/mandrel/commit/4f219fab6baf0165c2fd542697e54bca34001559))
46
+ * handoff preflight reports every finding in one pass and deposits close's typecheck credit before the suite ([#5957](https://github.com/dsj1984/mandrel/issues/5957)) ([#5989](https://github.com/dsj1984/mandrel/issues/5989)) ([85e6366](https://github.com/dsj1984/mandrel/commit/85e63668d39113eb53f43bb145268d476a342f7d))
47
+ * handoff preflight runs close's independent checks in admitted parallel lanes when a host opts in, and stays serial by default ([#5997](https://github.com/dsj1984/mandrel/issues/5997)) ([#6014](https://github.com/dsj1984/mandrel/issues/6014)) ([108b53c](https://github.com/dsj1984/mandrel/commit/108b53c1c440f278b8d26bbb6f93c8bf17e33ffe))
48
+ * handoff preflight skips a standalone ratchet the consumer's lint already ran on the same tree ([#5964](https://github.com/dsj1984/mandrel/issues/5964)) ([#6007](https://github.com/dsj1984/mandrel/issues/6007)) ([ccf5c96](https://github.com/dsj1984/mandrel/commit/ccf5c96c3d9541cbaa25950adee7028c2d1d3efa))
49
+ * handoff re-scores duplication rows before any credit, so a new clone is fix-required at handoff and close's re-score no-ops ([#5956](https://github.com/dsj1984/mandrel/issues/5956)) ([#5998](https://github.com/dsj1984/mandrel/issues/5998)) ([ebd1ba2](https://github.com/dsj1984/mandrel/commit/ebd1ba23c1e32b1302e5be4b6ffdc5f14e5794aa))
50
+ * handoff seats a Story's new-file baseline rows (MI before preflight, coverage after the capture) so one run reaches ready ([#5960](https://github.com/dsj1984/mandrel/issues/5960)) ([#6005](https://github.com/dsj1984/mandrel/issues/6005)) ([e235926](https://github.com/dsj1984/mandrel/commit/e23592648a94903ce8983672e78d45f720de4300))
51
+ * size-aware suite admission: a sized capture books its tier weight and a marked small run backfills ahead of a queued larger waiter ([#5963](https://github.com/dsj1984/mandrel/issues/5963)) ([#5990](https://github.com/dsj1984/mandrel/issues/5990)) ([3a5a70a](https://github.com/dsj1984/mandrel/commit/3a5a70af197e444f17e75434b1dc533d05016a6b))
52
+ * story handoff retries a GitHub ruleset-evaluation push failure as a first-parent stepped push instead of blocking ([#5965](https://github.com/dsj1984/mandrel/issues/5965)) ([#5995](https://github.com/dsj1984/mandrel/issues/5995)) ([5a68ce6](https://github.com/dsj1984/mandrel/commit/5a68ce67023efdf984cf6ac20d9bb41bcc6ad0d1))
53
+ * the committed CRAP baseline states each file path once and keys methods without startLine, so it stays far below host push-size limits and an edit above a method no longer rewrites its row ([#5971](https://github.com/dsj1984/mandrel/issues/5971)) ([#6002](https://github.com/dsj1984/mandrel/issues/6002)) ([ac40a9e](https://github.com/dsj1984/mandrel/commit/ac40a9e5e307e731be441fec49c302977b212913))
54
+ * the plan critic runs with only Read, Grep and Glob, and a hook keeps the acceptance critic's and auditor's writes under tempRoot ([#5978](https://github.com/dsj1984/mandrel/issues/5978)) ([#5986](https://github.com/dsj1984/mandrel/issues/5986)) ([ff6879c](https://github.com/dsj1984/mandrel/commit/ff6879c2fb224ab71e781de136d13463dd6d0843))
55
+ * the Story-scope review reports whether it reviewed nothing, part, or all of the diff, and a host can make an unreviewed merge block ([#5982](https://github.com/dsj1984/mandrel/issues/5982)) ([#6015](https://github.com/dsj1984/mandrel/issues/6015)) ([a18f741](https://github.com/dsj1984/mandrel/commit/a18f74191704ac128b2db5d9c98eeb95c8a8b900))
56
+ * with an opt-in key, every close attempt adds to one per-Story outcome record on GitHub, and a read-only report rolls those records up by gate and mandrel version ([#5977](https://github.com/dsj1984/mandrel/issues/5977)) ([#5999](https://github.com/dsj1984/mandrel/issues/5999)) ([4c99013](https://github.com/dsj1984/mandrel/commit/4c99013a7482c55b6fe2baceae763f2cc629d17b))
57
+
58
+
59
+ ### Fixed
60
+
61
+ * correct 22 defects found reviewing the changes since 2.111.0 ([#6018](https://github.com/dsj1984/mandrel/issues/6018)) ([15b93aa](https://github.com/dsj1984/mandrel/commit/15b93aad60ea3be7c73c36e15bd953b8fa936546))
62
+ * **test:** make suite-admission AC-6 backfill ordering deterministic on slow spawns (refs [#5963](https://github.com/dsj1984/mandrel/issues/5963)) ([#6009](https://github.com/dsj1984/mandrel/issues/6009)) ([0217f3d](https://github.com/dsj1984/mandrel/commit/0217f3d30a4a06e5f7ee75e10428e6dcd356bcf0))
63
+
64
+ ## [2.111.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.110.0...mandrel-v2.111.0) (2026-11-06)
65
+
66
+
67
+ ### Added
68
+
69
+ * add /audit-state-machines: a read-only lens that finds implicit state machines and the impossible states they can reach ([#5952](https://github.com/dsj1984/mandrel/issues/5952)) ([#5953](https://github.com/dsj1984/mandrel/issues/5953)) ([8ef0489](https://github.com/dsj1984/mandrel/commit/8ef0489c4a464726439a4575bb25574baa79694d))
70
+ * CI digest blames the failed run, not a same-name green one; add an audited governance-label recovery verdict ([#5945](https://github.com/dsj1984/mandrel/issues/5945)) ([#5946](https://github.com/dsj1984/mandrel/issues/5946)) ([1839f9d](https://github.com/dsj1984/mandrel/commit/1839f9df7d6d9482f9ad038ce6c11ea102508cf6))
71
+ * coverage-capture: a consumer-declared over-budget slice defers to CI instead of timing out handoff and close ([#5949](https://github.com/dsj1984/mandrel/issues/5949)) ([#5951](https://github.com/dsj1984/mandrel/issues/5951)) ([7ee6b55](https://github.com/dsj1984/mandrel/commit/7ee6b556667e375d6272b91ffc94160f481dfcf8))
72
+ * plan-persist: keep a source ticket's trailing HTML-comment marker line when rewriting it in place ([#5948](https://github.com/dsj1984/mandrel/issues/5948)) ([#5950](https://github.com/dsj1984/mandrel/issues/5950)) ([1afdfa3](https://github.com/dsj1984/mandrel/commit/1afdfa324452c36a44477c50228051e046fc225d))
73
+
18
74
  ## [2.110.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.109.0...mandrel-v2.110.0) (2026-11-05)
19
75
 
20
76