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
package/.agents/README.md CHANGED
@@ -269,7 +269,12 @@ and the prompt falls through to manual free-text entry — so a missing or
269
269
  stale `gh` never breaks the run.
270
270
 
271
271
  For non-interactive (CI) installs, pass `--owner`, `--repo`, and
272
- `--assume-yes`; pass `--skip-github` to defer the remote half.
272
+ `--assume-yes`; pass `--skip-github` to defer the remote half. A
273
+ non-interactive run creates no Projects V2 board unless one is stored in
274
+ `.agentrc.json` or named with `--project-number <name>`; `--no-project` (or an
275
+ empty / `none` `--project-number` or `GH_PROJECT_NUMBER`) skips it explicitly,
276
+ and labels are still provisioned. Interactively declining a new project also
277
+ continues without a board.
273
278
 
274
279
  After bootstrap, every Mandrel command is generated into a flat
275
280
  `.claude/commands/` tree by `npm run sync:commands` (kept current at install
@@ -13,6 +13,7 @@ Self-check your change against this lens's concerns before you ship:
13
13
  - [ ] Cycle detection.
14
14
  - [ ] Dead-export detection.
15
15
  - [ ] Hotspot ranking.
16
+ - [ ] Non-JS ecosystems.
16
17
  - [ ] LLM triage on top.
17
18
  - [ ] Documented architecture boundaries
18
19
  - [ ] Automated boundary checks
@@ -19,6 +19,7 @@ Self-check your change against this lens's concerns before you ship:
19
19
  - [ ] Dynamic imports
20
20
  - [ ] Test-only seams
21
21
  - [ ] Framework/registration hooks
22
+ - [ ] Non-JS ecosystems.
22
23
  - [ ] Churn-by-complexity hotspot cap.
23
24
  - [ ] Logic Complexity
24
25
  - [ ] Duplication
@@ -10,10 +10,13 @@
10
10
 
11
11
  Self-check your change against this lens's concerns before you ship:
12
12
 
13
- - [ ] Workflow static analysis (`actionlint`).
13
+ - [ ] Workflow static analysis (`actionlint`, GitHub Actions only).
14
14
  - [ ] Workflow security posture (`zizmor`).
15
15
  - [ ] Container linting (`hadolint`), presence-gated on Dockerfiles.
16
16
  - [ ] Pipeline reliability history (`gh run list`).
17
+ - [ ] Google Cloud Build (gated: `cloudbuild*.yaml` present).
18
+ - [ ] GitLab CI (gated: `.gitlab-ci.yml` present).
19
+ - [ ] Python toolchain (gated: Python manifests present).
17
20
  - [ ] Redundancy & Duplication
18
21
  - [ ] Performance Gaps
19
22
  - [ ] Security & Compliance
@@ -10,7 +10,7 @@
10
10
 
11
11
  Self-check your change against this lens's concerns before you ship:
12
12
 
13
- - [ ] Dependency CVEs (`npm audit`).
13
+ - [ ] Dependency CVEs, per detected ecosystem.
14
14
  - [ ] Secret scanning (`gitleaks` / `trufflehog`), with a grep fallback.
15
15
  - [ ] Grep battery (deterministic fallback / augmentation).
16
16
  - [ ] Manual surface review.
@@ -85,7 +85,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
85
85
  | `paths.tempRoot` | Yes | `string` | `"temp"` | Repo-relative gitignored scratch root. Every temporary artifact — gate transcripts, audit reports, plan authoring dirs — lands under it. |
86
86
  | `docsContextFiles` | No | `array<string>` | `["architecture.md","data-dictionary.md","decisions.md","patterns.md"]` | Files under `paths.docsRoot` the planner treats as standing context. Read digest-first — the docs digest names the file and the line range, and only the named section is pulled. |
87
87
  | `commands` | No | `object` | — | Shell commands the close-validation chain spawns. Each is run from the repo root. |
88
- | `commands.test` | No | `string` | `"npm test"` | Full test-suite command run by the close-validation chain. |
88
+ | `commands.test` | No | `string` | `"npm test"` | Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution). |
89
89
  | `commands.typecheck` | No | `string` \| `null` | `null` | Static type-check command. `null` disables the gate for projects with no type layer; the empty string is rejected so a typo cannot silently disable it. |
