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
@@ -40,17 +40,17 @@
40
40
  "incomparable": {
41
41
  "type": "integer",
42
42
  "minimum": 0,
43
- "description": "Story #4866: scanned methods the compare REFUSED to resolve because their line coordinate provenance differs from the matching baseline rows'. Reported, never scored — resolving them through the nearest-line drift heuristic is what manufactures a regression no change can satisfy."
43
+ "description": "Deprecated: always 0. The compare that refused methods with differing line-coordinate provenance was removed when CRAP rows stopped being keyed by startLine; kept for envelope compatibility."
44
44
  },
45
45
  "provenanceMismatched": {
46
46
  "type": "integer",
47
47
  "minimum": 0,
48
- "description": "Story #4871: scanned methods whose baseline candidates included at least one row expressed in a DIFFERENT line coordinate system, counted BEFORE the compare's provenance filter discards that evidence. This — not the drifted-row count, which by construction only ever counts rows whose coordinates agreed — is the quantity the unsound-basis backstop compares against its threshold."
48
+ "description": "Deprecated: always 0. CRAP rows no longer carry a line coordinate, so there is no provenance to mismatch; kept for envelope compatibility."
49
49
  },
50
50
  "unscorable": {
51
51
  "type": "integer",
52
52
  "minimum": 0,
53
- "description": "Story #4871: methods the scan could not score because no coverage artifact covered them. Reported rather than computed from an assumed zero percent coverage (which would drive CRAP maximal on untouched files), and excluded from the denominator of the unsound-basis ratio."
53
+ "description": "Story #4871: methods the scan could not score because no coverage artifact covered them. Reported rather than computed from an assumed zero percent coverage (which would drive CRAP maximal on untouched files)."
54
54
  },
55
55
  "removed": { "type": "integer", "minimum": 0 },
56
56
  "skippedNoCoverage": { "type": "integer", "minimum": 0 },
@@ -118,7 +118,7 @@
118
118
  },
119
119
  "diagnostics": {
120
120
  "type": "array",
121
- "description": "Story #4866: named, gate-level findings emitted INSTEAD of per-method verdicts when the gate has established that no verdict it could produce would be meaningful — an incomparable baseline, or a comparison basis whose drifted-row ratio proves the two sides disagree on line coordinates. Present only in that case; `violations` is then empty and the preview gate exits 0.",
121
+ "description": "Story #4866: named, gate-level findings emitted INSTEAD of per-method verdicts when the gate has established that no verdict it could produce would be meaningful — an incomparable baseline or a baseline stamped ahead of the running code. Present only in that case; `violations` is then empty and the preview gate exits 0. `crap-unsound-comparison-basis` is a retired name kept in the enum for compatibility and no longer emitted.",
122
122
  "items": {
123
123
  "type": "object",
124
124
  "required": ["name", "message"],
@@ -128,7 +128,8 @@
128
128
  "type": "string",
129
129
  "enum": [
130
130
  "crap-unsound-comparison-basis",
131
- "crap-baseline-incompatible"
131
+ "crap-baseline-incompatible",
132
+ "crap-baseline-ahead"
132
133
  ]
133
134
  },
134
135
  "message": { "type": "string" }
@@ -77,10 +77,19 @@
77
77
  },
