mandrel 2.74.0 → 2.76.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 (41) hide show
  1. package/.agents/audit-checklists/exceptions.md +24 -0
  2. package/.agents/docs/runbooks/mods.md +78 -16
  3. package/.agents/docs/workflows.md +2 -1
  4. package/.agents/mods/mandrel-status/hooks/register.tsx +942 -108
  5. package/.agents/mods/mandrel-status/types/index.d.ts +67 -11
  6. package/.agents/schemas/audit-exceptions-envelope.schema.json +268 -0
  7. package/.agents/schemas/audit-rules.json +43 -0
  8. package/.agents/schemas/story-progress.schema.json +48 -0
  9. package/.agents/scripts/audit-exceptions.js +145 -0
  10. package/.agents/scripts/lib/audit-exceptions/adapters/ci-gates.js +65 -0
  11. package/.agents/scripts/lib/audit-exceptions/adapters/code-allowlists.js +143 -0
  12. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-audit.js +160 -0
  13. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-patches.js +124 -0
  14. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-pins.js +177 -0
  15. package/.agents/scripts/lib/audit-exceptions/adapters/dependency-policy.js +243 -0
  16. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +30 -0
  17. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +107 -0
  18. package/.agents/scripts/lib/audit-exceptions/adapters/sca-exceptions.js +55 -0
  19. package/.agents/scripts/lib/audit-exceptions/adapters/test-skips.js +96 -0
  20. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +273 -0
  21. package/.agents/scripts/lib/audit-exceptions/classify.js +64 -0
  22. package/.agents/scripts/lib/audit-exceptions/dependency-index.js +266 -0
  23. package/.agents/scripts/lib/audit-exceptions/engine.js +249 -0
  24. package/.agents/scripts/lib/audit-exceptions/globs.js +106 -0
  25. package/.agents/scripts/lib/audit-exceptions/history.js +126 -0
  26. package/.agents/scripts/lib/audit-exceptions/locate.js +59 -0
  27. package/.agents/scripts/lib/audit-exceptions/probe.js +196 -0
  28. package/.agents/scripts/lib/audit-exceptions/range-subset.js +153 -0
  29. package/.agents/scripts/lib/audit-exceptions/read.js +101 -0
  30. package/.agents/scripts/lib/audit-exceptions/record.js +102 -0
  31. package/.agents/scripts/lib/audit-exceptions/scope.js +131 -0
  32. package/.agents/scripts/lib/audit-exceptions/tickets.js +98 -0
  33. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  34. package/.agents/scripts/lib/config/temp-paths.js +15 -0
  35. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  36. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +24 -3
  37. package/.agents/scripts/lib/orchestration/story-handoff.js +7 -0
  38. package/.agents/scripts/lib/orchestration/story-progress.js +127 -0
  39. package/.agents/workflows/audit-exceptions.md +235 -0
  40. package/docs/CHANGELOG.md +20 -0
  41. 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',
@@ -229,6 +229,21 @@ export function storyReviewDepositPath(sid, config) {
229
229
  );
230
230
  }
231
231
 
232
+ /**
233
+ * Live phase record for a Story's handoff or close. The trailing
234
+ * `-<id>` keys it to the Story for the retention purge.
235
+ *
236
+ * @param {number} sid
237
+ * @param {object} [config]
238
+ * @returns {string}
239
+ */
240
+ export function storyProgressPath(sid, config) {
241
+ return path.join(
242
+ orchestrationLogDir(config),
243
+ `story-progress-${storyId(sid)}.json`,
244
+ );
245
+ }
246
+
232
247
  const runId = (id) => {
233
248
  if (!Number.isInteger(id) || id <= 0) {
234
249
  throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);
@@ -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',
@@ -30,6 +30,7 @@ import {
30
30
  NEXT_COMMANDS,
31
31
  terminalFromWaitOutcome,
32
32
  } from '../story-deliver-terminal.js';
33
+ import { createStoryProgress } from '../story-progress.js';
33
34
  import { deriveCloseNote } from './close-note.js';
34
35
  import { closeArmedPr, runAutoMergePhase } from './phases/auto-merge.js';
35
36
  import { runBaseSyncPhase } from './phases/base-sync.js';
@@ -430,6 +431,7 @@ async function openAndReviewPr(ctx, deps) {
430
431
  progress,
431
432
  });
432
433
  const prNumber = parsePrNumber(prUrl);
434
+ ctx.recordPrNumber(prNumber);
433
435
  // Already merged (landed between invocations): skip review and arm; confirm observes it.
