mandrel 2.70.0 → 2.72.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 (79) hide show
  1. package/.agents/README.md +8 -9
  2. package/.agents/agents/acceptance-critic.md +1 -0
  3. package/.agents/agents/auditor.md +1 -0
  4. package/.agents/agents/plan-critic.md +1 -0
  5. package/.agents/agents/story-worker.md +63 -64
  6. package/.agents/docs/agentrc-reference.json +2 -1
  7. package/.agents/docs/configuration.md +7 -8
  8. package/.agents/rules/git-conventions-reference.md +2 -2
  9. package/.agents/schemas/agentrc.schema.json +19 -2
  10. package/.agents/schemas/story-deliver-terminal.schema.json +10 -1
  11. package/.agents/scripts/acceptance-eval.js +194 -15
  12. package/.agents/scripts/deliver-run.js +92 -43
  13. package/.agents/scripts/lib/audit-suite/index.js +1 -1
  14. package/.agents/scripts/lib/audit-suite/story-checklist.js +65 -0
  15. package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js +2 -2
  16. package/.agents/scripts/lib/bootstrap/issue-forms-template.js +1 -1
  17. package/.agents/scripts/lib/cli-args.js +22 -0
  18. package/.agents/scripts/lib/close-validation/gates.js +17 -3
  19. package/.agents/scripts/lib/config/agent-models.js +117 -0
  20. package/.agents/scripts/lib/config-settings-schema-delivery.js +13 -1
  21. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  23. package/.agents/scripts/lib/git/sync-from-base.js +89 -17
  24. package/.agents/scripts/lib/label-taxonomy.js +13 -3
  25. package/.agents/scripts/lib/notifications/notifier.js +11 -15
  26. package/.agents/scripts/lib/observability/close-telemetry.js +19 -3
  27. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  28. package/.agents/scripts/lib/orchestration/cancelled-run-discount.js +129 -0
  29. package/.agents/scripts/lib/orchestration/code-review.js +2 -2
  30. package/.agents/scripts/lib/orchestration/deliver-recover.js +166 -34
  31. package/.agents/scripts/lib/orchestration/file-assumptions.js +45 -11
  32. package/.agents/scripts/lib/orchestration/plan-context.js +17 -10
  33. package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
  34. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +19 -16
  35. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +1 -0
  36. package/.agents/scripts/lib/orchestration/plan-persist/summary.js +4 -3
  37. package/.agents/scripts/lib/orchestration/pr-watch.js +14 -3
  38. package/.agents/scripts/lib/orchestration/resolve-stories.js +10 -2
  39. package/.agents/scripts/lib/orchestration/review-providers/native.js +5 -165
  40. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +14 -2
  41. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +45 -0
  42. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +162 -58
  43. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +58 -6
  44. package/.agents/scripts/lib/orchestration/single-story-close/phases/merge-wait-recovery.js +296 -0
  45. package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +20 -4
  46. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +52 -6
  47. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +2 -2
  48. package/.agents/scripts/lib/orchestration/single-story-close/phases/story-branch-catch-up.js +50 -0
  49. package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js +64 -52
  50. package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-restore.js +133 -0
  51. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +187 -74
  52. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +46 -6
  53. package/.agents/scripts/lib/orchestration/story-handoff.js +849 -0
  54. package/.agents/scripts/lib/orchestration/story-init-result.js +83 -0
  55. package/.agents/scripts/lib/orchestration/task-body-validator.js +35 -5
  56. package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js +1 -1
  57. package/.agents/scripts/lib/orchestration/ticket-validator.js +20 -2
  58. package/.agents/scripts/lib/single-story/confirm-merge.js +44 -7
  59. package/.agents/scripts/lib/story-body/story-body.js +40 -5
  60. package/.agents/scripts/lib/templates/decomposer-prompts.js +33 -36
  61. package/.agents/scripts/pr-watch-with-update.js +5 -0
  62. package/.agents/scripts/single-story-close.js +8 -0
  63. package/.agents/scripts/single-story-confirm-merge.js +34 -3
  64. package/.agents/scripts/single-story-init.js +17 -32
  65. package/.agents/scripts/story-handoff.js +112 -0
  66. package/.agents/scripts/sync-claude-agents.js +58 -27
  67. package/.agents/workflows/helpers/acceptance-self-eval.md +24 -18
  68. package/.agents/workflows/helpers/code-review.md +3 -3
  69. package/.agents/workflows/helpers/deliver-digest.md +79 -80
  70. package/.agents/workflows/helpers/deliver-light.md +9 -7
  71. package/.agents/workflows/helpers/deliver-reference.md +38 -22
  72. package/.agents/workflows/helpers/deliver-story-reference.md +39 -18
  73. package/.agents/workflows/helpers/deliver-story.md +30 -23
  74. package/.agents/workflows/helpers/plan-reference.md +24 -9
  75. package/.agents/workflows/helpers/worktree-lifecycle.md +5 -5
  76. package/docs/CHANGELOG.md +31 -0
  77. package/lib/cli/registry.js +7 -0
  78. package/package.json +4 -3
  79. package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js +0 -272
@@ -17,21 +17,17 @@ description: >-
17
17
 
18
18
  ## 1. Dispatch — where the engine runs
19
19
 
20
- Read `stories[].dispatchMode` from the `resolve-stories.js` envelope.
21
- `inline` names one indivisible resource — **the router's own session** — so one
20
+ Read `stories[].dispatchMode` from the `resolve-stories.js` envelope. One
22
21
  rule produces it:
