mandrel 2.78.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 (35) hide show
  1. package/.agents/README.md +6 -1
  2. package/.agents/audit-checklists/architecture.md +1 -0
  3. package/.agents/audit-checklists/clean-code.md +1 -0
  4. package/.agents/audit-checklists/devops.md +4 -1
  5. package/.agents/audit-checklists/security.md +1 -1
  6. package/.agents/docs/configuration.md +1 -1
  7. package/.agents/schemas/agentrc.schema.json +1 -1
  8. package/.agents/scripts/bootstrap.js +87 -16
  9. package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
  10. package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
  11. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
  12. package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
  13. package/.agents/scripts/lib/close-validation/commands.js +33 -0
  14. package/.agents/scripts/lib/close-validation/gates.js +11 -4
  15. package/.agents/scripts/lib/config/explain.js +2 -1
  16. package/.agents/scripts/lib/config-settings-schema.js +2 -1
  17. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  18. package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
  19. package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
  20. package/.agents/scripts/lib/test-run-credit.js +46 -17
  21. package/.agents/workflows/audit-architecture.md +20 -4
  22. package/.agents/workflows/audit-clean-code.md +17 -1
  23. package/.agents/workflows/audit-devops.md +58 -14
  24. package/.agents/workflows/audit-performance.md +22 -0
  25. package/.agents/workflows/audit-quality.md +30 -0
  26. package/.agents/workflows/audit-security.md +23 -8
  27. package/.agents/workflows/helpers/audit-lens-core.md +48 -2
  28. package/README.md +13 -1
  29. package/docs/CHANGELOG.md +15 -0
  30. package/lib/cli/registry.js +85 -12
  31. package/lib/cli/uninstall.js +34 -18
  32. package/lib/cli/update.js +37 -6
  33. package/lib/migrations/index.js +2 -0
  34. package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
  35. 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
 
@@ -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
 
@@ -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
 
@@ -43,12 +43,58 @@ with its config-driven target set; navigability always evaluates the whole
43
43
  route tree regardless of the fence). Those lenses state their deviation in
44
44
  their own Scope section; every other lens follows the rule above verbatim.
45
45
 
46
+ ## Ecosystem detection & the absent-vs-inapplicable rule {#ecosystem-detection}
47
+
48
+ A lens's Step 0 instruments are ecosystem-specific, so detect the ecosystems
49
+ from repo-observable manifests **before** running any rung:
50
+
51
+ | Ecosystem | Detected by |
52
+ | --- | --- |
53
+ | JS / TS | `package.json` |
54
+ | Python | `pyproject.toml`, `setup.cfg`, `requirements*.txt` |
55
+ | Go | `go.mod` |
56
+ | Rust | `Cargo.toml` |
57
+ | CI — GitHub Actions | `.github/workflows/*.yml` / `*.yaml` |
58
+ | CI — Google Cloud Build | `cloudbuild*.yaml` |
59
+ | CI — GitLab CI | `.gitlab-ci.yml` |
60
+ | CI — Azure Pipelines | `azure-pipelines.yml` |
61
+
62
+ Run the rung for **every** detected ecosystem — a polyglot repo gets more than
63
+ one — and name the detected set in the Executive Summary. Then:
64
+
65
+ - **Absent is a gap.** A scanner for a **detected** ecosystem that is not
66
+ installed is a gap: record it as a Low-severity `Standardization` finding
67
+ (recommend adopting it) and fall through to the next rung or a manual read.
68
+ - **Inapplicable is never a finding.** A scanner for an ecosystem that is
69
+ **not detected** is inapplicable — skip it silently. It is never a finding,
70
+ not even a Low one (`actionlint` on a repo with no `.github/workflows/` is
71
+ inapplicable, not missing).
72
+ - **Non-JS fallback.** Where a lens's JS rung reads a Mandrel-shipped script
73
+ or a committed `baselines/*.json` file that does not exist in the consumer,
74
+ measure with the ecosystem's own instrument instead of reporting the missing
75
+ script or baseline:
76
+
77
+ | Dimension | Python | Go | Rust |
78
+ | --- | --- | --- | --- |
79
+ | Complexity / MI | `radon cc -s -a`, `radon mi -s` | `gocyclo` | `cargo clippy` (cognitive_complexity) |
80
+ | Dead code | `vulture` | `staticcheck` (U1000) | `cargo +nightly udeps`, rustc dead_code warnings |
81
+ | Duplication | `pylint --disable=all --enable=duplicate-code`, or `jscpd` | `jscpd` | `jscpd` |
82
+ | Import graph / cycles | `pydeps --show-cycles`, `import-linter` (`lint-imports`) | `go vet`, `go list -deps` | `cargo modules` |
83
+ | Coverage | `coverage report` / `pytest --cov` (coverage.py, pytest-cov) | `go test -cover` | `cargo llvm-cov`, `cargo tarpaulin` |
84
+ | Dependency CVEs | `pip-audit` | `govulncheck` | `cargo audit` |
85
+ | Profiling | `py-spy record`, `python -m cProfile` | `go test -cpuprofile`, `pprof` | `cargo flamegraph` |
86
+
46
87
  ## Report envelope & finding-block skeleton {#report-envelope}
47
88
 
48
89
  Each lens writes exactly one structured Markdown report to
