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.
- 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/audit-to-stories.js +39 -247
- 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/audit-to-stories/finding-adapter.js +1 -1
- 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/findings/route-finding.js +15 -0
- 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 +31 -11
- package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +35 -117
- package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +24 -22
- 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/templates/docs/audit-sweep-runbook.md +29 -59
- package/.agents/workflows/audit-to-stories.md +40 -67
- 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 +30 -0
- package/lib/cli/registry.js +7 -0
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.70.0-retire-audit-ledger.js +36 -0
- package/package.json +4 -3
- package/.agents/scripts/lib/audit-to-stories/ledger-commit.js +0 -184
- package/.agents/scripts/lib/audit-to-stories/ledger-pr.js +0 -279
- package/.agents/scripts/lib/audit-to-stories/ledger-record.js +0 -88
- package/.agents/scripts/lib/findings/audit-ledger.js +0 -289
- package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js +0 -272
|
@@ -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,36 @@ 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
|
+
|
|
37
|
+
## [2.70.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.69.0...mandrel-v2.70.0) (2026-09-29)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
### ⚠ BREAKING CHANGES
|
|
41
|
+
|
|
42
|
+
* audit-to-stories.js no longer accepts --ledger or --ledger-commit (both now fail as unknown options); the --auto run summary no longer carries the totals.suppressedByLedger or ledger fields, and no skip-accepted-risk classification exists. `mandrel update` runs the 2.70.0 migration, which deletes baselines/audit-ledger.json.
|
|
43
|
+
|
|
44
|
+
### Added
|
|
45
|
+
|
|
46
|
+
* retire the cross-run audit ledger: Issue provenance footers become the single dedup memory, and no sweep needs a ledger PR ([#5502](https://github.com/dsj1984/mandrel/issues/5502)) ([#5503](https://github.com/dsj1984/mandrel/issues/5503)) ([ac05436](https://github.com/dsj1984/mandrel/commit/ac05436eb5ca89c73d22fe0042d41e5cd0f717d8))
|
|
47
|
+
|
|
18
48
|
## [2.69.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.68.0...mandrel-v2.69.0) (2026-09-27)
|
|
19
49
|
|
|
20
50
|
|
package/lib/cli/registry.js
CHANGED
|
@@ -868,6 +868,10 @@ const TEST_CREDIT_DEPOSIT_COMMAND =
|
|
|
868
868
|
const COVERAGE_CAPTURE_COMMAND =
|
|
869
869
|
'node .agents/scripts/coverage-capture.js --cwd <workCwd>';
|
|
870
870
|
|
|
871
|
+
/** The worker's one tail command; it runs whichever depositor applies. */
|
|
872
|
+
const STORY_HANDOFF_COMMAND =
|
|
873
|
+
'node .agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>';
|
|
874
|
+
|
|
871
875
|
const TEST_CREDIT_REMEDY = `run the suite through the depositor instead of bare \`npm test\`: ${TEST_CREDIT_DEPOSIT_COMMAND}`;
|
|
872
876
|
|
|
873
877
|
const PRE_PUSH_REMEDY =
|
|
@@ -1010,6 +1014,9 @@ function describePrePushHook(projectRoot, readFileImpl) {
|
|
|
1010
1014
|
function runTestCreditPath({ projectRoot, readFile = fs.readFileSync } = {}) {
|
|
1011
1015
|
const root = projectRoot ?? process.cwd();
|
|
1012
1016
|
const parts = [
|
|
1017
|
+
{
|
|
1018
|
+
detail: `the worker's \`${STORY_HANDOFF_COMMAND}\` runs the credited run close reads`,
|
|
1019
|
+
},
|
|
1013
1020
|
describeCreditedRun({
|
|
1014
1021
|
scripts: readProjectScripts(root, readFile),
|
|
1015
1022
|
crapEnabled: isCrapEnabled(root, readFile),
|
package/lib/migrations/index.js
CHANGED
|
@@ -17,6 +17,7 @@ import { retirePlanningLimitKnobs } from './steps/2.57.0-retire-planning-limit-k
|
|
|
17
17
|
import { retireAuditResultsAutoFile } from './steps/2.60.0-retire-audit-results-autofile.js';
|
|
18
18
|
import { baselineMergeQueueShape } from './steps/2.63.0-baseline-merge-queue-shape.js';
|
|
19
19
|
import { foldClaudeMdIntoAgentsMdStep } from './steps/2.65.0-fold-claude-md-into-agents-md.js';
|
|
20
|
+
import { retireAuditLedger } from './steps/2.70.0-retire-audit-ledger.js';
|
|
20
21
|
import { stripRemovedAgentrcKeys } from './steps/strip-removed-agentrc-keys.js';
|
|
21
22
|
|
|
22
23
|
/**
|
|
@@ -42,6 +43,7 @@ export const migrations = [
|
|
|
42
43
|
stripRemovedAgentrcKeys,
|
|
43
44
|
baselineMergeQueueShape,
|
|
44
45
|
foldClaudeMdIntoAgentsMdStep,
|
|
46
|
+
retireAuditLedger,
|
|
45
47
|
];
|
|
46
48
|
|
|
47
49
|
export { compareVersions };
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
// lib/migrations/steps/2.70.0-retire-audit-ledger.js
|
|
2
|
+
/**
|
|
3
|
+
* Delete the retired cross-run audit ledger. Issue provenance footers are the
|
|
4
|
+
* only cross-run dedup memory now, so nothing reads the file. Deletes that one
|
|
5
|
+
* path and nothing else.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import nodeFs from 'node:fs';
|
|
9
|
+
import path from 'node:path';
|
|
10
|
+
|
|
11
|
+
const AUDIT_LEDGER_PATH = path.join('baselines', 'audit-ledger.json');
|
|
12
|
+
|
|
13
|
+
export const retireAuditLedger = {
|
|
14
|
+
version: '2.70.0',
|
|
15
|
+
description:
|
|
16
|
+
'delete the retired baselines/audit-ledger.json — Issue provenance ' +
|
|
17
|
+
'footers are the cross-run audit dedup memory (Story #5502)',
|
|
18
|
+
/**
|
|
19
|
+
* @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
|
|
20
|
+
* @param {typeof nodeFs} [fsImpl]
|
|
21
|
+
* @returns {boolean}
|
|
22
|
+
*/
|
|
23
|
+
detect(ctx, fsImpl = ctx?.fs ?? nodeFs) {
|
|
24
|
+
const root = ctx?.projectRoot ?? process.cwd();
|
|
25
|
+
return fsImpl.existsSync(path.join(root, AUDIT_LEDGER_PATH));
|
|
26
|
+
},
|
|
27
|
+
/**
|
|
28
|
+
* @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
|
|
29
|
+
* @param {typeof nodeFs} [fsImpl]
|
|
30
|
+
* @returns {void}
|
|
31
|
+
*/
|
|
32
|
+
apply(ctx, fsImpl = ctx?.fs ?? nodeFs) {
|
|
33
|
+
const root = ctx?.projectRoot ?? process.cwd();
|
|
34
|
+
fsImpl.rmSync(path.join(root, AUDIT_LEDGER_PATH), { force: true });
|
|
35
|
+
},
|
|
36
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mandrel",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.71.0",
|
|
4
4
|
"description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
|
|
5
5
|
"files": [
|
|
6
6
|
".agents/",
|
|
@@ -85,7 +85,7 @@
|
|
|
85
85
|
"author": "",
|
|
86
86
|
"license": "MIT",
|
|
87
87
|
"bin": {
|
|
88
|
-
"mandrel": "
|
|
88
|
+
"mandrel": "bin/mandrel.js"
|
|
89
89
|
},
|
|
90
90
|
"type": "module",
|
|
91
91
|
"bugs": {
|
|
@@ -141,11 +141,12 @@
|
|
|
141
141
|
"peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
|
|
142
142
|
"overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.3.2 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended. The floor has since been raised twice for advisories against the pinned range itself (most recently to ^4.3.2 for GHSA-2883-xcg3-v3hh, whose fix is 4.3.2) — raising it is safe and does NOT touch the coupling above; check-pinned-override-notes.js now fails the build if this sentence and the pin disagree.",
|
|
143
143
|
"dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions.",
|
|
144
|
+
"overrides.markdown-it": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT markdown-it 14.1.1, which carries GHSA-253c-mchw-3w2r (moderate — quadratic linkify paths block the event loop). The advisory’s vulnerable range is everything < 14.3.1, so this tree-wide ^14.3.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.23.3, a breaking bump coupled to the js-yaml major above; do not take it. `npm run lint` is what must be re-run if this pin moves.",
|
|
144
145
|
"overrides.smol-toml": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT smol-toml 1.6.1, which carries GHSA-7w5x-hrqm-74c2 (high — denial of service via malformed TOML). The advisory’s vulnerable range is everything <= 1.7.0, so no lockfile-only resolution reaches a patched version and this tree-wide ^1.7.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.21.0 — a DOWNGRADE presented as a breaking change; do not take it. An npm override wins over a transitive package’s own exact pin, so markdownlint-cli2 runs against a minor it never declared: `npm run lint` was confirmed green under the forced version and is what must be re-run if this pin moves. knip declares ^1.6.1 and is satisfied natively. smol-toml is NOT a direct dependency, so unlike overrides.js-yaml there is no lockstep duplicate range to keep in sync."
|
|
145
146
|
},
|
|
146
147
|
"overrides": {
|
|
147
148
|
"js-yaml": "^4.3.2",
|
|
148
|
-
"markdown-it": "^14.
|
|
149
|
+
"markdown-it": "^14.3.1",
|
|
149
150
|
"smol-toml": "^1.7.1"
|
|
150
151
|
}
|
|
151
152
|
}
|
|
@@ -1,184 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Persist the cross-run audit ledger, which an ephemeral checkout would
|
|
3
|
-
* otherwise discard.
|
|
4
|
-
*/
|
|
5
|
-
|
|
6
|
-
import { DEFAULT_LEDGER_PATH } from '../findings/audit-ledger.js';
|
|
7
|
-
import { gh as defaultGh } from '../gh-exec.js';
|
|
8
|
-
import { gitSync } from '../git-utils.js';
|
|
9
|
-
import { openLedgerPullRequest, probeGit } from './ledger-pr.js';
|
|
10
|
-
|
|
11
|
-
const DEFAULT_BASE_BRANCH = 'main';
|
|
12
|
-
|
|
13
|
-
/**
|
|
14
|
-
* @param {Date|string|number} [now]
|
|
15
|
-
* @returns {string}
|
|
16
|
-
*/
|
|
17
|
-
function isoDate(now) {
|
|
18
|
-
const date = now instanceof Date ? now : new Date(now ?? Date.now());
|
|
19
|
-
return date.toISOString().slice(0, 10);
|
|
20
|
-
}
|
|
21
|
-
|
|
22
|
-
/**
|
|
23
|
-
* Explicit, then config, then `main`; a failed config resolve must never break
|
|
24
|
-
* a sweep that has already done its work.
|
|
25
|
-
* @param {string} [explicit]
|
|
26
|
-
* @returns {Promise<string>}
|
|
27
|
-
*/
|
|
28
|
-
async function resolveBaseBranch(explicit) {
|
|
29
|
-
if (typeof explicit === 'string' && explicit.length > 0) return explicit;
|
|
30
|
-
try {
|
|
31
|
-
const { resolveConfig } = await import('../config-resolver.js');
|
|
32
|
-
const branch = resolveConfig()?.project?.baseBranch;
|
|
33
|
-
if (typeof branch === 'string' && branch.length > 0) return branch;
|
|
34
|
-
} catch (_) {
|
|
35
|
-
// fall through to the default
|
|
36
|
-
}
|
|
37
|
-
return DEFAULT_BASE_BRANCH;
|
|
38
|
-
}
|
|
39
|
-
|
|
40
|
-
/**
|
|
41
|
-
* `unpersisted`: the ledger changed but there is no `origin` or HEAD is off
|
|
42
|
-
* the base branch, so a commit here would not reach shared state.
|
|
43
|
-
*
|
|
44
|
-
* @param {object} [params]
|
|
45
|
-
* @param {string} [params.ledgerPath]
|
|
46
|
-
* @param {string} [params.baseBranch]
|
|
47
|
-
* @param {string} [params.cwd]
|
|
48
|
-
* @param {(cwd: string, ...args: string[]) => string} [params.git]
|
|
49
|
-
* @returns {Promise<{ ledgerPath: string, baseBranch: string, changed: boolean,
|
|
50
|
-
* hasOrigin: boolean, headBranch: string, onBaseBranch: boolean,
|
|
51
|
-
* unpersisted: boolean }>}
|
|
52
|
-
*/
|
|
53
|
-
async function assessLedgerPersistence({
|
|
54
|
-
ledgerPath = DEFAULT_LEDGER_PATH,
|
|
55
|
-
baseBranch,
|
|
56
|
-
cwd = process.cwd(),
|
|
57
|
-
git = gitSync,
|
|
58
|
-
} = {}) {
|
|
59
|
-
const base = await resolveBaseBranch(baseBranch);
|
|
60
|
-
const probe = (args) => probeGit(git, cwd, args);
|
|
61
|
-
const changed = ledgerIsDirty(probe, ledgerPath);
|
|
62
|
-
const hasOrigin = hasOriginRemote(probe);
|
|
63
|
-
const headBranch = headBranchOf(probe);
|
|
64
|
-
|
|
65
|
-
return {
|
|
66
|
-
ledgerPath,
|
|
67
|
-
baseBranch: base,
|
|
68
|
-
changed,
|
|
69
|
-
hasOrigin,
|
|
70
|
-
headBranch,
|
|
71
|
-
onBaseBranch: headBranch === base,
|
|
72
|
-
unpersisted: changed && (!hasOrigin || headBranch !== base),
|
|
73
|
-
};
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
/**
|
|
77
|
-
* Pathspec-scoped, so unrelated dirt never counts.
|
|
78
|
-
* @param {(args: string[]) => string} probe
|
|
79
|
-
* @param {string} ledgerPath
|
|
80
|
-
* @returns {boolean}
|
|
81
|
-
*/
|
|
82
|
-
function ledgerIsDirty(probe, ledgerPath) {
|
|
83
|
-
return probe(['status', '--porcelain', '--', ledgerPath]).length > 0;
|
|
84
|
-
}
|
|
85
|
-
|
|
86
|
-
/**
|
|
87
|
-
* @param {(args: string[]) => string} probe
|
|
88
|
-
* @returns {boolean}
|
|
89
|
-
*/
|
|
90
|
-
function hasOriginRemote(probe) {
|
|
91
|
-
return probe(['remote'])
|
|
92
|
-
.split('\n')
|
|
93
|
-
.map((line) => line.trim())
|
|
94
|
-
.includes('origin');
|
|
95
|
-
}
|
|
96
|
-
|
|
97
|
-
/**
|
|
98
|
-
* `''` when detached or commitless — both read as "not the base branch".
|
|
99
|
-
* @param {(args: string[]) => string} probe
|
|
100
|
-
* @returns {string}
|
|
101
|
-
*/
|
|
102
|
-
function headBranchOf(probe) {
|
|
103
|
-
return probe(['rev-parse', '--abbrev-ref', 'HEAD']);
|
|
104
|
-
}
|
|
105
|
-
|
|
106
|
-
/**
|
|
107
|
-
* @param {{ ledgerPath: string, baseBranch: string, hasOrigin: boolean, headBranch: string }} state
|
|
108
|
-
* @returns {string}
|
|
109
|
-
*/
|
|
110
|
-
function unpersistedWarning(state) {
|
|
111
|
-
const cause = state.hasOrigin
|
|
112
|
-
? `HEAD is on "${state.headBranch || '(detached)'}", not the base branch "${state.baseBranch}"`
|
|
113
|
-
: 'this checkout has no "origin" remote';
|
|
114
|
-
return `ledger not persisted: ${state.ledgerPath} changed but ${cause}, so this sweep's memory will be lost when the checkout goes away. Re-run with --ledger-commit to open a PR for it, or commit ${state.ledgerPath} by hand.`;
|
|
115
|
-
}
|
|
116
|
-
|
|
117
|
-
/**
|
|
118
|
-
* Marks the summary `unpersisted: true` (and warns) when the checkout cannot
|
|
119
|
-
* keep the new memory.
|
|
120
|
-
*
|
|
121
|
-
* @param {object} [params]
|
|
122
|
-
* @param {object|null} [params.ledger]
|
|
123
|
-
* @param {string} [params.ledgerPath]
|
|
124
|
-
* @param {boolean} [params.dryRun]
|
|
125
|
-
* @param {boolean} [params.ledgerCommit]
|
|
126
|
-
* @param {string} [params.cwd]
|
|
127
|
-
* @param {(cwd: string, ...args: string[]) => string} [params.git]
|
|
128
|
-
* @param {{ warn: Function }} [params.logger]
|
|
129
|
-
* @returns {Promise<object|null>} the (possibly annotated) ledger summary.
|
|
130
|
-
*/
|
|
131
|
-
export async function resolveLedgerSummary({
|
|
132
|
-
ledger = null,
|
|
133
|
-
ledgerPath = DEFAULT_LEDGER_PATH,
|
|
134
|
-
dryRun,
|
|
135
|
-
ledgerCommit,
|
|
136
|
-
cwd,
|
|
137
|
-
git,
|
|
138
|
-
logger,
|
|
139
|
-
} = {}) {
|
|
140
|
-
if (dryRun || ledgerCommit) return ledger;
|
|
141
|
-
const state = await assessLedgerPersistence({ ledgerPath, cwd, git });
|
|
142
|
-
if (!state.unpersisted) return ledger;
|
|
143
|
-
logger?.warn?.(unpersistedWarning(state));
|
|
144
|
-
return { ...(ledger ?? { path: ledgerPath }), unpersisted: true };
|
|
145
|
-
}
|
|
146
|
-
|
|
147
|
-
/**
|
|
148
|
-
* Failures are fatal and name their step; callers run this after printing the
|
|
149
|
-
* run summary so a broken remote never costs the sweep's findings.
|
|
150
|
-
*
|
|
151
|
-
* @param {object} [params]
|
|
152
|
-
* @param {string} [params.ledgerPath]
|
|
153
|
-
* @param {string} [params.baseBranch]
|
|
154
|
-
* @param {string} [params.cwd]
|
|
155
|
-
* @param {(cwd: string, ...args: string[]) => string} [params.git]
|
|
156
|
-
* @param {{ pr: { create: (flags: string[]) => Promise<unknown> } }} [params.gh]
|
|
157
|
-
* @param {Date|string|number} [params.now]
|
|
158
|
-
* @returns {Promise<{ committed: boolean, reason?: string, branch?: string,
|
|
159
|
-
* subject?: string, baseBranch?: string, prUrl?: string|null,
|
|
160
|
-
* resumed?: boolean, ledgerPath: string }>}
|
|
161
|
-
*/
|
|
162
|
-
export async function runLedgerCommit({
|
|
163
|
-
ledgerPath = DEFAULT_LEDGER_PATH,
|
|
164
|
-
baseBranch,
|
|
165
|
-
cwd = process.cwd(),
|
|
166
|
-
git = gitSync,
|
|
167
|
-
gh = defaultGh,
|
|
168
|
-
now,
|
|
169
|
-
} = {}) {
|
|
170
|
-
const state = await assessLedgerPersistence({
|
|
171
|
-
ledgerPath,
|
|
172
|
-
baseBranch,
|
|
173
|
-
cwd,
|
|
174
|
-
git,
|
|
175
|
-
});
|
|
176
|
-
return openLedgerPullRequest({
|
|
177
|
-
state,
|
|
178
|
-
ledgerPath,
|
|
179
|
-
cwd,
|
|
180
|
-
git,
|
|
181
|
-
gh,
|
|
182
|
-
date: isoDate(now),
|
|
183
|
-
});
|
|
184
|
-
}
|