mandrel 2.68.0 → 2.70.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.
@@ -1,33 +1,44 @@
1
1
  /**
2
- * What an audit-seeded plan leaves for the next sweep: `audit::*` labels (the
3
- * dedup corpus is label-listed, so footers alone are invisible to an indexed
4
- * sweep) and cross-run ledger entries.
2
+ * What an audit-seeded plan leaves for the next sweep: the provenance footers
3
+ * every Story carries (the cross-run dedup memory) and the `audit::*` labels
4
+ * (the dedup corpus is label-listed, so footers alone are invisible to an
5
+ * indexed sweep).
5
6
  */
6
7
 
7
- import {
8
- DEFAULT_LEDGER_PATH,
9
- readLedger,
10
- recordFiledIdentities,
11
- writeLedger,
12
- } from '../../findings/audit-ledger.js';
13
- import {
14
- parseAuditLabelFooter,
15
- parseFingerprintFooter,
16
- parseSemanticKeyFooter,
17
- } from '../../findings/route-finding.js';
18
- import { Logger } from '../../Logger.js';
8
+ import { parseAuditLabelFooter } from '../../findings/route-finding.js';
19
9
 
20
10
  /**
21
- * @param {string} [ledgerPath]
22
- * @returns {{ path: string, ledger: object|null, recorded: number, ambiguous: number }}
11
+ * @param {object|null} envelope
12
+ * @returns {boolean}
23
13
  */
