mandrel 2.75.0 → 2.77.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/.agents/audit-checklists/exceptions.md +24 -0
  2. package/.agents/docs/workflows.md +2 -1
  3. package/.agents/schemas/audit-exceptions-envelope.schema.json +268 -0
  4. package/.agents/schemas/audit-rules.json +43 -0
  5. package/.agents/scripts/audit-exceptions.js +145 -0
  6. package/.agents/scripts/lib/audit-exceptions/adapters/ci-gates.js +65 -0
  7. package/.agents/scripts/lib/audit-exceptions/adapters/code-allowlists.js +143 -0
  8. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-audit.js +160 -0
  9. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-patches.js +124 -0
  10. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-pins.js +177 -0
  11. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-policy.js +243 -0
  12. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +30 -0
  13. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +107 -0
  14. package/.agents/scripts/lib/audit-exceptions/adapters/sca-exceptions.js +55 -0
  15. package/.agents/scripts/lib/audit-exceptions/adapters/test-skips.js +96 -0
  16. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +273 -0
  17. package/.agents/scripts/lib/audit-exceptions/classify.js +64 -0
  18. package/.agents/scripts/lib/audit-exceptions/dependency-index.js +266 -0
  19. package/.agents/scripts/lib/audit-exceptions/engine.js +249 -0
  20. package/.agents/scripts/lib/audit-exceptions/globs.js +106 -0
  21. package/.agents/scripts/lib/audit-exceptions/history.js +126 -0
  22. package/.agents/scripts/lib/audit-exceptions/locate.js +59 -0
  23. package/.agents/scripts/lib/audit-exceptions/probe.js +196 -0
  24. package/.agents/scripts/lib/audit-exceptions/range-subset.js +153 -0
  25. package/.agents/scripts/lib/audit-exceptions/read.js +101 -0
  26. package/.agents/scripts/lib/audit-exceptions/record.js +102 -0
  27. package/.agents/scripts/lib/audit-exceptions/scope.js +131 -0
  28. package/.agents/scripts/lib/audit-exceptions/tickets.js +98 -0
  29. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  30. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  31. package/.agents/scripts/lib/orchestration/plan-persist/supersede-ops.js +34 -5
  32. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +8 -4
  33. package/.agents/workflows/audit-exceptions.md +235 -0
  34. package/.agents/workflows/helpers/plan-reference.md +10 -3
  35. package/docs/CHANGELOG.md +19 -0
  36. package/package.json +1 -1