78
78
  "gates": {
79
79
  "type": "object",
80
- "description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one. \"overridden\" is distinct from both: the gate ran, it FAILED, and an operator authorized delivery anyway via --override-review-block with a recorded reason. Reporting that as \"passed\" would erase the one fact a reader of this envelope most needs, and reporting it as \"skipped\" would claim the gate never ran. \"degraded\" (codeReview only, Story #5663) means a review surface ran but produced no verdict (CLI not logged in, out of quota, unparseable output); it is reported, not blocking, and ranks below \"overridden\".",
80
+ "description": "Outcome of each close gate this invocation was responsible for. A gate the run skipped (--skip-validation, or a phase it never reached) reports \"skipped\" rather than being omitted, so a missing gate is never mistaken for a passing one. \"overridden\" is distinct from both: the gate ran, it FAILED, and an operator authorized delivery anyway via --override-review-block with a recorded reason. Reporting that as \"passed\" would erase the one fact a reader of this envelope most needs, and reporting it as \"skipped\" would claim the gate never ran. codeReview alone also reports \"unreviewed\" (a review produced no verdict at all: CLI not logged in, out of quota, unparseable output, a skipped optional reviewer, an unresolvable base), \"partial\" (part of the diff went unreviewed) and \"degraded\" (the diff was reviewed with reduced context only), with precedence overridden > unreviewed > partial > degraded > passed. All three are reported, not blocking, unless delivery.codeReview.onNoVerdict is \"block\", which halts on unreviewed or partial. \"deferred\" (coverage-capture only, Story #5949) means the capture script declared its slice over this host's budget (exit 76) under coverage.onOverBudget: defer-to-ci, or that coverage.suiteOfRecord: ci (Story #5955) deferred it before anything spawned — no suite ran, the coverage-reading gates report \"skipped\", and CI owns the run.",
81
81
  "additionalProperties": {
82
82
  "type": "string",
83
- "enum": ["passed", "failed", "skipped", "overridden", "degraded"]
83
+ "enum": [
84
+ "passed",
85
+ "failed",
86
+ "skipped",
87
+ "overridden",
88
+ "unreviewed",
89
+ "partial",
90
+ "degraded",
91
+ "deferred"
92
+ ]
84
93
  }
85
94
  },
86
95
  "tail": {
@@ -97,6 +106,10 @@
97
106
  "epicRollup"
98
107
  ],
99
108
  "properties": {
109
+ "reviewRecord": {
110
+ "type": "boolean",
111
+ "description": "The merged PR carries a verification-results review record: close's own post (details.reviewRecord already-recorded), the handoff deposit matching the merged head posted at land (posted-from-deposit), or an Unreviewed marker (unreviewed-no-deposit | unreviewed-stale-deposit). A tail run without a PR number reports true with no-pr. Only a failed read or post reports false, and like every tail step that degrades the report, never the land."
112
+ },
100
113
  "followUps": { "type": "boolean" },
101
114
  "statusResync": { "type": "boolean" },
102
115
  "worktreeReap": {
@@ -162,7 +175,12 @@
162
175
  "description": "Present iff status === \"failed\".",
163
176
  "required": ["reason"],
164
177
  "properties": {
165
- "reason": { "type": "string", "minLength": 1 }
178
+ "reason": { "type": "string", "minLength": 1 },
179
+ "baselinesKinds": {
180
+ "type": "array",
181
+ "description": "Story #5956 — the check-baselines kinds that reported FAIL when close failed on a baselines entry; omitted when no kind line parsed.",
182
+ "items": { "type": "string", "minLength": 1 }
183
+ }
166
184
  },
167
185
  "additionalProperties": false
168
186
  },
@@ -225,6 +243,18 @@
225
243
  "ageSeconds": { "type": ["number", "null"], "minimum": 0 }
226
244
  },
227
245
  "additionalProperties": false
246
+ },
247
+ "admission": {
248
+ "type": "object",
249
+ "description": "Story #5963 — what the last declared run that waited was admitted at: its booked weight, the entry's declared weight, the sized slice's test-file count (null when unsized) and whether it backfilled ahead of an earlier waiter.",
250
+ "required": ["weight", "declaredWeight", "sliceFiles", "backfilled"],
251
+ "properties": {
252
+ "weight": { "type": "integer", "minimum": 1 },
253
+ "declaredWeight": { "type": "integer", "minimum": 1 },
254
+ "sliceFiles": { "type": ["integer", "null"], "minimum": 0 },
255
+ "backfilled": { "type": "boolean" }
256
+ },
257
+ "additionalProperties": false
228
258
  }
