mandrel 2.111.0 → 2.113.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 (183) 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 +367 -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/merge-envelopes.js +46 -1
  38. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  39. package/.agents/scripts/lib/baselines/reader.js +36 -9
  40. package/.agents/scripts/lib/baselines/refresh-service.js +93 -21
  41. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  42. package/.agents/scripts/lib/baselines/writer.js +36 -21
  43. package/.agents/scripts/lib/changed-files.js +70 -6
  44. package/.agents/scripts/lib/child-exec.js +10 -0
  45. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  46. package/.agents/scripts/lib/close-lock-events.js +8 -3
  47. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  48. package/.agents/scripts/lib/close-validation/gates.js +111 -35
  49. package/.agents/scripts/lib/close-validation/process.js +16 -7
  50. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  51. package/.agents/scripts/lib/close-validation/runner.js +55 -23
  52. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  53. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  54. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  55. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  56. package/.agents/scripts/lib/config/explain.js +5 -2
  57. package/.agents/scripts/lib/config/gates/coverage.schema.js +45 -1
  58. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  59. package/.agents/scripts/lib/config/git-roots.js +38 -4
  60. package/.agents/scripts/lib/config/handoff.js +24 -0
  61. package/.agents/scripts/lib/config/quality.js +26 -13
  62. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  63. package/.agents/scripts/lib/config-resolver.js +22 -2
  64. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  65. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  66. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  67. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  68. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  69. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  70. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  71. package/.agents/scripts/lib/coverage-capture.js +15 -0
  72. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  73. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  74. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  75. package/.agents/scripts/lib/crap-engine.js +3 -3
  76. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  77. package/.agents/scripts/lib/error-redactor.js +20 -0
  78. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  79. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  80. package/.agents/scripts/lib/failure-rows.js +121 -0
  81. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  82. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  83. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  84. package/.agents/scripts/lib/gh-env.js +3 -6
  85. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  86. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  87. package/.agents/scripts/lib/git/baseline-conflict-rows.js +60 -0
  88. package/.agents/scripts/lib/git/sync-from-base.js +18 -9
  89. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  90. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  91. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  92. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  93. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  94. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  95. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  96. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  97. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  98. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  99. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  100. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  101. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  102. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  103. package/.agents/scripts/lib/orchestration/handoff-gates.js +129 -62
  104. package/.agents/scripts/lib/orchestration/handoff-rescore.js +170 -0
  105. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  106. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  107. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  108. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  109. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  110. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  111. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +41 -12
  112. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +90 -39
  113. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  114. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +102 -3
  115. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  116. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  117. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  118. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  119. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  120. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  121. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  122. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  123. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +16 -3
  124. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  125. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +6 -0
  126. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  127. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +9 -12
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +26 -12
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-gate-steps.js +2 -1
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -2
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +50 -17
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  135. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  136. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  137. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  138. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  139. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  140. package/.agents/scripts/lib/orchestration/single-story-close/result.js +30 -13
  141. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  142. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -3
  143. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  144. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +77 -15
  145. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  146. package/.agents/scripts/lib/orchestration/story-handoff.js +796 -196
  147. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  148. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  149. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  150. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  151. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  152. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  153. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  154. package/.agents/scripts/lib/suite-admission.js +20 -8
  155. package/.agents/scripts/lib/suite-sizing.js +146 -0
  156. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  157. package/.agents/scripts/merge-baseline.js +14 -3
  158. package/.agents/scripts/providers/github/comments.js +19 -3
  159. package/.agents/scripts/providers/github.js +1 -0
  160. package/.agents/scripts/review-dispositions-report.js +1 -1
  161. package/.agents/scripts/role-scope-guard.js +267 -0
  162. package/.agents/scripts/single-story-close.js +4 -4
  163. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  164. package/.agents/scripts/single-story-init.js +24 -4
  165. package/.agents/scripts/story-handoff.js +3 -3
  166. package/.agents/scripts/story-outcomes-report.js +231 -0
  167. package/.agents/scripts/story-review-compute.js +9 -5
  168. package/.agents/scripts/update-coverage-baseline.js +12 -2
  169. package/.agents/scripts/update-crap-baseline.js +9 -1
  170. package/.agents/workflows/helpers/code-review.md +63 -9
  171. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  172. package/.agents/workflows/helpers/deliver-reference.md +233 -67
  173. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  174. package/.agents/workflows/helpers/deliver-story.md +7 -2
  175. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  176. package/docs/CHANGELOG.md +55 -0
  177. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  178. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  179. package/lib/cli/doctor-checks/llm-review.js +2 -11
  180. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  181. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  182. package/lib/cli/registry.js +5 -0
  183. package/package.json +1 -1
