mandrel 2.89.0 → 2.91.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 (175) hide show
  1. package/.agents/README.md +47 -7
  2. package/.agents/agents/story-worker.md +20 -0
  3. package/.agents/audit-checklists/lean.md +26 -0
  4. package/.agents/docs/agentrc-reference.json +5 -6
  5. package/.agents/docs/configuration.md +38 -30
  6. package/.agents/docs/workflows.md +7 -1
  7. package/.agents/instructions.md +3 -1
  8. package/.agents/runtime-deps.json +0 -2
  9. package/.agents/schemas/agentrc.schema.json +46 -45
  10. package/.agents/schemas/audit-rules.json +19 -0
  11. package/.agents/scripts/acceptance-eval.js +2 -6
  12. package/.agents/scripts/audit-exceptions.js +2 -4
  13. package/.agents/scripts/board-backfill.js +253 -0
  14. package/.agents/scripts/check-arch-cycles.js +1 -5
  15. package/.agents/scripts/check-context-budget.js +1 -5
  16. package/.agents/scripts/check-cyclomatic.js +1 -5
  17. package/.agents/scripts/check-dead-exports.js +23 -14
  18. package/.agents/scripts/check-doc-links.js +4 -4
  19. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  20. package/.agents/scripts/coverage-capture.js +14 -6
  21. package/.agents/scripts/diagnose-friction.js +8 -10
  22. package/.agents/scripts/generate-workflows-doc.js +5 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  24. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  25. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  26. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  27. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  28. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  29. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  30. package/.agents/scripts/lib/baselines/components.js +5 -5
  31. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  32. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  33. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  34. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  36. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  37. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  38. package/.agents/scripts/lib/baselines/writer.js +4 -4
  39. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  40. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  41. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  42. package/.agents/scripts/lib/child-exec.js +4 -4
  43. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  44. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  45. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  46. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  47. package/.agents/scripts/lib/close-validation/process.js +5 -1
  48. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  49. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  50. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  51. package/.agents/scripts/lib/config/commands.js +82 -7
  52. package/.agents/scripts/lib/config/explain.js +2 -1
  53. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  54. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  55. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  56. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  57. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  58. package/.agents/scripts/lib/config/git-roots.js +120 -0
  59. package/.agents/scripts/lib/config/quality.js +46 -50
  60. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  61. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  62. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  63. package/.agents/scripts/lib/config-resolver.js +5 -9
  64. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  65. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  66. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  67. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  68. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  69. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  70. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  71. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture.js +80 -43
  73. package/.agents/scripts/lib/coverage-utils.js +34 -16
  74. package/.agents/scripts/lib/cpu-pool.js +2 -4
  75. package/.agents/scripts/lib/crap-engine.js +19 -1
  76. package/.agents/scripts/lib/crap-utils.js +2 -1
  77. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  78. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  79. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  80. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  81. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  82. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  83. package/.agents/scripts/lib/gh-env.js +72 -0
  84. package/.agents/scripts/lib/gh-exec.js +26 -1
  85. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  86. package/.agents/scripts/lib/npm-scripts.js +1 -1
  87. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  88. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  89. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  90. package/.agents/scripts/lib/orchestration/board-access-latch.js +112 -0
  91. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  92. package/.agents/scripts/lib/orchestration/column-sync.js +107 -52
  93. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  94. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  95. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  96. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  97. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  98. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  99. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +44 -17
  100. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  101. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  102. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  103. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  104. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  105. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  106. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  107. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  108. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  109. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  110. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  111. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  112. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  113. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  114. package/.agents/scripts/lib/orchestration/story-handoff.js +27 -6
  115. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  116. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  117. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  118. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  119. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  120. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  121. package/.agents/scripts/lib/source-extensions.js +30 -15
  122. package/.agents/scripts/lib/test-run-credit.js +1 -9
  123. package/.agents/scripts/lib/test-temp.js +22 -21
  124. package/.agents/scripts/lib/util/ajv.js +111 -0
  125. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  126. package/.agents/scripts/lib/util/paths.js +51 -0
  127. package/.agents/scripts/lib/util/sleep.js +6 -0
  128. package/.agents/scripts/lib/util/slug.js +12 -0
  129. package/.agents/scripts/lib/validation-evidence.js +19 -40
  130. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  131. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  132. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  133. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  134. package/.agents/scripts/lint-issue-body.js +2 -2
  135. package/.agents/scripts/plan-context.js +2 -7
  136. package/.agents/scripts/providers/github/auth.js +3 -3
  137. package/.agents/scripts/providers/github/board-add.js +18 -9
  138. package/.agents/scripts/providers/github/errors.js +3 -1
  139. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  140. package/.agents/scripts/providers/github/issues.js +6 -2
  141. package/.agents/scripts/providers/github/mappers.js +1 -5
  142. package/.agents/scripts/providers/github/projects-v2-graphql.js +26 -6
  143. package/.agents/scripts/providers/github/search-budget.js +3 -1
  144. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  145. package/.agents/scripts/sync-agentrc.js +5 -14
  146. package/.agents/scripts/sync-claude-agents.js +38 -150
  147. package/.agents/scripts/sync-claude-commands.js +35 -218
  148. package/.agents/scripts/update-coverage-baseline.js +1 -1
  149. package/.agents/scripts/update-crap-baseline.js +1 -1
  150. package/.agents/scripts/update-duplication-baseline.js +2 -16
  151. package/.agents/scripts/validate-skills.js +6 -10
  152. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  153. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  154. package/.agents/workflows/audit-exceptions.md +9 -0
  155. package/.agents/workflows/audit-lean.md +129 -0
  156. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  157. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  158. package/.agents/workflows/helpers/code-review.md +15 -1
  159. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  160. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  161. package/.agents/workflows/mandrel-plan.md +2 -2
  162. package/docs/CHANGELOG.md +48 -0
  163. package/lib/cli/doctor-checks/codex.js +6 -5
  164. package/lib/cli/doctor-checks/llm-review.js +102 -0
  165. package/lib/cli/doctor-checks/project-access.js +124 -0
  166. package/lib/cli/doctor-checks/sync-parity.js +65 -140
  167. package/lib/cli/doctor-checks/test-credit-path.js +69 -28
  168. package/lib/cli/doctor-checks/toolchain.js +5 -3
  169. package/lib/cli/registry.js +11 -0
  170. package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
  171. package/lib/migrations/index.js +6 -0
  172. package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
  173. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
  174. package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
  175. package/package.json +1 -3
