mandrel 2.69.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.
- package/.agents/scripts/audit-to-stories.js +39 -247
- package/.agents/scripts/lib/audit-to-stories/finding-adapter.js +1 -1
- package/.agents/scripts/lib/findings/route-finding.js +15 -0
- package/.agents/scripts/lib/orchestration/plan-context.js +14 -1
- package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +35 -117
- package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -6
- package/.agents/templates/docs/audit-sweep-runbook.md +29 -59
- package/.agents/workflows/audit-to-stories.md +40 -67
- package/docs/CHANGELOG.md +11 -0
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.70.0-retire-audit-ledger.js +36 -0
- package/package.json +1 -1
- 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
|
@@ -1,33 +1,44 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* What an audit-seeded plan leaves for the next sweep:
|
|
3
|
-
*
|
|
4
|
-
*
|
|
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 {
|
|
22
|
-
* @returns {
|
|
11
|
+
* @param {object|null} envelope
|
|
12
|
+
* @returns {boolean}
|
|
23
13
|
*/
|
|
24
|
-
function
|
|
25
|
-
return
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
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 {
|
|
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:
|
|
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,
|
|
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
|
|
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,
|
|
17
|
-
findings
|
|
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
|
-
|
|
|
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
|
|
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
|
|
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
|
|
93
|
+
## Step 4 — Go live: file and wire
|
|
95
94
|
|
|
96
95
|
```bash
|
|
97
|
-
node .agents/scripts/audit-to-stories.js --auto
|
|
96
|
+
node .agents/scripts/audit-to-stories.js --auto
|
|
98
97
|
```
|
|
99
98
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
|
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 |
|
|
@@ -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
|
|
174
|
-
|
|
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
|
-
**
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
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]
|
|
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
|
|
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
|
|
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,
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
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
|
|
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
|
-
|
|
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,17 @@ 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
|
+
|
|
18
29
|
## [2.69.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.68.0...mandrel-v2.69.0) (2026-09-27)
|
|
19
30
|
|
|
20
31
|
|
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