mandrel 2.77.0 → 2.79.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/README.md +6 -1
- package/.agents/agents/auditor.md +2 -3
- package/.agents/audit-checklists/architecture.md +1 -0
- package/.agents/audit-checklists/clean-code.md +1 -0
- package/.agents/audit-checklists/devops.md +4 -1
- package/.agents/audit-checklists/security.md +1 -1
- package/.agents/docs/configuration.md +1 -1
- package/.agents/schemas/agentrc.schema.json +1 -1
- package/.agents/scripts/bootstrap.js +87 -16
- package/.agents/scripts/lib/audit-to-stories/build-story-body.js +48 -14
- package/.agents/scripts/lib/audit-to-stories/finding-bullets.js +33 -0
- package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js +6 -4
- package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +34 -19
- package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
- package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
- package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
- package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
- package/.agents/scripts/lib/close-validation/commands.js +33 -0
- package/.agents/scripts/lib/close-validation/gates.js +11 -4
- package/.agents/scripts/lib/config/explain.js +2 -1
- package/.agents/scripts/lib/config-settings-schema.js +2 -1
- package/.agents/scripts/lib/findings/severity.js +33 -6
- package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
- package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
- package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
- package/.agents/scripts/lib/test-run-credit.js +46 -17
- package/.agents/workflows/audit-architecture.md +20 -4
- package/.agents/workflows/audit-baselines.md +3 -3
- package/.agents/workflows/audit-clean-code.md +17 -1
- package/.agents/workflows/audit-devops.md +58 -14
- package/.agents/workflows/audit-exceptions.md +3 -2
- package/.agents/workflows/audit-performance.md +22 -0
- package/.agents/workflows/audit-quality.md +30 -0
- package/.agents/workflows/audit-security.md +23 -8
- package/.agents/workflows/audit-to-stories.md +9 -6
- package/.agents/workflows/helpers/audit-lens-core.md +53 -8
- package/README.md +13 -1
- package/docs/CHANGELOG.md +22 -0
- package/lib/cli/registry.js +85 -12
- package/lib/cli/uninstall.js +34 -18
- package/lib/cli/update.js +37 -6
- package/lib/migrations/index.js +2 -0
- package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
- package/package.json +1 -1
|
@@ -23,7 +23,10 @@ import path from 'node:path';
|
|
|
23
23
|
import { fileURLToPath } from 'node:url';
|
|
24
24
|
|
|
25
25
|
import { spawnCaptureAsync } from '../child-exec.js';
|
|
26
|
-
import {
|
|
26
|
+
import {
|
|
27
|
+
resolveLintCommand,
|
|
28
|
+
resolveTestGateArgv,
|
|
29
|
+
} from '../close-validation/commands.js';
|
|
27
30
|
import {
|
|
28
31
|
isCrapGateEnabled,
|
|
29
32
|
resolveCreditedDepositor,
|
|
@@ -331,6 +334,15 @@ function selectCreditedDepositor({ config, ...probe }) {
|
|
|
331
334
|
return resolveCreditedDepositor({ config, baseBranch, ...probe });
|
|
332
335
|
}
|
|
333
336
|
|
|
337
|
+
/**
|
|
338
|
+
* @param {object|null|undefined} config
|
|
339
|
+
* @returns {string[]}
|
|
340
|
+
*/
|
|
341
|
+
function testGateArgv(config) {
|
|
342
|
+
const { cmd, args } = resolveTestGateArgv(config);
|
|
343
|
+
return [cmd, ...args];
|
|
344
|
+
}
|
|
345
|
+
|
|
334
346
|
/** @param {object} ctx @returns {Promise<StepResult>} */
|
|
335
347
|
async function stepCreditedRun(ctx) {
|
|
336
348
|
const name = 'credited-run';
|
|
@@ -358,8 +370,8 @@ async function stepCreditedRun(ctx) {
|
|
|
358
370
|
'--worktree',
|
|
359
371
|
ctx.cwd,
|
|
360
372
|
'--',
|
|
361
|
-
'
|
|
362
|
-
|
|
373
|
+
// Close's `test` gate argv, so the deposit keys on its credit identity.
|
|
374
|
+
...testGateArgv(ctx.config),
|
|
363
375
|
]);
|
|
364
376
|
const extra = { evidencePath: run.evidencePath, depositor: ctx.depositor };
|
|
365
377
|
if (run.status !== 0) {
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* manufactures a pass.
|
|
6
6
|
*/
|
|
7
7
|
|
|
8
|
+
import { resolveTestGateArgv } from '../close-validation/commands.js';
|
|
8
9
|
import { getQuality, resolveConfig } from '../config-resolver.js';
|
|
9
10
|
import { isCoverageFresh } from '../coverage-capture.js';
|
|
10
11
|
import { gitSpawn } from '../git-utils.js';
|
|
@@ -134,7 +135,8 @@ export function resolveVerifyCredit(
|
|
|
134
135
|
fullSuite: true,
|
|
135
136
|
warning: FULL_SUITE_SHAPE_WARNING,
|
|
136
137
|
};
|
|
137
|
-
const
|
|
138
|
+
const config = resolveConfigImpl({ cwd: worktree });
|
|
139
|
+
const { crap } = getQualityImpl(config);
|
|
138
140
|
const mode =
|
|
139
141
|
crap?.enabled !== false &&
|
|
140
142
|
hasNpmScriptImpl(readPackageScriptsImpl(worktree), 'test:coverage')
|
|
@@ -163,6 +165,7 @@ export function resolveVerifyCredit(
|
|
|
163
165
|
// A stale stamp is not the last word: a green `npm test` deposits `test`
|
|
164
166
|
// evidence, consulted in both modes before spawning.
|
|
165
167
|
const verdict = readTestEvidence({
|
|
168
|
+
config,
|
|
166
169
|
storyId,
|
|
167
170
|
worktree,
|
|
168
171
|
cwd,
|
|
@@ -184,10 +187,13 @@ export function resolveVerifyCredit(
|
|
|
184
187
|
/**
|
|
185
188
|
* An unreadable HEAD is `no-head`, never a credit.
|
|
186
189
|
*
|
|
187
|
-
*
|
|
190
|
+
* The hashed argv is close's `test` gate argv (`project.commands.test`).
|
|
191
|
+
*
|
|
192
|
+
* @param {{ config: object|null, storyId: number|string, worktree: string, cwd: string, gitSpawnFn: Function, shouldSkipImpl: Function, hashCommandConfigImpl: Function, treeFingerprintImpl: Function }} args
|
|
188
193
|
* @returns {{ skip: boolean, reason: string }}
|
|
189
194
|
*/
|
|
190
195
|
function readTestEvidence({
|
|
196
|
+
config,
|
|
191
197
|
storyId,
|
|
192
198
|
worktree,
|
|
193
199
|
cwd,
|
|
@@ -204,8 +210,7 @@ function readTestEvidence({
|
|
|
204
210
|
gateName: 'test',
|
|
205
211
|
currentSha: headSha,
|
|
206
212
|
configHash: hashCommandConfigImpl({
|
|
207
|
-
|
|
208
|
-
args: ['test'],
|
|
213
|
+
...resolveTestGateArgv(config),
|
|
209
214
|
cwd: worktree,
|
|
210
215
|
}),
|
|
211
216
|
inputFingerprint: treeFingerprintImpl(worktree, gitSpawnFn),
|
|
@@ -9,6 +9,11 @@
|
|
|
9
9
|
|
|
10
10
|
import path from 'node:path';
|
|
11
11
|
|
|
12
|
+
import {
|
|
13
|
+
resolveTestCommand,
|
|
14
|
+
resolveTestGateArgv,
|
|
15
|
+
} from './close-validation/commands.js';
|
|
16
|
+
import { resolveConfig } from './config-resolver.js';
|
|
12
17
|
import { gitSpawn as defaultGitSpawn } from './git-utils.js';
|
|
13
18
|
import {
|
|
14
19
|
recordPass as defaultRecordPass,
|
|
@@ -19,11 +24,36 @@ import {
|
|
|
19
24
|
|
|
20
25
|
const GATE_NAME = 'test';
|
|
21
26
|
|
|
22
|
-
/**
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
+
/**
|
|
28
|
+
* The `test` credit identity. It must hash identically to the argv close
|
|
29
|
+
* spawns, so both derive from {@link resolveTestGateArgv}
|
|
30
|
+
* (`project.commands.test`, default `npm test`).
|
|
31
|
+
*
|
|
32
|
+
* @param {object|null|undefined} config - Resolved config; null → the default.
|
|
33
|
+
* @param {string} cwd
|
|
34
|
+
* @returns {string}
|
|
35
|
+
*/
|
|
36
|
+
function testGateConfigHash(config, cwd) {
|
|
37
|
+
const { cmd, args } = resolveTestGateArgv(config);
|
|
38
|
+
return hashCommandConfig({ cmd, args, cwd: path.resolve(cwd) });
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* The injected config, else the checkout's resolved config, or null (→ the
|
|
43
|
+
* `npm test` default) when it cannot be read — a deposit never fails the run.
|
|
44
|
+
*
|
|
45
|
+
* @param {object|null|undefined} config
|
|
46
|
+
* @param {string} cwd
|
|
47
|
+
* @returns {object|null}
|
|
48
|
+
*/
|
|
49
|
+
function depositConfig(config, cwd) {
|
|
50
|
+
if (config !== undefined) return config;
|
|
51
|
+
try {
|
|
52
|
+
return resolveConfig({ cwd });
|
|
53
|
+
} catch {
|
|
54
|
+
return null;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
27
57
|
|
|
28
58
|
/**
|
|
29
59
|
* @param {Function} gitSpawnFn
|
|
@@ -73,9 +103,11 @@ export function resolveEvidenceRoot(cwd, gitSpawnFn) {
|
|
|
73
103
|
* tier?: string,
|
|
74
104
|
* status?: number,
|
|
75
105
|
* durationMs?: number|null,
|
|
106
|
+
* config?: object|null,
|
|
76
107
|
* gitSpawnFn?: typeof defaultGitSpawn,
|
|
77
108
|
* recordPassFn?: typeof defaultRecordPass,
|
|
78
109
|
* }} args
|
|
110
|
+
* `config` defaults to the checkout's resolved config.
|
|
79
111
|
* @returns {{ deposited: boolean, reason: string, storyId?: number, sha?: string }}
|
|
80
112
|
*/
|
|
81
113
|
export function depositTestRunCredit({
|
|
@@ -83,6 +115,7 @@ export function depositTestRunCredit({
|
|
|
83
115
|
tier = 'full',
|
|
84
116
|
status = 0,
|
|
85
117
|
durationMs = null,
|
|
118
|
+
config,
|
|
86
119
|
gitSpawnFn = defaultGitSpawn,
|
|
87
120
|
recordPassFn = defaultRecordPass,
|
|
88
121
|
} = {}) {
|
|
@@ -102,6 +135,7 @@ export function depositTestRunCredit({
|
|
|
102
135
|
storyId,
|
|
103
136
|
sha,
|
|
104
137
|
cwd,
|
|
138
|
+
config: depositConfig(config, cwd),
|
|
105
139
|
evidenceRoot,
|
|
106
140
|
durationMs,
|
|
107
141
|
gitSpawnFn,
|
|
@@ -134,6 +168,7 @@ export function reportTestRunCredit({
|
|
|
134
168
|
* Every uncertainty resolves `false`.
|
|
135
169
|
*
|
|
136
170
|
* @param {{
|
|
171
|
+
* config?: object|null,
|
|
137
172
|
* storyId?: number|null,
|
|
138
173
|
* cwd?: string,
|
|
139
174
|
* evidenceCwd?: string|null,
|
|
@@ -144,6 +179,7 @@ export function reportTestRunCredit({
|
|
|
144
179
|
* @returns {boolean}
|
|
145
180
|
*/
|
|
146
181
|
export function predictsTestEvidenceCredit({
|
|
182
|
+
config,
|
|
147
183
|
storyId,
|
|
148
184
|
cwd,
|
|
149
185
|
evidenceCwd,
|
|
@@ -161,18 +197,14 @@ export function predictsTestEvidenceCredit({
|
|
|
161
197
|
storyId,
|
|
162
198
|
gateName: GATE_NAME,
|
|
163
199
|
currentSha: sha,
|
|
164
|
-
configHash:
|
|
165
|
-
cmd: GATE_COMMAND.cmd,
|
|
166
|
-
args: [...GATE_COMMAND.args],
|
|
167
|
-
cwd: path.resolve(cwd),
|
|
168
|
-
}),
|
|
200
|
+
configHash: testGateConfigHash(config, cwd),
|
|
169
201
|
inputFingerprint: treeFingerprint(cwd, gitSpawnImpl),
|
|
170
202
|
},
|
|
171
203
|
{ cwd: evidenceCwd ?? cwd, standalone: true },
|
|
172
204
|
);
|
|
173
205
|
if (verdict.skip !== true) return false;
|
|
174
206
|
log?.(
|
|
175
|
-
|
|
207
|
+
`[close-validation] a green \`${resolveTestCommand(config)}\` already deposited the test credit for this tree — registering the plain \`test\` gate so close reports it as credited.`,
|
|
176
208
|
);
|
|
177
209
|
return true;
|
|
178
210
|
} catch {
|
|
@@ -181,13 +213,14 @@ export function predictsTestEvidenceCredit({
|
|
|
181
213
|
}
|
|
182
214
|
|
|
183
215
|
/**
|
|
184
|
-
* @param {{ storyId: number, sha: string, cwd: string, evidenceRoot: string, durationMs: number|null, gitSpawnFn: Function, recordPassFn: Function }} args
|
|
216
|
+
* @param {{ storyId: number, sha: string, cwd: string, config: object|null, evidenceRoot: string, durationMs: number|null, gitSpawnFn: Function, recordPassFn: Function }} args
|
|
185
217
|
* @returns {{ deposited: boolean, reason: string, storyId: number, sha: string }}
|
|
186
218
|
*/
|
|
187
219
|
function writeRecord({
|
|
188
220
|
storyId,
|
|
189
221
|
sha,
|
|
190
222
|
cwd,
|
|
223
|
+
config,
|
|
191
224
|
evidenceRoot,
|
|
192
225
|
durationMs,
|
|
193
226
|
gitSpawnFn,
|
|
@@ -199,11 +232,7 @@ function writeRecord({
|
|
|
199
232
|
storyId,
|
|
200
233
|
gateName: GATE_NAME,
|
|
201
234
|
sha,
|
|
202
|
-
configHash:
|
|
203
|
-
cmd: GATE_COMMAND.cmd,
|
|
204
|
-
args: [...GATE_COMMAND.args],
|
|
205
|
-
cwd: path.resolve(cwd),
|
|
206
|
-
}),
|
|
235
|
+
configHash: testGateConfigHash(config, cwd),
|
|
207
236
|
exitCode: 0,
|
|
208
237
|
durationMs,
|
|
209
238
|
inputFingerprint: treeFingerprint(cwd, gitSpawnFn),
|
|
@@ -75,14 +75,30 @@ the failure mode this lens exists to prevent.
|
|
|
75
75
|
that is both heavily depended upon and frequently churned is the
|
|
76
76
|
highest-priority structural hotspot; lead the Triage Summary with it.
|
|
77
77
|
|
|
78
|
-
4. **
|
|
78
|
+
4. **Non-JS ecosystems.** Detect ecosystems per the core's
|
|
79
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and
|
|
80
|
+
run each detected one's rung (absent scanner = Low `Standardization` gap;
|
|
81
|
+
undetected ecosystem = inapplicable, never a finding). **Python:**
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
pydeps <package> --show-cycles --no-output # import graph / cycles
|
|
85
|
+
lint-imports # import-linter layer contracts
|
|
86
|
+
vulture <srcDir> # dead-export / dead-wiring candidates
|
|
87
|
+
radon cc -s -n C <srcDir> # testable surface: complex units to check for interleaved I/O
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Rank Python hotspots by fan-in / fan-out from the `pydeps` graph exactly as
|
|
91
|
+
step 3 does. Go and Rust use the core's fallback table.
|
|
92
|
+
|
|
93
|
+
5. **LLM triage on top.** Only after the tools have run do you apply the Step 2
|
|
79
94
|
dimensions to interpret, rank, and phrase the findings. A structural claim
|
|
80
95
|
that no tool grounds and no Step 2 dimension covers does not belong in this
|
|
81
96
|
report — route it to the ceded clean-code dimensions instead.
|
|
82
97
|
|
|
83
|
-
When a
|
|
84
|
-
**Automated Architecture Guardrails** finding (the
|
|
85
|
-
broken) rather than skipping the step silently.
|
|
98
|
+
When a checker for a **detected** ecosystem exits non-zero or is genuinely
|
|
99
|
+
absent, record that as an **Automated Architecture Guardrails** finding (the
|
|
100
|
+
guardrail is missing or broken) rather than skipping the step silently. A
|
|
101
|
+
checker for an undetected ecosystem is inapplicable and never a finding.
|
|
86
102
|
|
|
87
103
|
## Step 1: Context Gathering (Read-Only Scan)
|
|
88
104
|
|
|
@@ -124,7 +124,7 @@ Two envelope-level reads come **before** any finding:
|
|
|
124
124
|
stale beyond roughly a month or `surfaceStale` **Medium**, a `null` stamp
|
|
125
125
|
**Medium**, an unenforced kind **Low** or **Info**.
|
|
126
126
|
|
|
127
|
-
**Regeneration is the remediation, never an in-run step.** The
|
|
127
|
+
**Regeneration is the remediation, never an in-run step.** The Recommendation
|
|
128
128
|
names the matching script and its one-shot acknowledgment:
|
|
129
129
|
|
|
130
130
|
| Kind | Regeneration script | Acknowledgment |
|
|
@@ -211,7 +211,7 @@ Executive Summary and change it only on an explicit operator instruction.
|
|
|
211
211
|
A remediation Story that only burns debt down leaves the floor where it was,
|
|
212
212
|
and the reclaimed slack is silently re-spent by the next change — the loop
|
|
213
213
|
runs and the ratchet never moves. So **every Hotspot Cluster and Tightening
|
|
214
|
-
Headroom finding's
|
|
214
|
+
Headroom finding's Recommendation MUST** end the remediation with the ratchet
|
|
215
215
|
tightened and gate-enforced:
|
|
216
216
|
|
|
217
217
|
1. Lower the floor under `delivery.quality.gates` in `.agentrc.json` to the
|
|
@@ -222,7 +222,7 @@ tightened and gate-enforced:
|
|
|
222
222
|
gate that already exists at that Story's delivery time rather than by prose
|
|
223
223
|
nobody runs.
|
|
224
224
|
|
|
225
|
-
Use these two
|
|
225
|
+
Use these two Recommendation templates verbatim, substituting the envelope's own
|
|
226
226
|
values for the angle-bracketed slots:
|
|
227
227
|
|
|
228
228
|
- **Hotspot Cluster template:**
|
|
@@ -81,7 +81,23 @@ run the tools first.
|
|
|
81
81
|
files auto-loaded by convention (globbed listener/plugin dirs): reachable
|
|
82
82
|
via the framework, not the import graph.
|
|
83
83
|
|
|
84
|
-
5. **
|
|
84
|
+
5. **Non-JS ecosystems.** Detect ecosystems per the core's
|
|
85
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and
|
|
86
|
+
run each detected one's rung (absent scanner = Low `Standardization` gap;
|
|
87
|
+
undetected ecosystem = inapplicable, never a finding). **Python:**
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
radon cc -s -a <srcDir> && radon mi -s <srcDir> # complexity / MI
|
|
91
|
+
pylint --disable=all --enable=duplicate-code <srcDir> # duplication (or jscpd)
|
|
92
|
+
vulture <srcDir> # dead code
|
|
93
|
+
ruff check --select E722,BLE,S110,N <srcDir> # silent failures, naming
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Apply the dead-code exclusion taxonomy above to `vulture` output too
|
|
97
|
+
(entry points, `__all__` exports, decorator-registered hooks). Go and Rust
|
|
98
|
+
use the core's fallback table.
|
|
99
|
+
|
|
100
|
+
6. **Churn-by-complexity hotspot cap.** Rank candidate hotspots by
|
|
85
101
|
**churn × complexity** (frequently-changed files that also score poorly on
|
|
86
102
|
MI/CRAP) and **cap the Detailed Findings at the top ~15 hotspots** so the
|
|
87
103
|
report stays a ranked, actionable batch rather than an exhaustive dump. Note
|
|
@@ -27,13 +27,19 @@ Execution strategy.
|
|
|
27
27
|
## Step 1: Detection Battery (Read-Only, Tool-First)
|
|
28
28
|
|
|
29
29
|
Do **not** audit CI/CD from memory. Run the deterministic battery below first
|
|
30
|
-
and let its output ground every finding.
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
30
|
+
and let its output ground every finding. Detect the CI systems and language
|
|
31
|
+
ecosystems first per the core's
|
|
32
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and run
|
|
33
|
+
only the rungs for what is detected. Each tool is **presence-gated**: when the
|
|
34
|
+
binary for a **detected** surface is absent, record the gap as a Low-severity
|
|
35
|
+
`Standardization` finding (recommend adopting the scanner) and continue — a
|
|
36
|
+
missing scanner degrades the audit gracefully, it never aborts it. A tool for
|
|
37
|
+
an **undetected** surface is inapplicable and never a finding — `actionlint`,
|
|
38
|
+
`zizmor` and `gh run list` on a repo with no `.github/workflows/` are skipped,
|
|
39
|
+
not reported missing.
|
|
40
|
+
|
|
41
|
+
1. **Workflow static analysis (`actionlint`, GitHub Actions only).** When
|
|
42
|
+
`.github/workflows/` contains any `*.yml` / `*.yaml`, run:
|
|
37
43
|
|
|
38
44
|
```bash
|
|
39
45
|
command -v actionlint >/dev/null 2>&1 && actionlint -color=never || \
|
|
@@ -76,11 +82,49 @@ degrades the audit gracefully, it never aborts it.
|
|
|
76
82
|
or whose p95 duration is an outlier is a Reliability or Performance finding
|
|
77
83
|
with the observed number cited in **Current State**.
|
|
78
84
|
|
|
85
|
+
5. **Google Cloud Build (gated: `cloudbuild*.yaml` present).** Read each
|
|
86
|
+
definition for unpinned builder images (`gcr.io/cloud-builders/*` without a
|
|
87
|
+
digest/tag), secrets passed as plain `env` instead of `secretEnv` /
|
|
88
|
+
`availableSecrets`, an over-broad build service account, and missing
|
|
89
|
+
`timeout`. Then pull run history the same way step 4 does:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
gcloud builds list --limit 50 --format=json 2>/dev/null || \
|
|
93
|
+
echo "gcloud build history unavailable — Cloud Build findings degrade to config-only reasoning"
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Compute failure rate (`FAILURE` + `TIMEOUT` + `CANCELLED` / total) and
|
|
97
|
+
p50/p95 duration (`finishTime − startTime`) per trigger.
|
|
98
|
+
|
|
99
|
+
6. **GitLab CI (gated: `.gitlab-ci.yml` present).** Validate the definition
|
|
100
|
+
and read it for unpinned `image:` tags, `variables:` carrying secrets,
|
|
101
|
+
missing `rules:` / `interruptible:`, and absent `cache:` keys:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
glab ci lint 2>/dev/null || echo "glab: not installed — recommend adding it (Standardization gap)"
|
|
105
|
+
glab ci list --per-page 50 -F json 2>/dev/null || \
|
|
106
|
+
echo "glab pipeline history unavailable — GitLab findings degrade to config-only reasoning"
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Compute failure rate and p50/p95 duration per pipeline as in step 4.
|
|
110
|
+
Azure Pipelines (`azure-pipelines.yml`) is read config-only, with
|
|
111
|
+
`az pipelines runs list` as its history source when the CLI is present.
|
|
112
|
+
|
|
113
|
+
7. **Python toolchain (gated: Python manifests present).** Read the build and
|
|
114
|
+
lint configuration the Python manifests declare — `pyproject.toml`
|
|
115
|
+
(`[build-system]`, `[tool.ruff]`, `[tool.mypy]`, `[tool.pytest.ini_options]`),
|
|
116
|
+
`.pre-commit-config.yaml`, a lockfile (`uv.lock`, `poetry.lock`,
|
|
117
|
+
`requirements*.txt` with hashes) — and check that CI runs the linters and
|
|
118
|
+
type-checker the config declares. Validate with
|
|
119
|
+
`pre-commit validate-config` and `ruff check --statistics` where present.
|
|
120
|
+
|
|
79
121
|
Then read the surfaces the battery flags plus the standing config set:
|
|
80
|
-
CI/CD pipelines (`.github/workflows/`, `.gitlab-ci.yml`,
|
|
81
|
-
dependency/script manifests (`package.json`,
|
|
82
|
-
|
|
83
|
-
|
|
122
|
+
CI/CD pipelines (`.github/workflows/`, `cloudbuild*.yaml`, `.gitlab-ci.yml`,
|
|
123
|
+
`azure-pipelines.yml`), dependency/script manifests (`package.json`,
|
|
124
|
+
`pnpm-workspace.yaml`, `pyproject.toml`, `requirements*.txt`), lint/format
|
|
125
|
+
configs (`.eslintrc*`, `.prettierrc*`, `biome.json`, `tsconfig.json`,
|
|
126
|
+
`ruff.toml`, `.pre-commit-config.yaml`), and git hooks / commit standards
|
|
127
|
+
(`.husky/`, `commitlint.config.js`).
|
|
84
128
|
|
|
85
129
|
## Step 2: Analysis Dimensions
|
|
86
130
|
|
|
@@ -92,8 +136,8 @@ when absent, state "not present in scope" and skip.
|
|
|
92
136
|
1. **Redundancy & Duplication:** Overlapping tools or conflicting rules (e.g.,
|
|
93
137
|
Prettier vs. ESLint formatting, duplicated scripts in `package.json` and CI).
|
|
94
138
|
2. **Performance Gaps:** Bottlenecks in CI/CD, slow caching strategies, or
|
|
95
|
-
unoptimized hooks (e.g., missing `lint-staged`) — cite the
|
|
96
|
-
durations from Step 1.
|
|
139
|
+
unoptimized hooks (e.g., missing `lint-staged`) — cite the run-history
|
|
140
|
+
durations from Step 1 (`gh run list`, `gcloud builds list`, `glab ci list`).
|
|
97
141
|
3. **Security & Compliance:** Missing secret scanning, loose permissions (e.g.,
|
|
98
142
|
`GITHUB_TOKEN` scopes), outdated or vulnerable dependency resolution
|
|
99
143
|
strategies — grounded in the `zizmor` output.
|
|
@@ -103,7 +147,7 @@ when absent, state "not present in scope" and skip.
|
|
|
103
147
|
surfaced in Step 1.
|
|
104
148
|
5. **Reliability & Resilience:** Fragile pipeline steps, missing error handling,
|
|
105
149
|
silent failures, or lack of retries for network-dependent tasks — cite the
|
|
106
|
-
|
|
150
|
+
run-history failure rates from Step 1 for every detected CI system.
|
|
107
151
|
|
|
108
152
|
### Sub-step A — Dockerfile hardening (gated: `Dockerfile*` present)
|
|
109
153
|
|
|
@@ -184,9 +184,10 @@ When a Fix Properly finding's real remediation belongs to one of those
|
|
|
184
184
|
lenses, say so in the Recommendation and name the lens rather than
|
|
185
185
|
re-auditing its domain here.
|
|
186
186
|
|
|
187
|
-
## Step 4:
|
|
187
|
+
## Step 4: Recommendation templates
|
|
188
188
|
|
|
189
|
-
|
|
189
|
+
Write each finding's **Recommendation & Rationale** from the matching template,
|
|
190
|
+
substituting the envelope's own values for the angle-bracketed slots:
|
|
190
191
|
|
|
191
192
|
- **Dead bundle template:**
|
|
192
193
|
`Remove the <adapter> exceptions the audit-exceptions engine proved dead: <file:line list>. Each one exempts nothing (<verdictBasis>). Delete each entry, then re-run node .agents/scripts/audit-exceptions.js --out temp/audit-exceptions/envelope.json and confirm none of them reappears. For a dependency pin or patch, reinstall and confirm the lockfile resolves the same versions without it, and run the project's audit command to confirm no advisory returns.`
|
|
@@ -75,6 +75,28 @@ npx vite build --profile # or the repo's own build script
|
|
|
75
75
|
du -sh dist/ && find dist -name '*.js' -exec wc -c {} + | sort -n | tail
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
+
**Non-JS ecosystems.** Detect ecosystems per the core's
|
|
79
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection) and run
|
|
80
|
+
each detected one's rung (absent profiler = Low `Standardization` gap;
|
|
81
|
+
undetected ecosystem = inapplicable, never a finding). **Python** — timing,
|
|
82
|
+
CPU, memory, and interleaving:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
hyperfine --warmup 1 'python -m <entry> --help' # timing / cold start
|
|
86
|
+
python -X importtime -m <entry> --help 2>&1 | sort -t'|' -k2 -n | tail # import cost
|
|
87
|
+
py-spy record -o temp/audits/pyspy.svg -- python -m <entry> <args> # CPU (sampling)
|
|
88
|
+
python -m cProfile -s cumtime -m <entry> <args> | head -40 # CPU (fallback)
|
|
89
|
+
python -X tracemalloc=5 -m <entry> <args> # memory: tracemalloc snapshot diff (or memray run)
|
|
90
|
+
python -X dev -W error::RuntimeWarning -m <entry> <args> # interleaving: "coroutine was never awaited"
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
`py-spy` / `cProfile` hot frames are the Python counterpart of `--cpu-prof`;
|
|
94
|
+
an asyncio "never awaited" warning under `-X dev` is `measured` evidence for
|
|
95
|
+
the interleaving dimension; I/O is read off the same profile (frames in
|
|
96
|
+
`socket` / `ssl` / DB-driver calls) or `strace -c -f`. Payload/bundle stays
|
|
97
|
+
web-gated — a Python web app's shipped frontend is measured by the JS rung.
|
|
98
|
+
Go and Rust use the core's fallback table.
|
|
99
|
+
|
|
78
100
|
**Evidence discipline.** A finding tagged `measured` names the command above
|
|
79
101
|
whose output produced its number. A finding tagged `estimated` (e.g. a
|
|
80
102
|
Big-O argument read off the code without a runnable repro) says so plainly and
|
|
@@ -54,6 +54,36 @@ already compute and commit, rather than prose-scanning the tests:
|
|
|
54
54
|
- `baselines/mutation.json` — mutation-testing survivors where present: tests
|
|
55
55
|
that execute code without asserting on it (coverage without confidence).
|
|
56
56
|
|
|
57
|
+
**When `baselines/*.json` do not exist** (a consumer that does not run
|
|
58
|
+
Mandrel's baseline gates, or a non-JS repo), measure from the ecosystem's own
|
|
59
|
+
tools instead of reporting the missing baseline. Detect ecosystems per the
|
|
60
|
+
core's [Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection)
|
|
61
|
+
(absent scanner = Low `Standardization` gap; undetected ecosystem =
|
|
62
|
+
inapplicable, never a finding). **Python:**
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
coverage report -m # coverage.py, read an existing .coverage file
|
|
66
|
+
coverage json -o - # per-file covered ratio (or coverage.xml from pytest-cov)
|
|
67
|
+
radon cc -s <srcDir> # complexity, to pair with coverage as a CRAP proxy
|
|
68
|
+
mutmut results # mutation survivors, when a mutmut cache exists
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Read an existing `.coverage` / `coverage.xml` / `htmlcov/` artifact; do not run
|
|
72
|
+
`pytest --cov` yourself (the Constraint below forbids suite runs). With no
|
|
73
|
+
coverage artifact at all, record that as a `Coverage` finding — the repo
|
|
74
|
+
publishes no coverage signal. The other Python dimensions read non-running
|
|
75
|
+
instruments:
|
|
76
|
+
|
|
77
|
+
| Dimension | Python instrument |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| Flakiness | `.pytest_cache/v/cache/lastfailed`, `@pytest.mark.flaky` / `pytest-rerunfailures` markers, `time.sleep` in tests |
|
|
80
|
+
| Mocking | `unittest.mock` / `monkeypatch` / `responses` usage density per test file |
|
|
81
|
+
| Test data | `conftest.py` fixture scopes (`scope="session"` shared mutable state) |
|
|
82
|
+
| Performance & execution | `pytest --collect-only -q` (count by tier), `<testcase time=…>` in an existing JUnit XML, `pytest-xdist` presence |
|
|
83
|
+
| Property-based | `hypothesis` in the manifests (dimension 8) |
|
|
84
|
+
|
|
85
|
+
Go and Rust use the core's fallback table.
|
|
86
|
+
|
|
57
87
|
**Rank churn-by-coverage.** Order candidate findings by **churn × coverage
|
|
58
88
|
gap** — frequently-changed files (`git log --format= --name-only -n 200 | sort
|
|
59
89
|
| uniq -c | sort -rn`) that also score low coverage / high CRAP are the
|
|
@@ -41,20 +41,31 @@ baseline is silent — is out of scope for this lens.
|
|
|
41
41
|
## Step 1: Detection Battery (Tool-First, Read-Only)
|
|
42
42
|
|
|
43
43
|
Ground every finding in tool output, not vibes. Run the ladder below; each rung
|
|
44
|
-
is **presence-gated**
|
|
45
|
-
|
|
46
|
-
|
|
44
|
+
is **presence-gated** and **ecosystem-gated** per the core's
|
|
45
|
+
[Ecosystem detection](helpers/audit-lens-core.md#ecosystem-detection): when a
|
|
46
|
+
scanner for a detected ecosystem is absent, fall through to the next rung and
|
|
47
|
+
note the missing tool as a `Security Misconfiguration` finding (recommend
|
|
48
|
+
adopting it); a scanner for an undetected ecosystem is inapplicable and never a
|
|
49
|
+
finding.
|
|
47
50
|
|
|
48
|
-
1. **Dependency CVEs
|
|
51
|
+
1. **Dependency CVEs, per detected ecosystem.** Never recall CVEs from memory:
|
|
49
52
|
|
|
50
53
|
```bash
|
|
51
|
-
npm audit --omit=dev --json 2>/dev/null || echo "npm audit unavailable"
|
|
54
|
+
npm audit --omit=dev --json 2>/dev/null || echo "npm audit unavailable" # JS
|
|
55
|
+
pip-audit -r requirements.txt --format json # Python (or bare `pip-audit` in the venv)
|
|
56
|
+
govulncheck ./... # Go
|
|
57
|
+
cargo audit --json # Rust
|
|
52
58
|
```
|
|
53
59
|
|
|
54
|
-
Each advisory reachable in production (`--omit=dev
|
|
55
|
-
|
|
60
|
+
Each advisory reachable in production (`--omit=dev`; for Python, the
|
|
61
|
+
runtime requirements, not dev extras) at `high` or `critical` is a
|
|
62
|
+
_Vulnerable Components_ finding citing the advisory id and the violated
|
|
56
63
|
_Dependency Hygiene_ MUST.
|
|
57
64
|
|
|
65
|
+
**Python static analysis.** On a detected Python ecosystem also run
|
|
66
|
+
`bandit -r <srcDir> -f json` for injection / `eval` / `subprocess(shell=True)`
|
|
67
|
+
/ weak-crypto sinks — the Python counterpart of the grep battery below.
|
|
68
|
+
|
|
58
69
|
2. **Secret scanning (`gitleaks` / `trufflehog`), with a grep fallback.** When
|
|
59
70
|
`gitleaks` is installed, prefer it:
|
|
60
71
|
|
|
@@ -76,13 +87,17 @@ adopting it).
|
|
|
76
87
|
rg -n "(SELECT|INSERT|UPDATE|DELETE)\b[^;]*\$\{" -i
|
|
77
88
|
# Committed .env with real values (violates Secrets Management)
|
|
78
89
|
git ls-files | rg "(^|/)\.env($|\.)" | rg -v "\.env\.example$"
|
|
90
|
+
# Python sinks (detected Python only): shell exec, unsafe deserialization, f-string SQL
|
|
91
|
+
rg -n "shell=True|pickle\.loads?\(|yaml\.load\(|\.execute\(f['\"]" --type py
|
|
79
92
|
```
|
|
80
93
|
|
|
81
94
|
4. **Manual surface review.** Then read the surfaces the battery flags plus:
|
|
82
95
|
input-validation edges (API endpoints, form handlers — is input validated at
|
|
83
96
|
the boundary with a strict schema?), auth/session handling (token storage,
|
|
84
97
|
missing ownership checks on sensitive routes), and injection sinks
|
|
85
|
-
(`dangerouslySetInnerHTML`, raw SQL, command execution).
|
|
98
|
+
(`dangerouslySetInnerHTML`, raw SQL, command execution). On Python, read
|
|
99
|
+
the route decorators (Django views / DRF `permission_classes`, Flask /
|
|
100
|
+
FastAPI routes and `Depends` guards) for missing ownership checks.
|
|
86
101
|
|
|
87
102
|
## Step 2: Evaluation Dimensions
|
|
88
103
|
|
|
@@ -17,7 +17,8 @@ Engineering Lead
|
|
|
17
17
|
The `audit-*` workflows each produce a structured `audit-<dimension>-results.md`
|
|
18
18
|
report under `temp/audits/`. Every `### Finding` block in those reports
|
|
19
19
|
already carries the fields a Story body needs (Severity / Impact,
|
|
20
|
-
Dimension / Category, Current State, Recommendation,
|
|
20
|
+
Dimension / Category, Location, Current State, Recommendation, Acceptance
|
|
21
|
+
signal).
|
|
21
22
|
|
|
22
23
|
The audit producers themselves are **not modified** by this workflow.
|
|
23
24
|
They remain read-only emitters of audit reports.
|
|
@@ -143,9 +144,11 @@ node .agents/scripts/audit-to-stories.js --emit-plan-seed \
|
|
|
143
144
|
```
|
|
144
145
|
|
|
145
146
|
The seed renders the canonical one-pager sections — Problem Statement,
|
|
146
|
-
Recommended Direction
|
|
147
|
-
report), MVP Scope (**the findings,
|
|
148
|
-
|
|
147
|
+
Recommended Direction (a finding count and severity breakdown per dimension),
|
|
148
|
+
Key Assumptions (with links to every source report), MVP Scope (**the findings,
|
|
149
|
+
flat**, worst first, each with its Location, Recommendation and Acceptance
|
|
150
|
+
signal nested under it), Key Files (so `/mandrel-plan`'s authoring step has
|
|
151
|
+
concrete anchors), Not Doing.
|
|
149
152
|
|
|
150
153
|
**The seed states findings, not a partition.** MVP Scope used
|
|
151
154
|
to render one numbered bullet per group beneath a `## Grouping` container
|
|
@@ -205,8 +208,8 @@ node .agents/scripts/audit-to-stories.js --emit-stories \
|
|
|
205
208
|
For each entry whose plan classification is `create`, open a GitHub
|
|
206
209
|
Issue. Use the GitHub MCP tool when available (`issue_write` with
|
|
207
210
|
method `create`), or fall back to `gh issue create`. The body carries
|
|
208
|
-
the canonical sections (Summary, Acceptance Criteria
|
|
209
|
-
Context) plus the machine-readable fingerprint footer rendered by the
|
|
211
|
+
the canonical sections (Summary, Acceptance Criteria — one item per finding,
|
|
212
|
+
taken from its Acceptance signal — Findings, Context) plus the machine-readable fingerprint footer rendered by the
|
|
210
213
|
shared helper's `fingerprintFooter(sha)`
|
|
211
214
|
(`<!-- audit-fingerprints: sha1,sha1,... -->`) that Phase 6 relies on.
|
|
212
215
|
|