229
259
  },
230
260
  "additionalProperties": false
@@ -259,6 +289,22 @@
259
289
  "description": "Story #5417 — wall-clock seconds per close phase that ran (wrong-tree-guard, base-sync, close-validation, push, pull-request, code-review, auto-merge, confirm-merge, post-land). Optional and additive; absent or null when no phase was timed.",
260
290
  "additionalProperties": { "type": "number", "minimum": 0 }
261
291
  },
292
+ "baseSync": {
293
+ "type": ["object", "null"],
294
+ "description": "Story #5954 — close's base-sync decision under delivery.close.baseSync: mode (always | on-conflict), outcome (merged | already-current | skipped), reason (the mode itself, conflict-free on a skip, or the probe answer that forced a merge: conflict, intersects, unsupported, fetch-failed, already-current) and incoming (paths the base brought in). Optional and additive; null when no sync ran (--skip-sync, or a PR that had already landed).",
295
+ "required": ["mode", "outcome", "reason", "incoming"],
296
+ "properties": {
297
+ "mode": { "enum": ["always", "on-conflict"] },
298
+ "outcome": { "enum": ["merged", "already-current", "skipped"] },
299
+ "reason": { "type": "string", "minLength": 1 },
300
+ "incoming": { "type": "integer", "minimum": 0 }
301
+ },
302
+ "additionalProperties": false
303
+ },
304
+ "pushOutcome": {
305
+ "enum": ["pushed", "skipped-already-at-head", null],
306
+ "description": "Story #5967 — whether close's PR-opening push ran or was skipped because origin already held the Story-branch tip (read phaseDurations.push against it). Optional and additive; absent on every non-close envelope, null when the PR had already landed."
307
+ },
262
308
  "timestamp": { "type": "string", "format": "date-time" }
263
309
  },