@@ -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
 
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,61 @@ 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.113.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.112.0...mandrel-v2.113.0) (2026-11-07)
19
+
20
+
21
+ ### Fixed
22
+
23
+ * base sync keeps Story-only baseline rows on a baseline-only conflict, and preflight lint names the handoff-step downgrade ([#6022](https://github.com/dsj1984/mandrel/issues/6022)) ([#6026](https://github.com/dsj1984/mandrel/issues/6026)) ([1c281cd](https://github.com/dsj1984/mandrel/commit/1c281cd3840c52df9025a2a00b3cfede2ae0d171))
24
+ * code-review auth probe retries a non-JSON `claude auth status` once and records a redacted output prefix ([#6021](https://github.com/dsj1984/mandrel/issues/6021)) ([#6024](https://github.com/dsj1984/mandrel/issues/6024)) ([b719dd3](https://github.com/dsj1984/mandrel/commit/b719dd3281fecaa061abcf94610b0dfaa59ed904))
25
+ * duplication re-score moves only the rows a Story caused when baseSync on-conflict skipped the base merge ([#6019](https://github.com/dsj1984/mandrel/issues/6019)) ([#6025](https://github.com/dsj1984/mandrel/issues/6025)) ([1b9354a](https://github.com/dsj1984/mandrel/commit/1b9354af75976a3037db235f49769fc0eae3ae8a))
26
+
27
+ ## [2.112.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.111.0...mandrel-v2.112.0) (2026-11-07)
28
+
29
+
30
+ ### ⚠ BREAKING CHANGES
31
+
32
+ * 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".
33
+ * 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.
34
+
35
+ ### Added
36
+
37
+ * 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))
38
+ * 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))
39
+ * 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))
40
+ * 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))
41
+ * 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))
42
+ * 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))
43
+ * 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))
44
+ * 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))
45
+ * 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))
46
+ * 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))
47
+ * 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))
48
+ * 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))
49
+ * 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))
50
+ * 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))
51
+ * 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))
52
+ * 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))
53
+ * 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))
54
+ * 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))
55
+ * 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))
56
+ * 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))
57
+ * 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))
58
+ * 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))
59
+ * 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))
60
+ * 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))
61
+ * 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))
62
+ * 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))
63
+ * 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))
64
+ * 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))
65
+ * 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))
66
+
67
+
68
+ ### Fixed
69
+
70
+ * 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))
71
+ * **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))
72
+
18
73
  ## [2.111.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.110.0...mandrel-v2.111.0) (2026-11-06)
19
74
 
20
75
 
