mandrel 2.94.0 → 2.96.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 (119) hide show
  1. package/.agents/audit-checklists/red-team.md +20 -0
  2. package/.agents/docs/workflows.md +3 -1
  3. package/.agents/runtime-deps.json +6 -6
  4. package/.agents/schemas/audit-rules.json +16 -0
  5. package/.agents/scripts/agents-bootstrap-github.js +1 -1
  6. package/.agents/scripts/board-backfill.js +1 -1
  7. package/.agents/scripts/boot-sweep.js +1 -1
  8. package/.agents/scripts/check-arch-cycles.js +69 -41
  9. package/.agents/scripts/check-doc-links.js +5 -7
  10. package/.agents/scripts/check-gherkin-corpus.js +2 -11
  11. package/.agents/scripts/clean-temp.js +1 -1
  12. package/.agents/scripts/cleanup-repo-test-temp.js +1 -1
  13. package/.agents/scripts/diagnose-friction.js +1 -1
  14. package/.agents/scripts/generate-lens-checklists.js +4 -4
  15. package/.agents/scripts/generate-skills-index.js +3 -2
  16. package/.agents/scripts/generate-workflows-doc.js +2 -1
  17. package/.agents/scripts/lib/audit-baselines/read.js +2 -1
  18. package/.agents/scripts/lib/audit-exceptions/adapters/tool-config.js +13 -3
  19. package/.agents/scripts/lib/audit-exceptions/globs.js +12 -1
  20. package/.agents/scripts/lib/audit-exceptions/probe.js +24 -2
  21. package/.agents/scripts/lib/audit-exceptions/read.js +2 -2
  22. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  23. package/.agents/scripts/lib/audit-to-stories/group-findings.js +77 -67
  24. package/.agents/scripts/lib/baselines/components.js +21 -19
  25. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -8
  26. package/.agents/scripts/lib/baselines/kinds/maintainability.js +2 -3
  27. package/.agents/scripts/lib/baselines/preview-gates.js +2 -2
  28. package/.agents/scripts/lib/baselines/refresh-service.js +4 -7
  29. package/.agents/scripts/lib/baselines/writer.js +2 -7
  30. package/.agents/scripts/lib/bdd-runner-detect.js +2 -2
  31. package/.agents/scripts/lib/bdd-step-index.js +3 -7
  32. package/.agents/scripts/lib/bootstrap/baseline-merge-driver.js +11 -7
  33. package/.agents/scripts/lib/bootstrap/install-ledger.js +19 -4
  34. package/.agents/scripts/lib/bootstrap/json-io.js +14 -0
  35. package/.agents/scripts/lib/bootstrap/project-bootstrap.js +20 -44
  36. package/.agents/scripts/lib/bootstrap/quality-bootstrap.js +38 -54
  37. package/.agents/scripts/lib/branch-name-guard.js +2 -3
  38. package/.agents/scripts/lib/claude/agents-projection.js +1 -12
  39. package/.agents/scripts/lib/codex/agents-projection.js +2 -5
  40. package/.agents/scripts/lib/codex/skills-projection.js +4 -12
  41. package/.agents/scripts/lib/config/defaults.js +2 -1
  42. package/.agents/scripts/lib/config/qa.js +4 -5
  43. package/.agents/scripts/lib/config-schema.js +1 -8
  44. package/.agents/scripts/lib/config-settings-schema.js +0 -3
  45. package/.agents/scripts/lib/coverage-baseline.js +2 -3
  46. package/.agents/scripts/lib/coverage-utils.js +2 -1
  47. package/.agents/scripts/lib/cpu-pool.js +0 -1
  48. package/.agents/scripts/lib/cyclomatic-scope.js +2 -1
  49. package/.agents/scripts/lib/doc-tiers.js +2 -1
  50. package/.agents/scripts/lib/gh-exec.js +21 -1
  51. package/.agents/scripts/lib/git/sync-from-base.js +1 -1
  52. package/.agents/scripts/lib/import-graph.js +13 -28
  53. package/.agents/scripts/lib/json-utils.js +11 -0
  54. package/.agents/scripts/lib/label-constants.js +7 -1
  55. package/.agents/scripts/lib/maintainability-utils.js +14 -22
  56. package/.agents/scripts/lib/observability/runtime-friction.js +37 -1
  57. package/.agents/scripts/lib/orchestration/check-baselines/phases/parse-args.js +25 -1
  58. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +9 -12
  59. package/.agents/scripts/lib/orchestration/code-review.js +1 -6
  60. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  61. package/.agents/scripts/lib/orchestration/git-cleanup/phases/fast-forward.js +7 -14
  62. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes-ff.js +2 -21
  63. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +11 -20
  64. package/.agents/scripts/lib/orchestration/git-cleanup/phases/phase-drivers.js +65 -86
  65. package/.agents/scripts/lib/orchestration/git-cleanup/phases/prompts.js +2 -2
  66. package/.agents/scripts/lib/orchestration/git-cleanup/phases/stashes.js +15 -6
  67. package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js +5 -2
  68. package/.agents/scripts/lib/orchestration/merge-block-class.js +47 -48
  69. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +20 -1
  70. package/.agents/scripts/lib/orchestration/review-providers/claude-verdict.js +2 -3
  71. package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js +4 -2
  72. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -2
  73. package/.agents/scripts/lib/orchestration/story-close/ratchet-shrink-writeback.js +3 -3
  74. package/.agents/scripts/lib/orchestration/story-handoff.js +18 -5
  75. package/.agents/scripts/lib/orchestration/ticketing/transition.js +17 -21
  76. package/.agents/scripts/lib/runtime-deps/dep-resolution.js +19 -5
  77. package/.agents/scripts/lib/runtime-deps/scan-imports.js +4 -10
  78. package/.agents/scripts/lib/skills/parse-skill.js +2 -2
  79. package/.agents/scripts/lib/skills/walk-skill-files.js +7 -23
  80. package/.agents/scripts/lib/story-body/story-body.js +4 -14
  81. package/.agents/scripts/lib/util/atomic-write.js +14 -3
  82. package/.agents/scripts/lib/util/regex.js +4 -0
  83. package/.agents/scripts/lint-issue-body.js +65 -10
  84. package/.agents/scripts/notify.js +1 -1
  85. package/.agents/scripts/plan-context.js +1 -1
  86. package/.agents/scripts/plan-critics.js +3 -11
  87. package/.agents/scripts/providers/github/auth.js +0 -4
  88. package/.agents/scripts/providers/github/project-board.js +0 -1
  89. package/.agents/scripts/providers/github/tickets.js +0 -2
  90. package/.agents/scripts/resync-status-column.js +1 -1
  91. package/.agents/scripts/run-tests.js +1 -1
  92. package/.agents/scripts/test-wrapper.js +1 -1
  93. package/.agents/scripts/update-ticket-state.js +4 -3
  94. package/.agents/scripts/validate-skills.js +2 -1
  95. package/.agents/skills/core/gates-and-baselines/reference.md +1 -0
  96. package/.agents/workflows/audit-baselines.md +21 -9
  97. package/.agents/workflows/audit-red-team.md +191 -0
  98. package/.agents/workflows/audit-security.md +4 -1
  99. package/.agents/workflows/clean-git.md +1 -1
  100. package/.agents/workflows/helpers/audit-lens-core.md +1 -1
  101. package/.agents/workflows/helpers/code-quality-guardrails.md +3 -3
  102. package/.agents/workflows/mandrel-leverage.md +199 -0
  103. package/.agents/workflows/mandrel-plan.md +3 -1
  104. package/README.md +1 -1
  105. package/docs/CHANGELOG.md +48 -0
  106. package/lib/cli/claude-code-version.js +13 -7
  107. package/lib/cli/doctor-checks/llm-review.js +12 -5
  108. package/lib/cli/doctor-checks/merge-driver.js +10 -6
  109. package/lib/cli/doctor-checks/project-access.js +21 -8
  110. package/lib/cli/doctor-checks/read-json.js +2 -15
  111. package/lib/cli/doctor-checks/spawn.js +29 -9
  112. package/lib/cli/doctor-checks/test-credit-path.js +2 -1
  113. package/lib/cli/doctor-checks/toolchain.js +16 -12
  114. package/lib/cli/doctor.js +31 -8
  115. package/lib/cli/registry.js +7 -10
  116. package/lib/cli/sync.js +46 -10
  117. package/lib/cli/uninstall.js +259 -175
  118. package/lib/cli/update.js +3 -3
  119. package/package.json +23 -20
