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
@@ -18,7 +18,8 @@ mandatoryReads: [deliver-digest.md]
18
18
  The **one** delivery engine in v2:
19
19
 
20
20
  ```text
21
- single-story-init.js → implement + commits → ceremony → push
21
+ single-story-init.js → implement + commits → acceptance-eval.js --init
22
+ → score → story-handoff.js (preflight, credited run, push, review)
22
23
  ──hand-off──▶ single-story-close.js (gates, PR → main, agent::closing)
23
24
  → CI watch + merge → single-story-confirm-merge.js (agent::done)
24
25
  ```
@@ -33,8 +34,8 @@ that dispatched the work**, never to a spawned worker.
33
34
  - **Inline dispatch** (a one-Story run — digest § 1): one session is both
34
35
  roles and walks Steps 0→7, no hand-off.
35
36
  - **Sub-agent dispatch**: the `story-worker` boots on the `promptPath`
36
- `deliver-run.js` wrote for it, stops at Step 2.5 with the branch pushed and
37
- returns a hand-off; the dispatching `/mandrel-deliver` session runs Step 3
37
+ `deliver-run.js` wrote for it (its role file carries every worker MUST),
38
+ stops at Step 2.5 with `story-handoff.js` `ready` and returns a hand-off; the dispatching `/mandrel-deliver` session runs Step 3
38
39
  **in its own turn** and **serializes the tail — one close at a time across
39
40
  the run**, even though implementation ran in parallel (reference § Step 3).
40
41
 
@@ -81,9 +82,12 @@ One branch, one PR to `main`, commits against the inline `acceptance[]` /
81
82
 
82
83
  ### Step 1a — Bounded acceptance self-eval loop (**required**)
83
84
 
84
- Run the loop and score it with `acceptance-eval.js` — **digest § 4** carries
85
- the invocation and the proceed / redraft / block contract; per-round mechanics
86
- live in [`acceptance-self-eval.md`](acceptance-self-eval.md). **`proceed`** →
85
+ Start from the skeleton — `acceptance-eval.js --story <storyId> --init --cwd
86
+ <workCwd>` writes one empty record per `acceptance[]` item and prints the
87
+ change set and verdict owner — fill it, and score it with `acceptance-eval.js`;
88
+ **digest § 4** carries the invocations and the proceed / redraft / block
89
+ contract; per-round mechanics live in
90
+ [`acceptance-self-eval.md`](acceptance-self-eval.md). **`proceed`** →
87
91
  Step 2. **`block`** → **do not close**: post a `friction` comment and flip
88
92
  `agent::blocked` (reference § Step 1a).
89
93
 
@@ -91,23 +95,22 @@ Step 2. **`block`** → **do not close**: post a `friction` comment and flip
91
95
 
92
96
  The acceptance verdict owner comes from `delivery.routing.ceremonyProfile` and
93
97
  nothing else — not the diff, not the dispatch mode, never a planner-authored
94
- verdict. **Digest § 3** is the incantation (change set once, derive the level
95
- for review depth, resolve the owner with `ceremony-routing.js`) and the one
96
- home of the rule; edge cases are reference § Step 2. Hard gates always run in
97
- Step 3 — nothing here disables them; do **not** pre-run the chain here —
98
- Step 2.5's credited suite run is the sole exception.
98
+ verdict; `--init` prints it, resolved by `ceremony-routing.js` (**digest § 3** is the rule's one home; edge cases
99
+ are reference § Step 2). Hard gates always run in Step 3 — do **not** pre-run
100
+ the chain here; Step 2.5's credited suite run is the sole exception.
99
101
 
100
- ### Step 2.5 — The one credited suite run, the push, then hand off
102
+ ### Step 2.5 — `story-handoff.js`, then hand off
101
103
 
102
- After the self-eval loop's last fix commit, run the one credited suite run
103
- in the worktree — **digest § 5** is its only home and carries the
104
- invocation. Red → fix, commit, re-run. Then, before the push, seat the
105
- baseline rows for methods the Story added (`--seat-missing`, digest § 5).
104
+ After the self-eval loop's last fix commit, run the one tail command —
105
+ **digest § 5** is its only home: preflight, base merge, the one credited
106
+ suite run, `--seat-missing`, the push with its remote-ref check, and the held
107
+ review, settling `ready`, `fix-required` (fix, commit, re-run it) or
108
+ `blocked` (it flips `agent::blocked`).
106
109
 
107
- Push `story-<storyId>` to `origin`, confirming the remote ref moved. Then
108
- (sub-agent dispatch only) return the hand-off — Story id, `workCwd`,
109
- branch, pushed head SHA, self-eval verdict, `verify[]` evidence — and stop.
110
- Do not open the PR or compose a terminal envelope.
110
+ On `ready` (sub-agent dispatch only) return the hand-off — its envelope
111
+ (Story id, branch, pushed head SHA, review tally), `workCwd`, self-eval
112
+ verdict, `verify[]` evidence — and stop. Do not open the PR or compose a
113
+ terminal envelope.
111
114
 
112
115
  ## Step 3 — Close and land (`single-story-close.js`)
113
116
 
@@ -116,19 +119,23 @@ serialized against sibling Stories:
116
119
 
117
120
  ```bash
118
121
  node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo> \
119
- [--worker-tokens <n>]
122
+ [--worker-tokens <n>] [--worker-model <model>]
120
123
  ```
121
124
 
122
125
  When the host reported a total-token figure for the story-worker's Agent
123
126
  dispatch, pass it as `--worker-tokens <n>` — close records it in its
124
- result's local `telemetry`; omit it when the host reports none.
127
+ result's local `telemetry`; omit it when the host reports none. A
128
+ multi-Story close command from deliver-run already carries `--worker-model`.
125
129
 
126
130
  **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
127
131
  post-land tail in one process. Never background it, never delegate it to a
128
132
  child, and never end your turn while it is still running: "close is running"
129
133
  is not a return value. Branch on the envelope's `status` per **digest § 6**
130
134
  (`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
131
- → Step 4; `failed` → diagnose, re-run). Gate output is captured.
135
+ → Step 4; `failed` → diagnose, re-run; a `phase: base-sync` conflict comes
136
+ back with labels untouched — resolve it in `workCwd`, commit, run
137
+ `nextCommand`, and take the blocked path only if you cannot). Gate output is
138
+ captured.
132
139
 
133
140
  Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
134
141
  `autoMerge` policy and every close flag: reference § Step 3.
@@ -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
- - **Keep `## Spec` at contract-level prose** — interfaces, invariants,
177
- load-bearing constraints; no per-file behavior narration — and as long as
178
- the work needs. There is no word or token budget.
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[]` — a **bare path string**
187
- by default, or `{path, assumption}` with
188
- `creates|refactors-existing|deletes` to pin one, `non_goals`,
189
- `reason_to_exist`), top-level `acceptance[]`, `verify[]` (each a **bare
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 acceptance path absent at base, an empty `verify[]`, a source id
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
 
@@ -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),
@@ -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.69.0",
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": "./bin/mandrel.js"
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.2.0",
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
- }