@@ -0,0 +1,98 @@
1
+ /**
2
+ * Resolve the tickets exceptions cite to `open` / `closed`, so an exception
3
+ * whose every ticket is closed reads as orphaned. Unique refs only, capped;
4
+ * a missing or unauthenticated `gh` degrades the run instead of failing it.
5
+ *
6
+ * @module lib/audit-exceptions/tickets
7
+ */
8
+
9
+ import {
10
+ gh as defaultGh,
11
+ GhAuthError,
12
+ GhNotFoundError,
13
+ GhNotInstalledError,
14
+ } from '../gh-exec.js';
15
+ import { gitSpawn } from '../git-utils.js';
16
+
17
+ export const DEFAULT_TICKET_LIMIT = 50;
18
+
19
+ /**
20
+ * `owner/repo` of the analysed checkout's `origin`, or `null`.
21
+ *
22
+ * @param {string} root
23
+ * @returns {string|null}
24
+ */
25
+ function originSlug(root) {
26
+ const res = gitSpawn(root, 'remote', 'get-url', 'origin');
27
+ if (res.status !== 0) return null;
28
+ return (
29
+ /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?$/.exec(
30
+ res.stdout.trim(),
31
+ )?.[1] ?? null
32
+ );
33
+ }
34
+
35
+ function qualify(ref, slug) {
36
+ const [repo, num] = ref.split('#');
37
+ const owner = repo || slug;
38
+ return owner ? { owner, num } : null;
39
+ }
40
+
41
+ async function fetchState(ghFacade, target) {
42
+ const res = await ghFacade.api({
43
+ endpoint: `repos/${target.owner}/issues/${target.num}`,
44
+ fields: ['state'],
45
+ });
46
+ return String(res?.stdout ?? res ?? '').trim();
47
+ }
48
+
49
+ /**
50
+ * @param {string[]} refs
51
+ * @param {object} opts
52
+ * @param {string} opts.root
53
+ * @param {number} [opts.limit]
54
+ * @param {object} [opts.gh] - `createGh()` facade (test seam).
55
+ * @returns {Promise<{ states: Map<string, string>, degradations: object[] }>}
56
+ */
57
+ export async function resolveTicketStates(
58
+ refs,
59
+ { root, limit = DEFAULT_TICKET_LIMIT, gh = defaultGh },
60
+ ) {
61
+ const states = new Map();
62
+ const degradations = [];
63
+ const unique = [...new Set(refs)];
64
+ if (unique.length === 0) return { states, degradations };
65
+ if (unique.length > limit) {
66
+ degradations.push({
67
+ input: 'ticket-limit',
68
+ reason: `only the first ${limit} of ${unique.length} cited tickets were resolved`,
69
+ detail: '',
70
+ });
71
+ }
72
+ const slug = originSlug(root);
73
+ if (!slug && unique.some((ref) => ref.startsWith('#'))) {
74
+ degradations.push({
75
+ input: 'origin',
76
+ reason: 'no GitHub origin remote; same-repo #N refs were not resolved',
77
+ detail: '',
78
+ });
79
+ }
80
+ for (const ref of unique.slice(0, limit)) {
81
+ const target = qualify(ref, slug);
82
+ if (!target) continue;
83
+ try {
84
+ states.set(ref, await fetchState(gh, target));
85
+ } catch (err) {
86
+ if (err instanceof GhNotFoundError) continue;
87
+ const fatal =
88
+ err instanceof GhNotInstalledError || err instanceof GhAuthError;
89
+ degradations.push({
90
+ input: 'gh',
91
+ reason: 'ticket states unavailable',
92
+ detail: err?.message ?? String(err),
93
+ });
94
+ if (fatal) break;
95
+ }
96
+ }
97
+ return { states, degradations };
98
+ }
@@ -19,6 +19,7 @@ export const AUDIT_LENSES = Object.freeze([
19
19
  'dependencies',
20
20
  'devops',
21
21
  'documentation',
22
+ 'exceptions',
22
23
  'mobile',
23
24
  'navigability',
24
25
  'performance',
@@ -23,6 +23,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
23
23
  'agents-bootstrap-github.js',
24
24
  'apply-quality-bootstrap.js',
25
25
  'audit-baselines.js',
26
+ 'audit-exceptions.js',
26
27
  'audit-labels-bootstrap.js',
27
28
  'audit-to-stories.js',
28
29
  'boot-sweep.js',
@@ -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.`,
@@ -0,0 +1,235 @@
1
+ ---
2
+ description: Audit every exception and escape valve — inline suppressions, tool-config exemptions, dependency overrides, patches and allowlists, CI gate exemptions, test skips and code allowlists — and flag the ones that are dead, expired, orphaned, unjustified, or papering over a real fix.
3
+ ---
4
+
5
+ # Exception & Override Audit
6
+
7
+ You are a Principal Engineer auditing this repository's **escape valves**.
8
+ Every gate only prevents regression, and every exception is a way around one:
9
+ an `eslint-disable`, a dependency override, a patched package, an allowlisted
10
+ advisory, a skipped test, a `KNOWN_*` list. Nothing else checks whether they
11
+ still earn their place, so they pile up unnoticed. This lens is that check,
12
+ and it is read-only. The shared lens machinery lives in
13
+ [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
14
+ `{{auditOutputDir}}/audit-exceptions-results.md`. Dimension values:
15
+ `Dead | Expired | Orphaned | Unjustified | Fix Properly`.
16
+
17
+ > **Value-free titles (mandatory).** A finding title MUST NOT embed a count,
18
+ > a version or a date — write ``### `package.json` — npm overrides no longer
19
+ > needed``, not ``… — 3 overrides redundant since 4.3.2``. Every re-run
20
+ > re-measures, so a title carrying the reading changes each pass, its
21
+ > fingerprint changes with it, and `/audit-to-stories` files a duplicate
22
+ > instead of deduping against the open Story. Numbers belong in Current State.
23
+
24
+ ## Scope
25
+
26
+ Per the core's Scope interpretation:
27
+
28
+ ```text
29
+ {{changedFiles}}
30
+ ```
31
+
32
+ When the fence resolves to a file list (a Story or plan-run audit), this lens
33
+ reports **only newly added escape valves**: run Step 0 with
34
+ `--changed-since origin/<baseBranch>` (`project.baseBranch`, default `main`)
35
+ and keep a record only when `introduced` is `true`, its `file` is in the
36
+ fence, and it is `unjustified` or carries no `ticketRefs`. Everything older is
37
+ a codebase-wide concern; leave it to a manual run. When the fence renders
38
+ literally, run codebase-wide.
39
+
40
+ ## Constraint (lens-specific carve-out)
41
+
42
+ This lens **refines** the core's read-only constraint; it never relaxes it.
43
+
44
+ - The only command it runs is the read-only engine in Step 0. With `--probe`
45
+ the engine also runs the analysed repo's own biome, eslint, `tsc` and knip
46
+ to read their unused-suppression reports. They run without any write or fix
47
+ flag, and the engine never evaluates the repo's code or JS-format configs.
48
+ - It never removes, edits or re-justifies an exception, and never touches a
49
+ lockfile or `node_modules`. **Removal is a finding, never an in-run step.**
50
+ - Gitignored local overrides (`.agentrc.local.json`,
51
+ `.agents/instructions.local.md`) are operator-owned and out of scope; the
52
+ engine reads tracked files only, so they never appear.
53
+
54
+ ## Execution strategy
55
+
56
+ Run this lens as one `subagent_type: auditor` dispatch per the core's
57
+ Execution strategy.
58
+
59
+ ## Step 0: Run the engine (mandatory — measure before you judge)
60
+
61
+ ```bash
62
+ node .agents/scripts/audit-exceptions.js --out temp/audit-exceptions/envelope.json
63
+ ```
64
+
65
+ Optional flags: `--probe` (also read each installed tool's own report of
66
+ suppressions that suppress nothing; slower, and worth it on a codebase-wide
67
+ run with large inline clusters), `--changed-since <ref>` (scoped mode, above),
68
+ `--ticket-limit`, `--blame-limit` and `--max-records` (caps; each cap that
69
+ bites is named in `degradations`). Exit 0 means evidence was assembled
70
+ **including every degraded input**; exit 1 means no envelope exists — report
71
+ that and stop.
72
+
73
+ The envelope is validated against
74
+ `.agents/schemas/audit-exceptions-envelope.schema.json` and is this lens's
75
+ sole evidence base. Cite its fields by name:
76
+
77
+ | Section | Fields you cite |
78
+ | --- | --- |
79
+ | root | `isFrameworkSource`, `options`, `degradations`, `truncated` |
80
+ | `adapters[]` / `skipped[]` | `id`, `category`, `recordCount` / `reason` |
81
+ | `delegated[]` | `surface`, `lens`, `reason` |
82
+ | `clusters[]` | `adapter`, `category`, `rule`, `count`, `byVerdict`, `files` |
83
+ | `records[]` | `file`, `line`, `surface`, `target`, `rule`, `justification`, `ticketRefs`, `expires`, `addedAt`, `introduced`, `verdict`, `verdictBasis`, `probeBasis`, `permanentHint` |
84
+
85
+ `verdict` is the engine's mechanical call, first match wins: `dead` (a probe
86
+ proved it exempts nothing), `expired` (its stated date is past), `orphaned`
87
+ (every ticket it waits on is closed), `unjustified` (no reason and no
88
+ ticket), `live`, or `unknown` (a probe could not decide). `probeBasis` keeps
89
+ what the probe found even when a higher verdict won — an `unjustified`
90
+ override whose `probeBasis` is `dependent-needs-pin` is a different finding
91
+ from an unjustified `redundant` one.
92
+
93
+ Read these **before** any finding:
94
+
95
+ - **`degradations`.** Name every degraded input in the Executive Summary. A
96
+ missing lockfile or `dependency-manifests-unavailable` means dependency
97
+ pins could not be proven redundant; a `gh` or `origin` degradation means
98
+ no record could read as orphaned. Never present a degraded verdict as a
99
+ clean one.
100
+ - **`skipped[]`.** An adapter that did not apply is not a finding. List the
101
+ skipped adapters in one line so a reader can tell "nothing found" from
102
+ "nothing looked".
103
+ - **`delegated[]`.** `.agentrc.json` gate `ignoreGlobs` belong to
104
+ `/audit-baselines`. Do not file them here.
105
+ - **`truncated`.** Non-null means `records[]` was capped. `clusters[]` still
106
+ counts every record — grade from the clusters and say so.
107
+
108
+ ## Step 1: Evaluation Dimensions
109
+
110
+ The engine has already decided four of the five dimensions mechanically. Your
111
+ judgment is the fifth, plus severity and routing.
112
+
113
+ 1. **Dead.** `verdict: dead`. The exception exempts nothing: its package left
114
+ the tree (`absent-from-tree`), every dependent already asks for a range
115
+ inside the pin (`redundant`), a patch targets a version that no longer
116
+ resolves (`version-drift`, `patch-file-missing`), a glob matches nothing
117
+ (`matches-nothing`), an allowlisted path is gone (`path-missing`), or the
118
+ tool itself reports it unused (`tool`). A dead exception also silently
119
+ exempts the next thing that happens to match it. Grade a dead dependency
120
+ pin or audit allowlist entry **Medium**, everything else **Low**.
121
+
122
+ 2. **Expired.** `verdict: expired`. Its own justification set a date that has
123
+ passed — someone promised to revisit it. Grade an expired audit allowlist
124
+ entry **High** (a known advisory is being waved through past its agreed
125
+ window), anything else **Medium**.
126
+
127
+ 3. **Orphaned.** `verdict: orphaned`. The tickets it says it waits on
128
+ (`TODO(#n)`, "until #n", "tracked in #n") are all closed, so either the
129
+ fix landed and the exception should go, or the fix was abandoned and the
130
+ exception needs a new owner. **Medium**.
131
+
132
+ 4. **Unjustified.** `verdict: unjustified`. No reason and no ticket. Read
133
+ `probeBasis` first: when the probe proved it still needed
134
+ (`dependent-needs-pin`, `matches-tracked`), the remediation is to write
135
+ the reason down, not to remove it. Grade an unjustified dependency
136
+ exception or CI gate exemption **Medium**, an unjustified inline
137
+ suppression **Low**.
138
+
139
+ 5. **Fix Properly.** Your one judgment call, over `live` records only (and
140
+ `unknown` ones whose context makes the answer clear). The exception still
141
+ works, but it is covering for a defect that has a real fix: a suppression
142
+ that hides a genuine bug class, an override pinning around an upstream fix
143
+ that has since shipped, a skipped test hiding a broken code path, a CI
144
+ step that may fail without consequence. Open the cited file and line
145
+ before claiming it. Grade by what the exception hides — a disabled
146
+ security rule or a `continue-on-error` on a required gate is **High**.
147
+
148
+ **Permanent is not a finding.** A record with a `permanentHint`
149
+ (`platform-conditional`, `untracked-path`, `conventional-setting`) or a
150
+ justification that states a lasting reason is legitimately forever. Count
151
+ it in the inventory; never file it.
152
+
153
+ **`unknown` is not `dead`.** An undecided probe is never evidence of
154
+ obsolescence. List `unknown` records under Undecided (below) and file one
155
+ only when you can show the answer from the code yourself.
156
+
157
+ ## Step 2: Clustering and the dropped log
158
+
159
+ **Emit one finding per `(adapter, rule)` cluster — never one per record.**
160
+ Five hundred `eslint-disable no-await-in-loop` lines are one finding with one
161
+ remediation, not five hundred Stories. **Bundle every `dead` record of one
162
+ adapter into a single finding** whose remediation is removing them all, and
163
+ list each one's `file:line` in Current State.
164
+
165
+ Cap the Detailed Findings at **12 clusters**, ranked by severity, then
166
+ `count`. The report MUST carry a **Dropped Clusters** section naming every
167
+ cluster the cap excluded with its `adapter`, `rule` and `count`; write
168
+ `_None dropped._` when the cap did not bite.
169
+
170
+ ## Step 3: Boundaries with sibling lenses
171
+
172
+ > This lens owns whether an exception is **still needed, justified and
173
+ > tracked**. Whether the thing it exempts is bad belongs elsewhere:
174
+ > [`/audit-baselines`](audit-baselines.md) owns gate `ignoreGlobs` and floors;
175
+ > [`/audit-dependencies`](audit-dependencies.md) owns outdated, unused and
176
+ > upgrade-batch decisions — a pin this lens calls redundant is its input, not
177
+ > its verdict; [`/audit-security`](audit-security.md) owns whether an
178
+ > allowlisted advisory is exploitable; [`/audit-quality`](audit-quality.md)
179
+ > owns the coverage impact of a skipped test; and
180
+ > [`/audit-clean-code`](audit-clean-code.md) owns the code smell an inline
181
+ > suppression may hide.
182
+
183
+ When a Fix Properly finding's real remediation belongs to one of those
184
+ lenses, say so in the Recommendation and name the lens rather than
185
+ re-auditing its domain here.
186
+
187
+ ## Step 4: Agent Prompt templates
188
+
189
+ Substitute the envelope's own values for the angle-bracketed slots:
190
+
191
+ - **Dead bundle template:**
192
+ `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.`
193
+ - **Unjustified template:**
194
+ `Give each <rule> exception a written reason or remove it: <file:line list>. Where the exception is still needed, put the reason inline (or in the package.json // note for a dependency pin) and cite the ticket it waits on, if any. Where nobody can state a reason, remove it and fix what it was suppressing.`
195
+ - **Fix Properly template:**
196
+ `The <rule> exception at <file:line> still works but covers a defect with a real fix: <what it hides>. Fix the underlying cause, remove the exception, and add a test or gate that would have caught the regression it was hiding.`
197
+
198
+ ## Step 5: Hand off to `/audit-to-stories`
199
+
200
+ ```bash
201
+ node .agents/scripts/audit-to-stories.js --scan --glob temp/audits/audit-exceptions-results.md --out temp/audits/audit-to-stories-plan.json
202
+ ```
203
+
204
+ Report the plan path and the group count; the converter owns everything
205
+ downstream, including whether a finding becomes a Story at all.
206
+
207
+ ## Report additions
208
+
209
+ Beyond the shared skeleton (Executive Summary + Detailed Findings from the
210
+ core), this report carries its own title, an Exception Inventory, the
211
+ Undecided list and the Dropped Clusters budget log:
212
+
213
+ ```markdown
214
+ # Exception & Override Audit Report
215
+
216
+ ## Exception Inventory
217
+
218
+ | Category | Records | Dead | Expired | Orphaned | Unjustified | Live | Unknown |
219
+ | --- | --- | --- | --- | --- | --- | --- | --- |
220
+ | [inline / config / dependency / gate / test / allowlist] | [n] | [n] | [n] | [n] | [n] | [n] | [n] |
221
+
222
+ Skipped adapters: [ids, or "none"]. Degraded inputs: [inputs, or "none"].
223
+
224
+ ## Undecided
225
+
226
+ | File:line | Adapter | Target | Probe basis |
227
+ | --- | --- | --- | --- |
228
+ | [file:line] | [adapter] | [target] | [probeBasis] |
229
+
230
+ ## Dropped Clusters
231
+
232
+ | Adapter | Rule | Count |
233
+ | --- | --- | --- |
234
+ | [adapter] | [rule] | [count] |
235
+ ```
@@ -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,25 @@ 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.77.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.76.0...mandrel-v2.77.0) (2026-10-08)
19
+
20
+
21
+ ### Added
22
+
23
+ * 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))
24
+
25
+ ## [2.76.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.75.0...mandrel-v2.76.0) (2026-10-07)
26
+
27
+
28
+ ### Added
29
+
30
+ * add the /audit-exceptions lens: inventory every suppression, pin and allowlist and flag the ones that no longer earn their place ([#5560](https://github.com/dsj1984/mandrel/issues/5560)) ([#5563](https://github.com/dsj1984/mandrel/issues/5563)) ([4cd8f48](https://github.com/dsj1984/mandrel/commit/4cd8f48d9486179b79e8030a844fce380af55388))
31
+
32
+
33
+ ### Fixed
34
+
35
+ * let the SCA gate honor reviewed, dated exceptions for unpatchable dev-only advisories ([#5559](https://github.com/dsj1984/mandrel/issues/5559)) ([#5561](https://github.com/dsj1984/mandrel/issues/5561)) ([e522301](https://github.com/dsj1984/mandrel/commit/e522301bcac959826cc6baca310d05a726fcc79b))
36
+
18
37
  ## [2.75.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.74.0...mandrel-v2.75.0) (2026-10-02)
19
38
 
20
39
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.75.0",
3
+ "version": "2.77.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/",