@@ -27,6 +27,7 @@ import {
27
27
  PAYLOAD_SKILLS_SEGMENTS,
28
28
  } from './lib/skills/walk-skill-files.js';
29
29
  import { createAjv } from './lib/util/ajv.js';
30
+ import { toPosix } from './lib/util/paths.js';
30
31
 
31
32
  const MIN_CAPSULE_BULLETS = 5;
32
33
  const MAX_CAPSULE_BULLETS = 12;
@@ -156,7 +157,7 @@ function validateOne(absPath, repoRoot, validateFrontmatter, indexPaths) {
156
157
  }
157
158
 
158
159
  function rel(absPath, repoRoot) {
159
- return path.relative(repoRoot, absPath).split(path.sep).join('/');
160
+ return toPosix(path.relative(repoRoot, absPath));
160
161
  }
161
162
 
162
163
  /**
@@ -42,6 +42,7 @@ flagged a signed-off API-surface change. If the underlying change is an
42
42
  | Duplication | `npm run duplication:update` | `npm run duplication:reanchor` |
43
43
  | Dead-exports | `npm run dead-exports:update` (regenerates both passes; never hand-edit the JSON) | same — no scope flag applies |
44
44
  | Cyclomatic | `npm run cyclomatic:update` | same — no scope flag applies |
45
+ | Arch cycles | `npm run arch:update` | same — no scope flag applies |
45
46
  | Context budget | `node .agents/scripts/check-context-budget.js --update` | same — no scope flag applies |
46
47
 
47
48
  ## Procedure
@@ -219,19 +219,31 @@ runs and the ratchet never moves. So **every Hotspot Cluster and Tightening
219
219
  Headroom finding's Recommendation MUST** end the remediation with the ratchet
220
220
  tightened and gate-enforced:
221
221
 
222
- 1. Lower the floor under `delivery.quality.gates` in `.agentrc.json` to the
223
- newly measured level, **or** delete the burnt-down rows from that kind's
224
- file under `baselines/`.
225
- 2. Carry `node .agents/scripts/check-baselines.js --gate <kind>` in the
226
- remediation Story's `verify[]`, so the tightened floor is enforced by the
227
- gate that already exists at that Story's delivery time rather than by prose
228
- nobody runs.
222
+ 1. For a `gate` kind (its `surface` in `gateSurface[]`), lower the floor
223
+ under `delivery.quality.gates` in `.agentrc.json` to the newly measured
224
+ level, **or** delete the burnt-down rows from that kind's file under
225
+ `baselines/`. A `ratchet` kind has no floor: its shrunken baseline is the
226
+ tightening, banked at close (`arch-cycles` alone needs its checker's
227
+ `--update`).
228
+ 2. Carry each kind's checker in the remediation Story's `verify[]`, so the
229
+ tightened ratchet is enforced by the gate that already exists at that
230
+ Story's delivery time rather than by prose nobody runs. A `gate` kind uses
231
+ `node .agents/scripts/check-baselines.js --gate <kind>`; that command
232
+ rejects a `ratchet` kind with exit 3, so a ratchet uses its own checker:
233
+
234
+ | Ratchet kind | Checker |
235
+ | --- | --- |
236
+ | `arch-cycles` | `node .agents/scripts/check-arch-cycles.js` |
237
+ | `context-budget` | `node .agents/scripts/check-context-budget.js` |
238
+ | `cyclomatic` | `node .agents/scripts/check-cyclomatic.js` |
239
+ | `dead-exports` | `node .agents/scripts/check-dead-exports.js` |
240
+ | `dead-exports-production` | `node .agents/scripts/check-dead-exports.js --production` |
229
241
 
230
242
  Use these two Recommendation templates verbatim, substituting the envelope's own
231
- values for the angle-bracketed slots:
243
+ values for the angle-bracketed slots (`<checker>` is item 2's command per kind):
232
244
 
233
245
  - **Hotspot Cluster template:**
234
- `Burn down the measured debt in <hotspots.path>, an outlier across <gateKinds>. Refactor and add tests until its rows leave that kind's file under baselines/, then regenerate that baseline with the matching update-*-baseline script in a commit whose subject carries the baseline-refresh: tag. Finish by TIGHTENING the ratchet in the same Story — lower the kind's floor under delivery.quality.gates in .agentrc.json to the new measured level, or delete the burnt-down rows — and carry node .agents/scripts/check-baselines.js --gate <kind> in this Story's verify[] so the tightened floor is enforced at delivery.`
246
+ `Burn down the measured debt in <hotspots.path>, an outlier across <gateKinds>. Refactor and add tests until its rows leave each kind's file under baselines/, then regenerate a gate kind's baseline with the matching update-*-baseline script in a commit whose subject carries the baseline-refresh: tag. Finish by TIGHTENING the ratchet in the same Story — lower each gate kind's floor under delivery.quality.gates in .agentrc.json to the new measured level, or delete the burnt-down rows — and carry each kind's <checker> in this Story's verify[] so the tightened ratchet is enforced at delivery.`
235
247
  - **Tightening Headroom template:**
236
248
  `The <kind> gate's <axis> floor sits at <floor> while the measured rollup is <measured> (headroom <headroom>, direction <direction>), and that kind's trend is flat or improving. Tighten it: set that axis under delivery.quality.gates in .agentrc.json to the measured level so no slack remains for the next change to re-spend, and carry node .agents/scripts/check-baselines.js --gate <kind> in this Story's verify[] so the new floor is enforced. Regenerate no baseline in this Story — the floor edit is the whole change.`
237
249
 
@@ -0,0 +1,191 @@
1
+ ---
2
+ description: >-
3
+ Audit the project as a goal-directed adversary — attack paths that chain two
4
+ or more crossings, abuse of intended features, agent exposure to hostile
5
+ repository or inbound content, hostile operations and operator hazards —
6
+ graded under a reproduced-or-reasoned evidence bar. A deliberately-global
7
+ lens that runs on any project.
8
+ ---
9
+
10
+ # Red-Team Audit
11
+
12
+ You are a Red-Team Lead playing a **goal-directed adversary** against this
13
+ project. The per-dimension lenses each grade one crossing at a time; you ask
14
+ what an attacker _wants_, then chain the crossings that get them there. You
15
+ also own one surface no other lens audits: the paths by which hostile
16
+ repository-resident or inbound content can steer the **coding agents** that
17
+ operate on this repository.
18
+
19
+ The shared lens machinery lives in
20
+ [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
21
+ `{{auditResultsDir}}/audit-red-team-results.md`. Dimension values:
22
+ `Attack Path | Abuse & Misuse | Agent Exposure | Hostile Operations |
23
+ Operator Hazard`. Extra finding fields: **Adversary:**, **Path:**,
24
+ **Evidence:** and **Reproduction:** (see Report additions). The report adds a
25
+ mandatory **Adversary Model** section.
26
+
27
+ ## Whole-project scope (global lens)
28
+
29
+ An attack path spans files no change set names: the entry point an adversary
30
+ reaches is rarely the file whose weakness completes the chain. Narrowing to the
31
+ change set would blind this lens to its primary finding class, so it **always
32
+ evaluates the whole project**, and it applies to any project (it declares no
33
+ `target`).
34
+
35
+ Accordingly this lens declares `"scope": "global"` in
36
+ [`audit-rules.json`](../schemas/audit-rules.json) — the single source of truth
37
+ `resolveLensTier` in
38
+ [`lib/audit-suite/selector.js`](../scripts/lib/audit-suite/selector.js) reads —
39
+ and joins only the opt-in run-closeout roster (`gate3`); it never runs at Story
40
+ close or on a file pattern.
41
+
42
+ ```text
43
+ {{changedFiles}}
44
+ ```
45
+
46
+ - For this lens, **ignore** the `{{changedFiles}}` block above as a filter even
47
+ when it is populated: the project is evaluated whole. The block is rendered
48
+ only for envelope-shape parity with the scoped lenses. Do use it, when
49
+ populated, as a **prioritization hint** — a chain that runs through a changed
50
+ file is the first one to walk — never as a limit on what is audited or
51
+ reported.
52
+
53
+ ## Execution strategy
54
+
55
+ Run this lens as one `subagent_type: auditor` dispatch per the core's
56
+ Execution strategy. Fan out per dimension only when the operator's invocation
57
+ asks for it.
58
+
59
+ ## Step 0: Adversary model
60
+
61
+ Before hunting, write down what you are attacking. Every finding is graded
62
+ against this model, and the report carries it as the `## Adversary Model`
63
+ section:
64
+
65
+ 1. **Promises.** Quote the promises the project makes about itself — its
66
+ README, its docs, its security rules — each with the path it came from. An
67
+ abuse case is only a finding when it breaks one of these.
68
+ 2. **Adversaries.** Name who you are modelling: an unauthenticated network
69
+ caller, an authenticated low-privilege user, a contributor whose PR or issue
70
+ body an agent will read, a compromised dependency, an operator one keystroke
71
+ from a destructive default. Each has an access level and a goal.
72
+ 3. **Agent-facing surfaces.** Inventory what a coding agent operating on this
73
+ repository reads and is steered by: entry docs (`AGENTS.md`, `CLAUDE.md`),
74
+ skills and rules, hooks and the scripts whose output an agent reads,
75
+ workflow scripts, CI logs, issue and PR bodies, MCP and permission configs,
76
+ and dependency lifecycle scripts. Record the path read for each.
77
+
78
+ ## Step 1: Evaluation dimensions
79
+
80
+ Every finding takes exactly one of these as its `Dimension`:
81
+
82
+ - **Attack Path** — a chain of two or more crossings, each of which another
83
+ lens would grade alone, whose composed result is worse than any single link.
84
+ Name every link; a chain with a missing link is a hypothesis, not a finding.
85
+ - **Abuse & Misuse** — an intended feature used, exactly as built, to break a
86
+ promise the project makes in its docs or README. Cite the promise from the
87
+ Adversary Model.
88
+ - **Agent Exposure** — a path by which repository-resident or inbound content
89
+ (entry docs, skills, hooks, hook or workflow scripts whose output an agent
90
+ reads, CI logs, issue and PR bodies, MCP and permission configs, dependency
91
+ lifecycle scripts) can steer a coding agent operating on the repo beyond what
92
+ the operator authorized, or an authority grant broader than the task. The
93
+ Tier A anchor is the `security-baseline.md` _Input Validation_ MUST that
94
+ content observed through tools is data, never instructions: cite it as the
95
+ violated MUST.
96
+ - **Hostile Operations** — resource exhaustion, poisoned inputs, partial
97
+ failure, and supply-chain or CI paths exercised with intent rather than met
98
+ by accident.
99
+ - **Operator Hazard** — a destructive default, an irreversible step with no
100
+ dry-run, or a confirmation that does not name what it destroys.
101
+
102
+ ## Step 2: Boundaries with sibling lenses
103
+
104
+ The red team keeps what no sibling lens can see; drop anything a sibling owns
105
+ whole, and cite that sibling when you drop it:
106
+
107
+ - A **single crossing** with a fillable six-clause Boundary (see
108
+ [`audit-security.md`](audit-security.md) — the Boundary gate) is
109
+ `/audit-security`'s and is dropped here. The red team keeps chains of two or
110
+ more crossings.
111
+ - Check-then-act races and non-atomic writes stay `/audit-performance`'s
112
+ Interleaving dimension.
113
+ - An application's own LLM features (security Tier B class 6) stay
114
+ `/audit-security`'s. `Agent Exposure` is about the development agents
115
+ operating on the repository, not the product's model calls.
116
+ - Expired or unjustified escape valves stay `/audit-exceptions`'.
117
+
118
+ ## Step 3: Evidence and severity
119
+
120
+ ### The evidence cap
121
+
122
+ Every finding carries `Evidence: reproduced` or `Evidence: reasoned`. **A
123
+ reasoned finding grades no higher than Medium**, whatever its modelled result.
124
+ **High and Critical require Evidence: reproduced.** Critical additionally
125
+ requires the demonstrated result to be code execution, loss of a data store, a
126
+ leaked secret, or control of an account the adversary picks.
127
+
128
+ Otherwise grade on the shared scale with the anchors of `/audit-security`
129
+ Step 3: a crash is not code execution, and self-impact is not privilege gain.
130
+ When you cannot name the concrete damage, grade lower than instinct suggests.
131
+
132
+ ### The reproduction carve-out
133
+
134
+ This refines the shared read-only constraint for this lens only. A
135
+ reproduction is a command run against the project's own CLIs, tests or scripts
136
+ with crafted input, **whose every write lands under
137
+ `{{auditOutputDir}}/red-team/`** (on a manual run,
138
+ `<project.paths.tempRoot>/audits/red-team/`). A reproduction:
139
+
140
+ - never installs anything;
141
+ - never mutates git state, labels or tracked files;
142
+ - never opens a network connection to a deployed environment;
143
+ - never runs a payload whose effect it cannot bound in advance.
144
+
145
+ There is no runtime pass against `qa.environments`. A path that can only be
146
+ demonstrated against a live target stays `reasoned`, and the evidence cap
147
+ grades it accordingly.
148
+
149
+ ## Constraint (lens-specific carve-out)
150
+
151
+ Read-only over the repository, except the reproduction carve-out above and the
152
+ report artifact. Recording an attack path is the deliverable; closing it is a
153
+ separate pass.
154
+
155
+ ## Report additions
156
+
157
+ Beyond the core's shared skeleton, this lens adds its title, the mandatory
158
+ Adversary Model section before the findings, an `Evidence split` line in the
159
+ Executive Summary, and four finding fields. Write `_No findings._` under a
160
+ section rather than omitting it:
161
+
162
+ ```markdown
163
+ # Red-Team Audit Report
164
+
165
+ ## Executive Summary
166
+
167
+ [Headline read.]
168
+
169
+ Self-cross-check: kept <k> / dropped <d>.
170
+ Severity tally: Critical <n> / High <n> / Medium <n> / Low <n>
171
+ Evidence split: reproduced <n> / reasoned <n>
172
+
173
+ ## Adversary Model
174
+
175
+ - Promises: [quoted promise — `path`]
176
+ - Adversaries: [who, with what access, wanting what]
177
+ - Agent-facing surfaces: [surface — `path` read]
178
+
179
+ ## Detailed Findings
180
+
181
+ ### `path/to/primary-file.ext` — [Short title of the issue]
182
+
183
+ - **Dimension:** [Attack Path | Abuse & Misuse | Agent Exposure | Hostile Operations | Operator Hazard]
184
+ - **Severity:** [Critical | High | Medium | Low | Info — capped at Medium when reasoned]
185
+ - **Adversary:** [who, with what access, wanting what]
186
+ - **Path:** [preconditions → step (`path:line`) → … → result → blast radius, one line per step]
187
+ - **Evidence:** [reproduced | reasoned]
188
+ - **Reproduction:** [reproduced: the exact command run and the output line that shows the result | reasoned: none]
189
+ - [Location, Current State, Recommendation & Rationale, Acceptance signal —
190
+ per the core skeleton]
191
+ ```
@@ -119,7 +119,10 @@ for an undetected ecosystem is inapplicable and never a finding.
119
119
  ### Tier B — trust-boundary classes (cite a CWE)
120
120
 
121
121
  Each class names the sibling lens owning adjacent territory; when the only
122
- defect is the sibling's, cite that lens and drop the finding here.
122
+ defect is the sibling's, cite that lens and drop the finding here. Chains of two
123
+ or more crossings, and agent exposure (hostile repository or inbound content
124
+ steering the development agents that operate on the repo), are
125
+ `/audit-red-team`'s.
123
126
 
124
127
  1. **Business logic & state machines:** steps skipped, reordered or replayed;
125
128
  partial failure leaving step 1 applied; numeric coercion (negative, zero,
@@ -34,7 +34,7 @@ flags: `node .agents/scripts/clean-git.js --help`.
34
34
 
35
35
  | Phase | What it does | Safety contract |
36
36
  | --- | --- | --- |
37
- | **fast-forward-main** | `git fetch origin <base>` then `git merge --ff-only origin/<base>`. | Skipped silently on a dirty tree or a non-fast-forward; otherwise prompts `Fast-forward main by N commit(s)?`. Checks out `<base>` first when HEAD is elsewhere and does **not** restore the prior branch. |
37
+ | **fast-forward-main** | `git fetch origin <base>` then `git merge --ff-only origin/<base>`. | Skipped silently on a dirty tree or a non-fast-forward; otherwise prompts `Fast-forward main by N commit(s)?`. Checks out `<base>` first when HEAD is elsewhere, then restores the prior branch after the merge, even a failed one (best-effort: a failed restore warns and leaves HEAD on `<base>`). |
38
38
  | **prune-remotes** | `git fetch --prune origin` to drop `refs/remotes/origin/*` GitHub already deleted. | Prompts before pruning. Runs as its own phase regardless of `--remote`. |
39
39
  | **branches** | Reaps merged local branches (squash-aware: merged-PR, git-ancestry, and content-equivalence signals), removing an attached worktree first. Also enumerates **remote-only** merged branches. | Prints the candidate list, then prompts `Reap N merged branch(es)?`. `--remote` is required **on top of** `--execute` to delete any `origin/<branch>`. `content-merged` candidates carry a weaker-signal warning, and under `--yes` their **remote** ref is withheld unless `--include-content-merged` is passed (their local ref still goes — it is recoverable from the remote). |
40
40
  | **stashes** | Lists every stash and triages it. | Interactive: `drop / keep / quit` per entry (default `keep`). Under `--yes` / `--json`, drops require an explicit `--drop-stashes <ref>` allowlist (repeatable) — there is no "drop all". |
@@ -27,7 +27,7 @@ refines this shared constraint for that lens only.
27
27
 
28
28
  **Deliberate shortcuts are decisions.** In every lens, a `shortcut:` comment
29
29
  that names a ceiling and a trigger
30
- ([convention](code-quality-guardrails.md#deliberate-shortcuts)) is a decision,
30
+ (convention: `code-quality-guardrails.md` § Deliberate shortcuts) is a decision,
31
31
  not a finding, unless the lens can show the ceiling is already crossed at the
32
32
  expected load. A marker with no trigger, or one whose trigger has fired, is
33
33
  `/audit-exceptions`' finding, not the reading lens's.
@@ -13,7 +13,7 @@ read the same numbers from here so a "high cyclomatic complexity" finding in
13
13
 
14
14
  ## At-keyboard verification
15
15
 
16
- Run [`npm run quality:preview`](../../../package.json) before committing
16
+ Run `npm run quality:preview` before committing
17
17
  on any Story that touches production source. The preview runs
18
18
  `quality-preview.js`, which scopes the diff to `HEAD` by default (the
19
19
  alias passes no `--changed-since`; the script defaults to `HEAD`) and
@@ -63,7 +63,7 @@ No structural check enforces the pairing — it is a review-time rule
63
63
  ## Maintainability-Index drop refactor rule
64
64
 
65
65
  Per-file Maintainability Index (MI) is tracked in
66
- [`baselines/maintainability.json`](../../../baselines/maintainability.json).
66
+ `baselines/maintainability.json`.
67
67
  A commit that drops a file's MI by more than the configured
68
68
  `delivery.quality.gates.maintainability.tolerance` (default `0.5` points)
69
69
  requires a refactor in the same Story — not a baseline bump. `tolerance` is
@@ -108,7 +108,7 @@ Every judging surface reads the marker the same way:
108
108
  - **Rot**: a ceiling with no trigger. Nothing will ever say when to fix it.
109
109
  - **Fired**: the date has passed or the issue has closed. Fix it now.
110
110
 
111
- [`/audit-exceptions`](../audit-exceptions.md) lists every marker with its
111
+ `/audit-exceptions` lists every marker with its
112
112
  verdict.
113
113
 
114
114
  ## When a number changes
@@ -0,0 +1,199 @@
1
+ ---
2
+ description: Evidence-cited leverage review — draft five to twelve bets on how the project could be ~10x more useful, reliable or valuable, refute most of them with two maker-blind skeptics each, write the survivors, downgrades and refutations to temp/leverage/<run-id>/bets.md, and hand each survivor to /mandrel-plan behind a HITL gate.
3
+ ---
4
+
5
+ # /mandrel-leverage
6
+
7
+ Ask "how could this be 10x more useful, reliable or valuable" and make the
8
+ answer **survive its own refutation** before any of it becomes a Story. The
9
+ run gathers evidence (Phase 0), drafts bets that cite it (Phase 1), puts every
10
+ bet in front of two independent skeptics (Phase 2), writes one bets document
11
+ (Phase 3), and offers each survivor to the operator as a plan seed (Phase 4).
12
+
13
+ It is a front-end to [`/mandrel-plan`](mandrel-plan.md) in the same sense
14
+ [`/qa-assist`](qa-assist.md) and [`/audit-to-stories`](audit-to-stories.md)
15
+ are: it produces a seed and chains into plan. It **never persists an issue,
16
+ never mutates a label, and never starts delivery** — filing is
17
+ `/mandrel-plan`'s, behind the hand-off gate. Audits find defects against a
18
+ standard; this workflow prices upside, so a bet that does not clear the bar is
19
+ recorded as refuted, not filed as a finding.
20
+
21
+ ## Slash Command
22
+
23
+ ```text
24
+ /mandrel-leverage [<focus>] [--bar <multiplier>] [--evidence <path> ...]
25
+ ```
26
+
27
+ ### Arguments
28
+
29
+ | Name | Required | Shape / Example | Notes |
30
+ | ------------ | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
31
+ | `<focus>` | no | `"per-Story token cost"` | Narrows the question to one axis or subsystem. Omitted, the run is `general`. |
32
+ | `--bar` | no | `--bar 5` | The multiplier a bet must clear to survive. Default `10` — the name's promise. |
33
+ | `--evidence` | no | `--evidence temp/cost.md` | Repeatable. Operator-supplied files (a cost report, a usage export, user feedback) added to the evidence set. |
34
+
35
+ `<run-id>` is `<YYYYMMDD>-<focus-slug>`, or `<YYYYMMDD>-general` with no focus.
36
+ Every artifact the run writes lives under `temp/leverage/<run-id>/`.
37
+
38
+ ## Phase gates (HITL)
39
+
40
+ Gating is **light within a phase and firm at the boundary**, mirroring
41
+ [`/qa-assist`](qa-assist.md) § Phase gates. Phases 0–3 read, draft, dispatch
42
+ and write the local bets document without ceremony. **Every write that leaves
43
+ the local bets document is operator-confirmed individually**: each seed write
44
+ and each `/mandrel-plan` invocation is asked about and waited on, one at a
45
+ time. The plan → deliver hard stop is preserved.
46
+
47
+ ---
48
+
49
+ ## Phase 0 — Evidence intake (read-only)
50
+
51
+ Goal: fix the evidence set before any bet is drafted. Read, and list in the
52
+ bets document's `## Evidence set` with paths:
53
+
54
+ 1. **The docs digest set** (`project.docsContextFiles`): the roadmap's
55
+ Someday items, the decisions log's Accepted and Rejected entries, and the
56
+ architecture overview. Read digest-first and pull sections on demand.
57
+ 2. **The committed quality baselines** (the `baselines/` tree, when present)
58
+ as hotspot evidence — where complexity, churn and coverage debt sit.
59
+ 3. **Friction signals.** Every `signals.ndjson` stream under the temp root —
60
+ per-run `temp/run-<id>/signals.ndjson` and standalone
61
+ `temp/standalone/stories/story-<sid>/signals.ndjson` — rolled up by `kind`
62
+ and `category` (record shape:
63
+ [`signal-event.schema.json`](../schemas/signal-event.schema.json); where
64
+ the records come from:
65
+ [`execution-reference.md` § Friction telemetry](../docs/execution-reference.md#friction-telemetry)).
66
+ 4. **Every `--evidence` file** the operator passed.
67
+ 5. **Prior runs.** The `## Refuted` and `## Downgraded` sections of every
68
+ prior `temp/leverage/*/bets.md`. A prior refuted bet is **carried forward
69
+ as refuted unless new evidence names what changed**; never re-litigate a
70
+ refutation silently. A re-proposed bet cites the prior run and the new
71
+ evidence that reopens it.
72
+
73
+ Phase 0 writes nothing but the run directory.
74
+
75
+ ---
76
+
77
+ ## Phase 1 — Diverge
78
+
79
+ Goal: draft **between five and twelve bets**, each one block:
80
+
81
+ - **slug** — kebab-case, unique within the run.
82
+ - **axis** — `useful` (to users), `reliable`, or `valuable`.
83
+ - **claim** — a multiplier on a named, measurable quantity
84
+ (e.g. "10x fewer operator interventions per delivered Story").
85
+ - **mechanism** — one paragraph: why the change moves that quantity.
86
+ - **evidence** — citations as `path:line` or a signal roll-up figure;
87
+ **every bet carries at least one `path:line` or signal citation**. A bet
88
+ with no citation is not drafted.
89
+ - **must be true** — what would have to hold for the multiplier to
90
+ materialize.
91
+ - **cost** — a rough size in Stories.
92
+
93
+ A `<focus>` narrows the drafting; it does not lower the citation bar.
94
+
95
+ ---
96
+
97
+ ## Phase 2 — Skeptics (maker-blind)
98
+
99
+ Goal: refute what does not hold. This is the load-bearing invariant.
100
+
101
+ **Dispatch.** For every bet, dispatch **two independent
102
+ `subagent_type: general-purpose` skeptics in one turn**, all bets' skeptics
103
+ together. Each skeptic is handed **only the bet block and the evidence
104
+ paths** — never the drafting reasoning, never the other skeptic's verdict,
105
+ never a prior verdict. A skeptic that reads the maker's case grades the case,
106
+ not the bet; the same reasoning as
107
+ [`plan-critic.md` § Maker-blind](../agents/plan-critic.md). The `plan-critic`
108
+ role is a pre-mortem over an authored plan draft, a different charter — do not
109
+ dispatch it here.
110
+
111
+ **Skeptic charter** (paste it into each dispatch):
112
+
113
+ > Assume this bet shipped and the multiplier did not materialize. Name the
114
+ > most likely reason, with the evidence that supports it — read the cited
115
+ > paths yourself. Then credit the multiplier the evidence actually supports.
116
+ > Return one verdict block:
117
+ >
118
+ > - `verdict` — `holds` | `downgraded` | `refuted`
119
+ > - `credited` — a number (the multiplier you credit)
120
+ > - `reason` — one paragraph with `path:line` citations
121
+ > - `missing-evidence` — what evidence would change your verdict
122
+
123
+ **Scoring.** With `bar` the `--bar` value (default `10`):
124
+
125
+ - **survivor** — both skeptics credit at least the bar.
126
+ - **downgraded** — both credit at least 3, but one is below the bar.
127
+ - **refuted** — anything else.
128
+
129
+ **The caller never overrides a verdict.** It may re-draft a bet once with new
130
+ evidence and re-dispatch two fresh skeptics; the second pair's verdicts are
131
+ final.
132
+
133
+ ---
134
+
135
+ ## Phase 3 — Converge
136
+
137
+ Goal: write the one artifact, `temp/leverage/<run-id>/bets.md`, with these
138
+ sections in order:
139
+
140
+ - `## Evidence set` — every path read in Phase 0, plus the signal roll-up.
141
+ - `## Survivors` — ranked by the **lower** credited multiplier; each bet
142
+ block with both verdicts.
143
+ - `## Downgraded` — each bet block with both verdicts.
144
+ - `## Refuted` — every refuted bet with its refuting reason, kept so the next
145
+ run inherits it.
146
+ - `## Missing evidence` — the union of what the skeptics asked for: the
147
+ run's instrumentation backlog.
148
+
149
+ `bets.md` and the per-survivor seeds are the only files a run writes; nothing
150
+ lands under `docs/`.
151
+
152
+ ---
153
+
154
+ ## Phase 4 — Hand-off (HITL-gated)
155
+
156
+ Goal: turn survivors into plan seeds only where the operator says so.
157
+
158
+ 1. **Offer each survivor, one at a time**, with the host's question idiom:
159
+ **file as a plan seed**, **defer**, or **drop**. Show the bet block and both
160
+ verdicts.
161
+ 2. **On file**, confirm the seed write, then write
162
+ `temp/leverage/<run-id>/seed-<slug>.md` carrying the bet, both verdicts and
163
+ the evidence paths.
164
+ 3. **Confirm the plan invocation**, then chain into the planning entrypoint:
165
+
166
+ ```text
167
+ /mandrel-plan --seed-file temp/leverage/<run-id>/seed-<slug>.md
168
+ ```
169
+
170
+ `/mandrel-plan` owns interrogation, authoring and persistence from there.
171
+ 4. **No survivor** → the run ends at the bets document, and its
172
+ `## Missing evidence` section is the recommendation.
173
+
174
+ Every seed write and every `/mandrel-plan` invocation is confirmed
175
+ individually; one approval never covers the next survivor.
176
+
177
+ ---
178
+
179
+ ## Constraints
180
+
181
+ - **Read-only outside `temp/leverage/`.** The workflow never persists an
182
+ issue, never mutates a label, and never starts delivery.
183
+ - **Citations or nothing.** No bet is drafted, and no skeptic verdict is
184
+ scored, without a `path:line` or signal citation.
185
+ - **Maker-blind skeptics.** Bet block and evidence paths only; the caller
186
+ never overrides a verdict.
187
+ - **Refutations persist.** A prior refuted bet stays refuted unless new
188
+ evidence names what changed.
189
+ - **No project-specific refutations ship.** An operator may seed a first
190
+ run's `## Refuted` by hand from an earlier review.
191
+
192
+ ## See also
193
+
194
+ - [`/mandrel-plan`](mandrel-plan.md) — the planning pipeline Phase 4 chains
195
+ into; the plan → deliver hard stop is preserved across the handoff.
196
+ - [`/qa-assist`](qa-assist.md) — the precedent for light-within, firm-at-boundary
197
+ gating and the confirmed `/mandrel-plan` handoff.
198
+ - [`/audit-to-stories`](audit-to-stories.md) — the precedent for chaining
199
+ `/mandrel-plan --seed-file`.
@@ -172,4 +172,6 @@ source id ([ref](helpers/plan-reference.md)).
172
172
  ## See also
