mandrel 2.78.0 → 2.80.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 (57) hide show
  1. package/.agents/README.md +6 -1
  2. package/.agents/agents/auditor.md +8 -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/data-model.md +9 -1
  6. package/.agents/audit-checklists/devops.md +4 -1
  7. package/.agents/audit-checklists/security.md +1 -1
  8. package/.agents/docs/agentrc-reference.json +3 -0
  9. package/.agents/docs/configuration.md +2 -2
  10. package/.agents/docs/workflows.md +1 -1
  11. package/.agents/schemas/agentrc.schema.json +20 -2
  12. package/.agents/schemas/audit-rules.json +5 -1
  13. package/.agents/scripts/bootstrap.js +87 -16
  14. package/.agents/scripts/lib/audit-to-stories/seed-from-findings.js +37 -2
  15. package/.agents/scripts/lib/bootstrap/commit-push.js +3 -2
  16. package/.agents/scripts/lib/bootstrap/manifest.js +2 -2
  17. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +51 -15
  18. package/.agents/scripts/lib/bootstrap/prompt.js +30 -1
  19. package/.agents/scripts/lib/close-validation/commands.js +33 -0
  20. package/.agents/scripts/lib/close-validation/gates.js +11 -4
  21. package/.agents/scripts/lib/config/explain.js +3 -2
  22. package/.agents/scripts/lib/config-settings-schema.js +20 -2
  23. package/.agents/scripts/lib/findings/audit-finding-record.js +95 -0
  24. package/.agents/scripts/lib/findings/route-finding.js +4 -3
  25. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  26. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +182 -0
  27. package/.agents/scripts/lib/orchestration/plan-persist/audit-provenance.js +11 -10
  28. package/.agents/scripts/lib/orchestration/plan-persist/collision-message.js +52 -0
  29. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +5 -3
  30. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +28 -14
  31. package/.agents/scripts/lib/orchestration/plan-persist/wave-collision-gate.js +8 -4
  32. package/.agents/scripts/lib/orchestration/plan-persist/wave-serialisation.js +3 -2
  33. package/.agents/scripts/lib/orchestration/story-handoff.js +15 -3
  34. package/.agents/scripts/lib/orchestration/verify-credit.js +9 -4
  35. package/.agents/scripts/lib/qa/resolve-qa-contract.js +28 -9
  36. package/.agents/scripts/lib/templates/decomposer-prompts.js +2 -2
  37. package/.agents/scripts/lib/test-run-credit.js +46 -17
  38. package/.agents/scripts/lib/wave-runner/footprint.js +114 -17
  39. package/.agents/scripts/lib/wave-runner/ready-set.js +16 -5
  40. package/.agents/workflows/audit-architecture.md +20 -4
  41. package/.agents/workflows/audit-clean-code.md +17 -1
  42. package/.agents/workflows/audit-data-model.md +94 -10
  43. package/.agents/workflows/audit-devops.md +58 -14
  44. package/.agents/workflows/audit-performance.md +22 -0
  45. package/.agents/workflows/audit-quality.md +30 -0
  46. package/.agents/workflows/audit-security.md +23 -8
  47. package/.agents/workflows/audit-to-stories.md +22 -7
  48. package/.agents/workflows/helpers/audit-lens-core.md +56 -7
  49. package/.agents/workflows/helpers/plan-reference.md +11 -3
  50. package/README.md +13 -1
  51. package/docs/CHANGELOG.md +24 -0
  52. package/lib/cli/registry.js +85 -12
  53. package/lib/cli/uninstall.js +34 -18
  54. package/lib/cli/update.js +37 -6
  55. package/lib/migrations/index.js +2 -0
  56. package/lib/migrations/steps/2.79.0-container-safe-projections.js +91 -0
  57. package/package.json +1 -1
@@ -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
 
@@ -175,20 +175,35 @@ one-pager, and per-group even though the visible list is flat — they are the
175
175
  identity the next sweep matches on). `plan-persist` harvests them out of the seed on the
176
176
  `plan-context.json` envelope — which carries them apart from the seed text as
177
177
  `seed.provenance`, so an oversize seed cut for size keeps every footer — and
