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
@@ -1,24 +1,77 @@
1
- /** A Story whose worktree exists and whose close has not finished. */
2
- export type InFlight = {
3
- storyId: number;
4
- /** True once close has written its gate log. */
5
- isClosing: boolean;
6
- /** Minutes since the gate log last changed, when over the stall limit. */
7
- stalledMinutes: number | null;
1
+ /** The six stages of a /mandrel-deliver Story, in order. */
2
+ export type StageName =
3
+ | 'start'
4
+ | 'build'
5
+ | 'check'
6
+ | 'handoff'
7
+ | 'close'
8
+ | 'merge';
9
+
10
+ /** One stage as the Details pane lists it; times in epoch milliseconds. */
11
+ export type StageRow = {
12
+ name: StageName;
13
+ startedAt: number | null;
14
+ /** The next stage's start, or null while this one is current or pending. */
15
+ endedAt: number | null;
16
+ };
17
+
18
+ /** One close phase: its recorded duration and the learned median, in seconds. */
19
+ export type PhaseRow = {
20
+ name: string;
21
+ seconds: number | null;
22
+ usualSeconds: number | null;
8
23
  };
9
24
 
10
- /** The newest terminal envelope from the last two hours. */
11
- export type LastResult = {
25
+ /** The Story the band follows: in flight, or the newest recent result. */
26
+ export type Focus = {
12
27
  storyId: number;
28
+ title: string | null;
29
+ /** `in-flight`, or the terminal envelope's `status`. */
13
30
  status: string;
31
+ stage: StageName;
32
+ /** The current stage's step detail, already worded. */
33
+ detail: string;
34
+ stages: StageRow[];
35
+ handoffSteps: { name: string; at: number }[];
36
+ closePhases: PhaseRow[];
14
37
  prNumber: number | null;
15
38
  checksStatus: string | null;
39
+ /** The envelope's `elapsedSeconds`, for a finished result. */
16
40
  elapsedSeconds: number | null;
41
+ /** Milliseconds into the current phase, while in flight. */
42
+ phaseElapsedMs: number | null;
43
+ /** The learned median of the current phase, once it has 3+ samples. */
44
+ usualMs: number | null;
45
+ isStalled: boolean;
46
+ /** Minutes the gate log has been quiet, when the 10-minute rule fired. */
47
+ idleMinutes: number | null;
48
+ /** `blocked.blockClass` or `failure.reason`. */
49
+ problem: string | null;
50
+ nextCommand: string | null;
51
+ /** Bullets in `follow-ups-rollup-<id>.md`, when it exists. */
52
+ followUps: number | null;
53
+ };
54
+
55
+ /** The newest live multi-Story run ledger. */
56
+ export type RunLine = {
57
+ landed: number;
58
+ total: number;
59
+ current: { storyId: number; stage: string } | null;
60
+ queued: number;
17
61
  };
18
62
 
19
63
  export type Snapshot = {
20
- inFlight: InFlight | null;
21
- last: LastResult | null;
64
+ focus: Focus | null;
65
+ run: RunLine | null;
66
+ /** When the scan ran, epoch milliseconds; 0 before the first. */
67
+ scannedAt: number;
68
+ };
69
+
70
+ /** Per close phase: the median of the newest terminal envelopes' timings. */
71
+ export type Learned = {
72
+ /** When the medians were last computed; 0 before the first pass. */
73
+ at: number;
74
+ phases: Record<string, { medianSeconds: number; samples: number }>;
22
75
  };
23
76
 
24
77
  declare module 'claude-code' {
@@ -29,6 +82,9 @@ declare module 'claude-code' {
29
82
  seen: string[];
30
83
  /** False until the first scan, which records envelopes without a toast. */
31
84
  isSeeded: boolean;
85
+ learned: Learned;
86
+ /** The focus Story the person hid the band for; it shows again on a new one. */
87
+ hiddenFor: number | null;
32
88
  };
33
89
  }
34
90
  }
@@ -0,0 +1,268 @@
1
+ {
2
+ "$schema": "http://json-schema.org/draft-07/schema#",
3
+ "$id": "https://mandrel/.agents/schemas/audit-exceptions-envelope.schema.json",
4
+ "title": "AuditExceptionsEnvelope",
5
+ "description": "Evidence envelope emitted by `.agents/scripts/audit-exceptions.js` (Story #5560): every exception the adapter registry found in a repository (inline suppressions, tool-config exemptions, dependency pins / patches / allowlists, CI gate exemptions, test skips, code allowlists), each with a mechanical verdict, plus per-(adapter, rule) clusters, inapplicable adapters, delegations to sibling lenses, and degraded inputs.",
6
+ "type": "object",
7
+ "required": [
8
+ "kind",
9
+ "schemaVersion",
10
+ "generatedAt",
11
+ "cwd",
12
+ "isFrameworkSource",
13
+ "options",
14
+ "adapters",
15
+ "skipped",
16
+ "delegated",
17
+ "probes",
18
+ "degradations",
19
+ "totals",
20
+ "clusters",
21
+ "truncated",
22
+ "records"
23
+ ],
24
+ "additionalProperties": false,
25
+ "definitions": {
26
+ "verdict": {
27
+ "enum": ["dead", "expired", "orphaned", "unjustified", "live", "unknown"]
28
+ },
29
+ "category": {
30
+ "enum": ["inline", "config", "dependency", "gate", "test", "allowlist"]
31
+ },
32
+ "verdictCounts": {
33
+ "type": "object",
34
+ "required": [
35
+ "dead",
36
+ "expired",
37
+ "orphaned",
38
+ "unjustified",
39
+ "live",
40
+ "unknown"
41
+ ],
42
+ "additionalProperties": false,
43
+ "properties": {
44
+ "dead": { "type": "integer", "minimum": 0 },
45
+ "expired": { "type": "integer", "minimum": 0 },
46
+ "orphaned": { "type": "integer", "minimum": 0 },
47
+ "unjustified": { "type": "integer", "minimum": 0 },
48
+ "live": { "type": "integer", "minimum": 0 },
49
+ "unknown": { "type": "integer", "minimum": 0 }
50
+ }
51
+ },
52
+ "degradation": {
53
+ "type": "object",
54
+ "required": ["input", "reason", "detail"],
55
+ "additionalProperties": false,
56
+ "properties": {
57
+ "input": { "type": "string", "minLength": 1 },
58
+ "reason": { "type": "string" },
59
+ "detail": { "type": "string" }
60
+ }
61
+ },
62
+ "record": {
63
+ "type": "object",
64
+ "required": [
65
+ "id",
66
+ "adapter",
67
+ "category",
68
+ "surface",
69
+ "file",
70
+ "line",
71
+ "target",
72
+ "rule",
73
+ "justification",
74
+ "ticketRefs",
75
+ "expires",
76
+ "addedAt",
77
+ "introduced",
78
+ "verdict",
79
+ "verdictBasis",
80
+ "probeBasis",
81
+ "permanentHint"
82
+ ],
83
+ "additionalProperties": false,
84
+ "properties": {
85
+ "id": { "type": "string", "minLength": 1 },
86
+ "adapter": { "type": "string", "minLength": 1 },
87
+ "category": { "$ref": "#/definitions/category" },
88
+ "surface": { "type": "string", "minLength": 1 },
89
+ "file": {
90
+ "type": "string",
91
+ "minLength": 1,
92
+ "description": "Repo-relative, forward slashes."
93
+ },
94
+ "line": { "type": "integer", "minimum": 1 },
95
+ "target": {
96
+ "type": "string",
97
+ "description": "What the exception exempts: a rule, package, glob, setting or entry."
98
+ },
99
+ "rule": {
100
+ "type": "string",
101
+ "description": "Cluster key within the adapter."
102
+ },
103
+ "justification": { "type": ["string", "null"] },
104
+ "ticketRefs": { "type": "array", "items": { "type": "string" } },
105
+ "expires": {
106
+ "type": ["string", "null"],
107
+ "description": "ISO date parsed from the justification."
108
+ },
109
+ "addedAt": {
110
+ "type": ["string", "null"],
111
+ "description": "ISO date from git blame; null past --blame-limit or when uncommitted."
112
+ },
113
+ "introduced": {
114
+ "type": "boolean",
115
+ "description": "Line added since --changed-since; false when the flag is absent."
116
+ },
117
+ "verdict": { "$ref": "#/definitions/verdict" },
118
+ "verdictBasis": {
119
+ "type": "string",
120
+ "minLength": 1,
121
+ "description": "Why the verdict holds: a probe basis (absent-from-tree, redundant, matches-nothing, tool, ...), expiry-date, ticket-closed, no-justification, or none."
122
+ },
123
+ "probeBasis": {
124
+ "type": ["string", "null"],
125
+ "description": "What the mechanical probe found, kept even when a higher-precedence verdict (expired, orphaned, unjustified) wins; null when no probe applies."
126
+ },
127
+ "permanentHint": {
128
+ "type": ["string", "null"],
129
+ "description": "Set when the shape is legitimately permanent (platform-conditional, conventional-setting)."
130
+ }
131
+ }
132
+ }
133
+ },
134
+ "properties": {
135
+ "kind": { "const": "audit-exceptions-envelope" },
136
+ "schemaVersion": { "type": "string", "minLength": 1 },
137
+ "generatedAt": { "type": "string", "format": "date-time" },
138
+ "cwd": { "type": "string", "minLength": 1 },
139
+ "isFrameworkSource": {
140
+ "type": "boolean",
141
+ "description": "True only in the Mandrel source repo; elsewhere the materialized .agents/ payload is excluded from scope."
142
+ },
143
+ "options": {
144
+ "type": "object",
145
+ "required": [
146
+ "probe",
147
+ "changedSince",
148
+ "ticketLimit",
149
+ "blameLimit",
150
+ "maxRecords"
151
+ ],
152
+ "additionalProperties": false,
153
+ "properties": {
154
+ "probe": { "type": "boolean" },
155
+ "changedSince": { "type": ["string", "null"] },
156
+ "ticketLimit": { "type": "integer", "minimum": 0 },
157
+ "blameLimit": { "type": "integer", "minimum": 0 },
158
+ "maxRecords": { "type": "integer", "minimum": 1 }
159
+ }
160
+ },
161
+ "adapters": {
162
+ "type": "array",
163
+ "items": {
164
+ "type": "object",
165
+ "required": ["id", "category", "recordCount"],
166
+ "additionalProperties": false,
167
+ "properties": {
168
+ "id": { "type": "string", "minLength": 1 },
169
+ "category": { "$ref": "#/definitions/category" },
170
+ "recordCount": { "type": "integer", "minimum": 0 }
171
+ }
172
+ }
173
+ },
174
+ "skipped": {
175
+ "type": "array",
176
+ "items": {
177
+ "type": "object",
178
+ "required": ["id", "reason"],
179
+ "additionalProperties": false,
180
+ "properties": {
181
+ "id": { "type": "string", "minLength": 1 },
182
+ "reason": { "type": "string" }
183
+ }
184
+ }
185
+ },
186
+ "delegated": {
187
+ "type": "array",
188
+ "items": {
189
+ "type": "object",
190
+ "required": ["surface", "lens", "reason"],
191
+ "additionalProperties": false,
192
+ "properties": {
193
+ "surface": { "type": "string" },
194
+ "lens": { "type": "string" },
195
+ "reason": { "type": "string" }
196
+ }
197
+ }
198
+ },
199
+ "probes": {
200
+ "type": "array",
201
+ "items": {
202
+ "type": "object",
203
+ "required": ["id", "flagged"],
204
+ "additionalProperties": false,
205
+ "properties": {
206
+ "id": { "type": "string" },
207
+ "flagged": { "type": "integer", "minimum": 0 }
208
+ }
209
+ }
210
+ },
211
+ "degradations": {
212
+ "type": "array",
213
+ "items": { "$ref": "#/definitions/degradation" }
214
+ },
215
+ "totals": {
216
+ "type": "object",
217
+ "required": ["records", "byVerdict", "byCategory", "introduced"],
218
+ "additionalProperties": false,
219
+ "properties": {
220
+ "records": { "type": "integer", "minimum": 0 },
221
+ "byVerdict": { "$ref": "#/definitions/verdictCounts" },
222
+ "byCategory": {
223
+ "type": "object",
224
+ "additionalProperties": { "type": "integer", "minimum": 0 }
225
+ },
226
+ "introduced": { "type": "integer", "minimum": 0 }
227
+ }
228
+ },
229
+ "clusters": {
230
+ "type": "array",
231
+ "items": {
232
+ "type": "object",
233
+ "required": [
234
+ "adapter",
235
+ "category",
236
+ "rule",
237
+ "count",
238
+ "byVerdict",
239
+ "files"
240
+ ],
241
+ "additionalProperties": false,
242
+ "properties": {
243
+ "adapter": { "type": "string" },
244
+ "category": { "$ref": "#/definitions/category" },
245
+ "rule": { "type": "string" },
246
+ "count": { "type": "integer", "minimum": 1 },
247
+ "byVerdict": { "$ref": "#/definitions/verdictCounts" },
248
+ "files": { "type": "array", "items": { "type": "string" } }
249
+ }
250
+ }
251
+ },
252
+ "truncated": {
253
+ "oneOf": [
254
+ { "type": "null" },
255
+ {
256
+ "type": "object",
257
+ "required": ["kept", "dropped"],
258
+ "additionalProperties": false,
259
+ "properties": {
260
+ "kept": { "type": "integer", "minimum": 0 },
261
+ "dropped": { "type": "integer", "minimum": 1 }
262
+ }
263
+ }
264
+ ]
265
+ },
266
+ "records": { "type": "array", "items": { "$ref": "#/definitions/record" } }
267
+ }
268
+ }
@@ -182,6 +182,49 @@
182
182
  "scope": "cumulative",
183
183
  "substitutionKeys": []
184
184
  },