434
436
  if (alreadyMerged) {
435
437
  discardHeldReview(ctx.heldReview, 'PR already merged', progress);
@@ -623,18 +625,34 @@ export async function runSingleStoryClose({
623
625
  let phase = 'init';
624
626
  let observedGates = null;
625
627
  const phaseTimer = createPhaseTimer();
628
+ // Inert until the config resolves; no phase is entered before then.
629
+ let storyProgress = { phase() {}, prNumber() {} };
626
630
  const setPhase = (next) => {
627
631
  phase = next;
628
632
  phaseTimer.enter(next);
633
+ storyProgress.phase(next);
629
634
  };
630
635
  const setObservedGates = (gates) => {
631
636
  observedGates = gates;
632
637
  };
633
638
  try {
634
639
  const startedAtMs = Date.now();
640
+ const deps = resolveCloseDeps(options, injected);
641
+ storyProgress = createStoryProgress({
642
+ storyId: options.storyId,
643
+ stage: 'close',
644
+ config: deps.config,
645
+ });
635
646
  return await runClosePipeline(
636
- { options, setPhase, setObservedGates, phaseTimer, startedAtMs },
637
- resolveCloseDeps(options, injected),
647
+ {
648
+ options,
649
+ setPhase,
650
+ setObservedGates,
651
+ phaseTimer,
652
+ startedAtMs,
653
+ recordPrNumber: storyProgress.prNumber,
654
+ },
655
+ deps,
638
656
  );
639
657
  } catch (err) {
640
658
  if (err && typeof err === 'object') {
@@ -1007,7 +1025,10 @@ async function resolveCloseWorktree(ctx, deps) {
1007
1025
  !existingWorktreePath({ cwd, wtIsolation, storyId: ctx.storyId }) &&
1008
1026
  resolveWorktreeEnabled({ config: deps.config });
1009
1027
  ctx.landedPr = missing ? await findLandedPr(ctx, deps) : null;
1010
- if (ctx.landedPr) return null;
1028
+ if (ctx.landedPr) {
1029
+ ctx.recordPrNumber(ctx.landedPr.prNumber);
1030
+ return null;
1031
+ }
1011
1032
  return await resolveStoryWorktree({
1012
1033
  cwd,
1013
1034
  config: deps.config,
@@ -38,6 +38,7 @@ import { getStoryBranch, gitSpawn } from '../git-utils.js';
38
38
  import { readPackageScripts } from '../npm-scripts.js';
39
39
  import { TIMEOUT_EXIT_CODE } from '../process-group.js';
40
40
  import { probeHeldReviewDiff } from './review-deposit.js';
41
+ import { createStoryProgress, handoffStepName } from './story-progress.js';
41
42
  import {
42
43
  STATE_LABELS,
43
44
  transitionTicketState,
@@ -815,7 +816,13 @@ export async function runStoryHandoff({ storyId, cwd, config }, deps) {
815
816
  const steps = [];
816
817
  let stop = precheck(ctx);
817
818
  if (stop) steps.push(stop);
819
+ const storyProgress = createStoryProgress({
820
+ storyId,
821
+ stage: 'handoff',
822
+ config,
823
+ });
818
824
  for (const step of stop ? [] : stepOrder(ctx.depositor)) {
825
+ storyProgress.phase(handoffStepName(step));
819
826
  const result = await step(ctx);
820
827
  steps.push(result);
821
828
  progress(result.name, `${result.outcome} — ${result.detail}`);
@@ -0,0 +1,127 @@
1
+ /**
2
+ * The live story-progress record: which handoff step or close
3
+ * phase a Story is in right now, so live tooling can see the post-validation
4
+ * close phases that otherwise leave nothing on disk until the terminal
5
+ * envelope. Shape: `.agents/schemas/story-progress.schema.json`.
6
+ *
7
+ * Advisory only — nothing in Mandrel decides on it. Every write is best
8
+ * effort (an fs error is swallowed and logged at debug) and atomic (a
9
+ * `<file>.tmp` sibling renamed over the target), so a poller never parses
10
+ * half a file and an unwritable temp folder changes no delivery outcome.
11
+ */
12
+
13
+ import fs from 'node:fs';
14
+ import path from 'node:path';
15
+
16
+ import { storyProgressPath } from '../config/temp-paths.js';
17
+ import { Logger } from '../Logger.js';
18
+
19
+ const STORY_PROGRESS_KIND = 'story-progress';
20
+
21
+ /**
22
+ * A handoff step's reported name from its function name: `stepBaseMerge` →
23
+ * `base-merge`. The handoff suite pins that these equal the names each step
24
+ * reports in its envelope.
25
+ *
26
+ * @param {Function} step
27
+ * @returns {string}
28
+ */
29
+ export function handoffStepName(step) {
30
+ return step.name
31
+ .replace(/^step/, '')
32
+ .replace(/[A-Z]/g, (c, i) => `${i > 0 ? '-' : ''}${c.toLowerCase()}`);
33
+ }
34
+
35
+ /**
36
+ * Write `record` to `file` atomically. Never throws.
37
+ *
38
+ * @param {string} file
39
+ * @param {object} record
40
+ * @param {{ fsImpl?: typeof fs, debug?: (msg: string) => void }} [deps]
41
+ * @returns {boolean} whether the record landed
42
+ */
43
+ function writeStoryProgress(file, record, deps = {}) {
44
+ const fsImpl = deps.fsImpl ?? fs;
45
+ const debug = deps.debug ?? ((msg) => Logger.debug(msg));
46
+ const tmp = `${file}.tmp`;
47
+ try {
48
+ fsImpl.mkdirSync(path.dirname(file), { recursive: true });
49
+ fsImpl.writeFileSync(tmp, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
50
+ fsImpl.renameSync(tmp, file);
51
+ return true;
52
+ } catch (err) {
53
+ try {
54
+ fsImpl.rmSync(tmp, { force: true });
55
+ } catch {
56
+ // The stray tmp is harmless; the next write overwrites it.
57
+ }
58
+ debug(`[story-progress] write skipped for ${file}: ${err?.message ?? err}`);
59
+ return false;
60
+ }
61
+ }
62
+
63
+ /**
64
+ * A per-run recorder: `stageStartedAt` is fixed at creation, `phaseStartedAt`
65
+ * resets on each `phase()`, and `prNumber()` re-writes the current phase with
66
+ * the PR number once known. Nothing is written until the first `phase()`.
67
+ * Construction never throws either: a bad Story id or config degrades to a
68
+ * recorder that writes nothing.
69
+ *
70
+ * @param {{ storyId: number, stage: 'handoff'|'close', config?: object,
71
+ * file?: string, now?: () => Date, fsImpl?: typeof fs,
72
+ * debug?: (msg: string) => void }} args
73
+ * @returns {{ phase: (name: string) => boolean, prNumber: (n: number|null) => boolean, file: string|null }}
74
+ */
75
+ export function createStoryProgress({
76
+ storyId,
77
+ stage,
78
+ config,
79
+ file,
80
+ now = () => new Date(),
81
+ fsImpl,
82
+ debug,
83
+ }) {
84
+ let target = file ?? null;
85
+ if (!target) {
86
+ try {
87
+ target = storyProgressPath(storyId, config);
88
+ } catch (err) {
89
+ (debug ?? ((msg) => Logger.debug(msg)))(
90
+ `[story-progress] no progress path: ${err?.message ?? err}`,
91
+ );
92
+ }
93
+ }
94
+ const stageStartedAt = now().toISOString();
95
+ let current = null;
96
+ let phaseStartedAt = stageStartedAt;
97
+ let pr = null;
98
+ const write = () => {
99
+ if (!target || current === null) return false;
100
+ return writeStoryProgress(
101
+ target,
102
+ {
103
+ kind: STORY_PROGRESS_KIND,
104
+ storyId,
105
+ stage,
106
+ phase: current,
107
+ stageStartedAt,
108
+ phaseStartedAt,
109
+ prNumber: pr,
110
+ updatedAt: now().toISOString(),
111
+ },
112
+ { fsImpl, debug },
113
+ );
114
+ };
115
+ return {
116
+ file: target,
117
+ phase(name) {
118
+ current = name;
119
+ phaseStartedAt = now().toISOString();
120
+ return write();
121
+ },
122
+ prNumber(n) {
123
+ pr = Number.isInteger(n) && n > 0 ? n : null;
124
+ return write();
125
+ },
126
+ };
127
+ }
@@ -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
+ ```
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,26 @@ 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.76.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.75.0...mandrel-v2.76.0) (2026-10-07)
19
+
20
+
21
+ ### Added
22
+
23
+ * 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))
24
+
25
+
26
+ ### Fixed
27
+
28
+ * 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))
29
+
30
+ ## [2.75.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.74.0...mandrel-v2.75.0) (2026-10-02)
31
+
32
+
33
+ ### Added
34
+
35
+ * close and handoff write a story-progress file at every phase change, so live tooling can see post-validation close phases ([#5553](https://github.com/dsj1984/mandrel/issues/5553)) ([#5554](https://github.com/dsj1984/mandrel/issues/5554)) ([84c9a87](https://github.com/dsj1984/mandrel/commit/84c9a87c46253601e0ccbe681d0b9bd41eb20a4a))
36
+ * **mods:** mandrel-status band v2 with stage strip, learned ETAs and run line (refs [#5552](https://github.com/dsj1984/mandrel/issues/5552)) ([#5555](https://github.com/dsj1984/mandrel/issues/5555)) ([d194043](https://github.com/dsj1984/mandrel/commit/d194043b554bfb96371bfbc4ab0029b0c445bc9e))
37
+
18
38
  ## [2.74.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.73.0...mandrel-v2.74.0) (2026-10-02)
19
39
 
20
40
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.74.0",
3
+ "version": "2.76.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/",