mandrel 2.111.0 → 2.112.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (178) hide show
  1. package/.agents/agents/acceptance-critic.md +14 -0
  2. package/.agents/agents/auditor.md +14 -0
  3. package/.agents/agents/plan-critic.md +5 -0
  4. package/.agents/agents/story-worker.md +4 -1
  5. package/.agents/docs/agentrc-reference.json +22 -10
  6. package/.agents/docs/configuration.md +351 -37
  7. package/.agents/docs/execution-reference.md +11 -0
  8. package/.agents/rules/git-conventions-reference.md +7 -0
  9. package/.agents/schemas/agentrc.schema.json +174 -14
  10. package/.agents/schemas/baselines/baseline-envelope.schema.json +16 -4
  11. package/.agents/schemas/baselines/bundle-size.schema.json +1 -0
  12. package/.agents/schemas/baselines/coverage.schema.json +1 -0
  13. package/.agents/schemas/baselines/crap.schema.json +37 -10
  14. package/.agents/schemas/baselines/duplication.schema.json +1 -0
  15. package/.agents/schemas/baselines/maintainability.schema.json +1 -0
  16. package/.agents/schemas/baselines/mutation.schema.json +1 -0
  17. package/.agents/schemas/crap-report.schema.json +6 -5
  18. package/.agents/schemas/story-deliver-terminal.schema.json +41 -2
  19. package/.agents/schemas/story-progress.schema.json +1 -1
  20. package/.agents/schemas/validation-evidence.schema.json +2 -2
  21. package/.agents/scripts/boot-sweep.js +41 -3
  22. package/.agents/scripts/coverage-capture.js +37 -3
  23. package/.agents/scripts/coverage-ratchet.js +106 -0
  24. package/.agents/scripts/evidence-gate.js +84 -21
  25. package/.agents/scripts/lib/audit-baselines/read.js +8 -1
  26. package/.agents/scripts/lib/audit-baselines/trend.js +2 -1
  27. package/.agents/scripts/lib/baseline-loader.js +4 -2
  28. package/.agents/scripts/lib/baselines/codec.js +57 -0
  29. package/.agents/scripts/lib/baselines/crap-preview-incremental.js +8 -3
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +10 -16
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +4 -13
  32. package/.agents/scripts/lib/baselines/kernel.js +19 -1
  33. package/.agents/scripts/lib/baselines/kinds/_crap-codec.js +171 -0
  34. package/.agents/scripts/lib/baselines/kinds/_crap-read.js +56 -16
  35. package/.agents/scripts/lib/baselines/kinds/_shared-metric.js +0 -59
  36. package/.agents/scripts/lib/baselines/kinds/crap.js +283 -319
  37. package/.agents/scripts/lib/baselines/preview-gates.js +29 -10
  38. package/.agents/scripts/lib/baselines/reader.js +36 -9
  39. package/.agents/scripts/lib/baselines/refresh-service.js +79 -18
  40. package/.agents/scripts/lib/baselines/seat-missing.js +173 -7
  41. package/.agents/scripts/lib/baselines/writer.js +36 -21
  42. package/.agents/scripts/lib/changed-files.js +70 -6
  43. package/.agents/scripts/lib/child-exec.js +10 -0
  44. package/.agents/scripts/lib/claude/agents-projection.js +5 -5
  45. package/.agents/scripts/lib/close-lock-events.js +8 -3
  46. package/.agents/scripts/lib/close-validation/ci-deferral.js +40 -0
  47. package/.agents/scripts/lib/close-validation/gates.js +111 -35
  48. package/.agents/scripts/lib/close-validation/process.js +16 -7
  49. package/.agents/scripts/lib/close-validation/projections/crap.js +43 -10
  50. package/.agents/scripts/lib/close-validation/runner.js +55 -23
  51. package/.agents/scripts/lib/close-validation/skip-branch-test.js +144 -0
  52. package/.agents/scripts/lib/close-validation/test-delta.js +33 -8
  53. package/.agents/scripts/lib/codex/agents-projection.js +6 -0
  54. package/.agents/scripts/lib/config/agentrc-overlay.js +9 -5
  55. package/.agents/scripts/lib/config/explain.js +5 -2
  56. package/.agents/scripts/lib/config/gates/coverage.schema.js +45 -1
  57. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  58. package/.agents/scripts/lib/config/git-roots.js +38 -4
  59. package/.agents/scripts/lib/config/handoff.js +24 -0
  60. package/.agents/scripts/lib/config/quality.js +26 -13
  61. package/.agents/scripts/lib/config/worktree-isolation.js +2 -5
  62. package/.agents/scripts/lib/config-resolver.js +22 -2
  63. package/.agents/scripts/lib/config-settings-schema-delivery.js +87 -4
  64. package/.agents/scripts/lib/config-settings-schema-quality.js +36 -1
  65. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +1 -0
  67. package/.agents/scripts/lib/coverage-capture-delta.js +164 -32
  68. package/.agents/scripts/lib/coverage-capture-own-fix.js +232 -0
  69. package/.agents/scripts/lib/coverage-capture-usage.js +2 -2
  70. package/.agents/scripts/lib/coverage-capture.js +15 -0
  71. package/.agents/scripts/lib/coverage-deferral.js +96 -0
  72. package/.agents/scripts/lib/coverage-ratchet.js +187 -0
  73. package/.agents/scripts/lib/crap-baseline-join.js +5 -5
  74. package/.agents/scripts/lib/crap-engine.js +3 -3
  75. package/.agents/scripts/lib/crap-method-identity.js +104 -48
  76. package/.agents/scripts/lib/escomplex-anchor.js +135 -0
  77. package/.agents/scripts/lib/escomplex-kernel.js +30 -1
  78. package/.agents/scripts/lib/failure-rows.js +121 -0
  79. package/.agents/scripts/lib/full-suite-lock.js +44 -4
  80. package/.agents/scripts/lib/full-suite-queue.js +89 -13
  81. package/.agents/scripts/lib/generated/agentrc-validator.js +8 -2
  82. package/.agents/scripts/lib/gh-env.js +3 -6
  83. package/.agents/scripts/lib/gh-pr-rest.js +1 -0
  84. package/.agents/scripts/lib/git/base-sync-probe.js +182 -0
  85. package/.agents/scripts/lib/git-branch-lifecycle.js +9 -0
  86. package/.agents/scripts/lib/observability/close-telemetry.js +37 -2
  87. package/.agents/scripts/lib/observability/handoff-telemetry.js +170 -0
  88. package/.agents/scripts/lib/observability/review-dispositions.js +23 -6
  89. package/.agents/scripts/lib/observability/runtime-friction.js +17 -4
  90. package/.agents/scripts/lib/observability/source-classifier.js +3 -0
  91. package/.agents/scripts/lib/observability/story-outcome.js +393 -0
  92. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +2 -1
  93. package/.agents/scripts/lib/orchestration/check-baselines/phases/evaluate.js +19 -1
  94. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +84 -0
  95. package/.agents/scripts/lib/orchestration/check-baselines/phases/pipeline.js +14 -5
  96. package/.agents/scripts/lib/orchestration/check-baselines/phases/refresh-ack.js +3 -2
  97. package/.agents/scripts/lib/orchestration/check-baselines/phases/report.js +26 -6
  98. package/.agents/scripts/lib/orchestration/code-review.js +223 -19
  99. package/.agents/scripts/lib/orchestration/handoff-gates.js +129 -62
  100. package/.agents/scripts/lib/orchestration/handoff-rescore.js +169 -0
  101. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +45 -0
  102. package/.agents/scripts/lib/orchestration/preflight-lanes.js +208 -0
  103. package/.agents/scripts/lib/orchestration/review-base-ref.js +40 -17
  104. package/.agents/scripts/lib/orchestration/review-deposit.js +38 -12
  105. package/.agents/scripts/lib/orchestration/review-depth.js +21 -0
  106. package/.agents/scripts/lib/orchestration/review-history.js +124 -20
  107. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +23 -8
  108. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +82 -39
  109. package/.agents/scripts/lib/orchestration/review-providers/critical-verifier.js +64 -11
  110. package/.agents/scripts/lib/orchestration/review-providers/degraded-gates.js +98 -3
  111. package/.agents/scripts/lib/orchestration/review-providers/finding-identity.js +6 -2
  112. package/.agents/scripts/lib/orchestration/review-providers/findings-renderer.js +55 -8
  113. package/.agents/scripts/lib/orchestration/review-providers/review-guidance.js +1 -0
  114. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +42 -15
  115. package/.agents/scripts/lib/orchestration/review-providers/types.js +6 -0
  116. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +10 -1
  117. package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js +10 -0
  118. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +7 -4
  119. package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js +15 -3
  120. package/.agents/scripts/lib/orchestration/single-story-close/phases/code-review.js +59 -2
  121. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +6 -0
  122. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +15 -4
  123. package/.agents/scripts/lib/orchestration/single-story-close/phases/land-review-record.js +213 -0
  124. package/.agents/scripts/lib/orchestration/single-story-close/phases/normalize-pr-title.js +9 -12
  125. package/.agents/scripts/lib/orchestration/single-story-close/phases/open-pr.js +26 -12
  126. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +51 -26
  127. package/.agents/scripts/lib/orchestration/single-story-close/phases/pre-push.js +3 -2
  128. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +50 -17
  129. package/.agents/scripts/lib/orchestration/single-story-close/phases/push.js +59 -11
  130. package/.agents/scripts/lib/orchestration/single-story-close/phases/reconcile-done.js +1 -0
  131. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-block.js +31 -13
  132. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-halt.js +29 -6
  133. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-outcome.js +10 -12
  134. package/.agents/scripts/lib/orchestration/single-story-close/phases/review-override.js +19 -4
  135. package/.agents/scripts/lib/orchestration/single-story-close/result.js +30 -13
  136. package/.agents/scripts/lib/orchestration/single-story-close/review-overlap.js +73 -39
  137. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +11 -3
  138. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +3 -2
  139. package/.agents/scripts/lib/orchestration/story-close/duplication-close-rescore.js +20 -8
  140. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +7 -0
  141. package/.agents/scripts/lib/orchestration/story-handoff.js +774 -196
  142. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  143. package/.agents/scripts/lib/pr-body-lines.js +32 -0
  144. package/.agents/scripts/lib/single-story/ci-ratchet-gate.js +140 -0
  145. package/.agents/scripts/lib/single-story/confirm-and-land.js +17 -7
  146. package/.agents/scripts/lib/single-story/confirm-merge.js +12 -3
  147. package/.agents/scripts/lib/single-story-sweep/report-stalled-executing.js +202 -0
  148. package/.agents/scripts/lib/standalone-ratchets.js +37 -0
  149. package/.agents/scripts/lib/suite-admission.js +20 -8
  150. package/.agents/scripts/lib/suite-sizing.js +146 -0
  151. package/.agents/scripts/lib/workspace-provisioner.js +2 -2
  152. package/.agents/scripts/merge-baseline.js +14 -3
  153. package/.agents/scripts/providers/github/comments.js +19 -3
  154. package/.agents/scripts/providers/github.js +1 -0
  155. package/.agents/scripts/review-dispositions-report.js +1 -1
  156. package/.agents/scripts/role-scope-guard.js +267 -0
  157. package/.agents/scripts/single-story-close.js +4 -4
  158. package/.agents/scripts/single-story-confirm-merge.js +31 -5
  159. package/.agents/scripts/single-story-init.js +24 -4
  160. package/.agents/scripts/story-handoff.js +3 -3
  161. package/.agents/scripts/story-outcomes-report.js +231 -0
  162. package/.agents/scripts/story-review-compute.js +9 -5
  163. package/.agents/scripts/update-coverage-baseline.js +12 -2
  164. package/.agents/scripts/update-crap-baseline.js +9 -1
  165. package/.agents/workflows/helpers/code-review.md +63 -9
  166. package/.agents/workflows/helpers/deliver-digest.md +53 -54
  167. package/.agents/workflows/helpers/deliver-reference.md +233 -67
  168. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  169. package/.agents/workflows/helpers/deliver-story.md +7 -2
  170. package/.agents/workflows/helpers/parallel-tooling.md +29 -0
  171. package/docs/CHANGELOG.md +46 -0
  172. package/lib/cli/doctor-checks/coverage-ratchet.js +54 -0
  173. package/lib/cli/doctor-checks/effective-agentrc.js +23 -0
  174. package/lib/cli/doctor-checks/llm-review.js +2 -11
  175. package/lib/cli/doctor-checks/sync-parity.js +5 -1
  176. package/lib/cli/doctor-checks/test-credit-path.js +7 -2
  177. package/lib/cli/registry.js +5 -0
  178. package/package.json +1 -1