24
- function newAuditLedgerRecord(ledgerPath) {
25
- return {
26
- path: ledgerPath ?? DEFAULT_LEDGER_PATH,
27
- ledger: null,
28
- recorded: 0,
29
- ambiguous: 0,
30
- };
14
+ function seedWasTruncated(envelope) {
15
+ return (envelope?.truncated ?? []).some((t) => t?.field === 'seed');
16
+ }
17
+
18
+ /**
19
+ * The seed's provenance footers, in full. plan-context carries them apart
20
+ * from the seed text (`seed.provenance`) so a size cut cannot drop one; an
21
+ * envelope whose seed was cut and carries no such field cannot prove it
22
+ * kept them, so persist refuses before creating anything — a dropped footer
23
+ * is a finding silently re-filed by the next sweep.
24
+ *
25
+ * @param {object|null} envelope — the plan-context envelope, or null.
26
+ * @returns {string}
27
+ * @throws {Error} when the seed was truncated and its footers were not carried.
28
+ */
29
+ export function resolveSeedProvenance(envelope) {
30
+ const seed = envelope?.seed;
31
+ if (typeof seed?.provenance === 'string') return seed.provenance;
32
+ if (typeof seed?.content === 'string' && seedWasTruncated(envelope)) {
33
+ throw new Error(
34
+ '[plan-persist] the plan-context envelope truncated the seed and carries ' +
35
+ 'no seed.provenance, so audit provenance footers past the cut would be ' +
36
+ 'silently dropped and the next audit sweep would re-file those findings. ' +
37
+ 'Re-run plan-context with this Mandrel version to regenerate the ' +
38
+ 'envelope. No Issue was created.',
39
+ );
40
+ }
41
+ return seed?.content ?? '';
31
42
  }
32
43
 
33
44
  /**
@@ -47,96 +58,3 @@ export function withAuditLabels(stories, provenanceSource) {
47
58
  labels: [...new Set([...story.labels, ...fromSeed])],
48
59
  }));
49
60
  }
50
-
51
- /**
52
- * Identities are read off the stamped body. Union-carried (unattributed)
53
- * footers are never recorded: every sibling carries them, and a wrong
54
- * binding is worse than none.
55
- *
56
- * @param {{ story: object, id: number, ledgerRecord: object, attributed: boolean }} args
57
- */
58
- function recordAuditFiling({ story, id, ledgerRecord, attributed }) {
59
- const fingerprints = parseFingerprintFooter(story.body);
60
- if (fingerprints.length === 0) return;
61
- if (!attributed) {
62
- ledgerRecord.ambiguous += fingerprints.length;
63
- return;
64
- }
65
- const semanticKeys = parseSemanticKeyFooter(story.body);
66
- const identities = fingerprints.map((fingerprint, i) => ({
67
- fingerprint,
68
- semanticKey: semanticKeys[i] ?? '',
69
- title: story.title,
70
- }));
71
- const { ledger, recorded } = recordFiledIdentities({
72
- ledger: ledgerRecord.ledger ?? readLedger(ledgerRecord.path),
73
- identities,
74
- issue: { number: id },
75
- });
76
- ledgerRecord.ledger = ledger;
77
- ledgerRecord.recorded += recorded;
78
- }
79
-
80
- /**
81
- * @param {object} ledgerRecord
82
- * @param {{ warn: Function }} logger
83
- */
84
- function flushAuditLedger(ledgerRecord, logger) {
85
- if (ledgerRecord.ambiguous > 0) {
86
- logger.warn(
87
- `[plan-persist] audit ledger: ${ledgerRecord.ambiguous} identity(ies) not recorded — ` +
88
- 'the seed carried provenance footers but no Story attributed them, so ownership is ' +
89
- 'ambiguous. Author per-Story `provenance` to record them.',
90
- );
91
- }
92
- if (!ledgerRecord.ledger || ledgerRecord.recorded === 0) return;
93
- writeLedger(ledgerRecord.path, ledgerRecord.ledger);
94
- logger.warn(
95
- `[plan-persist] audit ledger: recorded ${ledgerRecord.recorded} filed finding(s) ` +
96
- `to ${ledgerRecord.path}.`,
97
- );
98
- }
99
-
100
- /**
101
- * One ledger write per plan, not per Story — the ledger is committed state.
102
- * A run that recorded nothing writes nothing.
103
- *
104
- * @param {object} params
105
- * @param {Array<object>} params.stories
106
- * @param {Array<{ slug: string, id: number }>} params.created
107
- * @param {Array<object>} params.tickets
108
- * @param {string} [params.ledgerPath]
109
- * @param {{ warn: Function }} [params.logger]
110
- * @param {boolean} [params.dryRun]
111
- * @returns {{ recorded: number, ambiguous: number }}
112
- */
113
- export function recordAuditFilings({
114
- stories,
115
- created,
116
- tickets,
117
- ledgerPath,
118
- logger,
119
- dryRun = false,
120
- }) {
121
- if (dryRun) return { recorded: 0, ambiguous: 0 };
122
- const record = newAuditLedgerRecord(ledgerPath);
123
- const idBySlug = new Map((created ?? []).map((c) => [c.slug, c.id]));
124
- // Attribution is what the plan authored, so read it off the raw tickets.
125
- const attributedSlugs = new Set(
126
- (tickets ?? [])
127
- .filter((t) => t?.provenance !== undefined && t?.provenance !== null)
128
- .map((t) => t?.slug),
129
- );
130
- for (const story of stories ?? []) {
131
- const id = idBySlug.get(story.slug);
132
- if (typeof id !== 'number') continue;
133
- recordAuditFiling({
134
- story,
135
- id,
136
- ledgerRecord: record,
137
- attributed: attributedSlugs.has(story.slug),
138
- });
139
- }
140
- flushAuditLedger(record, logger ?? Logger);
141
- return { recorded: record.recorded, ambiguous: record.ambiguous };
142
- }
@@ -33,7 +33,7 @@ import {
33
33
  } from '../ticket-validator-conflicts.js';
34
34
  import { upsertStructuredComment } from '../ticketing.js';
35
35
  import { renderRepair } from './acceptance-handle-repair.js';
36
- import { recordAuditFilings, withAuditLabels } from './audit-provenance.js';
36
+ import { resolveSeedProvenance, withAuditLabels } from './audit-provenance.js';
37
37
  import {
38
38
  resolveContainerEpic,
39
39
  resolveCrossPlanLinks,
@@ -423,6 +423,8 @@ export async function runPlanPersist({
423
423
  const runStartedAt = opts.metricsSince ?? new Date().toISOString();
424
424
 
425
425
  assertPersistablePlan(rawStories);
426
+ // Before any write: a truncated seed that lost its footers refuses here.
427
+ const seedProvenance = resolveSeedProvenance(planContextEnvelope);
426
428
 
427
429
  Logger.info(
428
430
  `[plan-persist] Running cross-validation on ${rawStories.length} Story ticket(s)...`,
@@ -451,14 +453,13 @@ export async function runPlanPersist({
451
453
  epicId: opts.adoptEpicId ?? null,
452
454
  });
453
455
 
454
- const seedContent = planContextEnvelope?.seed?.content ?? '';
455
456
  const { stories: assembled, warnings: supersedeWarnings } =
456
457
  assemblePlanStories(rawStories, {
457
458
  sharedSpec: techSpecContent,
458
459
  sourceTicketIds,
459
460
  // Audit footers carried onto every Story that did not attribute its own
460
461
  // `provenance`; empty for a `--tickets` run.
461
- provenanceSource: seedContent,
462
+ provenanceSource: seedProvenance,
462
463
  });
463
464
 
464
465
  warnings.push(...supersedeWarnings);
@@ -466,7 +467,7 @@ export async function runPlanPersist({
466
467
 
467
468
  // The dedup corpus is listed by `audit::*` label; footers alone leave the
468
469
  // Story invisible to an indexed sweep.
469
- const stories = withAuditLabels(assembled, seedContent);
470
+ const stories = withAuditLabels(assembled, seedProvenance);
470
471
 
471
472
  const assembledConflicts = analyzeAssembledStories({
472
473
  stories,
@@ -496,8 +497,6 @@ export async function runPlanPersist({
496
497
  opts: { dryRun },
497
498
  });
498
499
 
499
- recordAuditFilings({ stories, created, tickets: rawStories, dryRun });
500
-
501
500
  const primary = created[0];
502
501
 
503
502
  const planMetricsLine = await renderRunScopedPlanMetricsLine({
@@ -2,7 +2,7 @@
2
2
 
3
3
  > **Template generated by Mandrel.** Copy it into your own docs tree (e.g.
4
4
  > `docs/audit-sweep-runbook.md`), then localise every bracketed placeholder:
5
- > the cadence, the lens list, who reviews the ledger PR, and the label
5
+ > the cadence, the lens list, who files the Stories, and the label
6
6
  > conventions your repository actually uses. The steps themselves are the
7
7
  > contract — the values around them are yours.
8
8
  >
@@ -13,9 +13,9 @@
13
13
 
14
14
  ## What this runbook is for
15
15
 
16
- A maintenance **sweep** runs the `audit-*` lenses full-scope, folds their
17
- findings onto the cross-run ledger, and turns what is genuinely new into
18
- Stories. It is the unattended sibling of an interactive `/audit-to-stories`
16
+ A maintenance **sweep** runs the `audit-*` lenses full-scope, dedups their
17
+ findings against the Issues earlier sweeps filed, and turns what is genuinely
18
+ new into Stories. It is the unattended sibling of an interactive `/audit-to-stories`
19
19
  run: no HITL gates, so every judgement call the interactive path asks a human
20
20
  has to be settled here instead.
21
21
 
@@ -24,7 +24,7 @@ has to be settled here instead.
24
24
  | Cadence | _e.g. weekly, Sunday 02:00_ |
25
25
  | Lenses in scope | _e.g. security, clean-code, quality, dependencies_ |
26
26
  | Severity floor | _`--severity`, default `high`_ |
27
- | Ledger reviewer | _e.g. @your-handle_ |
27
+ | Story filer | _e.g. the scheduled job, or @your-handle_ |
28
28
  | Story triage owner | _e.g. the on-call maintainer_ |
29
29
 
30
30
  ## Step 1 — Run the lenses full-scope
@@ -63,7 +63,7 @@ A `###` heading with no severity axis and no field bullets is read as a
63
63
  against a zero tally.
64
64
 
65
65
  `--auto` **fails closed** on any such failure. It exits non-zero having opened
66
- no Issue and written no ledger, and names the offending report in
66
+ no Issue, and names the offending report in
67
67
  `summary.reportFailures[]`. `--allow-missing-tally` is a `--scan` affordance
68
68
  only; `--auto` ignores it by design, because an unattended run has no operator
69
69
  to read a warning.
@@ -85,63 +85,35 @@ node .agents/scripts/audit-to-stories.js --auto --dry-run
85
85
  exits non-zero naming the accepted levels rather than silently widening the run
86
86
  to every finding.
87
87
 
88
- `--dry-run` performs zero GitHub writes and skips the ledger write, printing
89
- only the run summary. Read `totals.create` before you let the sweep file
88
+ `--dry-run` performs zero GitHub writes, printing only the run summary. Read `totals.create` before you let the sweep file
90
89
  anything: a first full-scope run over an un-audited repository can propose more
91
90
  Stories than your team can triage in a quarter. Raise `--severity` until the
92
91
  create count is a batch you would actually take on, then go live.
93
92
 
94
- ## Step 4 — Go live, and persist the ledger
93
+ ## Step 4 — Go live: file and wire
95
94
 
96
95
  ```bash
97
- node .agents/scripts/audit-to-stories.js --auto --ledger-commit
96
+ node .agents/scripts/audit-to-stories.js --auto
98
97
  ```
99
98
 
100
- The cross-run ledger (`baselines/audit-ledger.json`) is **consumer state, not
101
- scratch output**. It is what lets the next sweep tell a re-detection from a
102
- fresh finding, and a deliberately-rejected finding from an unseen one. A
103
- scheduled job normally runs on an ephemeral checkout, so unless the ledger is
104
- committed back it dies with the clone and every later sweep starts amnesiac —
105
- re-proposing findings already filed and re-surfacing findings a human already
106
- rejected.
107
-
108
- `--ledger-commit` closes that loop. After the run summary has printed, and only
109
- when the ledger actually changed, it:
110
-
111
- 1. refuses, naming its step, if HEAD is not the base branch or there is no
112
- `origin` — before writing anything,
113
- 2. creates `chore/audit-ledger-<YYYY-MM-DD>-<shortsha>` from `origin/<base>`,
114
- 3. commits **only** the ledger file, subject
115
- `chore(audit): reconcile audit ledger <date>`,
116
- 4. pushes the branch,
117
- 5. opens a PR against your base branch, and
118
- 6. puts the checkout back on the branch it started from.
119
-
120
- It prints one line on stderr saying what happened: the branch and the PR URL on
121
- success, or the skip reason otherwise.
122
-
123
- **It is re-runnable.** The `<shortsha>` is the base commit, so a retry on the
124
- same day does not collide with the branch a failed run left behind — it
125
- recognises it. A ledger already committed on an **unpushed** ledger branch
126
- resumes at the push rather than reporting `ledger-unchanged` (the ledger file is
127
- clean: it is committed, just not pushed). Across a failed push and its retry you
128
- get exactly one PR.
129
-
130
- **Auto-merge is never requested.** The ledger records machine-derived lifecycle
131
- state, so a human glance before it lands is the point — nominate that reviewer
132
- in the table above. Review the PR for entries flipping to `accepted-risk` or
133
- `regressed`; those two are the ledger telling you something about your backlog,
134
- not about itself.
135
-
136
- Any git or `gh` failure in that sequence is fatal and names the step it broke
137
- on — but it happens _after_ the summary is printed, so a broken remote never
138
- costs you the sweep's findings.
139
-
140
- Without the flag, a run whose ledger changed on a checkout that cannot persist
141
- it — no `origin` remote, or HEAD parked off the base branch — sets
142
- `ledger.unpersisted: true` in the summary and warns on stderr naming the file.
143
- Treat that warning as a red sweep: the findings are fine, but the memory is
144
- about to be thrown away.
99
+ `--auto` writes nothing itself — no file, no branch, no PR. It prints the run
100
+ summary, including `createGroupKeys`: the groups nothing already filed covers.
101
+ File those as Issues (the `--emit-stories` payloads, each carrying its
102
+ `audit-fingerprints` / `audit-semantic-keys` footers), then replay the opened
103
+ numbers through `--wire-edges` (Step 5).
104
+
105
+ **The Issues are the sweep's memory.** There is no ledger to commit: the
106
+ provenance footers each filed Story carries are what the next sweep matches
107
+ findings against, read from live GitHub state. An **open** Issue with a
108
+ matching footer classifies the finding `skip-open`; a **closed** one —
109
+ completed or `not_planned` — classifies it `skip-reoccurring`, skipped by
110
+ default and surfaced in the summary for review; a finding reworded at an
111
+ unmoved location still matches on its semantic key. So an ephemeral checkout
112
+ loses nothing when it is thrown away, and to reject a finding for good, close
113
+ its Issue as `not_planned`.
114
+
115
+ Never strip or hand-edit a Story's `audit-*` footers: removing one is how a
116
+ finding gets re-proposed.
145
117
 
146
118
  ## Step 5 — Enrich before you deliver
147
119
 
@@ -200,11 +172,9 @@ to mint labels no taxonomy defines.
200
172
  | Symptom | Cause | Action |
201
173
  | --- | --- | --- |
202
174
  | Non-zero exit, `summary.reportFailures[]` populated | A lens report's tally is missing or disagrees with the parse | Re-run that lens; never downgrade with `--allow-missing-tally` |
203
- | `ledger.unpersisted: true` in the summary | No `origin`, or HEAD off the base branch | Re-run with `--ledger-commit`, or commit the ledger by hand |
204
- | `--ledger-commit failed at step "..."` | git or `gh` failed at the named step | Fix the cause and re-run; a retry resumes rather than duplicating, and the summary above it is still valid |
205
- | `--ledger-commit failed at step "verify-base-branch"` | HEAD is on a feature branch | Check out the base branch and re-run; nothing was committed |
206
175
  | `[resolve-stories] ... carries no "agent::*" label` | An unenriched audit Story was named for delivery | Plan it (Step 5), or pass `--allow-unlabelled` deliberately |
207
176
  | `[audit-to-stories] --severity "..." is not a severity` | A typo in the floor | Use one of the canonical levels |
208
177
  | `duplicate-tally` in `summary.reportFailures[]` | The report declares the tally twice | Reword the prose copy; the Executive Summary line is the declaration |
209
- | Same findings re-proposed every cycle | The ledger is not being committed | Adopt Step 4 |
178
+ | Same findings re-proposed every cycle | The filed Issues lack their `audit-fingerprints` footers, or dedup ran without the provider | File from the `--emit-stories` payloads verbatim; give dedup `gh` auth or `--issues-file` |
179
+ | `Unknown option` naming a `--ledger…` flag | A sweep script written before 2.70 | Drop the flag; there is no ledger to commit |
210
180
  | `totals.create` far larger than the team can absorb | Severity floor too low for a first full-scope run | Raise `--severity` and re-dry-run |
@@ -1,6 +1,5 @@
1
1
  ---
2
2
  description: Audit dependency CVEs, input-validation gaps, secrets handling, and auth boundaries; emit a structured High/Medium/Low findings report.
3
- command: false
4
3
  ---
5
4
 
6
5
  # Security & Vulnerability Audit
@@ -170,19 +170,22 @@ MVP Scope section carries each group's `audit-fingerprints` and
170
170
  `audit-semantic-keys` footers as HTML comments (invisible in the rendered
171
171
  one-pager, and per-group even though the visible list is flat — they are the
172
172
  identity the next sweep matches on). `plan-persist` harvests them out of the seed on the
173
- `plan-context.json` envelope and appends them to **every** Story body it
174
- persists, via `carryProvenanceFooters`
173
+ `plan-context.json` envelope — which carries them apart from the seed text as
174
+ `seed.provenance`, so an oversize seed cut for size keeps every footer — and
175
+ appends them to **every** Story body it persists, via `carryProvenanceFooters`
175
176
  ([`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)).
176
177
  The carry is additive, union-preserving and idempotent, so a resumed persist
177
178
  cannot stack footers and a hand-authored fingerprint is never dropped.
178
179
 
179
- **Persist records the ledger and the labels too.** It stamps the seed's
180
- `audit::<dimension>` labels — the dedup corpus is listed by them, and an indexed
181
- run answers lookups from that pool without reaching the provider, so a footer
182
- alone leaves a plan-path Story invisible — and records each Story's
183
- **attributed** identities. Union-only identities are not recorded: every sibling
184
- carries every fingerprint, so an owner would be a coin flip; persist says so on
185
- stderr. Author per-Story `provenance` to record them.
180
+ **The carry is fail-closed.** The footers are the only cross-run dedup memory,
181
+ so a dropped one is a finding silently re-filed by the next sweep. An envelope
182
+ whose seed was truncated and that carries no `seed.provenance` makes persist
183
+ refuse before creating any Issue, naming the cause — regenerate the envelope.
184
+
185
+ **Persist stamps the labels too.** It adds the seed's `audit::<dimension>`
186
+ labels — the dedup corpus is listed by them, and an indexed run answers lookups
187
+ from that pool without reaching the provider, so a footer alone leaves a
188
+ plan-path Story invisible. Persist writes no file.
186
189
 
187
190
  This is deliberately not an authoring step. If you find yourself copying a
188
191
  footer by hand, the carry is broken — fix it there rather than papering over it
@@ -239,16 +242,10 @@ Each entry in the emitted `--json` payload carries its own `groupKey` and
239
242
  `dependsOn`, so the map is a lookup, not a reconstruction. The pass re-renders
240
243
  every Story that has a resolvable blocker with a canonical
241
244
  `---` / `blocked by #N` footer **and** mirrors the same edges as native
242
- GitHub `blocked_by` relations. An edge whose target was never opened (deduped,
243
- ledger-suppressed) drops rather than becoming a `blocked by #undefined`.
244
-
245
- **This pass also records the ledger.** The `--ids` map is the only artifact
246
- carrying the numbers just opened, so `--wire-edges` folds in the cross-run
247
- record: each mapped group's findings are written `filed` against its Issue
248
- (`--ledger <path>`, default `baselines/audit-ledger.json`; `--dry-run`
249
- suppresses the write). The record runs **before** the provider loads, so a host
250
- with no `gh` still remembers what it filed. Without it nothing ever writes
251
- `filed` and the ledger suppresses nothing.
245
+ GitHub `blocked_by` relations. An edge whose target was never opened
246
+ (deduped) drops rather than becoming a `blocked by #undefined`. The pass writes
247
+ no file: the fingerprint footers each Issue was opened with are what the next
248
+ sweep recognises it by.
252
249
 
253
250
  **Do not skip this.** `/mandrel-deliver` has no other source for this cohort's order:
254
251
  its footprint guard ignores the shared provenance footers, so an unwired cohort
@@ -324,23 +321,17 @@ are read. An unreadable file is a hard error, never a silent fall-back to an
324
321
  unchecked run; an **empty** array — a valid first sweep — is reported with its
325
322
  count so it cannot pass for a failed fetch.
326
323
 
327
- ### Cross-run ledger
328
-
329
- The `--scan` classifications only see *live* issues. To decay findings across
330
- runs — recognizing re-detections, suppressing deliberately-rejected findings,
331
- and flagging genuine regressions — the sweep folds each scan onto a committed
332
- **ledger** (`baselines/audit-ledger.json`, the arch-cycles-baseline envelope
333
- shape). Each entry is keyed by the finding's fingerprint plus a location-based
334
- `semanticKey` and carries a lifecycle `status`
335
- (`new | filed | fixed | accepted-risk | regressed`). A finding whose tracking
336
- Issue was closed as `not_planned` becomes `accepted-risk` and is **suppressed**
337
- on every later scan; a `fixed` finding that re-appears becomes `regressed`. The
338
- ledger is written by the unattended `--auto` sweep, by any `--scan --ledger`
339
- run, by the Phase 5c `--wire-edges` pass, and by `plan-persist` on the Phase 5a
340
- chained path — the two filing paths both record what they filed; the
341
- plain `--scan` path leaves it untouched. A finding whose resolved Issue is open
342
- is recorded `filed` and is known on re-detection; a closed Issue still outranks
343
- that.
324
+ ### Cross-run memory is the Issues themselves
325
+
326
+ There is no ledger. Every verdict a cross-run record could hold is derived from
327
+ live GitHub state through the provenance footers each filed Story carries: an
328
+ **open** Issue whose `audit-fingerprints` / `audit-semantic-keys` footer matches
329
+ a finding classifies it `skip-open`; a **closed** one — completed or
330
+ `not_planned` — classifies it `skip-reoccurring`, skipped by default and
331
+ surfaced in the summary; a finding reworded at an unmoved location still
332
+ matches on its semantic key. So a run commits nothing and opens no PR of its
333
+ own; the footers stamped at filing time (Phase 5a's carry, Phase 5b's
334
+ `fingerprintFooter`) are the whole of what the next sweep remembers.
344
335
 
345
336
  ## Phase 7 — Summary & cleanup
346
337
 
@@ -398,11 +389,11 @@ writing their `temp/audits/audit-*-results.md` reports, then (2) invokes the
398
389
  CLI's **`--auto` mode** over those results:
399
390
 
400
391
  ```bash
401
- node .agents/scripts/audit-to-stories.js --auto [--dry-run] [--ledger-commit] \
392
+ node .agents/scripts/audit-to-stories.js --auto [--dry-run] \
402
393
  [--glob "temp/audits/audit-*-results.md"] [--severity <floor>]
403
394
  ```
404
395
 
405
- The routine shape is **lenses full-scope → dry-run → live with a ledger PR**:
396
+ The routine shape is **lenses full-scope → dry-run → live**:
406
397
 
407
398
  1. Run the `audit-*` lenses with no `--paths` and no change-set filter. A
408
399
  sweep scoped to a change set re-reports the same recent files every cycle
@@ -410,45 +401,27 @@ The routine shape is **lenses full-scope → dry-run → live with a ledger PR**
410
401
  2. `--auto --dry-run` for the first cycles — zero writes, summary only. Read
411
402
  `totals.create` and raise the severity floor until it is a batch the team
412
403
  would actually take on.
413
- 3. `--auto --ledger-commit` once the tallies stop surprising you.
404
+ 3. `--auto` once the tallies stop surprising you, filing the `create` groups
405
+ and wiring them (Phase 5c).
414
406
 
415
407
  `--auto` runs with **no interactive gates**: it resolves the severity floor
416
- from `--severity` (default `high`), applies the two-stage dedup, reconciles the cross-run ledger,
417
- and prints a run-summary JSON (create / skip-open / skip-reoccurring /
418
- suppressed-by-ledger tallies, the `create`-classified group keys the `--ids`
419
- map is built from, plus the re-detected open Issue numbers an operator may want
420
- a "re-detected" comment on). It opens no Issues itself, so run Phase 5c after
421
- filing or the sweep's memory stays empty. `--dry-run` performs zero GitHub
422
- writes and skips the ledger write, emitting only the summary.
408
+ from `--severity` (default `high`), applies the two-stage dedup, and prints a
409
+ run-summary JSON (create / skip-open / skip-reoccurring tallies, the
410
+ `create`-classified group keys the `--ids` map is built from, plus the
411
+ re-detected open Issue numbers an operator may want a "re-detected" comment
412
+ on). It opens no Issues and writes no file itself; file the `create` groups
413
+ with their fingerprint footers and run Phase 5c. `--dry-run` emits only the
414
+ summary.
423
415
 
424
416
  `--auto` **fails closed on any `summary.reportFailures[]` entry** (Phase 1): an
425
417
  unattended sweep has no operator to read a warning, so a missing or mismatched
426
418
  `Severity tally:` line — or a finding whose severity did not resolve — exits
427
- non-zero having opened no Issue and written no ledger. `--allow-missing-tally`
419
+ non-zero having opened no Issue. `--allow-missing-tally`
428
420
  is a `--scan` affordance that `--auto` ignores. A red sweep means the report is
429
421
  untrustworthy: re-run the lens. The host scheduler owns the cadence; this
430
422
  workflow owns the routing.
431
423
 
432
- ### The ledger is consumer state — commit it
433
-
434
- `baselines/audit-ledger.json` is **committed consumer state, not scratch
435
- output**. A scheduled sweep normally runs on an ephemeral checkout, so unless
436
- the reconciled ledger is committed back it dies with the clone: every later
437
- sweep starts amnesiac, re-proposing findings already filed and re-surfacing
438
- findings a human already rejected.
439
-
440
- `--ledger-commit` closes that loop. After the summary prints — and only when
441
- the ledger changed — it creates `chore/audit-ledger-<YYYY-MM-DD>` from HEAD,
442
- commits **only** the ledger file, pushes it, and opens a PR against
443
- `project.baseBranch`. **Auto-merge is never requested**: a human glance at the
444
- `accepted-risk` / `regressed` flips before it lands is the point. A git or `gh`
445
- failure is fatal and names its step, but only after the summary is printed, so
446
- a broken remote never costs the operator the run's findings. `--dry-run` skips
447
- the tail. Without the flag, a changed ledger on a checkout that cannot persist
448
- it — no `origin`, or HEAD off the base branch — sets `ledger.unpersisted: true`
449
- in the summary and warns on stderr naming the file.
450
-
451
- The full sweep procedure — tally cross-check, the ledger PR, the
424
+ The full sweep procedure — tally cross-check, filing and wiring, the
452
425
  enrich-before-deliver step and the label convention — ships as a
453
426
  consumer-copyable template at
454
427
  [`templates/docs/audit-sweep-runbook.md`](../templates/docs/audit-sweep-runbook.md).
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,24 @@ 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.70.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.69.0...mandrel-v2.70.0) (2026-09-29)
19
+
20
+
21
+ ### ⚠ BREAKING CHANGES
22
+
23
+ * 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.
24
+
25
+ ### Added
26
+
27
+ * 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))
28
+
29
+ ## [2.69.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.68.0...mandrel-v2.69.0) (2026-09-27)
30
+
31
+
32
+ ### Added
33
+
34
+ * **audit:** ship /audit-security as a slash command (refs [#5498](https://github.com/dsj1984/mandrel/issues/5498)) ([#5499](https://github.com/dsj1984/mandrel/issues/5499)) ([7df7649](https://github.com/dsj1984/mandrel/commit/7df76496cfc35f636d117961bb7042b5aa662ec6))
35
+
18
36
  ## [2.68.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.67.0...mandrel-v2.68.0) (2026-09-26)
19
37
 
20
38
 
@@ -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.68.0",
3
+ "version": "2.70.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/",