mandrel 2.76.0 → 2.78.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/agents/auditor.md +2 -3
- package/.agents/scripts/lib/audit-to-stories/build-story-body.js +48 -14
- package/.agents/scripts/lib/audit-to-stories/finding-bullets.js +33 -0
- package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js +6 -4
- package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +34 -19
- package/.agents/scripts/lib/findings/severity.js +33 -6
- package/.agents/scripts/lib/orchestration/plan-persist/supersede-ops.js +34 -5
- package/.agents/scripts/lib/orchestration/single-story-close/runner.js +8 -4
- package/.agents/workflows/audit-baselines.md +3 -3
- package/.agents/workflows/audit-exceptions.md +3 -2
- package/.agents/workflows/audit-to-stories.md +9 -6
- package/.agents/workflows/helpers/audit-lens-core.md +5 -6
- package/.agents/workflows/helpers/plan-reference.md +10 -3
- package/docs/CHANGELOG.md +14 -0
- package/package.json +1 -1
|
@@ -83,7 +83,8 @@ declares a deviation follows its own Scope section instead.
|
|
|
83
83
|
## Findings schema — the finding-block skeleton (MUST stay parseable)
|
|
84
84
|
|
|
85
85
|
Write the report with an `## Executive Summary` and a `## Detailed Findings`
|
|
86
|
-
section.
|
|
86
|
+
section. List findings in descending severity order (Critical first, Info
|
|
87
|
+
last). Every finding under Detailed Findings uses this shared skeleton; the
|
|
87
88
|
lens may **add** fields and may relabel `Severity` ↔ `Impact` and
|
|
88
89
|
`Dimension` ↔ `Category` ↔ `Type`, but never drops a shared field — the
|
|
89
90
|
`audit-to-stories` parser depends on this shape:
|
|
@@ -98,8 +99,6 @@ lens may **add** fields and may relabel `Severity` ↔ `Impact` and
|
|
|
98
99
|
- **Recommendation & Rationale:** [how to remediate and why it matters]
|
|
99
100
|
- **Acceptance signal:** [the command or observable that proves this finding is
|
|
100
101
|
remediated]
|
|
101
|
-
- **Agent Prompt:**
|
|
102
|
-
`[A copy-pasteable, highly specific prompt to execute this remediation independently]`
|
|
103
102
|
```
|
|
104
103
|
|
|
105
104
|
## Severity scale
|
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
import path from 'node:path';
|
|
7
|
+
import { sortBySeverity } from '../findings/severity.js';
|
|
7
8
|
import { RISK_LABELS, TYPE_LABELS } from '../label-constants.js';
|
|
8
9
|
import { serialize } from '../story-body/story-body.js';
|
|
9
10
|
import { definesAuditLabel } from './audit-label-taxonomy.js';
|
|
@@ -12,6 +13,7 @@ import {
|
|
|
12
13
|
renderFingerprintFooter,
|
|
13
14
|
renderSemanticKeyFooter,
|
|
14
15
|
} from './finding-adapter.js';
|
|
16
|
+
import { findingBullets, STORY_FINDING_FIELDS } from './finding-bullets.js';
|
|
15
17
|
|
|
16
18
|
// Deliberately no `agent::` state label: audit prose is not ready for pickup.
|
|
17
19
|
// `/mandrel-plan` stamps `agent::ready` once enriched; an absent state is a
|
|
@@ -55,14 +57,14 @@ function changesFromGroup(group) {
|
|
|
55
57
|
}
|
|
56
58
|
|
|
57
59
|
/**
|
|
58
|
-
* A checkable end-state anchored on title and primary file,
|
|
59
|
-
*
|
|
60
|
+
* A checkable end-state anchored on title and primary file, for a finding
|
|
61
|
+
* whose lens wrote no Acceptance signal.
|
|
60
62
|
*
|
|
61
63
|
* @param {object} finding
|
|
64
|
+
* @param {string} title
|
|
62
65
|
* @returns {string}
|
|
63
66
|
*/
|
|
64
|
-
function
|
|
65
|
-
const title = (finding.title ?? 'finding').trim();
|
|
67
|
+
function synthesizedAcceptance(finding, title) {
|
|
66
68
|
const primaryFile =
|
|
67
69
|
Array.isArray(finding.files) && finding.files.length > 0
|
|
68
70
|
? finding.files[0]
|
|
@@ -71,8 +73,22 @@ function acceptanceItemFromFinding(finding) {
|
|
|
71
73
|
return `${title} is remediated${where}: the recommended end-state holds and the finding is no longer reproducible`;
|
|
72
74
|
}
|
|
73
75
|
|
|
76
|
+
/**
|
|
77
|
+
* The lens's own Acceptance signal when it wrote one, else the synthesized
|
|
78
|
+
* end-state — never the verbatim recommendation, which stays in `## Findings`.
|
|
79
|
+
*
|
|
80
|
+
* @param {object} finding
|
|
81
|
+
* @returns {string}
|
|
82
|
+
*/
|
|
83
|
+
function acceptanceItemFromFinding(finding) {
|
|
84
|
+
const title = (finding.title ?? 'finding').trim();
|
|
85
|
+
return finding.acceptanceSignal
|
|
86
|
+
? `${title} — ${finding.acceptanceSignal}`
|
|
87
|
+
: synthesizedAcceptance(finding, title);
|
|
88
|
+
}
|
|
89
|
+
|
|
74
90
|
function acceptanceCriteriaFromGroup(group) {
|
|
75
|
-
return (group.findings ?? []).map(acceptanceItemFromFinding);
|
|
91
|
+
return sortBySeverity(group.findings ?? []).map(acceptanceItemFromFinding);
|
|
76
92
|
}
|
|
77
93
|
|
|
78
94
|
/**
|
|
@@ -107,13 +123,31 @@ function dependencyRefs(deps, issueByGroupKey) {
|
|
|
107
123
|
.map((n) => `#${n}`);
|
|
108
124
|
}
|
|
109
125
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
126
|
+
/**
|
|
127
|
+
* `####`, never `###`: the story-body parser reads a one-word `##`/`###`
|
|
128
|
+
* heading as a canonical section, so a finding titled `Verify` would bleed
|
|
129
|
+
* its bullets into `verify[]`.
|
|
130
|
+
*
|
|
131
|
+
* @param {object} finding
|
|
132
|
+
* @returns {string} a heading and the finding's present fields.
|
|
133
|
+
*/
|
|
134
|
+
function findingBlock(finding) {
|
|
135
|
+
return [
|
|
136
|
+
`#### ${finding.title}`,
|
|
137
|
+
'',
|
|
138
|
+
...findingBullets(finding, STORY_FINDING_FIELDS),
|
|
139
|
+
].join('\n');
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* One block per finding, worst first, carrying the remediation detail the
|
|
144
|
+
* acceptance list deliberately leaves out.
|
|
145
|
+
*
|
|
146
|
+
* @param {object} group
|
|
147
|
+
* @returns {string}
|
|
148
|
+
*/
|
|
149
|
+
function findingsSection(group) {
|
|
150
|
+
return sortBySeverity(group.findings).map(findingBlock).join('\n\n');
|
|
117
151
|
}
|
|
118
152
|
|
|
119
153
|
/**
|
|
@@ -204,9 +238,9 @@ export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
|
|
|
204
238
|
const body = [
|
|
205
239
|
canonicalSections,
|
|
206
240
|
'',
|
|
207
|
-
'##
|
|
241
|
+
'## Findings',
|
|
208
242
|
'',
|
|
209
|
-
|
|
243
|
+
findingsSection(group),
|
|
210
244
|
'',
|
|
211
245
|
'## Context',
|
|
212
246
|
'',
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Per-finding markdown bullets shared by the standalone Story body and the
|
|
3
|
+
* `/mandrel-plan` seed, so both render a finding's fields identically. Pure.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/** `[label, finding key]` pairs, in the order each surface lists them. */
|
|
7
|
+
export const STORY_FINDING_FIELDS = Object.freeze([
|
|
8
|
+
['Severity', 'severity'],
|
|
9
|
+
['Location', 'location'],
|
|
10
|
+
['Current State', 'currentState'],
|
|
11
|
+
['Recommendation', 'recommendation'],
|
|
12
|
+
]);
|
|
13
|
+
|
|
14
|
+
export const SEED_FINDING_FIELDS = Object.freeze([
|
|
15
|
+
['Location', 'location'],
|
|
16
|
+
['Recommendation', 'recommendation'],
|
|
17
|
+
['Acceptance signal', 'acceptanceSignal'],
|
|
18
|
+
]);
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Parsed fields are already trimmed; an empty or absent one is omitted rather
|
|
22
|
+
* than rendered as a placeholder.
|
|
23
|
+
*
|
|
24
|
+
* @param {object} finding
|
|
25
|
+
* @param {ReadonlyArray<readonly [string, string]>} fields
|
|
26
|
+
* @param {string} [indent='']
|
|
27
|
+
* @returns {string[]} one `- **Label:** value` line per present field.
|
|
28
|
+
*/
|
|
29
|
+
export function findingBullets(finding, fields, indent = '') {
|
|
30
|
+
return fields
|
|
31
|
+
.filter(([, key]) => finding[key])
|
|
32
|
+
.map(([label, key]) => `${indent}- **${label}:** ${finding[key]}`);
|
|
33
|
+
}
|
|
@@ -394,7 +394,8 @@ function parseBlockFields(bodyLines) {
|
|
|
394
394
|
* files: string[],
|
|
395
395
|
* currentState: string,
|
|
396
396
|
* recommendation: string,
|
|
397
|
-
*
|
|
397
|
+
* location: string,
|
|
398
|
+
* acceptanceSignal: string,
|
|
398
399
|
* rawFields: Record<string,string>,
|
|
399
400
|
* sourceReport: string,
|
|
400
401
|
* }>}
|
|
@@ -417,13 +418,13 @@ export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
|
|
|
417
418
|
const currentState = fields['current state'] ?? '';
|
|
418
419
|
const recommendation =
|
|
419
420
|
fields['recommendation & rationale'] ?? fields.recommendation ?? '';
|
|
420
|
-
const
|
|
421
|
+
const location = fields.location ?? '';
|
|
422
|
+
const acceptanceSignal = fields['acceptance signal'] ?? '';
|
|
421
423
|
const fileSet = new Set([
|
|
422
424
|
...deriveTitleFile(block.title, repoRoot),
|
|
423
425
|
...deriveLocationFiles(fields, repoRoot),
|
|
424
426
|
...extractFilePaths(currentState, repoRoot),
|
|
425
427
|
...extractFilePaths(recommendation, repoRoot),
|
|
426
|
-
...extractFilePaths(agentPrompt, repoRoot),
|
|
427
428
|
]);
|
|
428
429
|
|
|
429
430
|
return {
|
|
@@ -434,7 +435,8 @@ export function parseAuditReport({ markdown, sourceReport, repoRoot }) {
|
|
|
434
435
|
files: [...fileSet],
|
|
435
436
|
currentState,
|
|
436
437
|
recommendation,
|
|
437
|
-
|
|
438
|
+
location,
|
|
439
|
+
acceptanceSignal,
|
|
438
440
|
rawFields: fields,
|
|
439
441
|
sourceReport,
|
|
440
442
|
};
|
|
@@ -3,12 +3,13 @@
|
|
|
3
3
|
* Pure: returns a string.
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
-
import { SEVERITIES } from '../findings/severity.js';
|
|
6
|
+
import { SEVERITIES, sortBySeverity } from '../findings/severity.js';
|
|
7
7
|
import { auditLabelFooterForFindings } from './audit-label-taxonomy.js';
|
|
8
8
|
import {
|
|
9
9
|
renderFingerprintFooter,
|
|
10
10
|
renderSemanticKeyFooter,
|
|
11
11
|
} from './finding-adapter.js';
|
|
12
|
+
import { findingBullets, SEED_FINDING_FIELDS } from './finding-bullets.js';
|
|
12
13
|
|
|
13
14
|
const DIMENSION_LABEL = {
|
|
14
15
|
security: 'Security',
|
|
@@ -43,12 +44,17 @@ function tallyDimensions(findings) {
|
|
|
43
44
|
return tally;
|
|
44
45
|
}
|
|
45
46
|
|
|
46
|
-
|
|
47
|
+
/** `2 High, 1 Medium` — non-zero levels only, highest first. */
|
|
48
|
+
function formatTally(findings) {
|
|
47
49
|
const sev = tallySeverities(findings);
|
|
48
|
-
|
|
49
|
-
const tallyParts = SEVERITY_ORDER.filter((k) => sev[k] > 0)
|
|
50
|
+
return SEVERITY_ORDER.filter((k) => sev[k] > 0)
|
|
50
51
|
.map((k) => `${sev[k]} ${k.charAt(0).toUpperCase() + k.slice(1)}`)
|
|
51
52
|
.join(', ');
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function formatProblemStatement(findings) {
|
|
56
|
+
const dimensions = tallyDimensions(findings);
|
|
57
|
+
const tallyParts = formatTally(findings);
|
|
52
58
|
const topDims = [...dimensions.entries()]
|
|
53
59
|
.sort((a, b) => b[1] - a[1])
|
|
54
60
|
.slice(0, 3)
|
|
@@ -57,35 +63,44 @@ function formatProblemStatement(findings) {
|
|
|
57
63
|
return `An audit sweep surfaced ${findings.length} findings (${tallyParts}) concentrated in ${dimsPhrase}. These require remediation to restore release posture.`;
|
|
58
64
|
}
|
|
59
65
|
|
|
66
|
+
/**
|
|
67
|
+
* A count per dimension, not recommendation text: each finding's fix lives
|
|
68
|
+
* under it in MVP Scope, so repeating a truncated sample here only misleads.
|
|
69
|
+
*
|
|
70
|
+
* @param {object[]} findings
|
|
71
|
+
* @returns {string}
|
|
72
|
+
*/
|
|
60
73
|
function formatRecommendedDirection(findings) {
|
|
61
|
-
const byDim =
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
lines.push(`- **${label}** — ${head || 'See linked findings.'}`);
|
|
71
|
-
}
|
|
72
|
-
return lines.join('\n');
|
|
74
|
+
const byDim = Map.groupBy(findings, (f) => f.dimension);
|
|
75
|
+
return [...byDim.entries()]
|
|
76
|
+
.sort(([a], [b]) => String(a).localeCompare(String(b)))
|
|
77
|
+
.map(([dim, list]) => {
|
|
78
|
+
const label = DIMENSION_LABEL[dim] ?? dim;
|
|
79
|
+
const noun = list.length === 1 ? 'finding' : 'findings';
|
|
80
|
+
return `- **${label}** — ${list.length} ${noun} (${formatTally(list)})`;
|
|
81
|
+
})
|
|
82
|
+
.join('\n');
|
|
73
83
|
}
|
|
74
84
|
|
|
75
85
|
/**
|
|
76
86
|
* Flat, not grouped: the seed must not pre-decide the Story partition; that
|
|
77
|
-
* is the planner's cohesion call.
|
|
87
|
+
* is the planner's cohesion call. Worst first, each finding carrying its own
|
|
88
|
+
* Location, Recommendation and Acceptance signal so the planner need not
|
|
89
|
+
* reopen the source report.
|
|
78
90
|
*
|
|
79
91
|
* @param {object[]} findings
|
|
80
92
|
* @returns {string}
|
|
81
93
|
*/
|
|
82
94
|
function formatFindingsList(findings) {
|
|
83
|
-
return findings
|
|
95
|
+
return sortBySeverity(findings)
|
|
84
96
|
.map((f) => {
|
|
85
97
|
const label = DIMENSION_LABEL[f.dimension] ?? f.dimension;
|
|
86
98
|
const file = f.files?.[0] ? ` (\`${f.files[0]}\`)` : '';
|
|
87
99
|
const severity = f.severity ? `${f.severity} · ` : '';
|
|
88
|
-
|
|
100
|
+
const headline = `- **${f.title}** — ${severity}${label}${file}`;
|
|
101
|
+
return [headline, ...findingBullets(f, SEED_FINDING_FIELDS, ' ')].join(
|
|
102
|
+
'\n',
|
|
103
|
+
);
|
|
89
104
|
})
|
|
90
105
|
.join('\n');
|
|
91
106
|
}
|
|
@@ -29,14 +29,21 @@ const SEVERITY_ALIASES = Object.freeze({
|
|
|
29
29
|
trivial: 'info',
|
|
30
30
|
});
|
|
31
31
|
|
|
32
|
+
/**
|
|
33
|
+
* A named declaration, not a module-scope arrow: CRAP `--seat-missing` cannot
|
|
34
|
+
* resolve coverage for an anonymous function with no enclosing one.
|
|
35
|
+
*
|
|
36
|
+
* @param {string} severity
|
|
37
|
+
* @param {number} index
|
|
38
|
+
* @returns {[string, number]}
|
|
39
|
+
*/
|
|
40
|
+
function rankEntry(severity, index) {
|
|
41
|
+
return [severity, SEVERITIES.length - 1 - index];
|
|
42
|
+
}
|
|
43
|
+
|
|
32
44
|
/** @type {Readonly<Record<string, number>>} */
|
|
33
45
|
export const SEVERITY_RANK = Object.freeze(
|
|
34
|
-
Object.fromEntries(
|
|
35
|
-
SEVERITIES.map((severity, index) => [
|
|
36
|
-
severity,
|
|
37
|
-
SEVERITIES.length - 1 - index,
|
|
38
|
-
]),
|
|
39
|
-
),
|
|
46
|
+
Object.fromEntries(SEVERITIES.map(rankEntry)),
|
|
40
47
|
);
|
|
41
48
|
|
|
42
49
|
/**
|
|
@@ -86,6 +93,26 @@ export function highestSeverity(values) {
|
|
|
86
93
|
return best;
|
|
87
94
|
}
|
|
88
95
|
|
|
96
|
+
/**
|
|
97
|
+
* Stable highest-first order over items carrying a `severity` field; an
|
|
98
|
+
* unresolvable severity sorts after `info` rather than being dropped.
|
|
99
|
+
*
|
|
100
|
+
* @template {{ severity?: unknown }} T
|
|
101
|
+
* @param {readonly T[]} items
|
|
102
|
+
* @returns {T[]} a new array.
|
|
103
|
+
*/
|
|
104
|
+
export function sortBySeverity(items) {
|
|
105
|
+
return [...items].sort(compareSeverityDesc);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
function rankOf(item) {
|
|
109
|
+
return SEVERITY_RANK[item?.severity] ?? -1;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function compareSeverityDesc(a, b) {
|
|
113
|
+
return rankOf(b) - rankOf(a);
|
|
114
|
+
}
|
|
115
|
+
|
|
89
116
|
/** Test-only: the alias-table invariant is unobservable via the API. */
|
|
90
117
|
export const __testing = {
|
|
91
118
|
DEFAULT_SEVERITY,
|
|
@@ -17,8 +17,14 @@ import { upsertStructuredComment } from '../ticketing.js';
|
|
|
17
17
|
|
|
18
18
|
const SUPERSEDED_BY_COMMENT_TYPE = 'superseded-by';
|
|
19
19
|
|
|
20
|
-
/**
|
|
21
|
-
|
|
20
|
+
/**
|
|
21
|
+
* The claiming Story carries the work, so `duplicate`: nothing has shipped
|
|
22
|
+
* (not `completed`), but the ticket is not abandoned either.
|
|
23
|
+
*/
|
|
24
|
+
export const SUPERSEDE_CLOSE_REASON = 'duplicate';
|
|
25
|
+
|
|
26
|
+
/** Retried once when the provider refuses `duplicate`. */
|
|
27
|
+
const SUPERSEDE_FALLBACK_CLOSE_REASON = 'not_planned';
|
|
22
28
|
|
|
23
29
|
/**
|
|
24
30
|
* Stripped, not rewritten to `agent::done`: a retired ticket has no agent
|
|
@@ -33,8 +39,8 @@ const AGENT_STATE_LABELS = Object.freeze(Object.values(AGENT_LABELS));
|
|
|
33
39
|
* @param {{ labels?: unknown }} ticket The probe's fresh copy.
|
|
34
40
|
* @returns {object} Mutations for `provider.updateTicket`.
|
|
35
41
|
*/
|
|
36
|
-
function supersedeCloseMutations(ticket) {
|
|
37
|
-
const close = { state: 'closed', state_reason:
|
|
42
|
+
function supersedeCloseMutations(ticket, reason = SUPERSEDE_CLOSE_REASON) {
|
|
43
|
+
const close = { state: 'closed', state_reason: reason };
|
|
38
44
|
const labels = Array.isArray(ticket?.labels) ? ticket.labels : [];
|
|
39
45
|
const remove = AGENT_STATE_LABELS.filter((label) => labels.includes(label));
|
|
40
46
|
if (remove.length === 0) return close;
|
|
@@ -288,6 +294,28 @@ export function buildSupersedeCommentBody({
|
|
|
288
294
|
return lines.join('\n');
|
|
289
295
|
}
|
|
290
296
|
|
|
297
|
+
/**
|
|
298
|
+
* Close as `duplicate`; on refusal, retry once as `not_planned` so a
|
|
299
|
+
* supersede never fails on the reason alone.
|
|
300
|
+
*
|
|
301
|
+
* @returns {Promise<void>}
|
|
302
|
+
*/
|
|
303
|
+
async function closeSupersededSource(provider, id, ticket) {
|
|
304
|
+
try {
|
|
305
|
+
await provider.updateTicket(id, supersedeCloseMutations(ticket));
|
|
306
|
+
} catch (err) {
|
|
307
|
+
Logger.warn(
|
|
308
|
+
`[plan-persist] closing #${id} as ${SUPERSEDE_CLOSE_REASON} was ` +
|
|
309
|
+
`refused (${err.message}) — retrying as ` +
|
|
310
|
+
`${SUPERSEDE_FALLBACK_CLOSE_REASON}.`,
|
|
311
|
+
);
|
|
312
|
+
await provider.updateTicket(
|
|
313
|
+
id,
|
|
314
|
+
supersedeCloseMutations(ticket, SUPERSEDE_FALLBACK_CLOSE_REASON),
|
|
315
|
+
);
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
|
|
291
319
|
/**
|
|
292
320
|
* The ticket rides along so the close needs no second read.
|
|
293
321
|
*
|
|
@@ -335,8 +363,9 @@ async function closeOneSupersededTicket({
|
|
|
335
363
|
note,
|
|
336
364
|
sourceTicketIds,
|
|
337
365
|
}),
|
|
366
|
+
{ story: story.id },
|
|
338
367
|
);
|
|
339
|
-
await provider
|
|
368
|
+
await closeSupersededSource(provider, id, probe.ticket);
|
|
340
369
|
return { outcome: 'closed' };
|
|
341
370
|
} catch (err) {
|
|
342
371
|
return { outcome: 'failed', reason: err.message };
|
|
@@ -148,10 +148,14 @@ function noopResult(storyId, reason) {
|
|
|
148
148
|
return { storyId, standalone: true, action: 'noop', reason };
|
|
149
149
|
}
|
|
150
150
|
|
|
151
|
+
/** Close reasons meaning nothing merged — superseded or abandoned. */
|
|
152
|
+
const UNLANDED_CLOSE_REASONS = new Set(['not_planned', 'duplicate']);
|
|
153
|
+
|
|
151
154
|
/**
|
|
152
|
-
* Terminal for an already-closed Story. `not_planned`
|
|
153
|
-
* so it fails rather than reporting `landed` (which would
|
|
154
|
-
* dependents); `completed` or null (GitHub's default) reads as
|
|
155
|
+
* Terminal for an already-closed Story. `not_planned` / `duplicate` mean
|
|
156
|
+
* nothing merged, so it fails rather than reporting `landed` (which would
|
|
157
|
+
* also unblock dependents); `completed` or null (GitHub's default) reads as
|
|
158
|
+
* landed.
|
|
155
159
|
*/
|
|
156
160
|
async function alreadyClosedResult(
|
|
157
161
|
storyId,
|
|
@@ -159,7 +163,7 @@ async function alreadyClosedResult(
|
|
|
159
163
|
config,
|
|
160
164
|
worker = NO_WORKER,
|
|
161
165
|
) {
|
|
162
|
-
if (stateReason
|
|
166
|
+
if (UNLANDED_CLOSE_REASONS.has(stateReason)) {
|
|
163
167
|
progress(
|
|
164
168
|
'NOOP',
|
|
165
169
|
`Story #${storyId} is closed as not planned — nothing to land.`,
|
|
@@ -124,7 +124,7 @@ Two envelope-level reads come **before** any finding:
|
|
|
124
124
|
stale beyond roughly a month or `surfaceStale` **Medium**, a `null` stamp
|
|
125
125
|
**Medium**, an unenforced kind **Low** or **Info**.
|
|
126
126
|
|
|
127
|
-
**Regeneration is the remediation, never an in-run step.** The
|
|
127
|
+
**Regeneration is the remediation, never an in-run step.** The Recommendation
|
|
128
128
|
names the matching script and its one-shot acknowledgment:
|
|
129
129
|
|
|
130
130
|
| Kind | Regeneration script | Acknowledgment |
|
|
@@ -211,7 +211,7 @@ Executive Summary and change it only on an explicit operator instruction.
|
|
|
211
211
|
A remediation Story that only burns debt down leaves the floor where it was,
|
|
212
212
|
and the reclaimed slack is silently re-spent by the next change — the loop
|
|
213
213
|
runs and the ratchet never moves. So **every Hotspot Cluster and Tightening
|
|
214
|
-
Headroom finding's
|
|
214
|
+
Headroom finding's Recommendation MUST** end the remediation with the ratchet
|
|
215
215
|
tightened and gate-enforced:
|
|
216
216
|
|
|
217
217
|
1. Lower the floor under `delivery.quality.gates` in `.agentrc.json` to the
|
|
@@ -222,7 +222,7 @@ tightened and gate-enforced:
|
|
|
222
222
|
gate that already exists at that Story's delivery time rather than by prose
|
|
223
223
|
nobody runs.
|
|
224
224
|
|
|
225
|
-
Use these two
|
|
225
|
+
Use these two Recommendation templates verbatim, substituting the envelope's own
|
|
226
226
|
values for the angle-bracketed slots:
|
|
227
227
|
|
|
228
228
|
- **Hotspot Cluster template:**
|
|
@@ -184,9 +184,10 @@ When a Fix Properly finding's real remediation belongs to one of those
|
|
|
184
184
|
lenses, say so in the Recommendation and name the lens rather than
|
|
185
185
|
re-auditing its domain here.
|
|
186
186
|
|
|
187
|
-
## Step 4:
|
|
187
|
+
## Step 4: Recommendation templates
|
|
188
188
|
|
|
189
|
-
|
|
189
|
+
Write each finding's **Recommendation & Rationale** from the matching template,
|
|
190
|
+
substituting the envelope's own values for the angle-bracketed slots:
|
|
190
191
|
|
|
191
192
|
- **Dead bundle template:**
|
|
192
193
|
`Remove the <adapter> exceptions the audit-exceptions engine proved dead: <file:line list>. Each one exempts nothing (<verdictBasis>). Delete each entry, then re-run node .agents/scripts/audit-exceptions.js --out temp/audit-exceptions/envelope.json and confirm none of them reappears. For a dependency pin or patch, reinstall and confirm the lockfile resolves the same versions without it, and run the project's audit command to confirm no advisory returns.`
|
|
@@ -17,7 +17,8 @@ Engineering Lead
|
|
|
17
17
|
The `audit-*` workflows each produce a structured `audit-<dimension>-results.md`
|
|
18
18
|
report under `temp/audits/`. Every `### Finding` block in those reports
|
|
19
19
|
already carries the fields a Story body needs (Severity / Impact,
|
|
20
|
-
Dimension / Category, Current State, Recommendation,
|
|
20
|
+
Dimension / Category, Location, Current State, Recommendation, Acceptance
|
|
21
|
+
signal).
|
|
21
22
|
|
|
22
23
|
The audit producers themselves are **not modified** by this workflow.
|
|
23
24
|
They remain read-only emitters of audit reports.
|
|
@@ -143,9 +144,11 @@ node .agents/scripts/audit-to-stories.js --emit-plan-seed \
|
|
|
143
144
|
```
|
|
144
145
|
|
|
145
146
|
The seed renders the canonical one-pager sections — Problem Statement,
|
|
146
|
-
Recommended Direction
|
|
147
|
-
report), MVP Scope (**the findings,
|
|
148
|
-
|
|
147
|
+
Recommended Direction (a finding count and severity breakdown per dimension),
|
|
148
|
+
Key Assumptions (with links to every source report), MVP Scope (**the findings,
|
|
149
|
+
flat**, worst first, each with its Location, Recommendation and Acceptance
|
|
150
|
+
signal nested under it), Key Files (so `/mandrel-plan`'s authoring step has
|
|
151
|
+
concrete anchors), Not Doing.
|
|
149
152
|
|
|
150
153
|
**The seed states findings, not a partition.** MVP Scope used
|
|
151
154
|
to render one numbered bullet per group beneath a `## Grouping` container
|
|
@@ -205,8 +208,8 @@ node .agents/scripts/audit-to-stories.js --emit-stories \
|
|
|
205
208
|
For each entry whose plan classification is `create`, open a GitHub
|
|
206
209
|
Issue. Use the GitHub MCP tool when available (`issue_write` with
|
|
207
210
|
method `create`), or fall back to `gh issue create`. The body carries
|
|
208
|
-
the canonical sections (Summary, Acceptance Criteria
|
|
209
|
-
Context) plus the machine-readable fingerprint footer rendered by the
|
|
211
|
+
the canonical sections (Summary, Acceptance Criteria — one item per finding,
|
|
212
|
+
taken from its Acceptance signal — Findings, Context) plus the machine-readable fingerprint footer rendered by the
|
|
210
213
|
shared helper's `fingerprintFooter(sha)`
|
|
211
214
|
(`<!-- audit-fingerprints: sha1,sha1,... -->`) that Phase 6 relies on.
|
|
212
215
|
|
|
@@ -54,8 +54,9 @@ Summary carries the self-cross-check `kept <k> / dropped <d>` line
|
|
|
54
54
|
([below](#self-cross-check)) and, beside it, the machine-readable severity
|
|
55
55
|
tally ([below](#severity-tally)).
|
|
56
56
|
|
|
57
|
-
Every finding under `## Detailed Findings` uses the shared
|
|
58
|
-
below
|
|
57
|
+
Every finding under `## Detailed Findings` uses the shared 6-field skeleton
|
|
58
|
+
below, ordered by severity — Critical, High, Medium, Low, then Info — so a
|
|
59
|
+
reader that stops early, or a truncated read, still sees the worst first. A lens may **add** fields (e.g. a WCAG success criterion, a CWE ID, a
|
|
59
60
|
`Baseline MUST`, a `Route / Door` + `Persona(s)` pair, an `Evidence` tag) and
|
|
60
61
|
may **relabel** the two normalized axes — `Severity` ↔ `Impact`, `Dimension` ↔
|
|
61
62
|
`Category` ↔ `Type` — as its preamble declares; the parser
|
|
@@ -73,8 +74,8 @@ Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
|
|
|
73
74
|
|
|
74
75
|
## Detailed Findings
|
|
75
76
|
|
|
76
|
-
[For every finding, use the following strict
|
|
77
|
-
the primary file the finding lives in:]
|
|
77
|
+
[For every finding, in descending severity order, use the following strict
|
|
78
|
+
structure. Lead each title with the primary file the finding lives in:]
|
|
78
79
|
|
|
79
80
|
### `path/to/primary-file.ext` — [Short title of the issue]
|
|
80
81
|
|
|
@@ -86,8 +87,6 @@ the primary file the finding lives in:]
|
|
|
86
87
|
- **Acceptance signal:** [the command or observable that proves this finding is
|
|
87
88
|
remediated — e.g. a grep that now returns empty, an added regression test, or
|
|
88
89
|
a re-run of this lens]
|
|
89
|
-
- **Agent Prompt:**
|
|
90
|
-
`[A copy-pasteable, highly specific prompt to execute this remediation independently]`
|
|
91
90
|
```
|
|
92
91
|
|
|
93
92
|
## Severity scale {#severity-scale}
|
|
@@ -550,9 +550,16 @@ fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is
|
|
|
550
550
|
|
|
551
551
|
**Default on.** After the Stories exist, persist comments on each source
|
|
552
552
|
issue naming the specific Story that claims it — plus that Story's optional
|
|
553
|
-
per-supersede `note` — and closes it with reason **`
|
|
554
|
-
(`state_reason`)
|
|
555
|
-
be a lie.
|
|
553
|
+
per-supersede `note` — and closes it with reason **`duplicate`**
|
|
554
|
+
(`state_reason`): the claiming Story carries the work, and nothing has
|
|
555
|
+
shipped at persist time, so `completed` would be a lie. A provider that
|
|
556
|
+
refuses `duplicate` gets one logged retry as `not_planned`.
|
|
557
|
+
|
|
558
|
+
The comment opens with
|
|
559
|
+
`<!-- ap:structured-comment type="superseded-by" story="<id>" -->`, `<id>`
|
|
560
|
+
the claiming Story's issue number. That marker is a **stable consumer
|
|
561
|
+
contract** — tooling mirroring issue state may follow it to the successor —
|
|
562
|
+
and will not change shape without a CHANGELOG `BREAKING CHANGE`.
|
|
556
563
|
|
|
557
564
|
The default also **clears the source's `agent::*` label** in the same write — a
|
|
558
565
|
retired ticket has no agent state. Pass **`--no-close-superseded`** for a
|
package/docs/CHANGELOG.md
CHANGED
|
@@ -15,6 +15,20 @@ 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.78.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.77.0...mandrel-v2.78.0) (2026-10-09)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
* audit findings: drop the Agent Prompt field and carry Acceptance signal and Recommendation through to Stories and plan seeds ([#5569](https://github.com/dsj1984/mandrel/issues/5569)) ([#5570](https://github.com/dsj1984/mandrel/issues/5570)) ([0ac754d](https://github.com/dsj1984/mandrel/commit/0ac754d4897e8cb16bd7c5bfcf4034efcd039f3d))
|
|
24
|
+
|
|
25
|
+
## [2.77.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.76.0...mandrel-v2.77.0) (2026-10-08)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
### Added
|
|
29
|
+
|
|
30
|
+
* plan-persist: name the claiming Story in the superseded-by marker and close superseded tickets as duplicate ([#5565](https://github.com/dsj1984/mandrel/issues/5565)) ([#5566](https://github.com/dsj1984/mandrel/issues/5566)) ([941fc0a](https://github.com/dsj1984/mandrel/commit/941fc0a340d7ffa5b605db48ba6a60a8172c0b5e))
|
|
31
|
+
|
|
18
32
|
## [2.76.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.75.0...mandrel-v2.76.0) (2026-10-07)
|
|
19
33
|
|
|
20
34
|
|
package/package.json
CHANGED