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.
Files changed (44) hide show
  1. package/.agents/README.md +6 -1
  2. package/.agents/agents/auditor.md +2 -3
  3. package/.agents/audit-checklists/architecture.md +1 -0
  4. package/.agents/audit-checklists/clean-code.md +1 -0
  5. package/.agents/audit-checklists/devops.md +4 -1
  6. package/.agents/audit-checklists/security.md +1 -1
  7. package/.agents/docs/configuration.md +1 -1
  8. package/.agents/schemas/agentrc.schema.json +1 -1
  9. package/.agents/scripts/bootstrap.js +87 -16
  10. package/.agents/scripts/lib/audit-to-stories/build-story-body.js +48 -14
  11. package/.agents/scripts/lib/audit-to-stories/finding-bullets.js +33 -0
  12. package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js +6 -4
  13. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +34 -19
  14. package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
  15. package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
  16. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
  17. package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
  18. package/.agents/scripts/lib/close-validation/commands.js +33 -0
  19. package/.agents/scripts/lib/close-validation/gates.js +11 -4
  20. package/.agents/scripts/lib/config/explain.js +2 -1
  21. package/.agents/scripts/lib/config-settings-schema.js +2 -1
  22. package/.agents/scripts/lib/findings/severity.js +33 -6
  23. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  24. package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
  25. package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
  26. package/.agents/scripts/lib/test-run-credit.js +46 -17
  27. package/.agents/workflows/audit-architecture.md +20 -4
  28. package/.agents/workflows/audit-baselines.md +3 -3
  29. package/.agents/workflows/audit-clean-code.md +17 -1
  30. package/.agents/workflows/audit-devops.md +58 -14
  31. package/.agents/workflows/audit-exceptions.md +3 -2
  32. package/.agents/workflows/audit-performance.md +22 -0
  33. package/.agents/workflows/audit-quality.md +30 -0
  34. package/.agents/workflows/audit-security.md +23 -8
  35. package/.agents/workflows/audit-to-stories.md +9 -6
  36. package/.agents/workflows/helpers/audit-lens-core.md +53 -8
  37. package/README.md +13 -1
  38. package/docs/CHANGELOG.md +22 -0
  39. package/lib/cli/registry.js +85 -12
  40. package/lib/cli/uninstall.js +34 -18
  41. package/lib/cli/update.js +37 -6
  42. package/lib/migrations/index.js +2 -0
  43. package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
  44. 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 { resolveLintCommand } from '../close-validation/commands.js';
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
- 'npm',
362
- 'test',
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 { crap } = getQualityImpl(resolveConfigImpl({ cwd: worktree }));
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
- * @param {{ storyId: number|string, worktree: string, cwd: string, gitSpawnFn: Function, shouldSkipImpl: Function, hashCommandConfigImpl: Function, treeFingerprintImpl: Function }} args
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
- cmd: 'npm',
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
- /** Must hash identically to the command close spawns. */
23
- const GATE_COMMAND = Object.freeze({
24
- cmd: 'npm',
25
- args: Object.freeze(['test']),
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: hashCommandConfig({
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
- '[close-validation] a green `npm test` already deposited the test credit for this tree — registering the plain `test` gate so close reports it as credited.',
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: hashCommandConfig({
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. **LLM triage on top.** Only after the tools have run do you apply the Step 2
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 shipped checker exits non-zero or is genuinely absent, record that as an
84
- **Automated Architecture Guardrails** finding (the guardrail is missing or
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 Agent Prompt
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 Agent Prompt MUST** end the remediation with the ratchet
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 Agent Prompt templates verbatim, substituting the envelope's own
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. **Churn-by-complexity hotspot cap.** Rank candidate hotspots by
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. Each tool is **presence-gated**: when
31
- the binary is absent, record the gap as a Low-severity `Standardization`
32
- finding (recommend adopting the scanner) and continue — a missing scanner
33
- degrades the audit gracefully, it never aborts it.
34
-
35
- 1. **Workflow static analysis (`actionlint`).** When `.github/workflows/`
36
- contains any `*.yml` / `*.yaml`, run:
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`, `azure-pipelines.yml`),
81
- dependency/script manifests (`package.json`, `pnpm-workspace.yaml`), lint/format
82
- configs (`.eslintrc*`, `.prettierrc*`, `biome.json`, `tsconfig.json`), and git
83
- hooks / commit standards (`.husky/`, `commitlint.config.js`).
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 `gh run list`
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
- `gh run list` failure rates from Step 1.
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: Agent Prompt templates
187
+ ## Step 4: Recommendation templates
188
188
 
189
- Substitute the envelope's own values for the angle-bracketed slots:
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** — when a scanner is absent, fall through to the next rung
45
- and note the missing tool as a `Security Misconfiguration` finding (recommend
46
- adopting it).
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 (`npm audit`).** Never recall CVEs from memory:
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`) at `high` or `critical`
55
- is a _Vulnerable Components_ finding citing the advisory id and the violated
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, Agent Prompt).
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, Key Assumptions (with links to every source
147
- report), MVP Scope (**the findings, flat**), Key Files (so `/mandrel-plan`'s
148
- authoring step has concrete anchors), Not Doing.
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, Agent Prompts,
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