@@ -8,52 +8,18 @@
8
8
  * worktree and the host reading from the main checkout converge on one file.
9
9
  */
10
10
 
11
- import { execFileSync } from 'node:child_process';
12
11
  import { mkdtempSync } from 'node:fs';
13
12
  import os from 'node:os';
14
13
  import path from 'node:path';
15
14
 
16
15
  import { reapOnExit } from '../test-temp.js';
16
+ import { _clearGitRootCaches, mainCheckoutRoot } from './git-roots.js';
17
17
 
18
- /** Keyed by cwd; a cached `null` records a non-repo miss. */
19
- const _mainCheckoutRootCache = new Map();
20
-
21
- /**
22
- * Parent of `--git-common-dir`, which is the main checkout root from both the
23
- * main checkout and any linked worktree. `null` outside a repo.
24
- *
25
- * @param {string} [cwd=process.cwd()]
26
- * @param {{ exec?: typeof execFileSync }} [deps]
27
- * @returns {string|null}
28
- */
29
- export function mainCheckoutRoot(cwd = process.cwd(), deps = {}) {
30
- const exec = deps.exec ?? execFileSync;
31
- // Only the real resolver is memoized.
32
- const memoize = !deps.exec;
33
- if (memoize && _mainCheckoutRootCache.has(cwd)) {
34
- return _mainCheckoutRootCache.get(cwd);
35
- }
36
- let resolved = null;
37
- try {
38
- const out = exec('git', ['rev-parse', '--git-common-dir'], {
39
- cwd,
40
- encoding: 'utf8',
41
- stdio: ['ignore', 'pipe', 'ignore'],
42
- }).trim();
43
- if (out) {
44
- const commonDir = path.isAbsolute(out) ? out : path.resolve(cwd, out);
45
- resolved = path.dirname(commonDir);
46
- }
47
- } catch {
48
- resolved = null;
49
- }
50
- if (memoize) _mainCheckoutRootCache.set(cwd, resolved);
51
- return resolved;
52
- }
18
+ export { mainCheckoutRoot } from './git-roots.js';
53
19
 