173
173
 
174
174
  [`/mandrel-deliver`](mandrel-deliver.md), [`/audit-to-stories`](audit-to-stories.md),
175
- [`helpers/plan-reference.md`](helpers/plan-reference.md) (on-demand detail).
175
+ [`/mandrel-leverage`](mandrel-leverage.md) (evidence-cited bets that chain in
176
+ as seeds), [`helpers/plan-reference.md`](helpers/plan-reference.md) (on-demand
177
+ detail).
package/README.md CHANGED
@@ -90,7 +90,7 @@ separate, planned pass.
90
90
 
91
91
  | Area | Lenses |
92
92
  | ---- | ------ |
93
- | Code & design | `architecture`, `clean-code`, `adrs`, `data-model`, `documentation`, `exceptions` |
93
+ | Code & design | `architecture`, `clean-code`, `adrs`, `data-model`, `documentation`, `exceptions`, `lean` |
94
94
  | Quality & ops | `quality`, `baselines`, `performance`, `devops`, `sre`, `dependencies` |
95
95
  | Security & privacy | `security`, `privacy` |
96
96
  | Product & UX | `ux-ui`, `accessibility`, `mobile`, `navigability`, `seo` |
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,54 @@ 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.96.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.95.0...mandrel-v2.96.0) (2026-10-21)
19
+
20
+
21
+ ### Added
22
+
23
+ * add /audit-red-team: a global adversarial lens that reports attack paths, abuse cases and agent exposure with a reproduced-or-reasoned evidence bar ([#5838](https://github.com/dsj1984/mandrel/issues/5838)) ([#5841](https://github.com/dsj1984/mandrel/issues/5841)) ([36bc0fb](https://github.com/dsj1984/mandrel/commit/36bc0fb34dea12c389f892c42f170026f5dfcd88))
24
+ * add /mandrel-leverage, a leverage review with maker-blind skeptics (refs [#5839](https://github.com/dsj1984/mandrel/issues/5839)) ([#5840](https://github.com/dsj1984/mandrel/issues/5840)) ([146310f](https://github.com/dsj1984/mandrel/commit/146310f9477d4753ca441f19bdde0c708263a1eb))
25
+
26
+
27
+ ### Fixed
28
+
29
+ * harden this repo's Claude Code settings and record why Bash and Write stay broad (refs [#5844](https://github.com/dsj1984/mandrel/issues/5844)) ([#5846](https://github.com/dsj1984/mandrel/issues/5846)) ([f56c028](https://github.com/dsj1984/mandrel/commit/f56c02861e91370c7cee89ab745c99e3706bcc6f))
30
+ * stop the issue-body conformance comment from echoing issue text as the Actions bot, and update one marker comment instead of posting a new one per edit ([#5843](https://github.com/dsj1984/mandrel/issues/5843)) ([#5845](https://github.com/dsj1984/mandrel/issues/5845)) ([bd6cbe7](https://github.com/dsj1984/mandrel/commit/bd6cbe70651408b5311be0629dc641db8953b80e))
31
+
32
+ ## [2.95.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.94.0...mandrel-v2.95.0) (2026-10-21)
33
+
34
+
35
+ ### Added
36
+
37
+ * observe invalid agent:: state transitions instead of leaving the transition table unwired ([#5805](https://github.com/dsj1984/mandrel/issues/5805)) ([#5821](https://github.com/dsj1984/mandrel/issues/5821)) ([68bb4c1](https://github.com/dsj1984/mandrel/commit/68bb4c122c99f96bcb70b0b10a1d40ca1f72885f))
38
+ * tighten the quality floors after the burn-down, refresh stale baselines, and stop check-baselines ignoring unknown gate kinds ([#5817](https://github.com/dsj1984/mandrel/issues/5817)) ([#5833](https://github.com/dsj1984/mandrel/issues/5833)) ([37705a7](https://github.com/dsj1984/mandrel/commit/37705a7ac6a44a1d1df080273c708b958d532246))
39
+
40
+
41
+ ### Fixed
42
+
43
+ * address the post-v2.94.0 review: accept js-yaml 4 at consumer roots, observe every agent:: transition, and close error-path regressions ([#5836](https://github.com/dsj1984/mandrel/issues/5836)) ([5e0c216](https://github.com/dsj1984/mandrel/commit/5e0c216e7b79b084427b20f565db59eada73ec12))
44
+ * clear the dev-only npm advisories and refresh dependencies: markdownlint-cli2 0.24 with js-yaml 5, jscpd 4.3, minor batch, c8 12, chokidar 6 ([#5815](https://github.com/dsj1984/mandrel/issues/5815)) ([#5831](https://github.com/dsj1984/mandrel/issues/5831)) ([aba9345](https://github.com/dsj1984/mandrel/commit/aba93456869d150f256bbb1694de1fc9db1d326e))
45
+ * **deps:** clear the markdown-it GHSA-gfr2-rv44-r23c advisory (refs [#5799](https://github.com/dsj1984/mandrel/issues/5799)) ([#5800](https://github.com/dsj1984/mandrel/issues/5800)) ([9f5ccd1](https://github.com/dsj1984/mandrel/commit/9f5ccd1d31977fcb19bc630ff8d769d37e7f2baa))
46
+ * fix [#5804](https://github.com/dsj1984/mandrel/issues/5804): gh-exec.js ends child.stdin with no 'error' listener, so a g… ([#5819](https://github.com/dsj1984/mandrel/issues/5819)) ([#5820](https://github.com/dsj1984/mandrel/issues/5820)) ([86a1ffb](https://github.com/dsj1984/mandrel/commit/86a1ffb9f9a95775ae1e7b25ad00fdd006871ed0))
47
+ * justify or remove the dead and unexplained exceptions: GitHub auth coverage ignores, knip/biome/prettier exemptions, eslint comments ([#5812](https://github.com/dsj1984/mandrel/issues/5812)) ([#5828](https://github.com/dsj1984/mandrel/issues/5828)) ([66213b9](https://github.com/dsj1984/mandrel/commit/66213b98f6e4ae8a79978926cc5a3691c8c779de))
48
+ * plan-persist --dry-run prints 'Rewrote #&lt;id&gt; in place; it is agent::rea… ([#5802](https://github.com/dsj1984/mandrel/issues/5802)) ([#5803](https://github.com/dsj1984/mandrel/issues/5803)) ([d39f797](https://github.com/dsj1984/mandrel/commit/d39f7970198f7a6487c53d53638ba58487e7a085))
49
+ * stop interactive /clean-git from dropping every stash: await the stash decision and drop only on an explicit 'drop' ([#5834](https://github.com/dsj1984/mandrel/issues/5834)) ([#5835](https://github.com/dsj1984/mandrel/issues/5835)) ([9c8c890](https://github.com/dsj1984/mandrel/commit/9c8c8909d31feb9ea684e9378969c5c67fc568d6))
50
+ * write sync output and orchestration state files atomically, and make mandrel sync skip unchanged files ([#5813](https://github.com/dsj1984/mandrel/issues/5813)) ([#5829](https://github.com/dsj1984/mandrel/issues/5829)) ([9760a2f](https://github.com/dsj1984/mandrel/commit/9760a2f056351a9c078a98d15e2d822160b8acd8))
51
+
52
+
53
+ ### Performance
54
+
55
+ * run mandrel doctor checks concurrently, dedupe claude --version, and probe the user rung first for user-owned boards ([#5814](https://github.com/dsj1984/mandrel/issues/5814)) ([#5830](https://github.com/dsj1984/mandrel/issues/5830)) ([a699bc0](https://github.com/dsj1984/mandrel/commit/a699bc001c10067deef5ee5ae275a5113688daaf))
56
+
57
+
58
+ ### Changed
59
+
60
+ * adopt the shared helpers the tree re-implements: toPosix, walkFiles, isObject, parseGateArgv, escapeRegExp ([#5816](https://github.com/dsj1984/mandrel/issues/5816)) ([#5832](https://github.com/dsj1984/mandrel/issues/5832)) ([ae332d3](https://github.com/dsj1984/mandrel/commit/ae332d364f2c53c46be7b4037a7e57beb3e8747b))
61
+ * burn down the bootstrap hotspots and collapse their duplicated JSON readers ([#5807](https://github.com/dsj1984/mandrel/issues/5807)) ([#5825](https://github.com/dsj1984/mandrel/issues/5825)) ([f07f470](https://github.com/dsj1984/mandrel/commit/f07f470862aaf131b5f5e0b8e924418225f12074))
62
+ * burn down the lib/cli/uninstall.js CRAP and cyclomatic hotspot ([#5808](https://github.com/dsj1984/mandrel/issues/5808)) ([#5822](https://github.com/dsj1984/mandrel/issues/5822)) ([883d16a](https://github.com/dsj1984/mandrel/commit/883d16a6aaafedeca3fc81fc93f52db44c6be589))
63
+ * burn down the remaining single-file hotspots: baselines/components, merge-block-class, group-findings, config-schema ([#5810](https://github.com/dsj1984/mandrel/issues/5810)) ([#5826](https://github.com/dsj1984/mandrel/issues/5826)) ([39136ff](https://github.com/dsj1984/mandrel/commit/39136ffeafc94c78b219ebcb40c5b116daa4f820))
64
+ * test the git-cleanup phase drivers and probes, and remove their pass-through forwarders ([#5809](https://github.com/dsj1984/mandrel/issues/5809)) ([#5824](https://github.com/dsj1984/mandrel/issues/5824)) ([b97880b](https://github.com/dsj1984/mandrel/commit/b97880b212bf942a52b77e0ecfebb6d2c442d945))
65
+
18
66
  ## [2.94.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.93.0...mandrel-v2.94.0) (2026-10-20)
19
67
 
20
68
 
@@ -5,8 +5,8 @@
5
5
  * framework never hydrates, so the check fails. A missing `claude` binary,
6
6
  * unparseable output, or a project still carrying CLAUDE.md skips with
7
7
  * `ok: true` so headless/CI hosts are never blocked. The `claude --version`
8
- * spawn is injected by the registry (fixed argv, never user input); with no
9
- * runner the check skips.
8
+ * spawn goes through the injected `runner` (fixed argv, never user input);
9
+ * with neither `runner` nor `runClaude` the check skips.
10
10
  *
11
11
  * @module cli/claude-code-version
12
12
  */
@@ -33,15 +33,21 @@ export function parseClaudeVersion(text) {
33
33
  * projectRoot?: string,
34
34
  * cwd?: () => string,
35
35
  * existsSync?: (p: string) => boolean,
36
- * runClaude?: () => { status: number|null, stdout: string, error?: NodeJS.ErrnoException },
36
+ * runner?: (cmd: string, args: string[], opts?: object) => unknown,
37
+ * runClaude?: () => { status: number|null, stdout: string, error?: NodeJS.ErrnoException } | Promise<{ status: number|null, stdout: string, error?: NodeJS.ErrnoException }>,
37
38
  * }} [opts]
38
- * @returns {{ ok: boolean, detail: string, remedy?: string }}
39
+ * @returns {Promise<{ ok: boolean, detail: string, remedy?: string }>}
39
40
  */
40
- export function runClaudeCodeVersion({
41
+ export async function runClaudeCodeVersion({
41
42
  projectRoot,
42
43
  cwd = () => process.cwd(),
43
44
  existsSync = fs.existsSync,
44
- runClaude = () => ({ status: null, stdout: '', error: new Error('none') }),
45
+ runner = () => ({ status: null, stdout: '', error: new Error('none') }),
46
+ runClaude = () =>
47
+ runner('claude', ['--version'], {
48
+ shell: process.platform === 'win32',
49
+ timeout: 10_000,
50
+ }),
45
51
  } = {}) {
46
52
  const root = projectRoot ?? cwd();
47
53
  if (existsSync(path.join(root, 'CLAUDE.md'))) {
@@ -50,7 +56,7 @@ export function runClaudeCodeVersion({
50
56
  if (!existsSync(path.join(root, 'AGENTS.md'))) {
51
57
  return { ok: true, detail: 'skipped: no AGENTS.md' };
52
58
  }
53
- const r = runClaude();
59
+ const r = await runClaude();
54
60
  if (r.error || r.status !== 0) {
55
61
  return { ok: true, detail: 'skipped: claude not found on PATH' };
56
62
  }