90
90
  | `commands.lint` | No | `string` \| `null` | `null` | Lint command run as a close-validation gate. `null` (the default) uses `npm run lint`; the gate is mandatory, so unlike `typecheck` this key cannot disable it. Point it at the scoped command your hooks already run to stop paying for a third whole-repo lint at close — the gate still lints the diff, and CI still owns whole-repo drift. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-linter pair in one npm script and name that. |
91
91
  | `commands.formatCheck` | No | `string` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. |
@@ -81,7 +81,7 @@
81
81
  "pattern": "([;&|`]|\\$\\()"
82
82
  },
83
83
  "minLength": 1,
84
- "description": "Full test-suite command run by the close-validation chain.",
84
+ "description": "Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution).",
85
85
  "default": "npm test"
86
86
  },
87
87
  "typecheck": {
@@ -48,7 +48,13 @@ Flags:
48
48
  private | public | internal (default: private)
49
49
  --operator-handle <name> GitHub handle for github.operatorHandle
50
50
  --base-branch <name> Base branch (default: origin/HEAD or 'main')
51
- --project-number <n> Projects V2 number/name (optional)
51
+ --project-number <n> Projects V2 number/name (optional). An empty
52
+ value or \`none\` skips the board. A non-
53
+ interactive run with no stored number skips it
54
+ unless a name/number is given.
55
+ --no-project Skip the Projects V2 board (labels are still
56
+ provisioned). GH_PROJECT_NUMBER set to empty or
57
+ \`none\` does the same.
52
58
  --assume-yes Accept every default + approve GitHub-admin
53
59
  mutations. A non-TTY run requires this (or
54
60
  --approve-github-admin) — there is no operator
@@ -405,8 +411,25 @@ async function createGithubProject(state, execImpl = exec) {
405
411
  return number;
406
412
  }
407
413
 
408
- /** The Step 3 question list. */
409
- export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
414
+ /** A stored number first, so a re-run never reads as a new board. */
415
+ function projectDefault(defaults, flags, opts) {
416
+ if (defaults.projectNumber) return defaults.projectNumber;
417
+ const interactive = opts.interactive ?? !flags?.['assume-yes'];
418
+ return interactive ? defaults.repo : null;
419
+ }
420
+
421
+ /**
422
+ * The Step 3 question list. `opts.interactive` (default: no `--assume-yes`)
423
+ * picks the project default: a non-interactive run never creates a board
424
+ * from the repo name — only a stored number or an explicit value selects one.
425
+ */
426
+ export function buildQuestions(
427
+ defaults,
428
+ flags,
429
+ env = process.env,
430
+ lists = {},
431
+ opts = {},
432
+ ) {
410
433
  const owner = resolveOwnerForPicker(defaults, flags, env);
411
434
  // Pre-fetched lists are empty when the owner was unknown up front, so the
412
435
  // pickers fall back to a live fetch keyed off the typed `answers.owner`.
@@ -473,11 +496,11 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
473
496
  key: 'projectNumber',
474
497
  flag: 'project-number',
475
498
  env: 'GH_PROJECT_NUMBER',
499
+ skipFlag: 'no-project',
476
500
  message: 'New GitHub Project V2 name',
477
501
  pickerMessage:
478
502
  'GitHub Project V2 name - Select existing or press ENTER to create',
479
- // A stored number first, so a re-run never reads as a new board.
480
- default: defaults.projectNumber || defaults.repo,
503
+ default: projectDefault(defaults, flags, opts),
481
504
  required: false,
482
505
  picker: {
483
506
  list: (answers) => {
@@ -769,14 +792,51 @@ async function resolveOptIns(state) {
769
792
  return optIns;
770
793
  }
771
794
 
772
- async function approveCreation(state, creation) {
773
- if (state.flags['dry-run'] || !(creation.newRepo || creation.newProject)) {
774
- return true;
795
+ /**
796
+ * Approve each new resource separately. A declined repo aborts (nothing can
797
+ * continue without it); a declined project clears `projectNumber` and the run
798
+ * continues without a board, so labels are still provisioned.
799
+ *
800
+ * @returns {Promise<boolean>} false only when repo creation is declined.
801
+ */
802
+ export async function approveCreation(
803
+ state,
804
+ answers,
805
+ creation,
806
+ confirm = confirmYesNo,
807
+ ) {
808
+ if (state.flags['dry-run']) return true;
809
+ if (!(await approveNewRepo(state, answers, creation, confirm))) return false;
810
+ await approveNewProject(state, answers, creation, confirm);
811
+ return true;
812
+ }
813
+
814
+ async function approveNewRepo(state, answers, creation, confirm) {
815
+ if (!creation.newRepo) return true;
816
+ const ok = await confirm(
817
+ `Create the new GitHub repo ${answers.owner}/${answers.repo}?`,
818
+ state.interactive,
819
+ );
820
+ if (!ok) {
821
+ Logger.error(
822
+ '[Bootstrap] Repo creation declined — cannot continue without the repo. Exiting.',
823
+ );
775
824
  }
776
- return confirmYesNo(
777
- 'Create the new GitHub repo/project listed above?',
825
+ return ok;
826
+ }
827
+
828
+ async function approveNewProject(state, answers, creation, confirm) {
829
+ if (!creation.newProject) return;
830
+ const ok = await confirm(
831
+ `Create the new GitHub Project V2 "${answers.projectNumber}"?`,
778
832
  state.interactive,
779
833
  );
834
+ if (ok) return;
835
+ answers.projectNumber = '';
836
+ creation.newProject = false;
837
+ Logger.info(
838
+ '[Bootstrap] Project creation declined — skipping the Projects V2 board and continuing.',
839
+ );
780
840
  }
781
841
 
782
842
  async function confirmSummary(state, answers, creation, projectsList) {
@@ -819,6 +879,7 @@ export async function collectAndConfirm(state) {
819
879
  state.flags,
820
880
  process.env,
821
881
  lists,
882
+ { interactive: state.interactive },
822
883
  ),
823
884
  flags: state.flags,
824
885
  interactive: state.interactive,
@@ -844,10 +905,7 @@ export async function collectAndConfirm(state) {
844
905
  silentAccept = [];
845
906
  continue;
846
907
  }
847
- if (!(await approveCreation(state, creation))) {
848
- Logger.error(
849
- '[Bootstrap] Creation declined — cannot continue without the repo/project. Exiting.',
850
- );
908
+ if (!(await approveCreation(state, answers, creation))) {
851
909
  return { ok: false, exit: 1 };
852
910
  }
853
911
  const optIns = await resolveOptIns(state);
@@ -855,7 +913,7 @@ export async function collectAndConfirm(state) {
855
913
  }
856
914
  }
857
915
 
858
- function renderDryRunPlan(state) {
916
+ export function renderDryRunPlan(state) {
859
917
  const a = state.answers ?? {};
860
918
  const c = state.creation ?? {};
861
919
  const flagList = Object.entries(state.flags ?? {}).map(([k, v]) =>
@@ -994,6 +1052,19 @@ export function persistProjectNumber(state) {
994
1052
  return { ok: true, payload: {} };
995
1053
  }
996
1054
 
1055
+ /**
1056
+ * `--with-project-board` decorates a board only when one was selected: with
1057
+ * the project skipped, `runBootstrap` would otherwise create one.
1058
+ */
1059
+ export function resolveBoardDecoration(state) {
1060
+ if (state.withProjectBoard !== true) return false;
1061
+ if (String(state.answers?.projectNumber ?? '').length > 0) return true;
1062
+ Logger.info(
1063
+ '[Bootstrap] Projects V2 board skipped — skipping board decoration (--with-project-board ignored).',
1064
+ );
1065
+ return false;
1066
+ }
1067
+
997
1068
  /** Step 6b — GitHub-side bootstrap. Honours `--skip-github`. */
998
1069
  export async function executeGithubBootstrap(state) {
999
1070
  if (state.flags['skip-github']) {
@@ -1004,7 +1075,7 @@ export async function executeGithubBootstrap(state) {
1004
1075
  state.report.github = await runGithubBootstrap(state.answers, {
1005
1076
  assumeYes: state.assumeYes,
1006
1077
  githubAdminApproved: state.githubAdminApproved === true,
1007
- withProjectBoard: state.withProjectBoard === true,
1078
+ withProjectBoard: resolveBoardDecoration(state),
1008
1079
  reapConflictingWorkflows: Boolean(
1009
1080
  state.flags['reap-conflicting-workflows'],
1010
1081
  ),
@@ -11,8 +11,9 @@ import fs from 'node:fs';
11
11
  import path from 'node:path';
12
12
 
13
13
  /**
14
- * Mirrors what the bootstrap writes; `.claude/commands/` is generated and
15
- * gitignored, so it is absent.
14
+ * Mirrors what the bootstrap writes; the `.claude/commands/` and
15
+ * `.claude/agents/` projections are generated by `prepare` and gitignored,
16
+ * so both are absent.
16
17
  *
17
18
  * @type {readonly string[]}
18
19
  */
@@ -81,7 +81,7 @@ export function buildMutationManifest(ctx = {}) {
81
81
  target: rel('.gitignore'),
82
82
  action: 'merge',
83
83
  detail:
84
- 'Ignore .claude/commands/ (generated), .mcp.json + .env (carry secrets), and the per-clone install ledger.',
84
+ 'Ignore the .claude/commands/ and .claude/agents/ projections (generated by prepare), .mcp.json + .env (carry secrets), and the per-clone install ledger.',
85
85
  reversible: true,
86
86
  },
87
87
  );
@@ -101,7 +101,7 @@ export function buildMutationManifest(ctx = {}) {
101
101
  target: rel('package.json'),
102
102
  action: 'merge',
103
103
  detail:
104
- 'Seed/merge the sync:commands, prepare, and bootstrap npm scripts.',
104
+ 'Seed/merge the sync:commands, sync:agents, prepare, and bootstrap npm scripts. `prepare` is guarded: it exits 0 without writing when .agents/scripts/ is absent (a manifest-only container `npm ci`), and otherwise regenerates the .claude/commands/ and .claude/agents/ projections — both gitignored.',
105
105
  reversible: true,
106
106
  },
107
107
  {
@@ -29,6 +29,19 @@ export const SYNC_AGENTS_COMMAND = 'node .agents/scripts/sync-claude-agents.js';
29
29
 
30
30
  export const BOOTSTRAP_COMMAND = 'node .agents/scripts/bootstrap.js';
31
31
 
32
+ /** The pre-guard `prepare` form; bootstrap and the 2.79.0 migration upgrade it. */
33
+ export const LEGACY_PREPARE_COMMAND = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
34
+
35
+ /**
36
+ * Exits 1 when `.agents/scripts/` exists so `||` runs the projections, and 0
37
+ * otherwise so a manifest-only `npm ci` (no `.agents/` yet) skips them. Only
38
+ * `node -e` and `||`/`&&`/`()` — portable across npm's sh and cmd shells.
39
+ */
40
+ const PREPARE_GUARD = `node -e "process.exit(require('fs').existsSync('.agents/scripts')?1:0)"`;
41
+
42
+ /** The `prepare` script bootstrap writes: guarded, then both projections. */
43
+ export const PREPARE_COMMAND = `${PREPARE_GUARD} || (${LEGACY_PREPARE_COMMAND})`;
44
+
32
45
  export { SYSTEM_PROMPT_BLOCK, SYSTEM_PROMPT_IMPORT };
33
46
 
34
47
  /** Install template for a fresh AGENTS.md (also the legacy CLAUDE.md one). */
@@ -40,6 +53,11 @@ export const GITIGNORE_BLOCKS = Object.freeze({
40
53
  block:
41
54
  '\n# Claude Code command projection is generated from .agents/workflows/ — do not commit.\n.claude/commands/\n',
42
55
  },
56
+ agents: {
57
+ pattern: /^\s*\.claude\/agents\/?\s*$/m,
58
+ block:
59
+ '\n# Claude Code agent projection is generated from .agents/agents/ by `prepare` — do not commit.\n.claude/agents/\n',
60
+ },
43
61
  mcp: {
44
62
  pattern: /^\s*\.mcp\.json\s*$/m,
45
63
  block:
@@ -137,22 +155,38 @@ function ensureScript(scripts, key, command) {
137
155
  return 'added';
138
156
  }
139
157
 
140
- /** Append each projection independently so a partial prepare gains the other. */
141
- function ensurePrepareScript(scripts) {
158
+ /** Each projection `prepare` must run: [script file it names, its command]. */
159
+ const PREPARE_PROJECTIONS = Object.freeze([
160
+ ['sync-claude-commands.js', SYNC_COMMAND],
161
+ ['sync-claude-agents.js', SYNC_AGENTS_COMMAND],
162
+ ]);
163
+
164
+ /** Outcomes that mean `ensurePackageJson` changed the manifest. */
165
+ const PACKAGE_JSON_MUTATIONS = new Set([true, 'added', 'appended', 'upgraded']);
166
+
167
+ /**
168
+ * Seed the guarded `prepare`, upgrade the exact legacy bare form to it, and
169
+ * otherwise append each missing projection so a partial prepare gains the
170
+ * other. An operator `prepare` already naming both scripts is left alone.
171
+ *
172
+ * @param {Record<string, string>} scripts - Mutated in place.
173
+ * @returns {'added'|'upgraded'|'appended'|'already-present'}
174
+ */
175
+ export function ensurePrepareScript(scripts) {
142
176
  const prepare = scripts.prepare;
143
177
  if (!prepare) {
144
- scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
178
+ scripts.prepare = PREPARE_COMMAND;
145
179
  return 'added';
146
180
  }
147
- let next = prepare;
148
- if (!next.includes('sync-claude-commands.js')) {
149
- next = `${next} && ${SYNC_COMMAND}`;
150
- }
151
- if (!next.includes('sync-claude-agents.js')) {
152
- next = `${next} && ${SYNC_AGENTS_COMMAND}`;
181
+ if (prepare === LEGACY_PREPARE_COMMAND) {
182
+ scripts.prepare = PREPARE_COMMAND;
183
+ return 'upgraded';
153
184
  }
154
- if (next === prepare) return 'already-present';
155
- scripts.prepare = next;
185
+ const missing = PREPARE_PROJECTIONS.filter(
186
+ ([script]) => !prepare.includes(script),
187
+ ).map(([, command]) => command);
188
+ if (missing.length === 0) return 'already-present';
189
+ scripts.prepare = [prepare, ...missing].join(' && ');
156
190
  return 'appended';
157
191
  }
158
192
 
@@ -190,8 +224,8 @@ export function ensurePackageJson(ctx) {
190
224
  scriptsPrepare: ensurePrepareScript(pkg.scripts),
191
225
  scriptsBootstrap: ensureScript(pkg.scripts, 'bootstrap', BOOTSTRAP_COMMAND),
192
226
  };
193
- const mutated = Object.values(outcomes).some(
194
- (v) => v === true || v === 'added' || v === 'appended',
227
+ const mutated = Object.values(outcomes).some((v) =>
228
+ PACKAGE_JSON_MUTATIONS.has(v),
195
229
  );
196
230
  if (mutated) writeJson(pkgPath, pkg, fsImpl);
197
231
  return { ...outcomes, path: pkgPath, mutated };
@@ -309,8 +343,9 @@ async function validateAgentrc(ctx) {
309
343
  *
310
344
  * @param {object} ctx
311
345
  * @param {typeof fs} [ctx.fsImpl]
346
+ * @param {readonly string[]} [keys] - Restrict to these block keys (default: all).
312
347
  */
313
- export function ensureGitignore(ctx) {
348
+ export function ensureGitignore(ctx, keys = Object.keys(GITIGNORE_BLOCKS)) {
314
349
  const { fsImpl = fs } = ctx;
315
350
  const target = path.join(ctx.projectRoot, '.gitignore');
316
351
  const existing = fsImpl.existsSync(target)
@@ -318,7 +353,8 @@ export function ensureGitignore(ctx) {
318
353
  : '';
319
354
  let body = existing;
320
355
  const outcomes = {};
321
- for (const [key, def] of Object.entries(GITIGNORE_BLOCKS)) {
356
+ for (const key of keys) {
357
+ const def = GITIGNORE_BLOCKS[key];
322
358
  if (def.pattern.test(body)) {
323
359
  outcomes[key] = 'already-present';
324
360
  continue;
@@ -26,6 +26,7 @@ const KNOWN_FLAGS = Object.freeze({
26
26
  'help',
27
27
  'dry-run',
28
28
  'reap-conflicting-workflows',
29
+ 'no-project',
29
30
  ],
30
31
  });
31
32
 
@@ -154,6 +155,30 @@ export function inferDefaults(projectRoot) {
154
155
  * @property {NodeJS.WritableStream} output
155
156
  */
156
157
 
158
+ /** A bare flag (`true`), an empty value, or `none` is an explicit skip. */
159
+ const isSkipToken = (v) =>
160
+ v === true ||
161
+ (typeof v === 'string' && ['', 'none'].includes(v.trim().toLowerCase()));
162
+
163
+ /**
164
+ * Explicit skip for a question carrying `skipFlag` → `''`, which no later
165
+ * resolver or default overrides. An env var skips only when PRESENT and no
166
+ * value flag is set.
167
+ *
168
+ * @param {ResolverContext} ctx
169
+ * @returns {{ kind: 'value'|'skip', value?: string }}
170
+ */
171
+ function resolveExplicitSkip({ q, flags, env }) {
172
+ if (!q.skipFlag) return { kind: 'skip' };
173
+ const flagValue = flags[q.flag];
174
+ const envSkip =
175
+ flagValue === undefined &&
176
+ Object.hasOwn(env, q.env ?? '') &&
177
+ isSkipToken(env[q.env]);
178
+ const skip = flags[q.skipFlag] === true || isSkipToken(flagValue) || envSkip;
179
+ return skip ? { kind: 'value', value: '' } : { kind: 'skip' };
180
+ }
181
+
157
182
  /**
158
183
  * @param {ResolverContext} ctx
159
184
  * @returns {{ kind: 'value'|'skip', value?: string }}
@@ -299,6 +324,7 @@ export function resolveAssumeYes(ctx) {
299
324
 
300
325
  /** Priority order; the first non-`skip` outcome wins. */
301
326
  export const RESOLVERS = Object.freeze([
327
+ resolveExplicitSkip,
302
328
  resolveFromFlag,
303
329
  resolveFromEnv,
304
330
  resolveFromSilent,
@@ -313,11 +339,13 @@ export const RESOLVERS = Object.freeze([
313
339
  * @param {object} args
314
340
  * @param {Array<{ key: string, flag: string, env?: string, message: string,
315
341
  * default?: string|null, required?: boolean,
342
+ * skipFlag?: string,
316
343
  * validate?: (v: string) => string|null }>} args.questions
317
344
  * @param {Record<string, string|boolean>} args.flags
318
345
  * @param {boolean} args.interactive
319
346
  * @param {boolean} args.assumeYes
320
347
  * @param {Iterable<string>} [args.silentAccept]
348
+ * @param {NodeJS.ProcessEnv} [args.env=process.env]
321
349
  * @param {NodeJS.ReadableStream} [args.input=process.stdin]
322
350
  * @param {NodeJS.WritableStream} [args.output=process.stdout]
323
351
  * @returns {Promise<{ answers: Record<string, string>, missing: string[] }>}
@@ -329,6 +357,7 @@ export async function collectAnswers(args) {
329
357
  interactive,
330
358
  assumeYes,
331
359
  silentAccept,
360
+ env = process.env,
332
361
  input = process.stdin,
333
362
  output = process.stdout,
334
363
  } = args;
@@ -345,7 +374,7 @@ export async function collectAnswers(args) {
345
374
  const ctx = {
346
375
  q,
347
376
  flags,
348
- env: process.env,
377
+ env,
349
378
  silentSet,
350
379
  interactive,
351
380
  assumeYes,
@@ -13,6 +13,13 @@ const TYPECHECK_FALLBACK = 'npm run typecheck';
13
13
  */
14
14
  const LINT_FALLBACK = 'npm run lint';
15
15
 
16
+ /**
17
+ * Must stay byte-identical: it is the close `test` gate's argv and the credit
18
+ * identity `test-run-credit` and `verify-credit` hash, so drift would
19
+ * invalidate every recorded `test` evidence record.
20
+ */
21
+ const TEST_FALLBACK = 'npm test';
22
+
16
23
  export const FORMAT_CHECK_FALLBACK = 'npx biome format .';
17
24
 
18
25
  const FORMAT_WRITE_FALLBACK = 'npx biome format --write .';
@@ -63,6 +70,32 @@ export function resolveLintCommand(config) {
63
70
  return resolveCommandWithFallback(config, 'lint', LINT_FALLBACK);
64
71
  }
65
72
 
73
+ /**
74
+ * The close `test` gate's command. Like every `project.commands.*` key it is a
75
+ * single argv — the schema rejects `;`, `&&`, pipes and substitution.
76
+ *
77
+ * @param {{ project?: { commands?: object } } | null | undefined} config
78
+ * @returns {string}
79
+ */
80
+ export function resolveTestCommand(config) {
81
+ return resolveCommandWithFallback(config, 'test', TEST_FALLBACK);
82
+ }
83
+
84
+ /**
85
+ * The argv close's `test` gate spawns — the one identity every `test`
86
+ * credit (deposit, close probe, `verify[]` credit) hashes. Whitespace split,
87
+ * as the gate builder splits every other `commands.*` key.
88
+ *
89
+ * @param {{ project?: { commands?: object } } | null | undefined} config
90
+ * @returns {{ cmd: string, args: string[] }}
91
+ */
92
+ export function resolveTestGateArgv(config) {
93
+ const [cmd, ...args] = resolveTestCommand(config)
94
+ .split(/\s+/)
95
+ .filter(Boolean);
96
+ return { cmd, args };
97
+ }
98
+
66
99
  /**
67
100
  * @param {{ project?: { commands?: object } } | null | undefined} config
68
101
  * @returns {string}
@@ -15,6 +15,7 @@ import {
15
15
  resolveFormatCheckCommand,
16
16
  resolveFormatWriteCommand,
17
17
  resolveLintCommand,
18
+ resolveTestGateArgv,
18
19
  resolveTypecheckCommand,
19
20
  } from './commands.js';
20
21
 
@@ -80,16 +81,20 @@ function isCoverageCaptureActive(config, scripts) {
80
81
 
81
82
  /**
82
83
  * The plain `test` gate, unless coverage-capture will run the suite — every
83
- * close must keep exactly one working test gate.
84
+ * close must keep exactly one working test gate. Its argv is
85
+ * `project.commands.test` (default `npm test`).
84
86
  *
85
87
  * @param {boolean} coverageCaptureRunsSuite
88
+ * @param {object|undefined|null} config - Canonical resolved config.
86
89
  * @returns {Gate[]}
87
90
  */
88
- function buildTestGateEntry(coverageCaptureRunsSuite) {
91
+ function buildTestGateEntry(coverageCaptureRunsSuite, config) {
89
92
  if (coverageCaptureRunsSuite) return [];
90
93
  // `fullSuiteLock` serializes this suite behind the host lock; when
91
94
  // coverage-capture runs instead, `runCapture` takes the lock itself.
92
- return [{ name: 'test', cmd: 'npm', args: ['test'], fullSuiteLock: true }];
95
+ return [
96
+ { name: 'test', ...resolveTestGateArgv(config), fullSuiteLock: true },
97
+ ];
93
98
  }
94
99
 
95
100
  const CHECK_BASELINES_HINT =
@@ -424,10 +429,11 @@ export function buildDefaultGates({
424
429
  } = {}) {
425
430
  const scripts = packageScripts ?? readPackageScripts(cwd);
426
431
  const coverageCaptureActive = isCoverageCaptureActive(config, scripts);
427
- // A credited bare `npm test` registers the plain `test` gate beside the
432
+ // A credited `project.commands.test` run registers the plain `test` gate beside the
428
433
  // capture so the credit is reported, never re-spent.
429
434
  const testCredited = resolveTestCredited({
430
435
  coverageCaptureActive,
436
+ config,
431
437
  storyId,
432
438
  cwd,
433
439
  evidenceCwd,
@@ -491,6 +497,7 @@ export function buildDefaultGates({
491
497
  captureSkipPredicted,
492
498
  testCredited,
493
499
  }),
500
+ config,
494
501
  ),
495
502
  {
496
503
  name: 'format',
@@ -45,7 +45,8 @@ const KEY_MEANINGS = Object.freeze({
45
45
  'Root for gitignored scratch output (per-run state, mirrors, logs).',
46
46
  'project.docsContextFiles':
47
47
  'Authoritative files an agent must read before starting any task.',
48
- 'project.commands.test': 'Test command the close-validation chain runs.',
48
+ 'project.commands.test':
49
+ "Test command close's `test` gate runs and its credit identity hashes.",
49
50
  'project.commands.typecheck':
50
51
  'Typecheck command (null disables the typecheck gate).',
51
52
  'project.commands.formatCheck':
@@ -85,7 +85,8 @@ const COMMANDS_SCHEMA = {
85
85
  test: {
86
86
  ...SAFE_STRING,
87
87
  minLength: 1,
88
- description: 'Full test-suite command run by the close-validation chain.',
88
+ description:
89
+ "Full test-suite command close's `test` gate spawns, and the identity its `test` credit is hashed under — the deposit `run-tests.js` makes, close's credit probe and `verify[]` credit all key on it, as does `mandrel doctor`'s `test-credit-path` check. Set it for a non-npm project (e.g. `python3 scripts/validation.py`); unset, it is `npm test`. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution).",
89
90
  default: COMMANDS_DEFAULTS.test,
90
91
  },
91
92
  typecheck: {