54
20
  /** Test-only. */
55
21
  export function _clearMainCheckoutRootCache() {
56
- _mainCheckoutRootCache.clear();
22
+ _clearGitRootCaches();
57
23
  }
58
24
 
59
25
  /**
@@ -12,14 +12,13 @@ import {
12
12
  } from './config/agentrc-overlay.js';
13
13
  import { getCiDelivery } from './config/ci.js';
14
14
  import { getCommands } from './config/commands.js';
15
- import { applyGhConfigDir } from './config/gh-config-dir.js';
15
+ import { overlayRoot, resolveAgentrcRoot } from './config/git-roots.js';
16
16
  import { getGitHub } from './config/github.js';
17
17
  import { resolvePaths } from './config/paths.js';
18
18
  import { validateOrchestrationConfig } from './config/validate-orchestration.js';
19
19
  import { getWorktreeIsolation } from './config/worktree-isolation.js';
20
20
  import { getAgentrcValidator } from './config-schema.js';
21
21
  import { loadEnv } from './env-loader.js';
22
- import { PROJECT_ROOT } from './project-root.js';
23
22
 
24
23
  export { getAcceptanceEval } from './config/acceptance-eval.js';
25
24
  export { BASELINES_DEFAULTS, getBaselines } from './config/baselines.js';
@@ -147,7 +146,7 @@ function applyDefaults(raw) {
147
146
  */
