mandrel 2.69.0 → 2.71.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 (76) 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/scripts/acceptance-eval.js +194 -15
  11. package/.agents/scripts/audit-to-stories.js +39 -247
  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/audit-to-stories/finding-adapter.js +1 -1
  17. package/.agents/scripts/lib/bootstrap/issue-forms-template.js +1 -1
  18. package/.agents/scripts/lib/cli-args.js +22 -0
  19. package/.agents/scripts/lib/close-validation/gates.js +17 -3
  20. package/.agents/scripts/lib/config/agent-models.js +117 -0
  21. package/.agents/scripts/lib/config-settings-schema-delivery.js +13 -1
  22. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  23. package/.agents/scripts/lib/findings/route-finding.js +15 -0
  24. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  25. package/.agents/scripts/lib/git/sync-from-base.js +89 -17
  26. package/.agents/scripts/lib/label-taxonomy.js +13 -3
  27. package/.agents/scripts/lib/notifications/notifier.js +11 -15
  28. package/.agents/scripts/lib/observability/close-telemetry.js +19 -3
  29. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  30. package/.agents/scripts/lib/orchestration/code-review.js +2 -2
  31. package/.agents/scripts/lib/orchestration/file-assumptions.js +45 -11
  32. package/.agents/scripts/lib/orchestration/plan-context.js +31 -11
  33. package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +35 -117
  34. package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
  35. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +24 -22
  36. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +1 -0
  37. package/.agents/scripts/lib/orchestration/plan-persist/summary.js +4 -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/base-sync.js +151 -56
  42. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +4 -0
  43. package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +20 -4
  44. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +26 -17
  45. package/.agents/scripts/lib/orchestration/story-handoff.js +849 -0
  46. package/.agents/scripts/lib/orchestration/story-init-result.js +83 -0
  47. package/.agents/scripts/lib/orchestration/task-body-validator.js +35 -5
  48. package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js +1 -1
  49. package/.agents/scripts/lib/orchestration/ticket-validator.js +20 -2
  50. package/.agents/scripts/lib/single-story/confirm-merge.js +44 -7
  51. package/.agents/scripts/lib/story-body/story-body.js +40 -5
  52. package/.agents/scripts/lib/templates/decomposer-prompts.js +33 -36
  53. package/.agents/scripts/single-story-close.js +8 -0
  54. package/.agents/scripts/single-story-init.js +17 -32
  55. package/.agents/scripts/story-handoff.js +112 -0
  56. package/.agents/scripts/sync-claude-agents.js +58 -27
  57. package/.agents/templates/docs/audit-sweep-runbook.md +29 -59
  58. package/.agents/workflows/audit-to-stories.md +40 -67
  59. package/.agents/workflows/helpers/acceptance-self-eval.md +24 -18
  60. package/.agents/workflows/helpers/code-review.md +3 -3
  61. package/.agents/workflows/helpers/deliver-digest.md +79 -80
  62. package/.agents/workflows/helpers/deliver-light.md +9 -7
  63. package/.agents/workflows/helpers/deliver-reference.md +38 -22
  64. package/.agents/workflows/helpers/deliver-story-reference.md +11 -9
  65. package/.agents/workflows/helpers/deliver-story.md +30 -23
  66. package/.agents/workflows/helpers/plan-reference.md +24 -9
  67. package/docs/CHANGELOG.md +30 -0
  68. package/lib/cli/registry.js +7 -0
  69. package/lib/migrations/index.js +2 -0
  70. package/lib/migrations/steps/2.70.0-retire-audit-ledger.js +36 -0
  71. package/package.json +4 -3
  72. package/.agents/scripts/lib/audit-to-stories/ledger-commit.js +0 -184
  73. package/.agents/scripts/lib/audit-to-stories/ledger-pr.js +0 -279
  74. package/.agents/scripts/lib/audit-to-stories/ledger-record.js +0 -88
  75. package/.agents/scripts/lib/findings/audit-ledger.js +0 -289
  76. package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js +0 -272
@@ -36,15 +36,20 @@ per-criterion, mid-delivery, and evaluates the actual work product.
36
36
  alone**:
37
37
 
38
38
  > ```bash
39
- > node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>
39
+ > node <main-repo>/.agents/scripts/acceptance-eval.js --story <storyId> --init --cwd <workCwd>
40
40
  > ```
41
41
  >
42
- > One call computes the change set once (`files`), derives the level and
43
- > classes **for review depth**, and resolves the owner (`mode`, `reason`,
44
- > `verdictOwner`): **`minimal` / `standard` → `inline`** (the default — you
45
- > author the verdict yourself), **`strict` → `fresh`** (dispatch the
46
- > maker-blind critic). The derived level feeds `review-depth.js`, not
47
- > this decision; review depth resolves `deep` for any sensitive path.
42
+ > One call writes the verdict **skeleton** — one record per
43
+ > `acceptance[]` item, in order, `index` and `criterion` filled, `verdict`
44
+ > and `evidence` empty, plus `storyId`, `schemaVersion`, the next `round`
45
+ > and HEAD — under `temp/scratch/story-<id>/`, and prints its path, the
46
+ > change set computed once (`files`) and the `verdictOwner`, derived by the
47
+ > same function `ceremony-derive.js` uses: **`minimal` / `standard` →
48
+ > `inline`** (the default — you fill the skeleton yourself), **`strict` →
49
+ > `fresh`** (dispatch the maker-blind critic with that `files` list).
50
+ > `ceremony-derive.js` stays for close and for a critic hand-off outside
51
+ > this loop; the level it derives feeds `review-depth.js`, not this
52
+ > decision.
48
53
 
