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.
@@ -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. Every finding under Detailed Findings uses this shared skeleton; the
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, not the verbatim
59
- * recommendation (which stays in the prompts/footer).
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 acceptanceItemFromFinding(finding) {
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
- function agentPromptsSection(group) {
111
- const blocks = (group.findings ?? [])
112
- .filter(
113
- (f) => typeof f.agentPrompt === 'string' && f.agentPrompt.length > 0,
114
- )
115
- .map((f) => `**${f.title}**\n\n\`\`\`\n${f.agentPrompt}\n\`\`\``);
116
- return blocks.join('\n\n') || '_(no copy-pasteable prompts captured)_';
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
- '## Agent Prompts',
241
+ '## Findings',
208
242
  '',
209
- agentPromptsSection(group),
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
- * agentPrompt: string,
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 agentPrompt = fields['agent prompt'] ?? '';
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
- agentPrompt,
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
- function formatProblemStatement(findings) {
47
+ /** `2 High, 1 Medium` — non-zero levels only, highest first. */
48
+ function formatTally(findings) {
47
49
  const sev = tallySeverities(findings);
48
- const dimensions = tallyDimensions(findings);
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 = new Map();
62
- for (const f of findings) {
63
- if (!byDim.has(f.dimension)) byDim.set(f.dimension, []);
64
- if (f.recommendation) byDim.get(f.dimension).push(f.recommendation);
65
- }
66
- const lines = [];
67
- for (const [dim, recs] of [...byDim.entries()].sort()) {
68
- const label = DIMENSION_LABEL[dim] ?? dim;
69
- const head = recs.slice(0, 2).join(' ');
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
- return `- **${f.title}** — ${severity}${label}${file}`;
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
- /** Nothing has shipped at persist time, so `not_planned`, not `completed`. */
21
- export const SUPERSEDE_CLOSE_REASON = 'not_planned';
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: SUPERSEDE_CLOSE_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.updateTicket(id, supersedeCloseMutations(probe.ticket));
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` means nothing merged,
153
- * so it fails rather than reporting `landed` (which would also unblock
154
- * dependents); `completed` or null (GitHub's default) reads as landed.
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 === 'not_planned') {
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 Agent Prompt
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 Agent Prompt MUST** end the remediation with the ratchet
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 Agent Prompt templates verbatim, substituting the envelope's own
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: Agent Prompt templates
187
+ ## Step 4: Recommendation templates
188
188
 
189
- Substitute the envelope's own values for the angle-bracketed slots:
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, Agent Prompt).
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, Key Assumptions (with links to every source
147
- report), MVP Scope (**the findings, flat**), Key Files (so `/mandrel-plan`'s
148
- authoring step has concrete anchors), Not Doing.
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, Agent Prompts,
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 7-field skeleton
58
- below. A lens may **add** fields (e.g. a WCAG success criterion, a CWE ID, a
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 structure. Lead each title with
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 **`not_planned`**
554
- (`state_reason`) — nothing has shipped at persist time, so `completed` would
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.76.0",
3
+ "version": "2.78.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/",