185
+ "audit-exceptions": {
186
+ "triggers": {
187
+ "gates": ["gate1", "gate3"],
188
+ "keywords": [
189
+ "exception",
190
+ "suppression",
191
+ "suppress",
192
+ "override",
193
+ "overrides",
194
+ "allowlist",
195
+ "waiver",
196
+ "version pin",
197
+ "patch-package",
198
+ "patched dependency",
199
+ "eslint-disable",
200
+ "biome-ignore",
201
+ "ts-expect-error",
202
+ "skipped test"
203
+ ],
204
+ "filePatterns": [
205
+ "**/package.json",
206
+ "**/pnpm-workspace.yaml",
207
+ "**/.npmrc",
208
+ "patches/**",
209
+ "renovate.json",
210
+ ".github/renovate.json",
211
+ ".nsprc",
212
+ "audit-ci.json",
213
+ "audit-ci.jsonc",
214
+ "knip.json",
215
+ "knip.jsonc",
216
+ "biome.json",
217
+ "biome.jsonc",
218
+ ".eslintrc*",
219
+ "**/tsconfig*.json",
220
+ ".c8rc*",
221
+ ".prettierignore",
222
+ ".eslintignore"
223
+ ]
224
+ },
225
+ "scope": "cumulative",
226
+ "substitutionKeys": []
227
+ },
185
228
  "audit-documentation": {
186
229
  "triggers": {
187
230
  "gates": ["gate1", "gate3"],
@@ -0,0 +1,48 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/story-progress.schema.json",
4
+ "title": "story-progress",
5
+ "description": "The live progress record a Story's handoff and close rewrite at every step or phase change (Story #5553), at <tempRoot>/orchestration/story-progress-<id>.json. It exists because push, PR, review, auto-merge and the merge wait leave nothing on disk until the terminal envelope. Advisory only: nothing in Mandrel reads it to decide anything, every write is best effort, and each write is atomic (a <file>.tmp sibling renamed over the target).",
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "required": [
9
+ "kind",
10
+ "storyId",
11
+ "stage",
12
+ "phase",
13
+ "stageStartedAt",
14
+ "phaseStartedAt",
15
+ "prNumber",
16
+ "updatedAt"
17
+ ],
18
+ "properties": {
19
+ "kind": { "type": "string", "const": "story-progress" },
20
+ "storyId": { "type": "integer", "minimum": 1 },
21
+ "stage": {
22
+ "type": "string",
23
+ "enum": ["handoff", "close"],
24
+ "description": "handoff — the worker's story-handoff.js run; close — single-story-close.js."
25
+ },
26
+ "phase": {
27
+ "type": "string",
28
+ "minLength": 1,
29
+ "description": "For close, the phase name close passes to setPhase (the phaseDurations keys). For handoff, the step name: preflight, base-merge, credited-run, seat, push, review."
30
+ },
31
+ "stageStartedAt": {
32
+ "type": "string",
33
+ "format": "date-time",
34
+ "description": "When this handoff or close run started; fixed for the run."
35
+ },
36
+ "phaseStartedAt": {
37
+ "type": "string",
38
+ "format": "date-time",
39
+ "description": "When the current phase started; resets on each phase change."
40
+ },
41
+ "prNumber": {
42
+ "type": ["integer", "null"],
43
+ "minimum": 1,
44
+ "description": "The Story PR's number from the moment close parses it; null before then and throughout handoff."
45
+ },
46
+ "updatedAt": { "type": "string", "format": "date-time" }
47
+ }
48
+ }
@@ -0,0 +1,145 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * CLI: the deterministic evidence half of `/audit-exceptions` — every
5
+ * suppression, dependency pin / patch / allowlist, CI gate exemption, test skip
6
+ * and code allowlist in a repo, each with a mechanical verdict. Read-only:
7
+ * writes only the `--out` envelope. Degraded inputs still exit 0; only a
8
+ * missing or unwritable `--out` fails.
9
+ */
10
+
11
+ // Must be the first import: fail fast before any third-party import evaluates.
12
+ import './lib/runtime-deps/ensure-installed.js';
13
+ import fs from 'node:fs';
14
+ import path from 'node:path';
15
+ import process from 'node:process';
16
+ import { fileURLToPath } from 'node:url';
17
+ import Ajv from 'ajv';
18
+ import addFormats from 'ajv-formats';
19
+ import {
20
+ DEFAULT_MAX_RECORDS,
21
+ runEngine,
22
+ summarize,
23
+ } from './lib/audit-exceptions/engine.js';
24
+ import { DEFAULT_BLAME_LIMIT } from './lib/audit-exceptions/history.js';
25
+ import { DEFAULT_TICKET_LIMIT } from './lib/audit-exceptions/tickets.js';
26
+ import { defineFlags } from './lib/cli-args.js';
27
+ import { runAsCli } from './lib/cli-utils.js';
28
+
29
+ const SCHEMA_PATH = path.resolve(
30
+ path.dirname(fileURLToPath(import.meta.url)),
31
+ '..',
32
+ 'schemas',
33
+ 'audit-exceptions-envelope.schema.json',
34
+ );
35
+
36
+ const FLAG_SPEC = {
37
+ out: { type: 'string' },
38
+ cwd: { type: 'string' },
39
+ probe: { type: 'boolean' },
40
+ 'changed-since': { type: 'string' },
41
+ 'ticket-limit': { type: 'integer' },
42
+ 'blame-limit': { type: 'integer' },
43
+ 'max-records': { type: 'integer' },
44
+ };
45
+
46
+ let validator;
47
+
48
+ /**
49
+ * Throws on a schema mismatch — a malformed envelope is an engine bug.
50
+ *
51
+ * @param {object} envelope
52
+ * @returns {void}
53
+ */
54
+ export function assertEnvelope(envelope) {
55
+ if (!validator) {
56
+ const ajv = new Ajv({ allErrors: true, strict: false });
57
+ addFormats(ajv);
58
+ validator = ajv.compile(JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8')));
59
+ }
60
+ if (validator(envelope)) return;
61
+ const detail = (validator.errors ?? [])
62
+ .map((e) => `${e.instancePath || '/'} ${e.message}`)
63
+ .join('; ');
64
+ throw new Error(
65
+ `[audit-exceptions] envelope failed schema validation: ${detail}`,
66
+ );
67
+ }
68
+
69
+ /**
70
+ * @param {{ argv?: string[], cwd?: string, stdout?: { write: (s: string) => void },
71
+ * gh?: object, spawn?: Function }} [opts]
72
+ * @returns {Promise<number>} exit code
73
+ */
74
+ export async function runCli({
75
+ argv = process.argv.slice(2),
76
+ cwd = process.cwd(),
77
+ stdout = process.stdout,
78
+ gh,
79
+ spawn,
80
+ } = {}) {
81
+ const { values } = defineFlags(FLAG_SPEC, argv);
82
+ if (!values.out) {
83
+ throw new Error('[audit-exceptions] --out <path> is required');
84
+ }
85
+ const repoRoot = path.resolve(values.cwd ?? cwd);
86
+ const outPath = path.resolve(repoRoot, values.out);
87
+
88
+ const envelope = await runEngine({
89
+ cwd: repoRoot,
90
+ probe: values.probe === true,
91
+ changedSince: values.changedSince ?? null,
92
+ ticketLimit: values.ticketLimit ?? DEFAULT_TICKET_LIMIT,
93
+ blameLimit: values.blameLimit ?? DEFAULT_BLAME_LIMIT,
94
+ maxRecords: values.maxRecords ?? DEFAULT_MAX_RECORDS,
95
+ gh,
96
+ spawn,
97
+ });
98
+ assertEnvelope(envelope);
99
+
100
+ fs.mkdirSync(path.dirname(outPath), { recursive: true });
101
+ fs.writeFileSync(outPath, `${JSON.stringify(envelope, null, 2)}\n`, 'utf8');
102
+
103
+ stdout.write(`${JSON.stringify(summarize(envelope, outPath), null, 2)}\n`);
104
+ return 0;
105
+ }
106
+
107
+ runAsCli(import.meta.url, async () => runCli(), {
108
+ source: 'audit-exceptions',
109
+ propagateExitCode: true,
110
+ errorPrefix: '[audit-exceptions] ❌ Fatal error',
111
+ usage: {
112
+ invocation:
113
+ 'node .agents/scripts/audit-exceptions.js --out <path> [--cwd <dir>] [--probe] [--changed-since <ref>] [--ticket-limit <n>] [--blame-limit <n>] [--max-records <n>]',
114
+ summary:
115
+ 'Read-only exception inventory: find every suppression, dependency pin, patch and allowlist, CI gate exemption, test skip and code allowlist, and mark each dead, expired, orphaned, unjustified, live or unknown.',
116
+ flags: [
117
+ ['--out <path>', 'Write the JSON envelope here (required).'],
118
+ ['--cwd <dir>', 'Repository root to analyse (default: cwd).'],
119
+ [
120
+ '--probe',
121
+ "Also run each installed tool's own unused-suppression report (biome, eslint, tsc, knip).",
122
+ ],
123
+ [
124
+ '--changed-since <ref>',
125
+ 'Mark records on lines added since <ref> as introduced.',
126
+ ],
127
+ [
128
+ '--ticket-limit <n>',
129
+ `Unique cited tickets resolved via gh (default: ${DEFAULT_TICKET_LIMIT}).`,
130
+ ],
131
+ [
132
+ '--blame-limit <n>',
133
+ `Records given an addedAt date via git blame (default: ${DEFAULT_BLAME_LIMIT}).`,
134
+ ],
135
+ [
136
+ '--max-records <n>',
137
+ `Records kept in the envelope; clusters always count all (default: ${DEFAULT_MAX_RECORDS}).`,
138
+ ],
139
+ ],
140
+ notes: [
141
+ "Never edits a file, never runs a tool with a write or fix flag, and never evaluates the analysed repo's code.",
142
+ 'Exit codes:\n 0 evidence assembled (including every degraded input)\n 1 the envelope could not be built or written',
143
+ ],
144
+ },
145
+ });
@@ -0,0 +1,65 @@
1
+ /**
2
+ * CI gate exemptions in GitHub Actions workflows: `continue-on-error: true`
3
+ * (a red job or step that cannot fail the run) and `if: false` (a gate switched
4
+ * off outright). Read line by line so each record carries its real line.
5
+ * `.agentrc.json` `ignoreGlobs` are deliberately not read here — the engine
6
+ * delegates them to `/audit-baselines`, which owns dead ignore globs.
7
+ *
8
+ * @module lib/audit-exceptions/adapters/ci-gates
9
+ */
10
+
11
+ import { readText } from '../read.js';
12
+ import { makeRecord } from '../record.js';
13
+
14
+ const WORKFLOW_RE = /^\.github\/workflows\/[^/]+\.ya?ml$/;
15
+
16
+ const SHAPES = Object.freeze([
17
+ { re: /^\s*-?\s*continue-on-error:\s*true\b/, rule: 'continue-on-error' },
18
+ {
19
+ re: /^\s*-?\s*if:\s*(?:false|\$\{\{\s*false\s*\}\})\s*(?:#|$)/,
20
+ rule: 'if-false',
21
+ },
22
+ ]);
23
+
24
+ function reasonFor(lines, i) {
25
+ const trailing = /#\s*(.*)$/.exec(lines[i])?.[1];
26
+ if (trailing) return trailing;
27
+ const prev = lines[i - 1]?.trim() ?? '';
28
+ return prev.startsWith('#') ? prev.slice(1) : null;
29
+ }
30
+
31
+ function workflowRecords(ctx, file) {
32
+ const lines = (readText(ctx.root, file) ?? '').split('\n');
33
+ const records = [];
34
+ lines.forEach((line, i) => {
35
+ const shape = SHAPES.find((s) => s.re.test(line));
36
+ if (!shape) return;
37
+ records.push(
38
+ makeRecord({
39
+ adapter: 'ci-gates',
40
+ category: 'gate',
41
+ surface: 'github-actions',
42
+ file,
43
+ line: i + 1,
44
+ target: shape.rule,
45
+ rule: shape.rule,
46
+ justification: reasonFor(lines, i),
47
+ probe: { verdict: 'live', basis: 'setting-in-force' },
48
+ }),
49
+ );
50
+ });
51
+ return records;
52
+ }
53
+
54
+ export const ciGates = Object.freeze({
55
+ id: 'ci-gates',
56
+ category: 'gate',
57
+ applies: (ctx) =>
58
+ ctx.scope.files.some((f) => WORKFLOW_RE.test(f))
59
+ ? { applies: true, reason: 'GitHub Actions workflows present' }
60
+ : { applies: false, reason: 'no .github/workflows' },
61
+ extract: (ctx) =>
62
+ ctx.scope.files
63
+ .filter((f) => WORKFLOW_RE.test(f))
64
+ .flatMap((f) => workflowRecords(ctx, f)),
65
+ });