@@ -0,0 +1,54 @@
1
+ // lib/cli/doctor-checks/coverage-ratchet.js — Doctor check: coverage-ratchet.
2
+
3
+ import fs from 'node:fs';
4
+ import { readEffectiveAgentrc } from './effective-agentrc.js';
5
+
6
+ const KEY = 'delivery.quality.gates.coverage';
7
+
8
+ /** Which setting hands the coverage ratchet to CI, else `null`. */
9
+ function deferringSetting(gate) {
10
+ if (gate.suiteOfRecord === 'ci') return `${KEY}.suiteOfRecord: "ci"`;
11
+ if (gate.onOverBudget === 'defer-to-ci') {
12
+ return `${KEY}.onOverBudget: "defer-to-ci"`;
13
+ }
14
+ return null;
15
+ }
16
+
17
+ /**
18
+ * Fails when coverage can be deferred to CI (`suiteOfRecord: "ci"` or
19
+ * `onOverBudget: "defer-to-ci"`) with no `ciRatchetCheck` naming the CI check
20
+ * that ratchets it — a deferred Story would land unratcheted.
21
+ *
22
+ * @param {{ projectRoot?: string, cwd?: () => string, fsImpl?: { readFileSync: Function, existsSync: Function } }} [opts]
23
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string }>}
24
+ */
25
+ export async function runCoverageRatchet({
26
+ projectRoot,
27
+ cwd,
28
+ fsImpl = fs,
29
+ } = {}) {
30
+ const root = projectRoot ?? (cwd ?? (() => process.cwd()))();
31
+ // The `ci` posture is a host setting, so the local overlay counts.
32
+ const gate =
33
+ readEffectiveAgentrc(root, fsImpl)?.delivery?.quality?.gates?.coverage ??
34
+ {};
35
+ const setting = deferringSetting(gate);
36
+ if (!setting) {
37
+ return {
38
+ ok: true,
39
+ detail: 'coverage is never deferred to CI on this host',
40
+ };
41
+ }
42
+ const check = gate.ciRatchetCheck;
43
+ if (typeof check === 'string' && check.trim().length > 0) {
44
+ return {
45
+ ok: true,
46
+ detail: `${setting} — CI check "${check}" ratchets deferred Stories`,
47
+ };
48
+ }
49
+ return {
50
+ ok: false,
51
+ detail: `${setting} can defer coverage to CI, but no CI check is named to ratchet it — a deferred Story lands with no coverage or CRAP ratchet`,
52
+ remedy: `Set ${KEY}.ciRatchetCheck to the CI check that runs .agents/scripts/coverage-ratchet.js on a deferred PR.`,
53
+ };
54
+ }
@@ -0,0 +1,23 @@
1
+ // Shared doctor-check config read: .agentrc.json with the local overlay.
2
+
3
+ import path from 'node:path';
4
+ import { applyLocalOverlay } from '../../../.agents/scripts/lib/config/agentrc-overlay.js';
5
+ import { readJsonOrNull } from '../../../.agents/scripts/lib/json-utils.js';
6
+
7
+ /**
8
+ * `.agentrc.json` with `.agentrc.local.json` merged over it; an unparseable
9
+ * overlay leaves the committed file in force (the config check reports it).
10
+ *
11
+ * @param {string} projectRoot
12
+ * @param {{ readFileSync: Function, existsSync: Function }} fsImpl
13
+ * @returns {object}
14
+ */
15
+ export function readEffectiveAgentrc(projectRoot, fsImpl) {
16
+ const committed =
17
+ readJsonOrNull(path.join(projectRoot, '.agentrc.json'), fsImpl) ?? {};
18
+ try {
19
+ return applyLocalOverlay({ fsImpl, projectRoot, committed }).effective;
20
+ } catch {
21
+ return committed;
22
+ }
23
+ }
@@ -1,11 +1,9 @@
1
1
  // lib/cli/doctor-checks/llm-review.js — Doctor check: llm-review-provider.
2
2
 
3
3
  import fs from 'node:fs';
4
- import path from 'node:path';
5
- import { applyLocalOverlay } from '../../../.agents/scripts/lib/config/agentrc-overlay.js';
6
4
  import { DEFAULT_REVIEW_PROVIDERS } from '../../../.agents/scripts/lib/config/review-chain-default.js';
7
5
  import { REVIEW_PROVIDER_CLIS } from '../../../.agents/scripts/lib/config/review-provider-clis.js';
8
- import { readJsonSafe } from './read-json.js';
6
+ import { readEffectiveAgentrc } from './effective-agentrc.js';
9
7
  import { spawn } from './spawn.js';
10
8
 
11
9
  const NATIVE_ONLY_ADVISORY =
@@ -20,14 +18,7 @@ const NATIVE_ONLY_ADVISORY =
20
18
  * @returns {{ entries: ReadonlyArray<object>, pinned: boolean }}
21
19
  */