49
54
  **Never run both**, and never run a preliminary self-assessment before
50
55
  dispatching a fresh critic — the redundant pre-pass buys no measurable
@@ -95,13 +100,11 @@ per-criterion, mid-delivery, and evaluates the actual work product.
95
100
  without being respawned; a stale or absent stamp reports `spawn: true` and
96
101
  the command runs for real. The credited run itself is stated once, in
97
102
  [`deliver-digest.md`](deliver-digest.md) § 5.
98
- + Emits **one** verdict file under `temp/scratch/story-<id>/` conforming to
103
+ + **Fills the skeleton** into **one** verdict file conforming to
99
104
  [`acceptance-eval-verdict.schema.json`](../../schemas/acceptance-eval-verdict.schema.json):
100
- one `{ index, criterion, verdict: met|partial|unmet, evidence,
101
- verifyEvidence[] }` record per `acceptance[]` item, in acceptance-array
102
- order, under a single top-level `storyId`, `schemaVersion`, `round` and
103
- `commitSha`. A fresh critic **returns that path to you** rather than
104
- calling the gate itself.
105
+ every `{ index, criterion, verdict: met|partial|unmet, evidence,
106
+ verifyEvidence[] }` record, in acceptance-array order. A fresh critic
107
+ **returns that path to you** rather than calling the gate itself.
105
108
  2. **Decide — exactly one gate call per round.** Run the gate against that one
106
109
  verdict file (the caller's Step 1a names the exact invocation — omit
107
110
  `--epic`). The gate **scores the verdict the round produced** — schema
@@ -115,8 +118,10 @@ per-criterion, mid-delivery, and evaluates the actual work product.
115
118
  The gate reads the Story's `acceptance[]` count itself (Story #5313): a
116
119
  verdict whose `criteria[]` length differs — one covering only part of the
117
120
  Story — is rejected **before scoring**, with an error naming the count and
118
- consuming **no round**. `--expected-criteria` is still accepted but
119
- redundant; when passed it must agree with that count.
121
+ consuming **no round**. A skeleton record left unfilled (empty `verdict`
122
+ or `evidence`) is likewise rejected before scoring, naming the unfilled
123
+ indices, with no round consumed. `--expected-criteria` is still accepted
124
+ but redundant; when passed it must agree with that count.
120
125
 
121
126
  > **Why one call per round and not several.** The round counter is
122
127
  > **Story-scoped** — derived by counting `acceptance-eval` signals in the
@@ -127,11 +132,12 @@ per-criterion, mid-delivery, and evaluates the actual work product.
127
132
  The gate validates the verdict against the schema, applies the round cap,
128
133
  emits the per-criterion `acceptance-eval` signal into the retro / feedback
129
134
  substrate, prints a JSON envelope, and exits with one of three decisions:
130
- + **`decision: "proceed"`** (every criterion `met`) → exit 0. Proceed to
131
- close.
135
+ + **`decision: "proceed"`** (every criterion `met`) → exit 0. Run the one
136
+ tail command, `story-handoff.js` ([`deliver-digest.md`](deliver-digest.md)
137
+ § 5).
132
138
  + **`decision: "redraft"`** (some `partial`/`unmet`, rounds remaining) →
133
139
  exit 0. Redraft the flagged criteria (named in `unmetCriteria[]`), commit
134
- the fix, and start another round.
140
+ the fix, re-run `--init` for the next round's skeleton, and score again.
135
141
  + **`decision: "block"`** (round cap reached, criteria still unmet) → exit
136
142
  non-zero. **Do not proceed to close.** Take the caller's blocked path
137
143
  (transition to `agent::blocked`) and post a `friction` comment naming the
@@ -79,7 +79,7 @@ How each tier changes the review protocol:
79
79
  The LLM-backed review providers (code-review, codex, security-review,
80
80
  ultrareview) render the resolved `depth` into the prompt/instructions they emit so the underlying
81
81
  model actually changes thoroughness. The native provider deliberately ignores
82
- `depth` — its mechanical lint + maintainability sweep already scales with diff
82
+ `depth` — its mechanical maintainability sweep already scales with diff
83
83
  size, and there is no "review harder" knob a deterministic scorer can turn (its
84
84
  module JSDoc documents this). When you (the host LLM) perform the Step 2 pillar
85
85
  review yourself, honor the `depth` semantics above directly.
@@ -108,8 +108,8 @@ diff `baseRef..headRef`, with the LLM-backed providers honoring `depth`
108
108
  The pipeline will:
109
109
 
110
110
  - Generate a `git diff baseRef..headRef`.
111
- - Calculate maintainability scores for all new/modified files.
112
- - Run a focused lint check on the change set.
111
+ - Calculate maintainability scores for all new/modified files (lint is a
112
+ close-validation gate, so the review does not re-run it).
113
113
  - Post a structured summary report to the `[TICKET_ID]` issue.
114
114
 
115
115
  ### Story scope runs no lens pass
@@ -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