mandrel 2.70.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.
- package/.agents/README.md +8 -9
- package/.agents/agents/acceptance-critic.md +1 -0
- package/.agents/agents/auditor.md +1 -0
- package/.agents/agents/plan-critic.md +1 -0
- package/.agents/agents/story-worker.md +63 -64
- package/.agents/docs/agentrc-reference.json +2 -1
- package/.agents/docs/configuration.md +7 -8
- package/.agents/rules/git-conventions-reference.md +2 -2
- package/.agents/schemas/agentrc.schema.json +19 -2
- package/.agents/scripts/acceptance-eval.js +194 -15
- package/.agents/scripts/deliver-run.js +92 -43
- package/.agents/scripts/lib/audit-suite/index.js +1 -1
- package/.agents/scripts/lib/audit-suite/story-checklist.js +65 -0
- package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js +2 -2
- package/.agents/scripts/lib/bootstrap/issue-forms-template.js +1 -1
- package/.agents/scripts/lib/cli-args.js +22 -0
- package/.agents/scripts/lib/close-validation/gates.js +17 -3
- package/.agents/scripts/lib/config/agent-models.js +117 -0
- package/.agents/scripts/lib/config-settings-schema-delivery.js +13 -1
- package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/git/sync-from-base.js +89 -17
- package/.agents/scripts/lib/label-taxonomy.js +13 -3
- package/.agents/scripts/lib/notifications/notifier.js +11 -15
- package/.agents/scripts/lib/observability/close-telemetry.js +19 -3
- package/.agents/scripts/lib/observability/source-classifier.js +1 -0
- package/.agents/scripts/lib/orchestration/code-review.js +2 -2
- package/.agents/scripts/lib/orchestration/file-assumptions.js +45 -11
- package/.agents/scripts/lib/orchestration/plan-context.js +17 -10
- package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +19 -16
- package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +1 -0
- package/.agents/scripts/lib/orchestration/plan-persist/summary.js +4 -3
- package/.agents/scripts/lib/orchestration/resolve-stories.js +10 -2
- package/.agents/scripts/lib/orchestration/review-providers/native.js +5 -165
- package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +14 -2
- package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +151 -56
- package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +4 -0
- package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +20 -4
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +26 -17
- package/.agents/scripts/lib/orchestration/story-handoff.js +849 -0
- package/.agents/scripts/lib/orchestration/story-init-result.js +83 -0
- package/.agents/scripts/lib/orchestration/task-body-validator.js +35 -5
- package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js +1 -1
- package/.agents/scripts/lib/orchestration/ticket-validator.js +20 -2
- package/.agents/scripts/lib/single-story/confirm-merge.js +44 -7
- package/.agents/scripts/lib/story-body/story-body.js +40 -5
- package/.agents/scripts/lib/templates/decomposer-prompts.js +33 -36
- package/.agents/scripts/single-story-close.js +8 -0
- package/.agents/scripts/single-story-init.js +17 -32
- package/.agents/scripts/story-handoff.js +112 -0
- package/.agents/scripts/sync-claude-agents.js +58 -27
- package/.agents/workflows/helpers/acceptance-self-eval.md +24 -18
- package/.agents/workflows/helpers/code-review.md +3 -3
- package/.agents/workflows/helpers/deliver-digest.md +79 -80
- package/.agents/workflows/helpers/deliver-light.md +9 -7
- package/.agents/workflows/helpers/deliver-reference.md +38 -22
- package/.agents/workflows/helpers/deliver-story-reference.md +11 -9
- package/.agents/workflows/helpers/deliver-story.md +30 -23
- package/.agents/workflows/helpers/plan-reference.md +24 -9
- package/docs/CHANGELOG.md +19 -0
- package/lib/cli/registry.js +7 -0
- package/package.json +4 -3
- 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
|
|
25
|
-
shape —
|
|
26
|
-
|
|
27
|
-
2. **Every other run is `subagent
|
|
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
|
|
32
|
-
|
|
33
|
-
|
|
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.
|
|
44
|
+
the only sanctioned landing.
|
|
49
45
|
|
|
50
46
|
## 3. Change set — computed once, handed to everyone
|
|
51
47
|
|
|
52
|
-
One enumeration per Story
|
|
53
|
-
|
|
54
|
-
set, the level and the ceremony
|
|
55
|
-
|
|
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
|
|
67
|
-
|
|
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
|
-
>
|
|
74
|
-
>
|
|
75
|
-
>
|
|
76
|
-
>
|
|
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.
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
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
|
|
94
|
-
whose `criteria[]` length differs
|
|
95
|
-
|
|
96
|
-
Story
|
|
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` →
|
|
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
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
`
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
**
|
|
127
|
-
`
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
|
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
|
|
160
|
-
`
|
|
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
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
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
|
|
181
|
-
|
|
182
|
-
|
|
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[]`,
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
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
|
|
363
|
-
the configured `project.commands.lint` (falling back to
|
|
364
|
-
`quality-preview.js --changed-since origin/<baseBranch
|
|
365
|
-
|
|
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
|
|
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
|
|
403
|
-
|
|
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.
|
|
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
|
|
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,
|
|
425
|
-
code review
|
|
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
|
-
|
|
437
|
-
|
|
438
|
-
- **A CRITICAL is the worker's to fix.**
|
|
439
|
-
|
|
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.**
|
|
148
|
-
(footprint-matched **local**-lens authoring checklists
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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.
|
|
158
|
-
|
|
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
|
|
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
|
|
|
@@ -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 →
|
|
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
|
|
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
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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. **
|
|
95
|
-
|
|
96
|
-
|
|
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 —
|
|
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
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
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
|
-
|
|
108
|
-
(
|
|
109
|
-
|
|
110
|
-
|
|
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
|
|
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.
|
|
@@ -173,9 +173,23 @@ anything a plan authored.
|
|
|
173
173
|
is then a dry-run **warning**, not a rejection. `deletes` stays explicit —
|
|
174
174
|
a bare path can never express a removal — and a `deletes` naming a path
|
|
175
175
|
absent at base is the one `changes[]` shape still refused.
|
|
176
|
-
-
|
|
177
|
-
|
|
178
|
-
|
|
176
|
+
- **`## Spec` decides.** Every load-bearing mechanism is chosen there with
|
|
177
|
+
its why; a choice is left to the deliverer only when it is genuinely not
|
|
178
|
+
load-bearing. It stays contract-level — no per-file behavior narration —
|
|
179
|
+
and as long as the work needs. There is no word or token budget.
|
|
180
|
+
- **`## Context` is the handoff.** An optional text section after `## Spec`:
|
|
181
|
+
entry points (file + symbol), the pattern to mirror, the test file or
|
|
182
|
+
harness to extend, known traps, the scoped test command — verified facts,
|
|
183
|
+
tersely, never a walkthrough. Backticked repo paths in it are probed at
|
|
184
|
+
persist and **warn** when absent at base.
|
|
185
|
+
- **`references[]` names the read-first files.** Author the files the
|
|
186
|
+
deliverer should read before editing. A bare path is the default: persist
|
|
187
|
+
derives `exists` by probing base and warns, never refuses, on an absent one.
|
|
188
|
+
- **Slicing checkpoints may end `— verify: <exact command>`** — encouraged
|
|
189
|
+
past two checkpoints, so each stage is proven before the next starts.
|
|
190
|
+
|
|
191
|
+
Context, References and checkpoint verify commands are advisory like
|
|
192
|
+
`changes[]`; `acceptance[]` / `verify[]` stay the only binding contract.
|
|
179
193
|
|
|
180
194
|
A faithfully-filled skeleton — placeholders replaced, pre-resolved entries
|
|
181
195
|
kept — passes the persist ticket validators with no round-trip.
|
|
@@ -183,10 +197,10 @@ kept — passes the persist ticket validators with no round-trip.
|
|
|
183
197
|
### Authored entry shape
|
|
184
198
|
|
|
185
199
|
Each `stories.json` entry: `slug` (`^[a-z0-9][a-z0-9-]*$`), `type: "story"`,
|
|
186
|
-
`title`, `body` (`goal`, optional `spec`, `changes[]`
|
|
187
|
-
by default, or `{path, assumption}` with
|
|
188
|
-
`creates|refactors-existing|deletes` to pin one, `
|
|
189
|
-
`
|
|
200
|
+
`title`, `body` (`goal`, optional `slicing` / `spec` / `context`, `changes[]`
|
|
201
|
+
— a **bare path string** by default, or `{path, assumption}` with
|
|
202
|
+
`creates|refactors-existing|deletes` to pin one, optional `references[]` and
|
|
203
|
+
`non_goals`), top-level `acceptance[]`, `verify[]` (each a **bare
|
|
190
204
|
command** — there is no tier suffix), and `depends_on[]` (a sibling slug, or
|
|
191
205
|
`#<id>` for an existing open Story).
|
|
192
206
|
|
|
@@ -368,7 +382,8 @@ Commit subjects are not scanned — the `commit-msg` hook and
|
|
|
368
382
|
**Warnings — listed, then the persist proceeds:** a `creates` on a path that
|
|
369
383
|
exists at base or a `refactors-existing` on one that does not (including a
|
|
370
384
|
path the base branch deleted or renamed, named with the removing commit), a
|
|
371
|
-
goal or
|
|
385
|
+
goal, acceptance or `## Context` path absent at base, a bare `references[]`
|
|
386
|
+
entry absent at base, an empty `verify[]`, a source id
|
|
372
387
|
assigned to the primary Story by default, a `verify[]` command naming an
|
|
373
388
|
absent test file, an `open-question` in a body (`Flag if…`, `TBD`, a trailing
|
|
374
389
|
`?`), and a `pinned-identifier` in an acceptance item — a backticked bare symbol
|
|
@@ -376,7 +391,7 @@ that is not a path, a label, a kebab token, a flag or a command, which the
|
|
|
376
391
|
advisory `changes[]` is free to reshape out from under the criterion. The
|
|
377
392
|
list also names every **repair** the run applied — a plain-string bullet or a
|
|
378
393
|
trailing parenthetical rewritten into `{ path, assumption }` by probing base,
|
|
379
|
-
and an `AC-<n>:` handle normalised off an acceptance item. The same list rides
|
|
394
|
+
a bare reference present at base derived as `exists`, and an `AC-<n>:` handle normalised off an acceptance item. The same list rides
|
|
380
395
|
the result envelope as `warnings[]` and `repairs[]`, carried from the
|
|
381
396
|
write-free pass onto the chained run's envelope.
|
|
382
397
|
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,25 @@ All notable changes to this project will be documented in this file.
|
|
|
15
15
|
-->
|
|
16
16
|
<!-- markdownlint-disable-file MD004 MD012 MD037 -->
|
|
17
17
|
|
|
18
|
+
## [2.71.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.70.0...mandrel-v2.71.0) (2026-09-30)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* close resolves baseline-only merge conflicts, hands other conflicts back to the delivering agent, and retries a failed done-label write instead of blocking for a human ([#5520](https://github.com/dsj1984/mandrel/issues/5520)) ([#5527](https://github.com/dsj1984/mandrel/issues/5527)) ([2e56566](https://github.com/dsj1984/mandrel/commit/2e565668bf0f02fc0c84b71779a50bec72ff84f4))
|
|
24
|
+
* deliver: the worker's tail is one story-handoff command that hands fixable failures back instead of blocking, the worker never writes agent::closing, and self-eval starts from a verdict skeleton ([#5518](https://github.com/dsj1984/mandrel/issues/5518)) ([#5524](https://github.com/dsj1984/mandrel/issues/5524)) ([74d2ef2](https://github.com/dsj1984/mandrel/commit/74d2ef2411efcb6a5a116401af5a52448cbd78fe))
|
|
25
|
+
* notify on agent::blocked, refuse agent::review-spec Stories at delivery, drop the native reviewer's duplicate lint pass, and correct the drift the SDLC review found ([#5517](https://github.com/dsj1984/mandrel/issues/5517)) ([#5523](https://github.com/dsj1984/mandrel/issues/5523)) ([7330307](https://github.com/dsj1984/mandrel/commit/7330307013a1678287dd0192a3f9042abca92432))
|
|
26
|
+
* plan: author Stories as a grounded handoff — decided Spec, References, a probed Context section and verifiable Slicing checkpoints, in a prompt no longer than today's ([#5516](https://github.com/dsj1984/mandrel/issues/5516)) ([#5522](https://github.com/dsj1984/mandrel/issues/5522)) ([f7b8388](https://github.com/dsj1984/mandrel/commit/f7b8388524737cf230eaa6a3bf19860b45d10ce5))
|
|
27
|
+
* role agents declare a model default, delivery.routing.agentModels overrides it per role, and close records the dispatched worker's model ([#5519](https://github.com/dsj1984/mandrel/issues/5519)) ([#5526](https://github.com/dsj1984/mandrel/issues/5526)) ([39a93d8](https://github.com/dsj1984/mandrel/commit/39a93d86942c2814cdea5b0074e7f352e3db832e))
|
|
28
|
+
* story-handoff preflight runs the standalone ratchets CI's baselines job runs, so a dead-export or cycle is fix-required at handoff instead of a CI red ([#5528](https://github.com/dsj1984/mandrel/issues/5528)) ([#5530](https://github.com/dsj1984/mandrel/issues/5530)) ([23c44d0](https://github.com/dsj1984/mandrel/commit/23c44d062b9a771373bf82b32ea7a70839af6446))
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
### Fixed
|
|
32
|
+
|
|
33
|
+
* **agents:** stop story-worker flipping agent::closing at hand-off (refs [#5515](https://github.com/dsj1984/mandrel/issues/5515)) ([#5521](https://github.com/dsj1984/mandrel/issues/5521)) ([1f5b564](https://github.com/dsj1984/mandrel/commit/1f5b5649747b9dad826205f9819bc12738bbe55e))
|
|
34
|
+
* **deps:** clear brace-expansion, fast-uri, and markdown-it advisories ([#5508](https://github.com/dsj1984/mandrel/issues/5508)) ([fd97225](https://github.com/dsj1984/mandrel/commit/fd972259f111390d9ca1515d1a5cde45995c1709)), closes [#5507](https://github.com/dsj1984/mandrel/issues/5507)
|
|
35
|
+
* story-handoff: a non-fast-forward push rejection is fix-required, not blocked ([#5525](https://github.com/dsj1984/mandrel/issues/5525)) ([#5529](https://github.com/dsj1984/mandrel/issues/5529)) ([332389c](https://github.com/dsj1984/mandrel/commit/332389c03fcaf9497b134d4574ae7a1a712d62b6))
|
|
36
|
+
|
|
18
37
|
## [2.70.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.69.0...mandrel-v2.70.0) (2026-09-29)
|
|
19
38
|
|
|
20
39
|
|