23
22
 
24
- 1. **Run topology.** A run resolving **one** Story is `inline` whatever its
25
- shape — sub-agent isolation only matters against a *concurrent* sibling
26
- racing the same checkout, and a one-Story run has none.
27
- 2. **Every other run is `subagent`.** A multi-Story run dispatches every Story
28
- as a sub-agent however trivial its shape — the run's size is the whole
29
- premise, and nothing about a Story's own shape enters it.
23
+ 1. **Run topology.** A one-Story run is `inline` (the router's own session)
24
+ whatever its shape — isolation only matters against a *concurrent*
25
+ sibling, and a one-Story run has none.
26
+ 2. **Every other run is `subagent`**, however trivial each Story's shape.
30
27
 
31
- `inline` removes the `story-worker` boot and nothing else. It does **not**
32
- change the acceptance verdict owner — that is § 3's decision, and the profile
33
- alone makes it. **`subagent` and `inline` run the same engine**: same gates,
34
- same PR to `main`, same terminal envelope, byte for byte.
28
+ `inline` removes the `story-worker` boot and nothing else — not the verdict
29
+ owner, which the profile alone names (§ 3). **`subagent` and `inline` run the same engine**: same gates,
30
+ same PR to `main`, same terminal envelope.
35
31
 
36
32
  ## 2. Engine invariants
37
33
 
@@ -45,14 +41,14 @@ same PR to `main`, same terminal envelope, byte for byte.
45
41
  | Paths | Prefix every path-based tool with the absolute `workCwd` — `cd` does not scope them |
46
42
 
47
43
  **Land or block.** Worktree → `story-<id>` → close-validation → PR to `main` is
48
- the only sanctioned landing. A silent local build is not a delivery.
44
+ the only sanctioned landing.
49
45
 
50
46
  ## 3. Change set — computed once, handed to everyone
51
47
 
52
- One enumeration per Story. A critic that re-runs its own `git diff`
53
- can score a different set than the one that routed it. Derive the change
54
- set, the level and the ceremony with **one script** — never a hand-carried
55
- import block:
48
+ One enumeration per Story: a critic that re-runs its own `git diff` can
49
+ score a different set than the one that routed it. **One script** derives
50
+ the change set, the level and the ceremony (close and critic hand-offs call
51
+ it; the worker gets it from § 4's `--init`):
56
52
 
57
53
  ```bash
58
54
  node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>
@@ -63,108 +59,111 @@ handed (`null` when the diff could not be enumerated) — plus `level` and
63
59
  `classes` from `review-depth.js`, and `mode`, `reason` and `verdictOwner`
64
60
  from `ceremony-routing.js`. Level rules: a sensitive path registered in
65
61
  `audit-rules.json` → `high`, none → `low`, an unenumerable diff → `null`.
66
- The level drives **review depth** only; close's `review-depth.js` reads the
67
- same derived level, so the two cannot disagree. A sensitive footprint
68
- therefore buys a **deep review**, not a fresh acceptance critic.
62
+ The level drives **review depth** only (close reads the same level): a
63
+ sensitive footprint buys a **deep review**, not a fresh acceptance critic.
69
64
 
70
65
  > **The ceremony rule, stated once.** The **profile alone** names the verdict
71
66
  > owner: `minimal` / `standard` → `inline`, `strict` → `fresh`. Nothing else
72
- > moves it — not the
73
- > derived change level, not the footprint's sensitivity, and **not the
74
- > dispatch mode**: an `inline` Story under `strict` still spawns the fresh
75
- > maker-blind critic, one nesting level shallower than a dispatched one. The
76
- > only sanctioned inline authoring under `strict` is the harness fallback in
77
- > [`acceptance-self-eval.md`](acceptance-self-eval.md) — a host that cannot
78
- > spawn the critic at all, noted in the friction comment if you block.
67
+ > moves it — not the change level, not sensitivity, **not the dispatch
68
+ > mode**: an `inline` Story under `strict` still spawns the fresh critic. The
69
+ > only inline authoring under `strict` is the harness fallback in
70
+ > [`acceptance-self-eval.md`](acceptance-self-eval.md), noted in any friction
71
+ > comment.
79
72
 
80
73
  ## 4. Acceptance self-eval (Step 1a, required)
81
74
 
82
75
  **One verdict owner per Story** — named by `verdictOwner`: the inline
83
76
  self-eval under `minimal` / `standard` (the default), a fresh maker-blind
84
- critic under `strict`. Never both, and never a warm-up pass. The owner
85
- authors **one** verdict file covering every `acceptance[]` item, scored
86
- against the change set above with `verify[]` output as evidence, and it is
87
- scored in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
77
+ critic under `strict`. Never both, and never a warm-up pass. Start from the
78
+ skeleton — it derives § 3's `files` and `verdictOwner` with the same function:
79
+
80
+ `node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId> --init
81
+ --cwd <workCwd>`
82
+
83
+ It writes one empty record per `acceptance[]` item (plus the next round and
84
+ HEAD) under `temp/scratch/story-<id>/`. The owner fills **every** record,
85
+ scored against that change set with `verify[]` output as evidence, and scores
86
+ it in **one** gate call. Bounded by `delivery.acceptanceEval.maxRounds`
88
87
  (default 2; `0` scores once with no redraft).
89
88
 
90
89
  `node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId>
91
90
  --verdict <verdict-path>`
92
91
 
93
- The gate reads the Story's `acceptance[]` count itself and rejects a verdict
94
- whose `criteria[]` length differs **before** scoring, consuming no round. A
95
- second gate call in the same round spends a round for nothing and races the
96
- Story-scoped ledger.
92
+ The gate reads the Story's `acceptance[]` count itself and rejects, **before**
93
+ scoring and consuming no round, a verdict whose `criteria[]` length differs
94
+ or with an unfilled record (naming its indices). A second gate call in the
95
+ same round wastes it and races the Story ledger.
97
96
 
98
- `proceed` → close. `redraft` → one more round inside the cap. `block` → **do
97
+ `proceed` → § 5. `redraft` → one more round inside the cap. `block` → **do
99
98
  not close**: post a `friction` comment and flip `agent::blocked`.
100
99
  Per-round mechanics: [`acceptance-self-eval.md`](acceptance-self-eval.md).
101
100
 
102
- ## 5. The one credited run
103
-
104
- **Preflight first — blocking.** After the self-eval loop, run the configured
105
- `project.commands.lint` and `node <main-repo>/.agents/scripts/quality-preview.js
106
- --changed-since origin/<baseBranch>` in the worktree; fix and commit every
107
- finding. Close's gates stay authoritative
108
- ([`deliver-reference.md`](deliver-reference.md) § Preflight).
109
-
110
- After the last fix commit, fetch and merge
111
- `origin/<baseBranch>` into the Story branch **first**, ahead of this run and
112
- the push: close's base-sync then no-ops, so neither stamp goes stale. Then run
113
- **one** depositor in the worktree, picked by the predicate close registers
114
- `coverage-capture` on — CRAP gate enabled **and** a `test:coverage` script:
115
-
116
- - **Capture-active** →
117
- `node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`.
118
- It takes the host full-suite lock, runs `test:coverage` and writes the stamp
119
- close's capture finds fresh. Signal: `Wrote content-digest capture stamp`.
120
- Non-zero is a red suite (or the lock / timeout it names): fix, re-run. No
121
- second `npm test`.
122
- - **Otherwise** → `node <main-repo>/.agents/scripts/evidence-gate.js
123
- --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test`.
124
- Signal: `✓ test passed` — the `test` evidence close reads, keyed on the tree.
125
-
126
- **Seat, then push.** CRAP or MI gate on → run
127
- `update-crap-baseline.js --seat-missing` and its maintainability twin (signal
128
- `seated: N`); commit it as `chore(baselines): baseline-refresh: …`.
129
-
130
- A later commit voids either credit; a baseline-JSON seat keeps the stamp. Read
131
- the **output**, not the exit code: a run that prints no signal deposits
132
- nothing. `mandrel doctor`'s `test-credit-path` check names this project's
133
- depositor. Seat order, runner shapes, background dispatch, redraft rounds:
101
+ ## 5. The one credited run — `story-handoff.js`
102
+
103
+ After the self-eval loop's last fix commit the worker runs **one** command,
104
+ which performs this section in order and prints one envelope:
105
+
106
+ `node <main-repo>/.agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>`
107
+
108
+ `ready` (exit 0) → hand off. `fix-required` (exit 2) → a finding, a red or
109
+ deferred suite, a base-merge conflict (files named), a non-fast-forward push
110
+ or a CRITICAL: fix, commit, re-run; labels untouched. `blocked` (exit 1) →
111
+ only a remote-refused push, an unreachable remote, an unconfirmed base branch
112
+ or an unregistered merge driver: it flips `agent::blocked` and posts
113
+ `friction`. A re-run skips every step still valid for HEAD. It never runs
114
+ close, opens a PR or writes another label. Outruns the sync Bash ceiling → run
115
+ it in the **background**.
116
+
117
+ 1. **Preflight — blocking.** `project.commands.lint`,
118
+ `quality-preview.js --changed-since origin/<baseBranch>`, then each
119
+ baselined standalone ratchet (dead exports, cycles, cyclomatic) — [`deliver-reference.md`](deliver-reference.md) § Preflight.
120
+ 2. **Base merge.** It will merge `origin/<baseBranch>` into the Story branch
121
+ **first**, ahead of this run and the push: close's base-sync then no-ops,
122
+ so neither stamp goes stale.
123
+ 3. **One depositor**, by the predicate close registers `coverage-capture` on
124
+ (one shared function) — CRAP gate enabled **and** a `test:coverage` script:
125
+ - **Capture-active** →
126
+ `node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`,
127
+ behind the host full-suite lock. Signal: `Wrote content-digest capture
128
+ stamp`. No second `npm test`.
129
+ - **Otherwise** → `node <main-repo>/.agents/scripts/evidence-gate.js
130
+ --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test`.
131
+ Signal: `✓ test passed` — the `test` evidence close reads.
132
+ 4. **Seat.** CRAP or MI gate on → `--seat-missing` for each (signal
133
+ `seated: N`), committed as `chore(baselines): baseline-refresh: …`.
134
+ 5. **Push** `story-<id>`; the remote ref must equal HEAD.
135
+ 6. **Held review** — [`deliver-reference.md`](deliver-reference.md)
136
+ § Held review.
137
+
138
+ A later commit voids either credit; a baseline-JSON seat keeps the stamp. The
139
+ handoff reads the **output**, not the exit code: a run that prints no signal
140
+ deposits nothing. Seat order, runner shapes, redraft rounds:
134
141
  [`deliver-reference.md`](deliver-reference.md) § Credited run.
135
142
 
136
143
  `verify[]` is scoped entries **plus** this one run: an entry that is itself a
137
144
  full-suite command is reported credited against the same record, never
138
145
  respawned.
139
146
 
140
- After the push, compute the held review and fix a CRITICAL before hand-off:
141
- [`deliver-reference.md`](deliver-reference.md) § Held review.
142
-
143
147
  ## 6. Terminal envelope — the return contract
144
148
 
145
149
  `single-story-close.js` emits exactly one envelope on stdout between
146
150
  `--- STORY DELIVER TERMINAL ---` markers, schema-validated against
147
151
  [`story-deliver-terminal.schema.json`](../../schemas/story-deliver-terminal.schema.json)
148
- — the SSOT; read the JSON only when you need a field this table omits.
149
- Relay it verbatim; never hand-compose one, never substitute prose.
152
+ — the SSOT. Relay it verbatim; never hand-compose one or substitute prose.
150
153
 
151
154
  | `status` | Exit | Meaning | You do |
152
155
  | --- | --- | --- | --- |
153
156
  | `landed` | 0 | PR merged, `agent::done`, tail ran (`tail.*: false` degrades the report, not the land) | Relay it. Done. |
154
157
  | `pending` | 3 | **Resumable, not a failure** — the bounded wait expired healthy, or a human owns the merge. Nothing was mutated. | Run `nextCommand`. |
155
158
  | `blocked` | 1 | Hard block; `blocked.blockClass` names it | `checks-failed` → fix + resume; else relay |
156
- | `failed` | 1 | A phase crashed; `phase` names which | Diagnose, fix, re-run close |
159
+ | `failed` | 1 | A phase crashed; `phase` names which | Diagnose, fix, re-run close. `base-sync` conflict (files in `failure.reason`): resolve in `workCwd`, commit, run `nextCommand`; block only if you cannot |
157
160
 
158
161
  Required fields: `kind` (`story-deliver-terminal`), `storyId`, `status`,
159
- `phase`, `elapsedSeconds`, `nextCommand`. `phase` is one of `init`,
160
- `wrong-tree-guard`, `base-sync`, `close-validation`, `push`, `pull-request`,
161
- `code-review`, `auto-merge`, `confirm-merge`, `post-land`, `done`. `gates`
162
+ `phase` (the schema's enum names where it stopped), `elapsedSeconds`,
163
+ `nextCommand`. `gates`
162
164
  reports every gate as `passed` / `failed` / `skipped` — a skipped gate is
163
165
  reported, never omitted, so a missing gate is never read as a passing one.
164
166
 
165
- Gate output is captured to a log, not streamed
166
- ([`deliver-reference.md`](deliver-reference.md) § Gate output).
167
-
168
167
  ## 7. When to leave this file
169
168
 
170
169
  Unclear state / a re-run refusal → `deliver-recover.js --story <id>`
@@ -104,13 +104,15 @@ is not being loosened.
104
104
  This is [`/mandrel-deliver`](../mandrel-deliver.md)'s worktree/branch/lease/label engine,
105
105
  invoked, not reimplemented.
106
106
 
107
- 3. **Implement + self-eval.** `cd` into `workCwd`, implement the change, run
108
- the full suite once in the worktree **so close can credit it** — the
109
- crediting invocation and the freshness contract are
110
- [`deliver-digest.md`](deliver-digest.md) § 5, unchanged here — then run
111
- the bounded acceptance self-eval loop
112
- ([`deliver-story.md`](deliver-story.md) Step 1a). Commit
113
- on `story-<id>` with `(refs #<storyId>)`.
107
+ 3. **Implement + self-eval + handoff.** `cd` into `workCwd`, implement the
108
+ change and commit on `story-<id>` with `(refs #<storyId>)`. Then the
109
+ skeleton-scored self-eval — `acceptance-eval.js --story <storyId> --init
110
+ --cwd <workCwd>`, fill every record, score it once
111
+ ([`deliver-story.md`](deliver-story.md) Step 1a) — followed by the one
112
+ tail command, `story-handoff.js --story <storyId> --cwd <workCwd>`: its
113
+ credited suite run is what close credits
114
+ ([`deliver-digest.md`](deliver-digest.md) § 5, unchanged here).
115
+ `fix-required` → fix, commit, re-run it.
114
116
 
115
117
  4. **Diff backstop.** Before close, re-check the ACTUAL diff:
116
118
 
@@ -177,9 +177,10 @@ into batches of `cap` and dispatch each batch in its own turn.
177
177
  exposes agent dispatch, spawn each ready Story as its own
178
178
  `subagent_type: story-worker` sub-agent — it boots on the role-scoped
179
179
  [`story-worker`](../../agents/story-worker.md) context (its own system prompt, no
180
- entry-doc @-closure) carrying the load-bearing delivery MUSTs standalone. The
181
- sub-agent executes [`deliver-story.md`](deliver-story.md) Steps 0–2.5
182
- (init → implement → acceptance self-eval → **push**) and stops there; **you**
180
+ entry-doc @-closure) carrying every worker MUST standalone. The sub-agent
181
+ runs init → implement → the skeleton-scored self-eval (`acceptance-eval.js
182
+ --init`, then one scoring call) → the one `story-handoff.js` command, and
183
+ stops at its `ready` envelope with the branch pushed; **you**
183
184
  own Step 3, serialized — see `/mandrel-deliver` § Closing what the workers hand back.
184
185
 
185
186
  **The beat writes the prompt; you pass the file.** Each `ready[]` entry carries
@@ -187,10 +188,12 @@ a `promptPath` under `<tempRoot>/run-<id>/`, and that file is the whole spawn
187
188
  payload: the Story id, the `workCwd` conventions, the `docsDigestPath` (null
188
189
  when `project.docsContextFiles` is unset), the `checklistPath` — the
189
190
  footprint-matched write-time audit checklist built from the Story's declared
190
- `changes[]` / `references[]`, empty when nothing matched — and the
191
- **change-set discipline** (derive the change set once with `ceremony-derive.js`
192
- and hand that one list to the verdict owner; never let a critic re-derive the
193
- diff). An unmatched checklist costs nothing: the maker-blind close-scope pass
191
+ `changes[]` / `references[]`, null when nothing matched, at the same
192
+ Story-scoped path `single-story-init.js` returns in its envelope — the Story's
193
+ `## Context` and `## References` sections verbatim when present, and the tail
194
+ (`acceptance-eval.js --init`, whose one `files` list goes to the verdict
195
+ owner — never let a critic re-derive the diff — then `story-handoff.js`). It
196
+ names no workflow doc as a mandatory read. An unmatched checklist costs nothing: the maker-blind close-scope pass
194
197
  still covers the Story.
195
198
 
196
199
  **Inline fallback (`roleScopedAgents: false` / no-nesting harness).** When the
@@ -359,10 +362,13 @@ sibling to unblock, and the foreground wait is the cheapest path to `landed`.
359
362
 
360
363
  ## Preflight (before close) {#preflight}
361
364
 
362
- Digest § 5 states the rule: before the credited suite run, the worker runs
363
- the configured `project.commands.lint` (falling back to `npm run lint`) and
364
- `quality-preview.js --changed-since origin/<baseBranch>` in the worktree, and
365
- fixes and commits every finding. It runs **before** the credited run because a
365
+ Digest § 5 states the rule: `story-handoff.js` runs, before the credited
366
+ suite run, the configured `project.commands.lint` (falling back to
367
+ `npm run lint`), `quality-preview.js --changed-since origin/<baseBranch>`,
368
+ then the shipped standalone ratchets CI's `baselines` job runs —
369
+ `check-dead-exports.js` (default and `--production`), `check-arch-cycles.js`
370
+ and `check-cyclomatic.js` — in the worktree; a finding is `fix-required` —
371
+ fix, commit, re-run it. It runs **before** the credited run because a
366
372
  fix commit afterwards would void that run's credit.
367
373
 
368
374
  - **Why.** Close runs lint and the maintainability half of the preview
@@ -373,6 +379,11 @@ fix commit afterwards would void that run's credit.
373
379
  on disk — the worker's credited capture when one exists — and triggers no
374
380
  capture of its own. With no artifact its methods report unscorable; a stale
375
381
  one can invent a violation. `--only mi` runs the maintainability half alone.
382
+ - **Ratchets run only when seeded.** Each runs only when its committed
383
+ baseline (`baselines/dead-exports.json`, `dead-exports-production.json`,
384
+ `arch-cycles.json`, `cyclomatic.json`) exists, and is judged by its exit
385
+ code and `(gate fail)` line; the finding names the offending `+` / `!`
386
+ rows. Close does not run them — CI stays their backstop.
376
387
  - **Close stays authoritative.** Its `quality-preview-crap` gate scores a
377
388
  fresh capture after `coverage-capture`; a preflight pass never skips it.
378
389
 
@@ -392,22 +403,23 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
392
403
  the project's test script routes through mandrel's own runner, which prints
393
404
  the outcome. On any other runner it deposits nothing and prints nothing, so
394
405
  silence is never evidence of credit.
395
- - **Background dispatch.** If the run outruns the host's sync Bash ceiling,
406
+ - **Background dispatch.** If the handoff outruns the host's sync Bash ceiling,
396
407
  dispatch it in the **background** — its completion re-invokes you; never
397
408
  spawn a task to poll or `sleep`-loop against it
398
409
  ([`parallel-tooling.md`](parallel-tooling.md) Rule 2).
399
410
  - **Redraft rounds.** Run the scoped projects for the roots you changed plus
400
411
  `verify[]`, not the whole suite; only the one run needs credit.
401
412
  - **Seating new methods (`--seat-missing`).** Close fails a Story whose own
402
- new methods have no baseline row, so after the credited run and before the
403
- push the worker runs, in `<workCwd>`, for each enabled gate:
413
+ new methods have no baseline row, so `story-handoff.js` runs, in
414
+ `<workCwd>`, for each enabled gate:
404
415
  `node .agents/scripts/update-crap-baseline.js --seat-missing` (CRAP) and
405
416
  `node .agents/scripts/update-maintainability-baseline.js --seat-missing`
406
417
  (MI). Each scores the files changed since the `origin/<baseBranch>`
407
418
  merge-base and writes **only** rows whose (path, method) key is absent —
408
419
  every existing row stays byte-identical, including rows whose scores moved
409
420
  (re-scoring stays close's auto-refresh). It prints `seated: N`; `seated: 0`
410
- writes nothing. Commit a change as `chore(baselines): baseline-refresh: …`.
421
+ writes nothing. The handoff commits a change as `chore(baselines):
422
+ baseline-refresh: seat rows for new methods (refs #<id>)`.
411
423
  - **Seat refusals.** The CRAP seat exits non-zero and writes nothing unless
412
424
  the coverage-capture stamp is fresh for the tree **and** method resolution
413
425
  over the in-scope files is exactly 100% — a lower rate means the artifact's
@@ -416,13 +428,16 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
416
428
  - **Seat order vs credit.** The capture stamp digests scorable sources only,
417
429
  so a baseline-JSON-only seat commit leaves it fresh and the capture credit
418
430
  stands. The evidence-gate `test` credit is keyed on the tree, so on that
419
- path seat first — MI is static and needs no coverage — then run the suite.
431
+ path the handoff seats first — MI is static and needs no coverage — then
432
+ runs the suite.
420
433
 
421
434
  ## Held review at hand-off {#held-review}
422
435
 
423
436
  The one home of this rule; the digest and the worker contract point here.
424
- After the credited run **and** the push, the worker computes the Story-scope
425
- code review itself, before handing off:
437
+ After the credited run **and** the push, `story-handoff.js` computes the
438
+ Story-scope code review as its last step, skipping it when a deposit already
439
+ matches the diff digest. The same computation stands alone for a manual
440
+ re-run:
426
441
 
427
442
  ```bash
428
443
  node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd <workCwd>
@@ -433,10 +448,11 @@ node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd
433
448
  takes no full-suite lock, and writes
434
449
  `temp/orchestration/story-review-<id>.json` beside the terminal envelope,
435
450
  keyed on the **diff digest** (sha256 of the exact three-dot diff text). It
436
- exits 0 whatever the findings; non-zero means the provider threw — report
437
- it in the hand-off; close computes the review itself.
438
- - **A CRITICAL is the worker's to fix.** Fix, commit, re-run the credited
439
- run (the fix commit voided its credit), push, and re-run the compute — the
451
+ never stops the handoff on a provider throw — the step reports `error`
452
+ and close computes the review itself.
453
+ - **A CRITICAL is the worker's to fix.** The handoff settles `fix-required`
454
+ naming the deposit; fix, commit, and re-run the handoff (the fix commit
455
+ voided the credit, so it re-runs the suite, pushes and re-computes) — the
440
456
  acceptance loop's redraft discipline, bounded by
441
457
  `delivery.acceptanceEval.maxRounds`. Still CRITICAL at the cap → take the
442
458
  blocked path. Anything else goes in the hand-off as the severity tally.
@@ -144,18 +144,18 @@ body/issue edit plus a fresh `resolve-stories.js` run.
144
144
  context points you at one; prefer a caller-provided `docsDigestPath` and pull
145
145
  individual files on demand. See [`.agents/instructions.md` § 3](../../instructions.md).
146
146
 
147
- **Write-time audit checklists.** When the caller provides a `checklistPath`
148
- (footprint-matched **local**-lens authoring checklists), read it before you
149
- write and self-check as you author. When absent, lens-aware coverage still
150
- runs maker-blind at Story-scope review inside the close subprocess. The
151
- dispatch step produces `checklistPath` from the Story's predicted footprint
152
- before it spawns the worker — see [`/mandrel-deliver`](../mandrel-deliver.md).
147
+ **Write-time audit checklists.** `single-story-init.js` returns a
148
+ `checklistPath` (footprint-matched **local**-lens authoring checklists built
149
+ from the Story's declared `changes[]` / `references[]`; null when no lens
150
+ matches) on every path, and a multi-Story dispatch prompt names the same
151
+ path. Read it before you write and self-check as you author.
153
152
 
154
153
  **Full-suite discipline (spine Step 2.5).** Repo-invariant guards —
155
154
  drift-guard and schema tests outside the Story's scoped greps — are the
156
155
  failure class that bounces deliveries, and close-validation discovers them
157
- only after the whole close pipeline has run. The run itself is stated once,
158
- in [`deliver-digest.md`](deliver-digest.md) § 5.
156
+ only after the whole close pipeline has run. `story-handoff.js` runs the one
157
+ credited suite before hand-off; what it runs is stated once, in
158
+ [`deliver-digest.md`](deliver-digest.md) § 5.
159
159
 
160
160
  **Conflict with `main` mid-implementation** → resolve as you would any branch
161
161
  rebase; the rebase base is `main` directly.
@@ -189,7 +189,9 @@ node .agents/scripts/update-ticket-state.js --ticket <storyId> --state agent::bl
189
189
  derivation ([`deriveChangeLevel`](../../scripts/lib/orchestration/review-depth.js))
190
190
  and the ceremony resolution
191
191
  ([`resolveCeremonyForRisk`](../../scripts/lib/orchestration/ceremony-routing.js))
192
- in one call. Hand the **same** `files` list to the verdict owner (Step 1a) —
192
+ in one call; the worker receives the same derivation from
193
+ `acceptance-eval.js --init`. Hand the **same** `files` list to the verdict
194
+ owner (Step 1a) —
193
195
  an evaluator that re-ran its own `git diff` could score a different set than
194
196
  the one that routed it.
195
197
 
@@ -324,8 +326,13 @@ The `single-story-close.js` script, in order:
324
326
  would strand a CLOSED issue with no merged work if the PR failed CI, went
325
327
  `BEHIND` base, or closed unmerged. A Story only reaches `agent::done` once
326
328
  its PR to `main` is confirmed merged (Step 5).
327
- 6. Reaps the worktree when `delivery.worktreeIsolation.reapOnSuccess`
328
- is enabled.
329
+ 6. **Leaves the worktree in place.** Worktree lifetime is Story lifetime:
330
+ only the post-land tail reaps it (`tail.worktreeReap`, run before
331
+ `tail.refCleanup` because `git branch -D` refuses a branch a live
332
+ worktree holds; `reapOnSuccess: false` keeps it), so a `pending`,
333
+ `blocked` or `failed` close keeps its working copy. A missing worktree is
334
+ recreated from `story-<id>` before close's first git operation — and the
335
+ `--wait` resume's — never falling back to the main checkout.
329
336
  7. **Releases the Story lease** — a no-op when the operator no longer holds
330
337
  the claim, so a late close never yanks a live claim. Best-effort: a
331
338
  release failure is logged, not fatal, and reported as
@@ -333,6 +340,18 @@ The `single-story-close.js` script, in order:
333
340
  own, so a claim stranded by a failed release is cleared only by `--steal`
334
341
  or by de-assigning the ticket.
335
342
 
343
+ The merge wait recovers on its own when `main` moves under the queued PR. A
344
+ `DIRTY` PR is merged with `origin/<base>` in the Story worktree in that same
345
+ poll (baseline-only conflicts auto-resolve), pushed with hooks, and the wait
346
+ continues — each sync spends one of the BEHIND update attempts. A conflict,
347
+ any other sync failure, or a spent budget posts `friction`, leaves the labels
348
+ alone, and ends `failed` at `phase: base-sync` naming the conflicted files
349
+ and the worktree: resolve there, commit, re-run close. The worktree is
350
+ resolved only for that sync, never to confirm a merge. A PR a new head
351
+ disarmed is re-armed once per head SHA, only when close armed it (the close
352
+ itself, or its persisted envelope) — never a `--no-auto-merge` or `strict`
353
+ PR, and not when the CI digest recorded a red against that head.
354
+
336
355
  ---
337
356
 
338
357
  ## Step 4 — CI watch + fix recovery
@@ -436,15 +455,17 @@ or an unrecoverable failure (→ `status: "failed"`) ends the turn — or a
436
455
  genuine `pending` (§ Step 7). The statuses are the shipped
437
456
  [terminal schema](../../schemas/story-deliver-terminal.schema.json)'s.
438
457
 
439
- ### Resurrecting the worktree after `reapOnSuccess`
458
+ ### A missing Story worktree
440
459
 
441
- `single-story-close.js` reaps the worktree on success when
442
- `delivery.worktreeIsolation.reapOnSuccess` is enabled (the default). To
443
- fix CI you must re-attach a worktree to the existing remote branch:
460
+ The worktree survives until the land, so a red PR's worktree is normally
461
+ still at `.worktrees/story-<storyId>/`. When it is gone, re-running close (or
462
+ the `--wait` resume) recreates it from `story-<storyId>`, fetching the ref
463
+ from origin when only the remote copy is left. To fix CI by hand first:
444
464
 
445
465
  ```bash
446
466
  cd <main-repo>
447
- git fetch origin story-<storyId>
467
+ git fetch origin story-<storyId>:story-<storyId>
468
+ git worktree prune # a deleted-but-registered entry blocks the add
448
469
  git worktree add .worktrees/story-<storyId> story-<storyId>
449
470
  cd .worktrees/story-<storyId>
450
471
  ```
@@ -533,8 +554,8 @@ once per project to delete the conflicting bot workflows entirely.
533
554
 
534
555
  ## Step 6 — Local branch cleanup detail
535
556
 
536
- > **The land tail already ran this** — it is `tail.refCleanup` and
537
- > `tail.baseFastForward` in the terminal envelope. Run it by hand only when
557
+ > **The land tail already ran this** — it is `tail.worktreeReap`,
558
+ > `tail.refCleanup` and `tail.baseFastForward` in the terminal envelope. Run it by hand only when
538
559
  > either step reported `false` (a dirty shared checkout is the common, benign
539
560
  > cause), or after a manual merge on a `--no-wait-merge` run:
540
561
 
@@ -18,7 +18,8 @@ mandatoryReads: [deliver-digest.md]
18
18
  The **one** delivery engine in v2:
19
19
 
20
20
  ```text
21
- single-story-init.js → implement + commits → ceremony → push
21
+ single-story-init.js → implement + commits → acceptance-eval.js --init
22
+ → score → story-handoff.js (preflight, credited run, push, review)
22
23
  ──hand-off──▶ single-story-close.js (gates, PR → main, agent::closing)
23
24
  → CI watch + merge → single-story-confirm-merge.js (agent::done)
24
25
  ```
@@ -33,8 +34,8 @@ that dispatched the work**, never to a spawned worker.
33
34
  - **Inline dispatch** (a one-Story run — digest § 1): one session is both
34
35
  roles and walks Steps 0→7, no hand-off.
35
36
  - **Sub-agent dispatch**: the `story-worker` boots on the `promptPath`
36
- `deliver-run.js` wrote for it, stops at Step 2.5 with the branch pushed and
37
- returns a hand-off; the dispatching `/mandrel-deliver` session runs Step 3
37
+ `deliver-run.js` wrote for it (its role file carries every worker MUST),
38
+ stops at Step 2.5 with `story-handoff.js` `ready` and returns a hand-off; the dispatching `/mandrel-deliver` session runs Step 3
38
39
  **in its own turn** and **serializes the tail — one close at a time across
39
40
  the run**, even though implementation ran in parallel (reference § Step 3).
40
41
 
@@ -81,9 +82,12 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
81
82
 
82
83
  ### Step 1a — Bounded acceptance self-eval loop (**required**)
83
84
 
84
- Run the loop and score it with `acceptance-eval.js` — **digest § 4** carries
85
- the invocation and the proceed / redraft / block contract; per-round mechanics
86
- live in [`acceptance-self-eval.md`](acceptance-self-eval.md). **`proceed`** →
85
+ Start from the skeleton — `acceptance-eval.js --story <storyId> --init --cwd
86
+ <workCwd>` writes one empty record per `acceptance[]` item and prints the
87
+ change set and verdict owner — fill it, and score it with `acceptance-eval.js`;
88
+ **digest § 4** carries the invocations and the proceed / redraft / block
89
+ contract; per-round mechanics live in
90
+ [`acceptance-self-eval.md`](acceptance-self-eval.md). **`proceed`** →
87
91
  Step 2. **`block`** → **do not close**: post a `friction` comment and flip
88
92
  `agent::blocked` (reference § Step 1a).
89
93
 
@@ -91,23 +95,22 @@ Step 2. **`block`** → **do not close**: post a `friction` comment and flip
91
95
 
92
96
  The acceptance verdict owner comes from `delivery.routing.ceremonyProfile` and
93
97
  nothing else — not the diff, not the dispatch mode, never a planner-authored
94
- verdict. **Digest § 3** is the incantation (change set once, derive the level
95
- for review depth, resolve the owner with `ceremony-routing.js`) and the one
96
- home of the rule; edge cases are reference § Step 2. Hard gates always run in
97
- Step 3 — nothing here disables them; do **not** pre-run the chain here —
98
- Step 2.5's credited suite run is the sole exception.
98
+ verdict; `--init` prints it, resolved by `ceremony-routing.js` (**digest § 3** is the rule's one home; edge cases
99
+ are reference § Step 2). Hard gates always run in Step 3 — do **not** pre-run
100
+ the chain here; Step 2.5's credited suite run is the sole exception.
99
101
 
100
- ### Step 2.5 — The one credited suite run, the push, then hand off
102
+ ### Step 2.5 — `story-handoff.js`, then hand off
101
103
 
102
- After the self-eval loop's last fix commit, run the one credited suite run
103
- in the worktree — **digest § 5** is its only home and carries the
104
- invocation. Red → fix, commit, re-run. Then, before the push, seat the
105
- baseline rows for methods the Story added (`--seat-missing`, digest § 5).
104
+ After the self-eval loop's last fix commit, run the one tail command —
105
+ **digest § 5** is its only home: preflight, base merge, the one credited
106
+ suite run, `--seat-missing`, the push with its remote-ref check, and the held
107
+ review, settling `ready`, `fix-required` (fix, commit, re-run it) or
108
+ `blocked` (it flips `agent::blocked`).
106
109
 
107
- Push `story-<storyId>` to `origin`, confirming the remote ref moved. Then
108
- (sub-agent dispatch only) return the hand-off — Story id, `workCwd`,
109
- branch, pushed head SHA, self-eval verdict, `verify[]` evidence — and stop.
110
- Do not open the PR or compose a terminal envelope.
110
+ On `ready` (sub-agent dispatch only) return the hand-off — its envelope
111
+ (Story id, branch, pushed head SHA, review tally), `workCwd`, self-eval
112
+ verdict, `verify[]` evidence — and stop. Do not open the PR or compose a
113
+ terminal envelope.
111
114
 
112
115
  ## Step 3 — Close and land (`single-story-close.js`)
113
116
 
@@ -116,19 +119,23 @@ serialized against sibling Stories:
116
119
 
117
120
  ```bash
118
121
  node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo> \
119
- [--worker-tokens <n>]
122
+ [--worker-tokens <n>] [--worker-model <model>]
120
123
  ```
121
124
 
122
125
  When the host reported a total-token figure for the story-worker's Agent
123
126
  dispatch, pass it as `--worker-tokens <n>` — close records it in its
124
- result's local `telemetry`; omit it when the host reports none.
127
+ result's local `telemetry`; omit it when the host reports none. A
128
+ multi-Story close command from deliver-run already carries `--worker-model`.
125
129
 
126
130
  **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
127
131
  post-land tail in one process. Never background it, never delegate it to a
128
132
  child, and never end your turn while it is still running: "close is running"
129
133
  is not a return value. Branch on the envelope's `status` per **digest § 6**
130
134
  (`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
131
- → Step 4; `failed` → diagnose, re-run). Gate output is captured.
135
+ → Step 4; `failed` → diagnose, re-run; a `phase: base-sync` conflict comes
136
+ back with labels untouched — resolve it in `workCwd`, commit, run
137
+ `nextCommand`, and take the blocked path only if you cannot). Gate output is
138
+ captured.
132
139
 
133
140
  Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
134
141
  `autoMerge` policy and every close flag: reference § Step 3.