49
90
  `{{auditOutputDir}}/audit-<lens>-results.md` (the lens preamble names its own
50
- path). The report MUST include every section its lens template mandates — write
51
- `_No findings._` rather than omitting a section — and always an
91
+ path). A dispatched run gets the anchor substituted; on a manual
92
+ `/audit-<lens>` invocation it renders the literal string `{{auditOutputDir}}`.
93
+ Treat that literal as `<project.paths.tempRoot>/audits` — **`temp/audits` by
94
+ default** — and write the report there, mirroring the `{{changedFiles}}`
95
+ manual-run rule above. The report MUST include every section its lens
96
+ template mandates — write `_No findings._` rather than omitting a section — and
97
+ always an
52
98
  `## Executive Summary` and a `## Detailed Findings` section. The Executive
53
99
  Summary carries the self-cross-check `kept <k> / dropped <d>` line
54
100
  ([below](#self-cross-check)) and, beside it, the machine-readable severity
package/README.md CHANGED
@@ -70,6 +70,16 @@ explicit `npx mandrel sync` above is the belt-and-suspenders step for
70
70
  `--ignore-scripts` or sandboxed-CI installs. Run `npx mandrel doctor` any
71
71
  time to confirm the install is healthy.
72
72
 
73
+ Bootstrap also writes a guarded `prepare` script that regenerates both
74
+ `.claude/` projections — `.claude/commands/` (from `.agents/workflows/`) and
75
+ `.claude/agents/` (from `.agents/agents/`). Both are generated and
76
+ gitignored; never commit them. The guard makes `prepare` exit 0 without
77
+ writing anything when `.agents/scripts/` is absent, so a manifest-only
78
+ container layer (`COPY package.json package-lock.json ./` then `npm ci`)
79
+ installs cleanly; once `.agents/` is present it runs both projections.
80
+ Existing installs pick up the guard and the `.claude/agents/` ignore entry
81
+ through the `mandrel update` migration.
82
+
73
83
  > **pnpm users — hoist mandrel's runtime deps.** The materialized
74
84
  > `./.agents/scripts/*.js` run from your project root and resolve their
75
85
  > third-party deps (ajv, js-yaml, …) from your top-level `node_modules`.
@@ -143,7 +153,9 @@ npx mandrel update
143
153
  - `--install-cmd "<cmd>"` — override the auto-detected install command. The
144
154
  package manager is normally detected from your lockfile
145
155
  (`pnpm-lock.yaml` ⇒ `pnpm add -D …`, `yarn.lock` ⇒ `yarn add -D …`,
146
- otherwise `npm install …`), so an override is rarely needed. When you do
156
+ otherwise `npm install …`), and it keeps your current pin style: an exact
157
+ pin installs with `--save-exact` (`--exact` on yarn), a tilde pin as
158
+ `mandrel@~<target>`, so an override is rarely needed. When you do
147
159
  pass one, a `{target}` placeholder is substituted with the resolved newest
148
160
  version — e.g. `--install-cmd "pnpm add -D mandrel@{target} -w"` —
149
161
  so the override can still consume the auto-probed version. The registry
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,21 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.79.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.78.0...mandrel-v2.79.0) (2026-10-09)
19
+
20
+
21
+ ### Added
22
+
23
+ * audit lenses: ecosystem-detected Step 0 rungs for Python and non-GitHub CI, and a stated manual output path ([#5583](https://github.com/dsj1984/mandrel/issues/5583)) ([#5586](https://github.com/dsj1984/mandrel/issues/5586)) ([3c5bf96](https://github.com/dsj1984/mandrel/commit/3c5bf9673b413800deca87e6fc30b956b10154c8))
24
+ * bootstrap: container-safe prepare hook and a gitignored .claude/agents/ projection ([#5581](https://github.com/dsj1984/mandrel/issues/5581)) ([#5590](https://github.com/dsj1984/mandrel/issues/5590)) ([96c4b20](https://github.com/dsj1984/mandrel/commit/96c4b2024724805122ab2b4d3f046cac8b3f7852))
25
+ * bootstrap: skip Projects V2 board creation non-interactively, and continue when project creation is declined ([#5584](https://github.com/dsj1984/mandrel/issues/5584)) ([#5587](https://github.com/dsj1984/mandrel/issues/5587)) ([14db7d3](https://github.com/dsj1984/mandrel/commit/14db7d33a017a314a98d7be2f344988da7e2ef3b))
26
+ * close and doctor honor project.commands.test instead of hardcoding npm test ([#5582](https://github.com/dsj1984/mandrel/issues/5582)) ([#5588](https://github.com/dsj1984/mandrel/issues/5588)) ([7849cf2](https://github.com/dsj1984/mandrel/commit/7849cf2945837631167241d6c30979433f9dcfea))
27
+
28
+
29
+ ### Fixed
30
+
31
+ * mandrel update preserves the consumer's exact or tilde pin instead of loosening it to a caret ([#5580](https://github.com/dsj1984/mandrel/issues/5580)) ([#5585](https://github.com/dsj1984/mandrel/issues/5585)) ([443c10a](https://github.com/dsj1984/mandrel/commit/443c10a2c0a7a2e6c7597b4196e9f3cb58440d23))
32
+
18
33
  ## [2.78.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.77.0...mandrel-v2.78.0) (2026-10-09)
19
34
 
20
35