148
147
  function readRawConfig(fsImpl, root) {
149
148
  const agentrcPath = path.join(root, '.agentrc.json');
150
- const localPath = path.join(root, '.agentrc.local.json');
149
+ const localPath = path.join(overlayRoot(root), '.agentrc.local.json');
151
150
  const hasAgentrc = fsImpl.existsSync(agentrcPath);
152
151
  const hasLocal = fsImpl.existsSync(localPath);
153
152
  if (!hasAgentrc) {
@@ -203,15 +202,13 @@ function ensureEnvLoaded(root) {
203
202
  /**
204
203
  * Returns `{ project, github, planning, delivery, qa?, raw, source }`. A
205
204
  * missing file falls back to defaults; malformed JSON or a schema failure
206
- * throws. A set `github.cliConfigDir` is applied to `GH_CONFIG_DIR`. A call with an injected `ctx.fs` neither reads nor fills the
207
- * shared cache.
205
+ * throws. The root is `resolveAgentrcRoot`'s; `GH_CONFIG_DIR` is gh-exec's. A call
206
+ * with an injected `ctx.fs` neither reads nor fills the shared cache.
208
207
  *
209
208
  * @param {{ bustCache?: boolean, cwd?: string, validate?: boolean, ctx?: object }} [opts]
210
209
  */
211
210
  export function resolveConfig(opts) {
212
- const root = path.resolve(
213
- opts?.cwd ?? process.env.AP_AGENTRC_CWD ?? PROJECT_ROOT,
214
- );
211
+ const root = resolveAgentrcRoot({ cwd: opts?.cwd });
215
212
  const validate = opts?.validate !== false;
216
213
  const injectedFs = opts?.ctx?.fs;
217
214
  const key = `${root}\0${validate}`;
@@ -223,7 +220,6 @@ export function resolveConfig(opts) {
223
220
  readRawConfig(injectedFs ?? fs, root),
224
221
  validate,
225
222
  );
226
- applyGhConfigDir(resolved.github, root, { fsImpl: injectedFs ?? fs });
227
223
  if (!injectedFs) _cacheByKey.set(key, resolved);
228
224
  return resolved;
229
225
  }
@@ -30,7 +30,7 @@ const EXECUTION_SCHEMA = {
30
30
  fullSuiteLock: {
31
31
  type: 'boolean',
32
32
  description:
33
- 'Serialize full-suite spawns (`npm test` / `npm run test:coverage`) behind a repository-level advisory lock shared by every worktree, so two concurrent deliveries do not run two suites against the same cores (see `capacity` / `workloads` for declared runs that may overlap). The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.',
33
+ "Serialize full-suite spawns (`npm test` / the coverage gate's `captureScript`) behind a repository-level advisory lock shared by every worktree, so two concurrent deliveries do not run two suites against the same cores (see `capacity` / `workloads` for declared runs that may overlap). The lock queues, it never overlaps: a wait that expires with a live holder spawns nothing and exits 75 (resumable), naming the holder. A dead or non-heartbeating holder is taken over, and a broken lockfile proceeds unserialized, so the lock can never fail a delivery. Set false — or export `MANDREL_FULL_SUITE_LOCK=0` for one invocation — to disable.",
34
34
  default: true,
35
35
  },
36
36
  capacity: {
@@ -51,7 +51,7 @@ const EXECUTION_SCHEMA = {
51
51
  ...SAFE_STRING,
52
52
  minLength: 1,
53
53
  description:
54
- 'The exact suite argv, as `project.commands.test` spells it (or `npm run test:coverage` for coverage capture).',
54
+ 'The exact suite argv, as `project.commands.test` spells it (or `<pm> run <captureScript>` for coverage capture).',
55
55
  },
56
56
  weight: {
57
57
  type: 'integer',
@@ -85,11 +85,12 @@ export const CODE_REVIEW_SCHEMA = {
85
85
  'native',
86
86
  'code-review',
87
87
  'codex',
88
+ 'llm-review',
88
89
  'security-review',
89
90
  'ultrareview',
90
91
  ],
91
92
  description:
92
- 'Registered provider key. Inline: native, code-review, codex, security-review. Manual-prompt: ultrareview.',
93
+ 'Registered provider key. Inline: native, code-review, codex, llm-review, security-review. Manual-prompt: ultrareview.',
93
94
  },
94
95
  scopes: {
95
96
  type: 'array',
@@ -132,7 +133,7 @@ export const CODE_REVIEW_SCHEMA = {
132
133
  additionalProperties: false,
133
134
  },
134
135
  description:
135
- "Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (maintainability scoring of the changed files) then an optional story-scoped `code-review` — a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge; hosts without the `claude` CLI skip it. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain.",
136
+ "Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (maintainability scoring of the changed files) then an optional story-scoped `llm-review` — the first available of `code-review` (a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge) and `codex` (`codex exec`), so a host with both CLIs runs one LLM review and a host with neither skips it. Pin `code-review` or `codex` to choose the CLI. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain.",
136
137
  default: DEFAULT_REVIEW_PROVIDERS,
137
138
  },
138
139
  autoFixSeverity: {
@@ -80,32 +80,31 @@ const PATHS_SCHEMA = {
80
80
  const COMMANDS_SCHEMA = {
81
81
  type: 'object',
82
82
  description:
83
- 'Shell commands the close-validation chain spawns. Each is run from the repo root.',
83
+ 'Shell commands the close-validation chain spawns, each run from the repo root. One tri-state per key: absent uses the default shown; an explicit `null` disables an optional gate (`typecheck`, `lint`, `formatCheck`) — close reports it as skipped (`<gate>-disabled`) and runs nothing; a string is that command. Like every command here it must be a single argv (no `;`, `&&`, pipes or substitution), so wrap a multi-tool pair in one script and name that.',
84
84
  properties: {
85
85
  test: {
86
86
  ...SAFE_STRING,
87
87
  minLength: 1,
88
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
+ "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`). Mandatory: `null` is rejected.",
90
90
  default: COMMANDS_DEFAULTS.test,
91
91
  },
92
92
  typecheck: {
93
93
  ...NULLABLE_NONEMPTY_SAFE_STRING,
94
94
  description:
95
- 'Static type-check command run as a close-validation gate. Left unset (the `null` default), it falls back to `npm run typecheck`. An explicit `null` disables the gate for projects with no type layer: close reports it as skipped (`typecheck-disabled`) and runs nothing. The empty string is rejected so a typo cannot silently disable it.',
95
+ 'Static type-check command run as a close-validation gate. An explicit `null` disables the gate for projects with no type layer (skip reason `typecheck-disabled`). The empty string is rejected so a typo cannot silently disable it.',
96
96
  default: COMMANDS_DEFAULTS.typecheck,
97
97
  },
98
98
  lint: {
99
99
  ...NULLABLE_NONEMPTY_SAFE_STRING,
100
100
  description:
101
- '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.',
101
+ 'Lint command run as a close-validation gate and by the handoff preflight. An explicit `null` disables both (skip reason `lint-disabled`). 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.',
102
102
  default: COMMANDS_DEFAULTS.lint,
103
103
  },
104
104
  formatCheck: {
105
- ...SAFE_STRING,
106
- minLength: 1,
105
+ ...NULLABLE_NONEMPTY_SAFE_STRING,
107
106
  description:
108
- 'Non-mutating format verification run as a close-validation gate.',
107
+ 'Non-mutating format verification run as a close-validation gate. An explicit `null` disables the gate (skip reason `format-disabled`).',
109
108
  default: COMMANDS_DEFAULTS.formatCheck,
110
109
  },
111
110
  formatWrite: {
@@ -7,12 +7,13 @@ import fs from 'node:fs';
7
7
  import path from 'node:path';
8
8
  import picomatch from 'picomatch';
9
9
  import { write, writeFile } from './baselines/writer.js';
10
+ import { COVERAGE_CAPTURE_DEFAULTS } from './config/gates/coverage.schema.js';
10
11
  import {
11
12
  captureStampPath,
12
13
  MissingCoverageArtifactError,
13
14
  } from './coverage-capture.js';
14
15
 
15
- const COVERAGE_FINAL_PATH = 'coverage/coverage-final.json';
16
+ const COVERAGE_FINAL_PATH = COVERAGE_CAPTURE_DEFAULTS.coveragePath;
16
17
  const COVERAGE_BASELINE_PATH = 'baselines/coverage.json';
17
18
  // Percentage points; baselines store two decimals.
18
19
  export const COVERAGE_TOLERANCE = 0.01;
@@ -6,6 +6,7 @@
6
6
  import fs from 'node:fs';
7
7
  import path from 'node:path';
8
8
  import { resolveChangedFilesRef } from './changed-files.js';
9
+ import { COVERAGE_CAPTURE_DEFAULTS } from './config/gates/coverage.schema.js';
9
10
  import {
10
11
  captureStampPath,
11
12
  reportCaptureFailure,
@@ -19,7 +20,7 @@ import {
19
20
  } from './coverage-capture-delta.js';
20
21
  import { tryIncrementalCapture } from './coverage-capture-incremental.js';
21
22
 
22
- const AFFECTED_CAPTURE_SCRIPT = 'test:coverage:affected';
23
+ const AFFECTED_CAPTURE_SCRIPT = COVERAGE_CAPTURE_DEFAULTS.affectedCaptureScript;
23
24
  const COVERAGE_BASE_REF_ENV = 'MANDREL_COVERAGE_BASE_REF';
24
25
 
25
26
  /** A configured scope with no script warns, and the caller runs full scope. */
@@ -32,7 +33,7 @@ function shouldCaptureAffected({
32
33
  if (coverage?.captureScope !== 'affected') return false;
33
34
  if (hasNpmScriptImpl(scripts, AFFECTED_CAPTURE_SCRIPT)) return true;
34
35
  logger.warn(
35
- `[coverage-capture] ⚠ captureScope is "affected" but package.json has no "${AFFECTED_CAPTURE_SCRIPT}" script — running the full npm run test:coverage instead.`,
36
+ `[coverage-capture] ⚠ captureScope is "affected" but package.json has no "${AFFECTED_CAPTURE_SCRIPT}" script — running the full ${coverage.captureScript} capture instead.`,
36
37
  );
37
38
  return false;
38
39
  }
@@ -163,7 +164,7 @@ function writeMerged({
163
164
  const scoped = readArtifact(artifactAbs, fsImpl);
164
165
  if (scoped === null) {
165
166
  logger.error(
166
- `[coverage-capture] ✖ npm run ${AFFECTED_CAPTURE_SCRIPT} exited 0 but wrote no readable artifact at ${crap.coveragePath} — point its coverage output there.`,
167
+ `[coverage-capture] ✖ the ${AFFECTED_CAPTURE_SCRIPT} script exited 0 but wrote no readable artifact at ${crap.coveragePath} — point its coverage output there.`,
167
168
  );
168
169
  return false;
169
170
  }
@@ -1,6 +1,8 @@
1
1
  /** Full-scope (default) capture path for `coverage-capture.js`. */
2
+
2
3
  import path from 'node:path';
3
4
  import { resolveChangedFilesRef } from './changed-files.js';
5
+ import { COVERAGE_CAPTURE_DEFAULTS } from './config/gates/coverage.schema.js';
4
6
  import {
5
7
  anyChangedUnderTargets,
6
8
  describeFreshness,
@@ -96,7 +98,7 @@ export async function runFullScopeCapture({
96
98
  }
97
99
 
98
100
  logger.info(
99
- `[coverage-capture] Coverage at ${crap.coveragePath} is ${describeFreshness(freshness, crap.targetDirs)}; running npm run ${crap.captureScript ?? 'test:coverage'}… ${detail}`,
101
+ `[coverage-capture] Coverage at ${crap.coveragePath} is ${describeFreshness(freshness, crap.targetDirs)}; running the ${crap.captureScript ?? COVERAGE_CAPTURE_DEFAULTS.captureScript} capture script… ${detail}`,
100
102
  );
101
103
  const tree = snapshotCapturedTree({
102
104
  cwd: args.cwd,
@@ -1,38 +1,127 @@
1
1
  /**
2
- * The ordered capture passes for `coverage-capture.js` and the capture-script
3
- * refusal. A shared source is one pass: the existing pipeline, scoped modes
4
- * included. An own CRAP source (`crap.ownCoverageSource`) first refreshes the
5
- * coverage gate's artifact exactly as before, then gives the CRAP artifact
6
- * its own full-scope pass via `crap.captureScript`, stamped in its own
7
- * directory. Scoped capture modes never apply to the own source.
2
+ * Capture passes, the refusal, and the registration predicate close, the
3
+ * handoff and `verify[]` credit share. An own CRAP source gets a second,
4
+ * full-scope pass after the coverage gate's.
8
5
  */
6
+ import { COVERAGE_CAPTURE_DEFAULTS } from './config/gates/coverage.schema.js';
9
7
  import { runFullScopeCapture } from './coverage-capture-fullscope.js';
8
+ import { hasNpmScript } from './npm-scripts.js';
10
9
 
11
- const COVERAGE_GATE_SCRIPT = 'test:coverage';
12
10
  const COVERAGE_PATH_KEY = 'delivery.quality.gates.coverage.coveragePath';
11
+ const COVERAGE_SCRIPT_KEY = 'delivery.quality.gates.coverage.captureScript';
13
12
  const CRAP_PATH_KEY = 'delivery.quality.gates.crap.coveragePath';
14
13
  const CRAP_SCRIPT_KEY = 'delivery.quality.gates.crap.captureScript';
15
14
 
16
15
  /**
17
- * The exit code when no capture may run: the CRAP gate is off (0), or its
18
- * capture script is missing from `package.json` (1, naming the fix).
16
+ * The resolved `{ crap, coverage }` pair a `getQuality` seam returns, with the
17
+ * coverage gate's capture fields always present: a shared source's artifact
18
+ * is the CRAP one, and the script defaults to the coverage gate default.
19
19
  *
20
- * @param {{ crap: object, scripts: object, hasNpmScriptImpl: Function, logger: object }} opts
21
- * @returns {number|null}
20
+ * @param {{ crap: object, coverage?: object }} quality
21
+ * @returns {{ crap: object, coverage: object }}
22
22
  */
23
- export function captureRefusal({ crap, scripts, hasNpmScriptImpl, logger }) {
24
- if (crap.enabled === false) {
25
- logger.info('[coverage-capture] CRAP gate disabled — skipping capture.');
23
+ export function captureGates({ crap, coverage }) {
24
+ const sharedPath = crap.ownCoverageSource ? undefined : crap.coveragePath;
25
+ return {
26
+ crap,
27
+ coverage: {
28
+ ...coverage,
29
+ coveragePath:
30
+ coverage?.coveragePath ??
31
+ sharedPath ??
32
+ COVERAGE_CAPTURE_DEFAULTS.coveragePath,
33
+ captureScript:
34
+ coverage?.captureScript ?? COVERAGE_CAPTURE_DEFAULTS.captureScript,
35
+ },
36
+ };
37
+ }
38
+
39
+ /** @param {{ crap: object, coverage: object }} gates */
40
+ function isCaptureGateEnabled({ crap, coverage }) {
41
+ return crap.enabled !== false || coverage.enabled !== false;
42
+ }
43
+
44
+ /** @param {object} crap */
45
+ function crapOwnsSource(crap) {
46
+ return crap.enabled !== false && crap.ownCoverageSource === true;
47
+ }
48
+
49
+ /** An enabled CRAP gate's own source, else the coverage gate's. @param {{ crap: object, coverage: object }} gates */
50
+ export function primaryCaptureSource({ crap, coverage }) {
51
+ return crapOwnsSource(crap)
52
+ ? {
53
+ coveragePath: crap.coveragePath,
54
+ captureScript: crap.captureScript,
55
+ scriptKey: CRAP_SCRIPT_KEY,
56
+ }
57
+ : {
58
+ coveragePath: coverage.coveragePath,
59
+ captureScript: coverage.captureScript,
60
+ scriptKey: COVERAGE_SCRIPT_KEY,
61
+ };
62
+ }
63
+
64
+ /** @param {{ crap: object, coverage: object, scripts: object|null|undefined, hasNpmScriptImpl?: Function }} opts */
65
+ export function isCaptureActive({
66
+ crap,
67
+ coverage,
68
+ scripts,
69
+ hasNpmScriptImpl = hasNpmScript,
70
+ }) {
71
+ return (
72
+ isCaptureGateEnabled({ crap, coverage }) &&
73
+ hasNpmScriptImpl(
74
+ scripts,
75
+ primaryCaptureSource({ crap, coverage }).captureScript,
76
+ )
77
+ );
78
+ }
79
+
80
+ /**
81
+ * 0 when both gates are off, 1 (naming the fix) when the script is missing.
82
+ *
83
+ * @param {{ crap: object, coverage: object, scripts: object, hasNpmScriptImpl: Function, logger: object }} opts
84
+ */
85
+ export function captureRefusal({
86
+ crap,
87
+ coverage,
88
+ scripts,
89
+ hasNpmScriptImpl,
90
+ logger,
91
+ }) {
92
+ if (!isCaptureGateEnabled({ crap, coverage })) {
93
+ logger.info(
94
+ '[coverage-capture] CRAP and coverage gates disabled — skipping capture.',
95
+ );
26
96
  return 0;
27
97
  }
28
- const script = crap.captureScript ?? COVERAGE_GATE_SCRIPT;
98
+ const { captureScript: script, scriptKey } = primaryCaptureSource({
99
+ crap,
100
+ coverage,
101
+ });
29
102
  if (hasNpmScriptImpl(scripts, script)) return null;
30
- // Name the fix rather than propagate npm's opaque "Missing script" exit.
103
+ return missingScriptExit({ crap, script, scriptKey, logger });
104
+ }
105
+
106
+ /**
107
+ * With the CRAP gate off nothing fails closed on a missing artifact, and close
108
+ * registers no capture without the script, so its absence is a skip (0).
109
+ * Otherwise name the fix rather than propagate the manager's opaque exit (1).
110
+ *
111
+ * @param {{ crap: object, script: string, scriptKey: string, logger: object }} opts
112
+ */
113
+ function missingScriptExit({ crap, script, scriptKey, logger }) {
114
+ if (crap.enabled === false) {
115
+ logger.info(
116
+ `[coverage-capture] CRAP gate disabled and no "${script}" script — skipping capture.`,
117
+ );
118
+ return 0;
119
+ }
31
120
  logger.error(
32
- `[coverage-capture] ✖ No "${script}" script in package.json (the CRAP capture script, set by ${CRAP_SCRIPT_KEY}). ` +
121
+ `[coverage-capture] ✖ No "${script}" script in package.json (the capture script, set by ${scriptKey}). ` +
33
122
  `Add one (e.g. "${script}": "node --test --experimental-test-coverage"), ` +
34
- `point ${CRAP_SCRIPT_KEY} at an existing script, ` +
35
- 'or disable the CRAP gate via delivery.quality.gates.crap.enabled=false.',
123
+ `point ${scriptKey} at an existing script, ` +
124
+ 'or disable the coverage and CRAP gates via delivery.quality.gates.{coverage,crap}.enabled=false.',
36
125
  );
37
126
  return 1;
38
127
  }
@@ -42,25 +131,21 @@ export function captureRefusal({ crap, scripts, hasNpmScriptImpl, logger }) {
42
131
  * @returns {Array<{ crap: object, configKey: string, own: boolean }>}
43
132
  */
44
133
  function planPasses({ crap, coverage, scripts, hasNpmScriptImpl, logger }) {
45
- if (crap.ownCoverageSource !== true) {
46
- return [{ crap, configKey: COVERAGE_PATH_KEY, own: false }];
47
- }
134
+ const gateCrap = {
135
+ ...crap,
136
+ coveragePath: coverage.coveragePath,
137
+ captureScript: coverage.captureScript,
138
+ };
139
+ const gatePass = { crap: gateCrap, configKey: COVERAGE_PATH_KEY, own: false };
140
+ if (!crapOwnsSource(crap)) return [gatePass];
48
141
  const ownPass = { crap, configKey: CRAP_PATH_KEY, own: true };
49
- if (!hasNpmScriptImpl(scripts, COVERAGE_GATE_SCRIPT)) {
142
+ if (!hasNpmScriptImpl(scripts, coverage.captureScript)) {
50
143
  logger.info(
51
- `[coverage-capture] No "${COVERAGE_GATE_SCRIPT}" script — skipping the coverage gate's capture; only the CRAP source at ${crap.coveragePath} is refreshed.`,
144
+ `[coverage-capture] No "${coverage.captureScript}" script — skipping the coverage gate's capture; only the CRAP source at ${crap.coveragePath} is refreshed.`,
52
145
  );
53
146
  return [ownPass];
54
147
  }
55
- const gateCrap = {
56
- ...crap,
57
- coveragePath: coverage.coveragePath,
58
- captureScript: COVERAGE_GATE_SCRIPT,
59
- };
60
- return [
61
- { crap: gateCrap, configKey: COVERAGE_PATH_KEY, own: false },
62
- ownPass,
63
- ];
148
+ return [gatePass, ownPass];
64
149
  }
65
150
 
66
151
  /**
@@ -131,7 +216,7 @@ export async function runCapturePasses({
131
216
  */
132
217
  function runOwnSource({ crap, coverage, args, capture, deps }) {
133
218
  deps.logger.info(
134
- `[coverage-capture] CRAP gate has its own coverage source (${CRAP_PATH_KEY}=${crap.coveragePath}, npm run ${crap.captureScript}).`,
219
+ `[coverage-capture] CRAP gate has its own coverage source (${CRAP_PATH_KEY}=${crap.coveragePath}, capture script ${crap.captureScript}).`,
135
220
  );
136
221
  return runFullScopeCapture({
137
222
  ...deps,
@@ -14,7 +14,7 @@ const COVERAGE_CAPTURE_USAGE = {
14
14
  invocation:
15
15
  'node .agents/scripts/coverage-capture.js [--skip-when-no-crap-files] [--require-credited] [--ref <git-ref>] [--cwd <path>]',
16
16
  summary:
17
- 'Ensure coverage/coverage-final.json is present and fresh before the CRAP gate fires, spawning `npm run test:coverage` only when it is stale (`npm run test:coverage:affected`, with the base ref in MANDREL_COVERAGE_BASE_REF, under delivery.quality.gates.coverage.captureScope="affected"). Writes a content-digest capture stamp that close-validation reads to skip a redundant re-run. When delivery.quality.gates.crap.coveragePath names its own artifact, that artifact is then refreshed full-scope with `npm run <delivery.quality.gates.crap.captureScript>` and stamped in its own directory.',
17
+ 'Ensure the coverage artifact (delivery.quality.gates.coverage.coveragePath) is present and fresh before the coverage and CRAP gates fire, spawning `<pm> run <delivery.quality.gates.coverage.captureScript>` under the detected package manager only when it is stale (the affected capture script, with the base ref in MANDREL_COVERAGE_BASE_REF, under delivery.quality.gates.coverage.captureScope="affected"). Writes a content-digest capture stamp beside the artifact that close-validation reads to skip a redundant re-run. When delivery.quality.gates.crap.coveragePath names its own artifact, that artifact is then refreshed full-scope with `<pm> run <delivery.quality.gates.crap.captureScript>` and stamped beside itself.',
18
18
  flags: [
19
19
  [
20
20
  '--skip-when-no-crap-files',