@@ -8,11 +8,10 @@ description: >-
8
8
  # Deliver digest (read once per session)
9
9
 
10
10
  > **Bundle, not a procedure.** [`deliver-story.md`](deliver-story.md) is still
11
- > the steps; this file is the material they reference, bundled so one read
12
- > covers the happy path. Situational material (lease preflight, recovery
13
- > routers, merge-wait budgets, CI remediation) stays on demand in
11
+ > the steps; this file bundles the material they reference. Situational
12
+ > material stays on demand in
14
13
  > [`deliver-story-reference.md`](deliver-story-reference.md) and
15
- > [`deliver-reference.md`](deliver-reference.md); read those only when routed.
14
+ > [`deliver-reference.md`](deliver-reference.md), read only when routed.
16
15
 
17
16
  ## 1. Dispatch — where the engine runs
18
17
 
@@ -21,12 +20,12 @@ rule produces it:
21
20
 
22
21
  1. **Run topology.** A one-Story run is `inline` (the router's own session)
23
22
  whatever its shape — isolation only matters against a *concurrent*
24
- sibling, and a one-Story run has none.
25
- 2. **Every other run is `subagent`**, however trivial each Story's shape.
23
+ sibling.
24
+ 2. **Every other run is `subagent`**, whatever each Story's shape.
26
25
 
27
26
  `inline` drops only the `story-worker` boot — not the verdict owner, which
28
27
  the profile alone names (§ 3). **`subagent` and `inline` run the same engine**: same gates,
29
- same PR to `main`, same terminal envelope.
28
+ same PR to `main`, same envelope.
30
29
 
31
30
  ## 2. Engine invariants
32
31
 
@@ -44,43 +43,41 @@ the only sanctioned landing.
44
43
 
45
44
  ## 3. Change set — computed once, handed to everyone
46
45
 
47
- One enumeration per Story: a critic that re-runs its own `git diff` can
48
- score a different set than the one that routed it. **One script** derives
49
- the change set, the level and the ceremony (close and critic hand-offs call
50
- it; the worker gets it from § 4's `--init`):
46
+ One enumeration per Story: a critic re-running `git diff` can score
47
+ another set. **One script** derives the change set, the level and the
48
+ ceremony (close and critic hand-offs call it; the worker gets it from § 4's
49
+ `--init`):
51
50
 
52
51
  ```bash
53
52
  node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>
54
53
  ```
55
54
 
56
- It prints one JSON object: `files` — the one change set the verdict owner is
57
- handed (`null` when the diff could not be enumerated) — plus `level` and
55
+ It prints one object: `files` — the one change set handed to the verdict
56
+ owner (`null` when the diff is unenumerable) — plus `level` and
58
57
  `classes` from `review-depth.js`, and `mode`, `reason` and `verdictOwner`
59
- from `ceremony-routing.js`. Level rules: a sensitive path registered in
60
- `audit-rules.json` → `high`, none → `low`, an unenumerable diff → `null`.
61
- The level drives **review depth** only (close reads the same level): a
58
+ from `ceremony-routing.js`. Level: a sensitive
59
+ `audit-rules.json` path → `high`, else `low`; unenumerable → `null`.
60
+ The level drives **review depth** only (close reads it too): a
62
61
  sensitive footprint buys a **deep review**, not a fresh acceptance critic.
63
62
 
64
63
  > **The ceremony rule, stated once.** The **profile alone** names the verdict
65
64
  > owner: `minimal` / `standard` → `inline`, `strict` → `fresh`. Nothing else
66
65
  > moves it — not the change level, not sensitivity, **not the dispatch
67
- > mode**: an `inline` Story under `strict` still spawns the fresh critic. The
68
- > only inline authoring under `strict` is the harness fallback in
69
- > [`acceptance-self-eval.md`](acceptance-self-eval.md), noted in any friction
70
- > comment.
66
+ > mode**: an `inline` Story under `strict` still spawns the fresh critic,
67
+ > bar the harness fallback in [`acceptance-self-eval.md`](acceptance-self-eval.md).
71
68
 
72
69
  ## 4. Acceptance self-eval (Step 1a, required)
73
70
 
74
71
  **One verdict owner per Story** — named by `verdictOwner`: the inline
75
72
  self-eval under `minimal` / `standard` (the default), a fresh maker-blind
76
- critic under `strict`. Never both, and never a warm-up pass. Start from the
73
+ critic under `strict`. Never both. Start from the
77
74
  skeleton — it derives § 3's `files` and `verdictOwner` with the same function:
78
75
 
79
76
  `node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId> --init
80
77
  --cwd <workCwd>`
81
78
 
82
- It writes one empty record per `acceptance[]` item (plus the next round and
83
- HEAD) under `temp/scratch/story-<id>/`. The owner fills **every** record,
79
+ It writes one empty record per `acceptance[]` item and prints its
80
+ path. The owner fills **every** record,
84
81
  scored against that change set with `verify[]` output as evidence, and scores
85
82
  it in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
86
83
  (default 2; `0` scores once with no redraft).
@@ -90,8 +87,7 @@ it in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
90
87
 
91
88
  The gate reads the Story's `acceptance[]` count itself and rejects, **before**
92
89
  scoring and consuming no round, a verdict whose `criteria[]` length differs
93
- or with an unfilled record (naming its indices). A second gate call in the
94
- same round wastes it and races the Story ledger.
90
+ or with an unfilled record (naming its indices).
95
91
 
96
92
  `proceed` → § 5. `redraft` → one more round inside the cap. `block` → **do
97
93
  not close**: post a `friction` comment and flip `agent::blocked`.
@@ -99,44 +95,47 @@ Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
99
95
 
100
96
  ## 5. The one credited run — `story-handoff.js`
101
97
 
102
- After the self-eval loop's last fix commit the worker runs **one** command,
103
- which runs this section in order and prints one envelope:
98
+ After the self-eval's last fix commit the worker runs **one** command:
104
99
 
105
100
  `node <main-repo>/.agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>`
106
101
 
107
102
  `ready` (exit 0) → hand off. `fix-required` (exit 2) → a finding, a red or
108
- deferred suite, a base-merge conflict (files named), a non-fast-forward push
109
- or a CRITICAL: fix, commit, re-run; labels untouched. `blocked` (exit 1) →
110
- only a remote-refused push, an unreachable remote, an unconfirmed base branch
111
- or an unregistered merge driver: it flips `agent::blocked` and posts
112
- `friction`. A re-run skips every step still valid for HEAD. It never runs
113
- close, opens a PR or writes another label. Outruns the sync Bash ceiling → run
114
- it in the **background**.
115
-
116
- 1. **Base merge.** It will merge `origin/<baseBranch>` into the Story branch
117
- **first**, ahead of every check: close's base-sync then no-ops.
118
- 2. **Preflight — blocking.** `lint`/`format` (close's credit),
103
+ deferred suite, a base-merge conflict, a non-fast-forward push,
104
+ a `commit_refs_rules` push stepping missed or a CRITICAL: fix, commit,
105
+ re-run; labels untouched. `blocked` (exit 1) → only a remote-refused push,
106
+ an unreachable remote, an unconfirmed base branch, an unregistered merge
107
+ driver or `host-resources` (exit 77): it flips `agent::blocked` and posts
108
+ `friction`. A re-run skips every step still valid for HEAD. Past the sync ceiling → **background**, explicit timeout: parallel-tooling Rule 2.
109
+
110
+ 1. **Base merge:** merge `origin/<baseBranch>` into the Story branch
111
+ **first**, ahead of every check: close's base-sync then no-ops. Then close's **duplication re-score**, committed
112
+ **untagged** before any credit.
113
+ 2. **Preflight — blocking.** `typecheck`/`lint`/`format` (close's credit),
119
114
  `quality-preview.js --changed-since origin/<baseBranch>`, then each
120
- baselined ratchet — [`deliver-reference.md`](deliver-reference.md) § Preflight.
115
+ baselined ratchet; one `fix-required` lists every finding. Serial unless
116
+ a per-host `.agentrc.local.json` sets `delivery.execution.preflightConcurrency`
117
+ above 1 (default 1): close's independent gates then run in admitted
118
+ lanes beside the base lane — [`deliver-reference.md`](deliver-reference.md) § Preflight.
121
119
  3. **One depositor**, by the one predicate close registers `coverage-capture`
122
120
  on — coverage or CRAP gate on **and** a `captureScript`:
123
121
  - **Capture-active** →
124
122
  `node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`,
125
- behind the host full-suite lock. Signal: `Wrote content-digest capture
123
+ behind the full-suite lock. Signal: `Wrote content-digest capture
126
124
  stamp`. No second `npm test`.
127
125
  - **Otherwise** → `node <main-repo>/.agents/scripts/evidence-gate.js
128
- --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test`.
129
- Signal: `✓ test passed` — the `test` evidence close reads.
130
- 4. **Seat.** CRAP or MI gate on → `--seat-missing` for each (signal
131
- `seated: N`), committed as `chore(baselines): baseline-refresh: …`; then
132
- post-capture checks: close's `quality-preview-crap` and `check-baselines`.
126
+ --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test`;
127
+ a predicted capture skip runs `testChanged --changed-since` the
128
+ merge-base, else says why. Signal: `✓ test passed`.
129
+ 4. **Seat.** `--seat-missing` (`seated: N`): MI before step 2, CRAP and
130
+ capture-path coverage here, committed `chore(baselines): baseline-refresh:
131
+ …`; then post-capture checks: close's `quality-preview-crap` and `check-baselines`,
132
+ then `delivery.handoff.postSeatChecks`. Children get `MANDREL_HANDOFF_STEP`.
133
133
  5. **Push** `story-<id>`; the remote ref must equal HEAD.
134
- 6. **Held review** beside step 3, which a CRITICAL aborts —
135
- [`deliver-reference.md`](deliver-reference.md) § Held review.
134
+ 6. **Held review** from step 1, beside 2: a CRITICAL skips or aborts 3,
135
+ one envelope with any finding — [`deliver-reference.md`](deliver-reference.md) § Held review.
136
136
 
137
137
  A later commit voids any credit; a baseline-JSON seat keeps the stamp. It
138
- reads the **output**, not the exit code: a run that prints no signal
139
- deposits nothing. Seat order, runner shapes, redraft rounds:
138
+ reads the **output**, not the exit code: no signal deposits nothing. Seat order, runner shapes:
140
139
  [`deliver-reference.md`](deliver-reference.md) § Credited run.
141
140
 
142
141
  `verify[]` is scoped entries **plus** this one run: an entry that is a
@@ -148,7 +147,7 @@ respawned.
148
147
  `single-story-close.js` emits exactly one envelope on stdout between
149
148
  `--- STORY DELIVER TERMINAL ---` markers, schema-validated against
150
149
  [`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
151
- — the SSOT. Relay it verbatim; never hand-compose one or substitute prose.
150
+ — the SSOT. Relay it verbatim; never hand-compose one.
152
151
 
153
152
  | `status` | Exit | Meaning | You do |
154
153
  | --- | --- | --- | --- |
@@ -161,12 +160,12 @@ Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
161
160
  `phase` (the schema's enum names where it stopped), `elapsedSeconds`,
162
161
  `nextCommand`. `gates`
163
162
  reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
164
- reported, never omitted, so a missing gate is never read as a passing one.
163
+ never omitted, so a missing gate never reads as passing.
165
164
 
166
165
  ## 7. When to leave this file
167
166
 
168
- Unclear state / a re-run refusal → `deliver-recover.js --story <id>`
169
- (read-only). Lease, sweep, worktree scope; sequencing, epilogue, checklist
170
- threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
167
+ Unclear state / a re-run refusal → `deliver-recover.js --story <id>`; boot
168
+ auto-lists stalled `agent::executing` Stories with it (read-only, advisory).
169
+ Lease, sweep, worktree scope; sequencing, epilogue, checklist threading → [`deliver-story-reference.md`](deliver-story-reference.md) and
171
170
  [`deliver-reference.md`](deliver-reference.md). CI red after the PR opens →
172
171
  [`rules/ci-remediation.md`](../../rules/ci-remediation.md).
@@ -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
 
@@ -513,11 +660,25 @@ full-suite lock wait expired) logs a deferred line and the close settles
513
660
  line naming host contention — neither is reported as failing tests. A
514
661
  coverage-capture exiting `76` (the consumer's capture script declared its
515
662
  slice over this host's budget, so nothing ran) follows
516
- `delivery.quality.gates.coverage.onOverBudget`: under `defer-to-ci` the gate
517
- reports `deferred`, the coverage-reading gates report `skipped`
518
- (`coverage-deferred-ci`), the handoff settles `ready` with a `coverage`
519
- field, and the PR body says coverage was deferred to CI; under the default
520
- `block` the handoff settles `blocked` and close fails, both naming the key.
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.
521
682
 
522
683
  Every full-suite run ends on `⏲ suite timings: lockWaitMs=… hostWaitMs=…
523
684
  testRunMs=…`. The handoff envelope carries its credited run's figures as
@@ -532,6 +693,11 @@ that writes `$MANDREL_SUITE_READY_FILE` when its tests start (after a
532
693
  consumer load gate) gets a fresh bound for them, so worst-case wall is lock
533
694
  wait + 2 × `timeoutMs`.
534
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
+
535
701
  **Delta re-credit after a base move.** When close's base sync merged
536
702
  incoming paths (`BASE MOVED`), the `test` gate is the suite gate, the
537
703
  pre-sync head holds `test` credit and `project.commands.testChanged` is set,