264
310
  "allOf": [
@@ -26,7 +26,7 @@
26
26
  "phase": {
27
27
  "type": "string",
28
28
  "minLength": 1,
29
- "description": "For close, the phase name close passes to setPhase (the phaseDurations keys). For handoff, the step name: preflight, base-merge, credited-run, seat, push, review."
29
+ "description": "For close, the phase name close passes to setPhase (the phaseDurations keys). For handoff, the step name: base-merge, duplication-rescore, seat-static, preflight, credited-run, seat, post-capture, push, review."
30
30
  },
31
31
  "stageStartedAt": {
32
32
  "type": "string",
@@ -75,12 +75,12 @@
75
75
  "scope": {
76
76
  "type": "string",
77
77
  "enum": ["full", "delta"],
78
- "description": "Optional note on how the pass was earned. `delta` is close's `test` delta re-credit: after a base sync, only the tests affected by the commits since `since` ran (`project.commands.testChanged`), and the record credits the merged tree under the full-suite identity."
78
+ "description": "Optional note on how the pass was earned. `delta` is close's `test` delta re-credit: after a base sync, only the tests affected by the commits since `since` ran (`project.commands.testChanged`), and the record credits the merged tree under the full-suite identity. It also marks the skip-branch first credit: a Story with no change under `crap.targetDirs` ran `testChanged` keyed on the `origin/<baseBranch>` merge-base `since`, credited under the same identity."
79
79
  },
80
80
  "since": {
81
81
  "type": "string",
82
82
  "pattern": "^[0-9a-f]{7,64}$",
83
- "description": "With `scope: delta`, the credited commit the affected-tests run was keyed on."
83
+ "description": "With `scope: delta`, the commit the affected-tests run was keyed on (the credited pre-sync head, or the skip-branch merge-base)."
84
84
  },
85
85
  "timestamp": {
86
86
  "type": "string",
@@ -13,7 +13,8 @@
13
13
  * tree and the tree this process runs from are never touched.
14
14
  *
15
15
  * Then it flips closed Stories stranded at `agent::closing` to
16
- * `agent::done` (`closingReconcile`).
16
+ * `agent::done` (`closingReconcile`), and reports — never touches — open
17
+ * `agent::executing` Stories stalled with no open PR (`stalledExecuting`).
17
18
  *
18
19
  * `content-merged` branches (merge-tree equivalence — no merge check ever
19
20
  * validated their exact diff) are never reaped here, only reported for
@@ -31,6 +32,7 @@ import { sweepStaleStoryWorktrees } from './lib/orchestration/plan-runner/worktr
31
32
  import { createProvider } from './lib/provider-factory.js';
32
33
  import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
33
34
  import { reconcileStrandedClosing } from './lib/single-story-sweep/reconcile-closing.js';
35
+ import { reportStalledExecuting } from './lib/single-story-sweep/report-stalled-executing.js';
34
36
  import {
35
37
  acquireSweepLock,
36
38
  resolveSweepLockPath,
@@ -66,6 +68,10 @@ the outcome lands under "worktreeSweep".
66
68
  Then flips closed Stories still labelled agent::closing whose story-<id> PR
67
69
  is MERGED to agent::done (at most 10 per run); the outcome lands under
68
70
  "closingReconcile".
71
+ Then reports (read-only) open agent::executing Stories whose story-<id>
72
+ origin head is older than the stall threshold and that have no open PR,
73
+ each with its deliver-recover.js command (at most 20 probed per run); the
74
+ outcome lands under "stalledExecuting".
69
75
  Branches detected only via the weaker content-equivalence signal
70
76
  (detectedBy: 'content-merged') are never reaped here — they are reported
71
77
  under "contentMerged" (and a routing hint in the summary line) for the
@@ -77,6 +83,8 @@ Options:
77
83
  --current <branch> A branch to always exclude (e.g. the active story).
78
84
  --base <branch> Base branch to fast-forward. Default: project baseBranch.
79
85
  --no-fast-forward Skip the base-branch fast-forward step.
86
+ --stalled-after-hours <n>
87
+ Stall threshold in hours (positive). Default: 6.
80
88
  --json Emit the result envelope as JSON.
81
89
  `;
82
90
 
@@ -154,10 +162,12 @@ export async function runWorktreeSweep({
154
162
  * acquireLockFn?: Function,
155
163
  * purgeFn?: Function,
156
164
  * closingReconcileFn?: Function,
165
+ * stalledExecutingFn?: Function,
166
+ * stalledAfterHours?: unknown,
157
167
  * logger?: { info?: Function, warn?: Function },
158
168
  * }} [args]
159
169
  * @returns {Promise<object>} the {@link sweepMergedBranches} envelope plus
160
- * `worktreeSweep`, `closingReconcile` and `tempPurge`.
170
+ * `worktreeSweep`, `closingReconcile`, `stalledExecuting` and `tempPurge`.
161
171
  */
162
172
  export async function runBootSweep({
163
173
  cwd,
@@ -173,6 +183,8 @@ export async function runBootSweep({
173
183
  acquireLockFn = acquireSweepLock,
174
184
  purgeFn = sweepTempRetention,
175
185
  closingReconcileFn = reconcileStrandedClosing,
186
+ stalledExecutingFn = reportStalledExecuting,
187
+ stalledAfterHours,
176
188
  logger = Logger,
177
189
  } = {}) {
178
190
  const root = path.resolve(cwd ?? PROJECT_ROOT);
@@ -233,6 +245,17 @@ export async function runBootSweep({
233
245
  },
234
246
  });
235
247
 
248
+ const stalledExecuting = await stalledExecutingFn({
249
+ provider,
250
+ config,
251
+ stalledAfterHours,
252
+ excludeStoryIds: [parseStoryBranch(current)],
253
+ logger: {
254
+ info: (m) => logger.info?.(`[boot-sweep] ${m}`),
255
+ warn: (m) => logger.warn?.(`[boot-sweep] ${m}`),
256
+ },
257
+ });
258
+
236
259
  // Temp-retention catch-up: reaped branches are confirmed merges, so their
237
260
  // artifacts are spent; the age floor collects the rest.
238
261
  const purge = await purgeFn({
@@ -241,7 +264,13 @@ export async function runBootSweep({
241
264
  label: 'boot-sweep',
242
265
  logger,
243
266
  });
244
- return { ...result, worktreeSweep, closingReconcile, tempPurge: purge };
267
+ return {
268
+ ...result,
269
+ worktreeSweep,
270
+ closingReconcile,
271
+ stalledExecuting,
272
+ tempPurge: purge,
273
+ };
245
274
  } catch (err) {
246
275
  const msg = err?.message ?? String(err);
247
276
  logger.warn?.(`[boot-sweep] sweep threw (host continues): ${msg}`);
@@ -282,6 +311,13 @@ export function buildSummaryLine(result) {
282
311
  result.closingReconcile?.reconciled,
283
312
  (n) => `flipped ${n} stranded agent::closing Story(ies) to agent::done`,
284
313
  ),
314
+ countSuffix(
315
+ result.stalledExecuting?.stalled,
316
+ (n) =>
317
+ `${n} agent::executing Story(ies) idle over ${result.stalledExecuting.thresholdHours}h with no open PR — run ${result.stalledExecuting.stalled
318
+ .map((s) => `deliver-recover.js --story ${s.storyId}`)
319
+ .join(', ')}`,
320
+ ),
285
321
  countSuffix(
286
322
  result.contentMerged,
287
323
  (n) => `${n} content-merged branch(es) left for /clean-git`,
@@ -310,6 +346,7 @@ export async function runBootSweepCli(
310
346
  exclude: { type: 'string', multiple: true, default: [] },
311
347
  current: { type: 'string' },
312
348
  'no-fast-forward': { type: 'boolean', default: false },
349
+ 'stalled-after-hours': { type: 'string' },
313
350
  json: { type: 'boolean', default: false },
314
351
  help: { type: 'boolean', short: 'h' },
315
352
  },
@@ -328,6 +365,7 @@ export async function runBootSweepCli(
328
365
  exclude: Array.isArray(values.exclude) ? values.exclude : [],
329
366
  current: typeof values.current === 'string' ? values.current : undefined,
330
367
  fastForward: values['no-fast-forward'] !== true,
368
+ stalledAfterHours: values['stalled-after-hours'],
331
369
  });
332
370
 
333
371
  if (values.json) {
@@ -14,9 +14,12 @@
14
14
  * it also refused the depositing run, leaving no path that could deposit.
15
15
  *
16
16
  * Exit codes: 0 fresh/skipped/captured; 1 capture failed or refused (callers
17
- * MUST surface it); 75 lock wait expired, nothing spawned; 124 suite timed out.
17
+ * MUST surface it); 75 lock wait expired, nothing spawned; 76 the capture
18
+ * script declared its slice over this host's budget, nothing ran or was
19
+ * stamped (callers settle it by `coverage.onOverBudget`); 77 the run lost
20
+ * workers to host memory with no failing test (callers block); 124 suite timed out.
18
21
  */
19
- import { getChangedFiles } from './lib/changed-files.js';
22
+ import { getChangedFiles, resolveCaptureBaseRef } from './lib/changed-files.js';
20
23
  import { isDirectInvocation } from './lib/cli-utils.js';
21
24
  import { claimLockEventSink, lockEventHooks } from './lib/close-lock-events.js';
22
25
  import { getQuality, resolveConfig } from './lib/config-resolver.js';
@@ -43,7 +46,7 @@ import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
43
46
  import { formatSuiteTimings } from './lib/supervised-suite.js';
44
47
 
45
48
  /**
46
- * A `null` ref defers the fallback to `resolveChangedFilesRef`.
49
+ * A `null` ref defers the fallback to `resolveCaptureBaseRef`.
47
50
  * @param {string[]} argv
48
51
  * @returns {{ skipWhenNoCrapFiles: boolean, requireCredited: boolean, ref: string | null, cwd: string }}
49
52
  */
@@ -70,6 +73,7 @@ export function parseArgs(argv) {
70
73
  * resolveConfigImpl?: typeof resolveConfig,
71
74
  * getQualityImpl?: typeof getQuality,
72
75
  * getChangedFilesImpl?: typeof getChangedFiles,
76
+ * resolveBaseRefImpl?: typeof resolveCaptureBaseRef,
73
77
  * readPackageScriptsImpl?: typeof readPackageScripts,
74
78
  * hasNpmScriptImpl?: typeof hasNpmScript,
75
79
  * isCoverageFreshImpl?: typeof isCoverageFresh,
@@ -114,6 +118,7 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
114
118
  logger,
115
119
  });
116
120
  if (refused !== null) return refused;
121
+ resolveRunRefs({ crap, args, config, deps, logger });
117
122
 
118
123
  // Outermost first: the credit probe announces or refuses the run, and only
119
124
  // a surviving run reaches the host-level full-suite lock.
@@ -162,6 +167,37 @@ export async function runCoverageCapture(argv = process.argv, deps = {}) {
162
167
  return code;
163
168
  }
164
169
 
170
+ /**
171
+ * Resolves the changed-files ref once so every pass, and the affected
172
+ * script's `MANDREL_COVERAGE_BASE_REF`, measures against the same ref.
173
+ */
174
+ function resolveRunRefs({ crap, args, config, deps, logger }) {
175
+ const baseBranch = config?.project?.baseBranch;
176
+ args.baseBranchRef = `origin/${baseBranch ?? 'main'}`;
177
+ const resolve = deps.resolveBaseRefImpl ?? resolveCaptureBaseRef;
178
+ const resolved = resolve({ crap, ref: args.ref, baseBranch, cwd: args.cwd });
179
+ args.ref = resolved.ref;
180
+ logRunRef(resolved, logger);
181
+ }
182
+
183
+ function logRunRef({ ref, source, unresolved }, logger) {
184
+ if (source === 'local-fallback') {
185
+ logger.warn(
186
+ `[coverage-capture] ⚠ ${unresolved} does not resolve in this clone — measuring changed files against the local ${ref} instead.`,
187
+ );
188
+ return;
189
+ }
190
+ logger.info(
191
+ `[coverage-capture] Changed files measured against ${ref} (${SOURCE_LABELS[source]}).`,
192
+ );
193
+ }
194
+
195
+ const SOURCE_LABELS = {
196
+ flag: '--ref',
197
+ config: 'incrementalCoverage.baseRef',
198
+ remote: 'default: origin/<baseBranch>',
199
+ };
200
+
165
201
  /**
166
202
  * The credited runner, failing a green run that wrote no artifact at the
167
203
  * pass's source.
@@ -0,0 +1,106 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * coverage-ratchet.js — CI's hand-back for a Story whose coverage capture was
4
+ * deferred to CI (`Coverage-deferred:` in the PR body). Adopts the artifact
5
+ * CI produced at `--head`, then runs the per-file coverage and CRAP value
6
+ * ratchet over it against `--base`. Exit 0: the ratchet holds; 1: refused
7
+ * or a ratchet step failed (named on stderr).
8
+ */
9
+
10
+ import path from 'node:path';
11
+ import { fileURLToPath } from 'node:url';
12
+
13
+ import { spawnChild } from './lib/child-exec.js';
14
+ import { runAsCli } from './lib/cli-utils.js';
15
+ import { getQuality, resolveConfig } from './lib/config-resolver.js';
16
+ import {
17
+ adoptArtifact,
18
+ parseRatchetArgs,
19
+ ratchetSteps,
20
+ scoreRatchet,
21
+ } from './lib/coverage-ratchet.js';
22
+ import { Logger } from './lib/Logger.js';
23
+
24
+ const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
25
+
26
+ const USAGE = {
27
+ invocation:
28
+ 'node .agents/scripts/coverage-ratchet.js --artifact <path> --head <sha> [--scope affected|full] [--base <ref>] [--adopt-only]',
29
+ summary:
30
+ "Adopt a CI-produced Istanbul coverage-final.json at the checked-out HEAD (placed at `delivery.quality.gates.coverage.coveragePath` and stamped like a green local capture), then run the coverage and CRAP value ratchet over it. CI's sharding and artifact merging stay the consumer's job.",
31
+ flags: [
32
+ ['--artifact <path>', 'The CI-produced coverage-final.json.'],
33
+ [
34
+ '--head <sha>',
35
+ 'The commit the artifact measured; refused unless it is the checked-out HEAD.',
36
+ ],
37
+ [
38
+ '--scope affected|full',
39
+ 'What the artifact measured. Default `affected`.',
40
+ ],
41
+ ['--base <ref>', 'The ratchet base. Default `origin/<baseBranch>`.'],
42
+ [
43
+ '--adopt-only',
44
+ 'Place and stamp the artifact, skip the ratchet (seat rows from it next).',
45
+ ],
46
+ ],
47
+ notes: [
48
+ 'Refuses (exit 1) a dirty tracked tree and a missing or unparseable artifact.',
49
+ 'On a pull_request event pass `--head "$(git rev-parse HEAD)"` from the job that produced the artifact; this job must check out the same ref.',
50
+ ],
51
+ };
52
+
53
+ /** Spawn one ratchet step in `cwd`, output passed through. */
54
+ function runStep(cwd) {
55
+ return (args, env) =>
56
+ spawnChild(process.execPath, args, {
57
+ cwd,
58
+ stdio: 'inherit',
59
+ env: env ? { ...process.env, ...env } : process.env,
60
+ }).status ?? 1;
61
+ }
62
+
63
+ async function main() {
64
+ const cwd = process.cwd();
65
+ const args = parseRatchetArgs(process.argv.slice(2));
66
+ if (args.error) {
67
+ Logger.error(`[coverage-ratchet] ✖ ${args.error}`);
68
+ return 1;
69
+ }
70
+ const config = resolveConfig({ cwd });
71
+ const base = args.base ?? `origin/${config?.project?.baseBranch ?? 'main'}`;
72
+ const refusal = adoptArtifact({
73
+ cwd,
74
+ quality: getQuality(config),
75
+ ...args,
76
+ base,
77
+ });
78
+ if (refusal) {
79
+ Logger.error(`[coverage-ratchet] ✖ refused: ${refusal}`);
80
+ return 1;
81
+ }
82
+ Logger.info(
83
+ `[coverage-ratchet] adopted ${args.artifact} at ${args.head} (${args.scope} scope)`,
84
+ );
85
+ if (args.adoptOnly) return 0;
86
+ const { failedStep, status } = await scoreRatchet(
87
+ ratchetSteps(SCRIPTS_DIR, base),
88
+ runStep(cwd),
89
+ );
90
+ if (failedStep) {
91
+ Logger.error(
92
+ `[coverage-ratchet] ✖ ${failedStep} failed (exit ${status}) — the coverage/CRAP ratchet does not hold against ${base}`,
93
+ );
94
+ return 1;
95
+ }
96
+ Logger.info(
97
+ `[coverage-ratchet] ✅ coverage and CRAP ratchet hold against ${base}`,
98
+ );
99
+ return 0;
100
+ }
101
+
102
+ runAsCli(import.meta.url, main, {
103
+ source: 'coverage-ratchet',
104
+ usage: USAGE,
105
+ propagateExitCode: true,
106
+ });