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.
- package/.agents/audit-checklists/exceptions.md +24 -0
- package/.agents/docs/workflows.md +2 -1
- package/.agents/schemas/audit-exceptions-envelope.schema.json +268 -0
- package/.agents/schemas/audit-rules.json +43 -0
- package/.agents/scripts/audit-exceptions.js +145 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/ci-gates.js +65 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/code-allowlists.js +143 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/dependency-audit.js +160 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/dependency-patches.js +124 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/dependency-pins.js +177 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/dependency-policy.js +243 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/index.js +30 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +107 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/sca-exceptions.js +55 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/test-skips.js +96 -0
- package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +273 -0
- package/.agents/scripts/lib/audit-exceptions/classify.js +64 -0
- package/.agents/scripts/lib/audit-exceptions/dependency-index.js +266 -0
- package/.agents/scripts/lib/audit-exceptions/engine.js +249 -0
- package/.agents/scripts/lib/audit-exceptions/globs.js +106 -0
- package/.agents/scripts/lib/audit-exceptions/history.js +126 -0
- package/.agents/scripts/lib/audit-exceptions/locate.js +59 -0
- package/.agents/scripts/lib/audit-exceptions/probe.js +196 -0
- package/.agents/scripts/lib/audit-exceptions/range-subset.js +153 -0
- package/.agents/scripts/lib/audit-exceptions/read.js +101 -0
- package/.agents/scripts/lib/audit-exceptions/record.js +102 -0
- package/.agents/scripts/lib/audit-exceptions/scope.js +131 -0
- package/.agents/scripts/lib/audit-exceptions/tickets.js +98 -0
- package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
- package/.agents/scripts/lib/observability/source-classifier.js +1 -0
- 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-exceptions.md +235 -0
- package/.agents/workflows/helpers/plan-reference.md +10 -3
- package/docs/CHANGELOG.md +19 -0
- 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
|
+
}
|
|
@@ -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.`,
|
|
@@ -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 **`
|
|
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,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