22
20
  function readReviewChain(projectRoot, fsImpl) {
23
- const committed =
24
- readJsonSafe(path.join(projectRoot, '.agentrc.json'), fsImpl) ?? {};
25
- let effective = committed;
26
- try {
27
- effective = applyLocalOverlay({ fsImpl, projectRoot, committed }).effective;
28
- } catch {
29
- // An unparseable overlay is the config check's to report.
30
- }
21
+ const effective = readEffectiveAgentrc(projectRoot, fsImpl);
31
22
  const providers = effective?.delivery?.codeReview?.providers;
32
23
  return Array.isArray(providers) && providers.length > 0
33
24
  ? { entries: providers, pinned: true }
@@ -13,6 +13,7 @@ import {
13
13
  listGeneratedClaudeCommands,
14
14
  } from '../../../.agents/scripts/lib/claude/commands-projection.js';
15
15
  import { getDeliveryRouting } from '../../../.agents/scripts/lib/config/delivery-routing.js';
16
+ import { overlayRoot } from '../../../.agents/scripts/lib/config/git-roots.js';
16
17
  import { projectionParity, readTextOrNull } from './codex.js';
17
18
  import { readJsonSafe } from './read-json.js';
18
19
 
@@ -61,7 +62,10 @@ export function runCommandsInSync({ projectRoot, cwd } = {}) {
61
62
  */
62
63
  function resolveRoleScopedAgentsFlag(projectRoot) {
63
64
  const base = readJsonSafe(path.join(projectRoot, '.agentrc.json'), fs);
64
- const local = readJsonSafe(path.join(projectRoot, '.agentrc.local.json'), fs);
65
+ const local = readJsonSafe(
66
+ path.join(overlayRoot(projectRoot), '.agentrc.local.json'),
67
+ fs,
68
+ );
65
69
  const merged = {
66
70
  delivery: {
67
71
  routing: {
@@ -4,6 +4,7 @@ import fs from 'node:fs';
4
4
  import path from 'node:path';
5
5
  import { COMMANDS_DEFAULTS } from '../../../.agents/scripts/lib/config/commands.js';
6
6
  import { COVERAGE_CAPTURE_DEFAULTS } from '../../../.agents/scripts/lib/config/gates/coverage.schema.js';
7
+ import { overlayRoot } from '../../../.agents/scripts/lib/config/git-roots.js';
7
8
  import { packageScriptArgv } from '../../../.agents/scripts/lib/detect-package-manager.js';
8
9
  import { toPosix } from '../../../.agents/scripts/lib/util/paths.js';
9
10
  import { readJsonSafe } from './read-json.js';
@@ -103,9 +104,13 @@ function scriptNamed(scripts, name) {
103
104
  */
104
105
  function overlaidValue(projectRoot, readFileImpl, pick, accept) {
105
106
  let value;
106
- for (const file of ['.agentrc.json', '.agentrc.local.json']) {
107
+ const files = [
108
+ path.join(projectRoot, '.agentrc.json'),
109
+ path.join(overlayRoot(projectRoot), '.agentrc.local.json'),
110
+ ];
111
+ for (const file of files) {
107
112
  const candidate = pick(
108
- readJsonSafe(path.join(projectRoot, file), {
113
+ readJsonSafe(file, {
109
114
  readFileSync: readFileImpl,
110
115
  }),
111
116
  );
@@ -17,6 +17,7 @@ import {
17
17
  runCodexInstructions,
18
18
  runCodexSkillsInSync,
19
19
  } from './doctor-checks/codex.js';
20
+ import { runCoverageRatchet } from './doctor-checks/coverage-ratchet.js';
20
21
  import { runLlmReviewProvider } from './doctor-checks/llm-review.js';
21
22
  import { runMergeDriver } from './doctor-checks/merge-driver.js';
22
23
  import { runAgentsDrift, runPinCurrent } from './doctor-checks/payload.js';
@@ -138,6 +139,10 @@ export const registry = [
138
139
  advisory: true,
139
140
  run: (opts) => runTestCreditPath(opts),
140
141
  },
142
+ {
143
+ name: 'coverage-ratchet',
144
+ run: (opts) => runCoverageRatchet(opts),
145
+ },
141
146
  ];
142
147
 
143
148
  export default registry;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.111.0",
3
+ "version": "2.113.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",