178
- appends them to **every** Story body it persists, via `carryProvenanceFooters`
178
+ appends them to the Story bodies it persists, via `carryProvenanceFooters`
179
179
  ([`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)).
180
- The carry is additive, union-preserving and idempotent, so a resumed persist
181
- cannot stack footers and a hand-authored fingerprint is never dropped.
180
+ The carry is additive and idempotent, so a resumed persist cannot stack
181
+ footers and a hand-authored fingerprint is never dropped.
182
+
183
+ **Which Story carries which finding.** Beside the group footers the seed
184
+ emits one seed-only `audit-finding` record per finding (sha, semantic key,
185
+ `audit::` label, files — primary first). A plan that persists **one** Story,
186
+ or a seed with no such records, stamps the union of every footer on every
187
+ Story. A plan that splits into **N>1** Stories attributes per Story instead:
188
+ an authored `provenance` wins outright; otherwise a Story owns each finding
189
+ whose primary file (or, when no Story covers the primary, any other file) its
190
+ `changes[]` covers by exact path or glob. A finding no Story covers is
191
+ **unattributed**: it is still stamped on every Story without an authored
192
+ `provenance`, and persist names it in its warnings as `unattributed audit
193
+ finding <sha12> (<file>) — carried on all N Stories`, so the smear is visible
194
+ rather than silent. The record itself is never stamped on a Story body.
182
195
 
183
196
  **The carry is fail-closed.** The footers are the only cross-run dedup memory,
184
197
  so a dropped one is a finding silently re-filed by the next sweep. An envelope
185
198
  whose seed was truncated and that carries no `seed.provenance` makes persist
186
199
  refuse before creating any Issue, naming the cause — regenerate the envelope.
187
200
 
188
- **Persist stamps the labels too.** It adds the seed's `audit::<dimension>`
189
- labels — the dedup corpus is listed by them, and an indexed run answers lookups
190
- from that pool without reaching the provider, so a footer alone leaves a
191
- plan-path Story invisible. Persist writes no file.
201
+ **Persist stamps the labels too.** It adds `audit::<dimension>` labels — the
202
+ dedup corpus is listed by them, and an indexed run answers lookups from that
203
+ pool without reaching the provider, so a footer alone leaves a plan-path Story
204
+ invisible. On the union path every Story gets the seed's union labels; under
205
+ N>1 attribution each Story gets the labels of the findings stamped on it (a
206
+ stamped sha with no seed record widens to the union). Persist writes no file.
192
207
 
193
208
  This is deliberately not an authoring step. If you find yourself copying a
194
209
  footer by hand, the carry is broken — fix it there rather than papering over it
@@ -22,8 +22,8 @@ a lens performs is its report artifact (plus, where a lens explicitly declares
22
22
  it, a single measurement/baseline artifact named in that lens's own
23
23
  Constraint). A lens that names a stricter or looser read-only carve-out in its
24
24
  own body (e.g. performance's non-mutating measurements, quality's permitted
25
- committed-baseline reads, data-model's no-database rule) refines this shared
26
- constraint for that lens only.
25
+ committed-baseline reads, data-model's opt-in read-only database carve-out)
26
+ refines this shared constraint for that lens only.
27
27
 
28
28
  ## Scope interpretation (Story / plan-run mode) {#scope-interpretation}
29
29
 
@@ -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
@@ -230,15 +276,18 @@ lens that has one, so a lens documents only its own probe.
230
276
  device profile, colour scheme — before finishing, so a following lens or QA
231
277
  run does not inherit it.
232
278
 
233
- **Skip reasons, and how to report them.** The pass is skipped, never faked, for
234
- either of two reasons, and the Executive Summary says which:
279
+ **Skip reasons, and how to report them.** The pass is skipped, never faked,
280
+ for any of the reasons below that applies to the lens's probe, and the
281
+ Executive Summary says which. A lens whose probe has further skip conditions
282
+ lists them in its own body:
235
283
 
236
284
  | Condition | Reported as |
237
285
  | --- | --- |
238
286
  | No `qa.environments` target is configured | `skipped — no target configured` |
239
287
  | The browser tooling is unavailable in this runtime | `skipped — browser tooling unavailable` |
288
+ | A database probe finds no opted-in `database` block on the target | `skipped — no database target configured` |
240
289
 
241
- The second is the one an unattended sweep meets: a scheduled run has no browser
290
+ The browser-tooling row is the one an unattended sweep meets: a scheduled run has no browser
242
291
  MCP server attached, so a lens that treated "cannot drive" as "nothing found"
243
292
  would report a clean runtime section it never ran. Do not invent a URL, do not
244
293
  start an arbitrary dev server, and do not fall back to a static-only claim
@@ -238,7 +238,14 @@ work this plan already tracked.
238
238
  | --- | --- |
239
239
  | Present | **Exactly** the identities listed — siblings' groups never leak in. |
240
240
  | Present but empty (`{}`) | Nothing. "Owns no findings" is a real answer. |
241
- | **Absent** | The **whole seed's** footers (the union) — the recall-safe default. |
241
+ | **Absent**, N>1 plan, seed carries `audit-finding` records | The findings whose files this Story's `changes[]` covers (exact path or glob; the primary file first, the others only when no Story covers it), plus every **unattributed** finding. |
242
+ | **Absent**, otherwise (N==1, or a record-less seed) | The **whole seed's** footers (the union) — the recall-safe default. |
243
+
244
+ An unattributed finding — one no Story owns by `provenance` or by path — is
245
+ stamped on every Story without an authored `provenance` and listed in
246
+ persist's warnings (`unattributed audit finding <sha12> (<file>) — carried on
247
+ all N Stories`). `audit::*` labels follow the stamped findings under
248
+ attribution, and the seed union otherwise.
242
249
 
243
250
  **The union fallback is load-bearing, not legacy** — hand-carrying provenance
244
251
  out of the seed's HTML comments is a step an author forgets. Attribution is
@@ -251,8 +258,9 @@ owning Story has **closed** is masked by an open neighbour. With ownership
251
258
  stamped, the issue carrying a finding's own fingerprint decides both the match
252
259
  and its state (`lib/findings/route-finding.js`).
253
260
 
254
- The audit path authors this mechanically from the per-group footers the seed
255
- already carries — see [`audit-to-stories`](../audit-to-stories.md). A `--seed`
261
+ The audit path attributes mechanically from the per-finding `audit-finding`
262
+ records the seed carries beside its per-group footers — see
263
+ [`audit-to-stories`](../audit-to-stories.md). A `--seed`
256
264
  or `--tickets` plan has nothing to attribute and omits the field.
257
265
 
258
266
  ## Cross-Story conflict analysis at persist
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,30 @@ 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.80.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.79.0...mandrel-v2.80.0) (2026-10-09)
19
+
20
+
21
+ ### Added
22
+
23
+ * audit-data-model: Dead Schema dimension and opt-in read-only live-schema verification pass ([#5594](https://github.com/dsj1984/mandrel/issues/5594)) ([#5595](https://github.com/dsj1984/mandrel/issues/5595)) ([3738dbe](https://github.com/dsj1984/mandrel/commit/3738dbe4af5bb7d71b97701684433d1feb13b839))
24
+ * audit-seeded N&gt;1 plans: attribute each finding's footers and audit:: label to the Stories that cover it ([#5597](https://github.com/dsj1984/mandrel/issues/5597)) ([#5600](https://github.com/dsj1984/mandrel/issues/5600)) ([a8529be](https://github.com/dsj1984/mandrel/commit/a8529bee4f51771677d646275081df6deb3a6543))
25
+ * collision predicate: a glob collides only with paths it can cover, and the message names the declarer ([#5596](https://github.com/dsj1984/mandrel/issues/5596)) ([#5599](https://github.com/dsj1984/mandrel/issues/5599)) ([dfea48c](https://github.com/dsj1984/mandrel/commit/dfea48caf755577e625002bb6873e2d54291e045))
26
+
27
+ ## [2.79.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.78.0...mandrel-v2.79.0) (2026-10-09)
28
+
29
+
30
+ ### Added
31
+
32
+ * 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))
33
+ * 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))
34
+ * 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))
35
+ * 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))
36
+
37
+
38
+ ### Fixed
39
+
40
+ * 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))
41
+
18
42
  ## [2.78.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.77.0...mandrel-v2.78.0) (2026-10-09)
19
43
 
20
44
 
@@ -860,9 +860,18 @@ function probeConfiguredDriver(command, runner, projectRoot) {
860
860
  /** The runner whose green full run deposits the close `test` credit itself. */
861
861
  const MANDREL_TEST_RUNNER = 'run-tests.js';
862
862
 
863
- /** Deposits the credit whatever `npm test` resolves to. */
864
- const TEST_CREDIT_DEPOSIT_COMMAND =
865
- 'node .agents/scripts/evidence-gate.js --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- npm test';
863
+ /** The close `test` gate's command when `project.commands.test` is unset. */
864
+ const DEFAULT_TEST_COMMAND = 'npm test';
865
+
866
+ /**
867
+ * The deposit command that works on any runner, wrapping `command`.
868
+ *
869
+ * @param {string} command
870
+ * @returns {string}
871
+ */
872
+ function testCreditDepositCommand(command) {
873
+ return `node .agents/scripts/evidence-gate.js --standalone --scope-id <storyId> --gate test --worktree <workCwd> -- ${command}`;
874
+ }
866
875
 
867
876
  /** The capture close's `coverage-capture` gate finds fresh, per digest § 5. */
868
877
  const COVERAGE_CAPTURE_COMMAND =
@@ -872,7 +881,13 @@ const COVERAGE_CAPTURE_COMMAND =
872
881
  const STORY_HANDOFF_COMMAND =
873
882
  'node .agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>';
874
883
 
875
- const TEST_CREDIT_REMEDY = `run the suite through the depositor instead of bare \`npm test\`: ${TEST_CREDIT_DEPOSIT_COMMAND}`;
884
+ /**
885
+ * @param {string} command
886
+ * @returns {string}
887
+ */
888
+ function testCreditRemedy(command) {
889
+ return `run the suite through the depositor instead of bare \`${command}\`: ${testCreditDepositCommand(command)}`;
890
+ }
876
891
 
877
892
  const PRE_PUSH_REMEDY =
878
893
  'wrap each hook gate in `node .agents/scripts/evidence-gate.js --standalone --scope-id <storyId> --gate <typecheck|lint> -- <command>` so the push deposits the credit close reads';
@@ -881,8 +896,8 @@ const PRE_PUSH_REMEDY =
881
896
  const HOOK_GATE_RE = /\b(typecheck|tsc|lint|eslint|biome)\b/;
882
897
 
883
898
  /**
884
- * Read from `package.json`, not `project.commands.test`: the close gate's argv
885
- * is the literal `npm test`.
899
+ * Consulted only while `project.commands.test` is unset — then the close
900
+ * gate's argv is `npm test`, which runs `scripts.test`.
886
901
  *
887
902
  * @param {string} projectRoot
888
903
  * @param {typeof fs.readFileSync} readFileImpl
@@ -930,23 +945,80 @@ function isCrapEnabled(projectRoot, readFileImpl) {
930
945
  return enabled;
931
946
  }
932
947
 
948
+ /**
949
+ * `project.commands.test` from `.agentrc.json` overlaid by
950
+ * `.agentrc.local.json` — the command close's `test` gate spawns. Read without
951
+ * `resolveConfig()` (built-ins only), like {@link isCrapEnabled}.
952
+ *
953
+ * @param {string} projectRoot
954
+ * @param {typeof fs.readFileSync} readFileImpl
955
+ * @returns {string|null} The configured command, or null when unset/default.
956
+ */
957
+ function configuredTestCommand(projectRoot, readFileImpl) {
958
+ let command = null;
959
+ for (const file of ['.agentrc.json', '.agentrc.local.json']) {
960
+ const value = readJsonSafe(path.join(projectRoot, file), {
961
+ readFileSync: readFileImpl,
962
+ })?.project?.commands?.test;
963
+ if (typeof value === 'string' && value.trim().length > 0) {
964
+ command = value.trim();
965
+ }
966
+ }
967
+ return command === DEFAULT_TEST_COMMAND ? null : command;
968
+ }
969
+
970
+ /**
971
+ * A configured `project.commands.test` is what close spawns, so the analysis
972
+ * is of that command, never of `scripts.test`.
973
+ *
974
+ * @param {string} command
975
+ * @returns {{ detail: string, remedy?: string }}
976
+ */
977
+ function describeConfiguredTestCommand(command) {
978
+ const lead = `\`project.commands.test\` sets close's \`test\` gate to \`${command}\``;
979
+ if (command.includes(MANDREL_TEST_RUNNER)) {
980
+ return {
981
+ detail: `${lead}, which reaches mandrel's runner — a green full run on a story branch deposits the close \`test\` credit itself`,
982
+ };
983
+ }
984
+ const remedy = testCreditRemedy(command);
985
+ return {
986
+ detail: `${lead}, which deposits no close \`test\` credit by itself — ${remedy}`,
987
+ remedy,
988
+ };
989
+ }
990
+
933
991
  /**
934
992
  * Which depositor digest § 5 selects, stated with its exact command.
935
993
  *
936
- * @param {{ scripts: Record<string, string>, crapEnabled: boolean }} probe
994
+ * @param {{ scripts: Record<string, string>, crapEnabled: boolean, testCommand: string|null }} probe
937
995
  * @returns {{ detail: string, remedy?: string }}
938
996
  */
939
- function describeCreditedRun({ scripts, crapEnabled }) {
997
+ function describeCreditedRun({ scripts, crapEnabled, testCommand }) {
940
998
  if (crapEnabled && scriptNamed(scripts, 'test:coverage') !== null) {
941
999
  return {
942
1000
  detail: `the CRAP gate is enabled and \`test:coverage\` exists, so close registers \`coverage-capture\` and the credited run is the coverage capture: \`${COVERAGE_CAPTURE_COMMAND}\` — its fresh stamp lets close's capture skip the suite`,
943
1001
  };
944
1002
  }
1003
+ return testCommand !== null
1004
+ ? describeConfiguredTestCommand(testCommand)
1005
+ : describeNpmTestScript(scripts);
1006
+ }
1007
+
1008
+ /**
1009
+ * With `project.commands.test` unset close spawns `npm test`, so the analysis
1010
+ * is of `scripts.test`.
1011
+ *
1012
+ * @param {Record<string, string>} scripts
1013
+ * @returns {{ detail: string, remedy?: string }}
1014
+ */
1015
+ function describeNpmTestScript(scripts) {
1016
+ const remedy = testCreditRemedy(DEFAULT_TEST_COMMAND);
945
1017
  const script = scriptNamed(scripts, 'test');
946
1018
  if (script === null) {
947
1019
  return {
948
- detail: `no \`test\` script in package.json — close still spawns \`npm test\`, so ${TEST_CREDIT_REMEDY}`,
949
- remedy: TEST_CREDIT_REMEDY,
1020
+ detail: `no \`test\` script in package.json — close still spawns \`npm test\`, so ${remedy}`,
1021
+ remedy,
950
1022
  };
951
1023
  }
952
1024
  if (script.includes(MANDREL_TEST_RUNNER)) {
@@ -955,8 +1027,8 @@ function describeCreditedRun({ scripts, crapEnabled }) {
955
1027
  };
956
1028
  }
957
1029
  return {
958
- detail: `\`npm test\` → \`${script}\` is this project's own runner and never reaches \`${MANDREL_TEST_RUNNER}\`, so it deposits no close \`test\` credit and prints nothing — ${TEST_CREDIT_REMEDY}`,
959
- remedy: TEST_CREDIT_REMEDY,
1030
+ detail: `\`npm test\` → \`${script}\` is this project's own runner and never reaches \`${MANDREL_TEST_RUNNER}\`, so it deposits no close \`test\` credit and prints nothing — ${remedy}`,
1031
+ remedy,
960
1032
  };
961
1033
  }
962
1034
 
@@ -1020,6 +1092,7 @@ function runTestCreditPath({ projectRoot, readFile = fs.readFileSync } = {}) {
1020
1092
  describeCreditedRun({
1021
1093
  scripts: readProjectScripts(root, readFile),
1022
1094
  crapEnabled: isCrapEnabled(root, readFile),
1095
+ testCommand: configuredTestCommand(root, readFile),
1023
1096
  }),
1024
1097
  describePrePushHook(root, readFile),
1025
1098
  ];