mandrel 2.90.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 (169) 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 +31 -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/check-arch-cycles.js +1 -5
  14. package/.agents/scripts/check-context-budget.js +1 -5
  15. package/.agents/scripts/check-cyclomatic.js +1 -5
  16. package/.agents/scripts/check-dead-exports.js +23 -14
  17. package/.agents/scripts/check-doc-links.js +4 -4
  18. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  19. package/.agents/scripts/coverage-capture.js +14 -6
  20. package/.agents/scripts/diagnose-friction.js +8 -10
  21. package/.agents/scripts/generate-workflows-doc.js +5 -0
  22. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  24. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  25. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  26. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  27. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  28. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  29. package/.agents/scripts/lib/baselines/components.js +5 -5
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  32. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  33. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  34. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  36. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  37. package/.agents/scripts/lib/baselines/writer.js +4 -4
  38. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  39. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  40. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  41. package/.agents/scripts/lib/child-exec.js +4 -4
  42. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  43. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  44. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  45. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  46. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  47. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  48. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  49. package/.agents/scripts/lib/config/commands.js +82 -7
  50. package/.agents/scripts/lib/config/explain.js +2 -1
  51. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  52. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  53. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  54. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  55. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  56. package/.agents/scripts/lib/config/git-roots.js +120 -0
  57. package/.agents/scripts/lib/config/quality.js +46 -50
  58. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  59. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  60. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  61. package/.agents/scripts/lib/config-resolver.js +5 -9
  62. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  63. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  64. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  65. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  67. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  68. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  69. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  70. package/.agents/scripts/lib/coverage-capture.js +31 -20
  71. package/.agents/scripts/lib/coverage-utils.js +34 -16
  72. package/.agents/scripts/lib/cpu-pool.js +2 -4
  73. package/.agents/scripts/lib/crap-engine.js +19 -1
  74. package/.agents/scripts/lib/crap-utils.js +2 -1
  75. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  76. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  77. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  78. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  79. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  80. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  81. package/.agents/scripts/lib/gh-env.js +72 -0
  82. package/.agents/scripts/lib/gh-exec.js +26 -1
  83. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  84. package/.agents/scripts/lib/npm-scripts.js +1 -1
  85. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  86. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  87. package/.agents/scripts/lib/orchestration/board-access-latch.js +19 -8
  88. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  89. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  90. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  91. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  92. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  93. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  94. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  95. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  96. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  97. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  98. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  99. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  100. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  101. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  102. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  103. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  104. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  105. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  106. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  107. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  108. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  109. package/.agents/scripts/lib/orchestration/story-handoff.js +13 -5
  110. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  111. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  112. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  113. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  114. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  115. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  116. package/.agents/scripts/lib/source-extensions.js +30 -15
  117. package/.agents/scripts/lib/test-run-credit.js +1 -9
  118. package/.agents/scripts/lib/test-temp.js +22 -21
  119. package/.agents/scripts/lib/util/ajv.js +111 -0
  120. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  121. package/.agents/scripts/lib/util/paths.js +51 -0
  122. package/.agents/scripts/lib/util/sleep.js +6 -0
  123. package/.agents/scripts/lib/util/slug.js +12 -0
  124. package/.agents/scripts/lib/validation-evidence.js +19 -40
  125. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  126. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  127. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  128. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  129. package/.agents/scripts/lint-issue-body.js +2 -2
  130. package/.agents/scripts/plan-context.js +2 -7
  131. package/.agents/scripts/providers/github/auth.js +3 -3
  132. package/.agents/scripts/providers/github/errors.js +3 -1
  133. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  134. package/.agents/scripts/providers/github/issues.js +6 -2
  135. package/.agents/scripts/providers/github/mappers.js +1 -5
  136. package/.agents/scripts/providers/github/projects-v2-graphql.js +11 -3
  137. package/.agents/scripts/providers/github/search-budget.js +3 -1
  138. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  139. package/.agents/scripts/sync-agentrc.js +5 -14
  140. package/.agents/scripts/sync-claude-agents.js +38 -150
  141. package/.agents/scripts/sync-claude-commands.js +35 -218
  142. package/.agents/scripts/update-coverage-baseline.js +1 -1
  143. package/.agents/scripts/update-crap-baseline.js +1 -1
  144. package/.agents/scripts/update-duplication-baseline.js +2 -16
  145. package/.agents/scripts/validate-skills.js +6 -10
  146. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  147. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  148. package/.agents/workflows/audit-exceptions.md +9 -0
  149. package/.agents/workflows/audit-lean.md +129 -0
  150. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  151. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  152. package/.agents/workflows/helpers/code-review.md +15 -1
  153. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  154. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  155. package/.agents/workflows/mandrel-plan.md +2 -2
  156. package/docs/CHANGELOG.md +35 -0
  157. package/lib/cli/doctor-checks/codex.js +6 -5
  158. package/lib/cli/doctor-checks/llm-review.js +102 -0
  159. package/lib/cli/doctor-checks/project-access.js +20 -10
  160. package/lib/cli/doctor-checks/sync-parity.js +65 -140
  161. package/lib/cli/doctor-checks/test-credit-path.js +69 -28
  162. package/lib/cli/doctor-checks/toolchain.js +5 -3
  163. package/lib/cli/registry.js +5 -0
  164. package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
  165. package/lib/migrations/index.js +6 -0
  166. package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
  167. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
  168. package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
  169. package/package.json +1 -3
@@ -73,7 +73,7 @@
73
73
  },
74
74
  "commands": {
75
75
  "type": "object",
76
- "description": "Shell commands the close-validation chain spawns. Each is run from the repo root.",
76
+ "description": "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.",
77
77
  "properties": {
78
78
  "test": {
79
79
  "type": "string",
@@ -81,7 +81,7 @@
81
81
  "pattern": "([;&|`]|\\$\\()"
82
82
  },
83
83
  "minLength": 1,
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).",
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`). Mandatory: `null` is rejected.",
85
85
  "default": "npm test"
86
86
  },
87
87
  "typecheck": {
@@ -91,8 +91,8 @@
91
91
  "type": "string",
92
92
  "pattern": "([;&|`]|\\$\\()"
93
93
  },
94
- "description": "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
- "default": null
94
+ "description": "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.",
95
+ "default": "npm run typecheck"
96
96
  },
97
97
  "lint": {
98
98
  "type": ["string", "null"],
@@ -101,16 +101,17 @@
101
101
  "type": "string",
102
102
  "pattern": "([;&|`]|\\$\\()"
103
103
  },
104
- "description": "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.",
105
- "default": null
104
+ "description": "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.",
105
+ "default": "npm run lint"
106
106
  },
107
107
  "formatCheck": {
108
- "type": "string",
108
+ "type": ["string", "null"],
109
+ "minLength": 1,
109
110
  "not": {
111
+ "type": "string",
110
112
  "pattern": "([;&|`]|\\$\\()"
111
113
  },
112
- "minLength": 1,
113
- "description": "Non-mutating format verification run as a close-validation gate.",
114
+ "description": "Non-mutating format verification run as a close-validation gate. An explicit `null` disables the gate (skip reason `format-disabled`).",
114
115
  "default": "npx biome format ."
115
116
  },
116
117
  "formatWrite": {
@@ -365,7 +366,7 @@
365
366
  "properties": {
366
367
  "fullSuiteLock": {
367
368
  "type": "boolean",
368
- "description": "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.",
369
+ "description": "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.",
369
370
  "default": true
370
371
  },
371
372
  "capacity": {
@@ -386,7 +387,7 @@
386
387
  "pattern": "([;&|`]|\\$\\()"
387
388
  },
388
389
  "minLength": 1,
389
- "description": "The exact suite argv, as `project.commands.test` spells it (or `npm run test:coverage` for coverage capture)."
390
+ "description": "The exact suite argv, as `project.commands.test` spells it (or `<pm> run <captureScript>` for coverage capture)."
390
391
  },
391
392
  "weight": {
392
393
  "type": "integer",
@@ -611,7 +612,7 @@
611
612
  },
612
613
  "floors": {
613
614
  "type": "object",
614
- "description": "Workspace-keyed absolute floors: `{ \"<workspace>\": { \"<metric>\": number } }`. `\"*\"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
615
+ "description": "Component-keyed absolute floors: `{ \"<component>\": { \"<metric>\": number } }` — the threshold half of the component mapping whose membership half is `components`. `\"*\"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
615
616
  "additionalProperties": {
616
617
  "type": "object",
617
618
  "additionalProperties": {
@@ -628,7 +629,7 @@
628
629
  },
629
630
  "components": {
630
631
  "type": "object",
631
- "description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
632
+ "description": "Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
632
633
  "additionalProperties": {
633
634
  "type": "array",
634
635
  "items": {
@@ -643,13 +644,20 @@
643
644
  "pattern": "([;&|`]|\\$\\()"
644
645
  },
645
646
  "minLength": 1,
646
- "description": "Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. The capture contract: `npm run test:coverage` MUST write Istanbul per-file JSON (the `json` reporter) here — the coverage and CRAP refreshes both read it. A `json-summary` (`coverage-summary.json`) alone cannot feed them, so a green capture that leaves no file here fails and a full-scope refresh refuses to run.",
647
+ "description": "Repo-relative path to the Istanbul `coverage-final.json` the capture step writes and the gate reads. The capture contract: `captureScript` MUST write Istanbul per-file JSON (the `json` reporter) here — the coverage and CRAP refreshes both read it. A `json-summary` (`coverage-summary.json`) alone cannot feed them, so a green capture that leaves no file here fails and a full-scope refresh refuses to run. Its capture stamp sits beside it (`.capture-stamp.<file>.json`), so another artifact may share its directory.",
647
648
  "default": "coverage/coverage-final.json"
648
649
  },
650
+ "captureScript": {
651
+ "type": "string",
652
+ "minLength": 1,
653
+ "pattern": "^[A-Za-z0-9@:._/-]+$",
654
+ "description": "`package.json` script (never a shell command) the coverage gate's capture runs, spawned as `<pm> run <script>` under the detected package manager (npm, pnpm, yarn or bun). Close registers the coverage-capture gate when the coverage or CRAP gate is enabled and this script exists; the full-suite lock's workload identity and `mandrel doctor`'s `test-credit-path` check follow it. Default `test:coverage`.",
655
+ "default": "test:coverage"
656
+ },
649
657
  "captureScope": {
650
658
  "type": "string",
651
659
  "enum": ["full", "affected"],
652
- "description": "What coverage-capture runs. `full` (default) runs `npm run test:coverage`. `affected` runs the consumer-owned `npm run test:coverage:affected` with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite.",
660
+ "description": "What coverage-capture runs. `full` (default) runs `captureScript`. `affected` runs the consumer-owned `test:coverage:affected` script with the base ref in `MANDREL_COVERAGE_BASE_REF`, merges its rows over the prior artifact and stamps it `affected`; baseline rows the scoped run did not measure are treated as unmeasured, never removed. Falls back to `full` with a warning when the script is absent. Meant for consumers whose CI already enforces coverage on the full suite.",
653
661
  "default": "full"
654
662
  },
655
663
  "timeoutMs": {
@@ -704,7 +712,7 @@
704
712
  },
705
713
  "floors": {
706
714
  "type": "object",
707
- "description": "Workspace-keyed absolute floors: `{ \"<workspace>\": { \"<metric>\": number } }`. `\"*\"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
715
+ "description": "Component-keyed absolute floors: `{ \"<component>\": { \"<metric>\": number } }` — the threshold half of the component mapping whose membership half is `components`. `\"*\"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
708
716
  "additionalProperties": {
709
717
  "type": "object",
710
718
  "additionalProperties": {
@@ -721,7 +729,7 @@
721
729
  },
722
730
  "components": {
723
731
  "type": "object",
724
- "description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
732
+ "description": "Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
725
733
  "additionalProperties": {
726
734
  "type": "array",
727
735
  "items": {
@@ -788,7 +796,7 @@
788
796
  },
789
797
  "incrementalCoverage": {
790
798
  "type": "object",
791
- "description": "The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full `npm run test:coverage` (Story #5065).",
799
+ "description": "The two independent full-suite economies (Story #4981, split by Story #5173). `skipWhenUnchanged` (default true) decides WHETHER to capture — no changed file under `crap.targetDirs` versus `baseRef` means no capture at all — and is a pure saving. `baselineJoin` (default false) loosens gate semantics: the CRAP join resolves a method in an untouched file from its committed baseline row instead of requiring fresh coverage for it. Neither narrows the capture run itself: a capture that does happen is the ordinary full run of the coverage gate's `captureScript` (Story #5065).",
792
800
  "properties": {
793
801
  "skipWhenUnchanged": {
794
802
  "type": "boolean",
@@ -811,17 +819,19 @@
811
819
  "coveragePath": {
812
820
  "type": ["string", "null"],
813
821
  "minLength": 1,
814
- "description": "Repo-relative Istanbul `coverage-final.json` the CRAP gate joins against (Story #5717). `null` or unset falls back to `delivery.quality.gates.coverage.coveragePath`. When it differs from that path the CRAP gate has its OWN coverage source: `coverage-capture.js` refreshes it full-scope via `captureScript`, and the handoff seat, close preview and `update-crap-baseline.js` read it. It must live in a different directory from the coverage gate's artifact (the capture stamp is per directory); a same-directory path is refused at config resolution.",
822
+ "description": "Repo-relative Istanbul `coverage-final.json` the CRAP gate joins against (Story #5717). `null` or unset falls back to `delivery.quality.gates.coverage.coveragePath`. When it differs from that path the CRAP gate has its OWN coverage source: `coverage-capture.js` refreshes it full-scope via `captureScript`, and the handoff seat, close preview and `update-crap-baseline.js` read it. Its capture stamp sits beside it, so it may share a directory with the coverage gate's artifact.",
815
823
  "default": null
816
824
  },
817
825
  "captureScript": {
818
826
  "type": "string",
819
827
  "minLength": 1,
820
828
  "pattern": "^[A-Za-z0-9@:._/-]+$",
821
- "description": "npm script name (run as `npm run <script>`, never a shell command) that writes the CRAP coverage artifact. Close registers the coverage-capture gate, and the capture refusal and credited-run probe key, on this script.",
822
- "default": "test:coverage"
829
+ "description": "`package.json` script (never a shell command) that writes the CRAP gate's OWN coverage artifact, spawned as `<pm> run <script>`. Valid only beside an own `coveragePath`: without one the CRAP gate reads the coverage gate's artifact, so this key is refused and `delivery.quality.gates.coverage.captureScript` runs. Unset beside an own `coveragePath`, it is the coverage gate's `captureScript`."
823
830
  }
824
831
  },
832
+ "dependencies": {
833
+ "captureScript": ["coveragePath"]
834
+ },
825
835
  "additionalProperties": false
826
836
  },
827
837
  "maintainability": {
@@ -866,7 +876,7 @@
866
876
  },
867
877
  "floors": {
868
878
  "type": "object",
869
- "description": "Workspace-keyed absolute floors: `{ \"<workspace>\": { \"<metric>\": number } }`. `\"*\"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
879
+ "description": "Component-keyed absolute floors: `{ \"<component>\": { \"<metric>\": number } }` — the threshold half of the component mapping whose membership half is `components`. `\"*\"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
870
880
  "additionalProperties": {
871
881
  "type": "object",
872
882
  "additionalProperties": {
@@ -881,7 +891,7 @@
881
891
  },
882
892
  "components": {
883
893
  "type": "object",
884
- "description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
894
+ "description": "Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
885
895
  "additionalProperties": {
886
896
  "type": "array",
887
897
  "items": {
@@ -974,7 +984,7 @@
974
984
  },
975
985
  "floors": {
976
986
  "type": "object",
977
- "description": "Workspace-keyed absolute floors: `{ \"<workspace>\": { \"<metric>\": number } }`. `\"*\"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
987
+ "description": "Component-keyed absolute floors: `{ \"<component>\": { \"<metric>\": number } }` — the threshold half of the component mapping whose membership half is `components`. `\"*\"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
978
988
  "additionalProperties": {
979
989
  "type": "object",
980
990
  "additionalProperties": {
@@ -989,7 +999,7 @@
989
999
  },
990
1000
  "components": {
991
1001
  "type": "object",
992
- "description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
1002
+ "description": "Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
993
1003
  "additionalProperties": {
994
1004
  "type": "array",
995
1005
  "items": {
@@ -1043,7 +1053,7 @@
1043
1053
  },
1044
1054
  "floors": {
1045
1055
  "type": "object",
1046
- "description": "Workspace-keyed absolute floors: `{ \"<workspace>\": { \"<metric>\": number } }`. `\"*\"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
1056
+ "description": "Component-keyed absolute floors: `{ \"<component>\": { \"<metric>\": number } }` — the threshold half of the component mapping whose membership half is `components`. `\"*\"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
1047
1057
  "additionalProperties": {
1048
1058
  "type": "object",
1049
1059
  "additionalProperties": {
@@ -1056,7 +1066,7 @@
1056
1066
  },
1057
1067
  "components": {
1058
1068
  "type": "object",
1059
- "description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
1069
+ "description": "Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
1060
1070
  "additionalProperties": {
1061
1071
  "type": "array",
1062
1072
  "items": {
@@ -1098,7 +1108,7 @@
1098
1108
  },
1099
1109
  "duplication": {
1100
1110
  "type": "object",
1101
- "description": "Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks, the jscpd `formats` it reads there, and `ignoreGlobs` to exclude files from the scan.",
1111
+ "description": "Code-duplication (DRY) gate (Story #3664). Shares the gate base and adds the scan-scope extras: the `targetDirs` the duplication scanner walks and `ignoreGlobs` to exclude files from the scan. The jscpd formats it reads are derived from the scorable-extension list every other gate scores (JavaScript, JSX, TypeScript, TSX), so they are not configurable (Story #5738).",
1102
1112
  "properties": {
1103
1113
  "enabled": {
1104
1114
  "type": "boolean",
@@ -1138,7 +1148,7 @@
1138
1148
  },
1139
1149
  "floors": {
1140
1150
  "type": "object",
1141
- "description": "Workspace-keyed absolute floors: `{ \"<workspace>\": { \"<metric>\": number } }`. `\"*\"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
1151
+ "description": "Component-keyed absolute floors: `{ \"<component>\": { \"<metric>\": number } }` — the threshold half of the component mapping whose membership half is `components`. `\"*\"` is the project-wide catch-all component; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.",
1142
1152
  "additionalProperties": {
1143
1153
  "type": "object",
1144
1154
  "additionalProperties": {
@@ -1153,7 +1163,7 @@
1153
1163
  },
1154
1164
  "components": {
1155
1165
  "type": "object",
1156
- "description": "Per-gate component map — component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
1166
+ "description": "Component-keyed membership map — the membership half of the component mapping whose threshold half is `floors`: component name to the glob list whose rows roll up under it (matched against the row key: the file path, or the bundle name for bundle-size). `check-baselines` reports one rollup per component that matches a row and holds it to `floors.<component>`, falling back to `floors[\"*\"]`. Defaults to `{ \"*\": [\"**\"] }` at the resolver layer.",
1157
1167
  "additionalProperties": {
1158
1168
  "type": "array",
1159
1169
  "items": {
@@ -1189,26 +1199,16 @@
1189
1199
  "additionalProperties": false
1190
1200
  }
1191
1201
  ],
1192
- "description": "Directories whose sources — the languages `formats` selects — the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664).",
1202
+ "description": "Directories whose scorable sources (`.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.tsx`, `.mts`, `.cts`) the duplication (DRY) gate scans for copy-paste clones. Mandrel ships a `src/`-centric default; projects whose executable code lives elsewhere (e.g. this repo's `.agents/scripts/`) override here. The framework default is intentionally not auto-discovered, so an override is the explicit, auditable signal (Story #3664).",
1193
1203
  "default": ["src"]
1194
1204
  },
1195
- "formats": {
1196
- "type": "array",
1197
- "items": {
1198
- "type": "string",
1199
- "minLength": 1
1200
- },
1201
- "minItems": 1,
1202
- "description": "jscpd format names the duplication (DRY) gate scans under `targetDirs`. The default covers JavaScript, JSX, TypeScript and TSX; jscpd's `javascript` format alone reads only `.js`/`.es`/`.es6`/`.mjs`/`.cjs`. Names are jscpd's own vocabulary and are not restricted here. Widening the set adds rows, so re-seat the baseline with `npm run duplication:reanchor` after changing it.",
1203
- "default": ["javascript", "jsx", "typescript", "tsx"]
1204
- },
1205
1205
  "ignoreGlobs": {
1206
1206
  "type": "array",
1207
1207
  "items": {
1208
1208
  "type": "string",
1209
1209
  "minLength": 1
1210
1210
  },
1211
- "description": "Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664).",
1211
+ "description": "Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from duplication discovery before scanning. Orthogonal to `components` (grouping). Absent or empty preserves the existing behaviour (Story #3664). This is the lever for scanning fewer files.",
1212
1212
  "default": []
1213
1213
  }
1214
1214
  },
@@ -1303,10 +1303,11 @@
1303
1303
  "native",
1304
1304
  "code-review",
1305
1305
  "codex",
1306
+ "llm-review",
1306
1307
  "security-review",
1307
1308
  "ultrareview"
1308
1309
  ],
1309
- "description": "Registered provider key. Inline: native, code-review, codex, security-review. Manual-prompt: ultrareview."
1310
+ "description": "Registered provider key. Inline: native, code-review, codex, llm-review, security-review. Manual-prompt: ultrareview."
1310
1311
  },
1311
1312
  "scopes": {
1312
1313
  "type": "array",
@@ -1350,13 +1351,13 @@
1350
1351
  },
1351
1352
  "additionalProperties": false
1352
1353
  },
1353
- "description": "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.",
1354
+ "description": "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.",
1354
1355
  "default": [
1355
1356
  {
1356
1357
  "name": "native"
1357
1358
  },
1358
1359
  {
1359
- "name": "code-review",
1360
+ "name": "llm-review",
1360
1361
  "scopes": ["story"],
1361
1362
  "optional": true
1362
1363
  }
@@ -200,6 +200,7 @@
200
200
  "gates": ["gate1", "gate3"],
201
201
  "keywords": [
202
202
  "exception",
203
+ "shortcut",
203
204
  "suppression",
204
205
  "suppress",
205
206
  "override",
@@ -238,6 +239,24 @@
238
239
  "scope": "cumulative",
239
240
  "substitutionKeys": []
240
241
  },
242
+ "audit-lean": {
243
+ "triggers": {
244
+ "gates": ["gate1", "gate3"],
245
+ "keywords": [
246
+ "reuse",
247
+ "reinvent",
248
+ "stdlib",
249
+ "yagni",
250
+ "bloat",
251
+ "over-engineered",
252
+ "one implementation",
253
+ "wrapper"
254
+ ],
255
+ "filePatterns": ["**/*"]
256
+ },
257
+ "scope": "cumulative",
258
+ "substitutionKeys": []
259
+ },
241
260
  "audit-documentation": {
242
261
  "triggers": {
243
262
  "gates": ["gate1", "gate3"],
@@ -22,10 +22,6 @@ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
22
22
  import path from 'node:path';
23
23
  import { fileURLToPath } from 'node:url';
24
24
  import { parseArgs } from 'node:util';
25
-
26
- import Ajv2020 from 'ajv/dist/2020.js';
27
- import addFormats from 'ajv-formats';
28
-
29
25
  import { deriveCeremony } from './ceremony-derive.js';
30
26
  import { runAsCli } from './lib/cli-utils.js';
31
27
  import { getDeliveryRouting } from './lib/config/delivery-routing.js';
@@ -46,6 +42,7 @@ import {
46
42
  } from './lib/orchestration/verify-credit.js';
47
43
  import { createProvider } from './lib/provider-factory.js';
48
44
  import { parse as parseStoryBody } from './lib/story-body/story-body.js';
45
+ import { createAjv2020 } from './lib/util/ajv.js';
49
46
 
50
47
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
51
48
 
@@ -68,8 +65,7 @@ function getVerdictValidator(
68
65
  schemaPath = VERDICT_SCHEMA_PATH,
69
66
  io = { readFileSync },
70
67
  ) {
71
- const ajv = new Ajv2020({ allErrors: true, strict: false });
72
- addFormats(ajv);
68
+ const ajv = createAjv2020({ allErrors: true, strict: false });
73
69
  const schema = JSON.parse(io.readFileSync(schemaPath, 'utf8'));
74
70
  return ajv.compile(schema);
75
71
  }
@@ -14,8 +14,6 @@ import fs from 'node:fs';
14
14
  import path from 'node:path';
15
15
  import process from 'node:process';
16
16
  import { fileURLToPath } from 'node:url';
17
- import Ajv from 'ajv';
18
- import addFormats from 'ajv-formats';
19
17
  import {
20
18
  DEFAULT_MAX_RECORDS,
21
19
  runEngine,
@@ -25,6 +23,7 @@ import { DEFAULT_BLAME_LIMIT } from './lib/audit-exceptions/history.js';
25
23
  import { DEFAULT_TICKET_LIMIT } from './lib/audit-exceptions/tickets.js';
26
24
  import { defineFlags } from './lib/cli-args.js';
27
25
  import { runAsCli } from './lib/cli-utils.js';
26
+ import { createAjv } from './lib/util/ajv.js';
28
27
 
29
28
  const SCHEMA_PATH = path.resolve(
30
29
  path.dirname(fileURLToPath(import.meta.url)),
@@ -53,8 +52,7 @@ let validator;
53
52
  */
54
53
  export function assertEnvelope(envelope) {
55
54
  if (!validator) {
56
- const ajv = new Ajv({ allErrors: true, strict: false });
57
- addFormats(ajv);
55
+ const ajv = createAjv({ allErrors: true, strict: false });
58
56
  validator = ajv.compile(JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8')));
59
57
  }
60
58
  if (validator(envelope)) return;
@@ -220,11 +220,7 @@ export async function runCli({
220
220
  return exitCode;
221
221
  }
222
222
 
223
- async function main() {
224
- return runCli();
225
- }
226
-
227
- runAsCli(import.meta.url, main, {
223
+ runAsCli(import.meta.url, runCli, {
228
224
  source: 'arch-cycles',
229
225
  propagateExitCode: true,
230
226
  errorPrefix: '[arch-cycles] ❌ Fatal error',
@@ -467,11 +467,7 @@ export async function runCli({
467
467
  return report.exitCode;
468
468
  }
469
469
 
470
- async function main() {
471
- return runCli();
472
- }
473
-
474
- runAsCli(import.meta.url, main, {
470
+ runAsCli(import.meta.url, runCli, {
475
471
  source: 'context-budget',
476
472
  propagateExitCode: true,
477
473
  errorPrefix: '[context-budget] ❌ Fatal error',
@@ -198,11 +198,7 @@ export async function runCli({
198
198
  return exitCode;
199
199
  }
200
200
 
201
- async function main() {
202
- return runCli();
203
- }
204
-
205
- runAsCli(import.meta.url, main, {
201
+ runAsCli(import.meta.url, runCli, {
206
202
  source: 'cyclomatic',
207
203
  propagateExitCode: true,
208
204
  errorPrefix: '[cyclomatic] ❌ Fatal error',
@@ -1,9 +1,8 @@
1
1
  /**
2
2
  * CLI: ratchet-down dead-export gate built on knip. Diffs knip's unused
3
3
  * exports — plus a `{ file, symbol: '*' }` row per module nothing imports —
4
- * against `baselines/dead-exports.json` by `(file, symbol)`. Exit 1 only on an
5
- * added row; a knip spawn/parse failure is advisory (exit 0 + warning) so a
6
- * broken knip cannot block CI.
4
+ * against `baselines/dead-exports.json` by `(file, symbol)`. Exit 1 on an
5
+ * added row; exit 2 when knip produced no report (fail closed).
7
6
  *
8
7
  * `--production` discounts test-only importers (production-dead code hides
9
8
  * behind its own tests) and uses its own baseline — see
@@ -67,6 +66,8 @@ export function diffRows(baselineRows, currentRows) {
67
66
  };
68
67
  }
69
68
 
69
+ const EXIT = Object.freeze({ CLEAN: 0, ADDED: 1, KNIP_FAILED: 2 });
70
+
70
71
  /**
71
72
  * `+`/`-` rows then a summary line. `label` tells the two back-to-back passes
72
73
  * apart in CI logs.
@@ -95,7 +96,7 @@ export function renderDiff(diff, label = 'dead-exports') {
95
96
  * runKnipImpl?: typeof runKnip,
96
97
  * loadBaselineImpl?: typeof readJsonBaseline,
97
98
  * }} [opts]
98
- * @returns {Promise<number>} exit code: 0 = clean or removals-only; 1 = added exports detected
99
+ * @returns {Promise<number>} exit code: 0 = clean or removals-only; 1 = added exports detected; 2 = no knip report
99
100
  */
100
101
  export async function runCli({
101
102
  argv = process.argv.slice(2),
@@ -135,7 +136,7 @@ export async function runCli({
135
136
  const currentRows = extractRowsFromKnip(knipEnvelope);
136
137
  const diff = diffRows(baselineRows, currentRows);
137
138
 
138
- const exitCode = knipError === null && diff.added.length > 0 ? 1 : 0;
139
+ const exitCode = gateExitCode(knipError, diff);
139
140
 
140
141
  if (json) {
141
142
  const envelope = {
@@ -156,21 +157,29 @@ export async function runCli({
156
157
  `[${label}] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
157
158
  );
158
159
  }
159
- if (knipError) {
160
- stderr.write(`[${label}] ⚠ knip run failed: ${knipError}\n`);
161
- }
162
- stdout.write(`\n--- ${label} preview ---\n`);
163
- stdout.write(`${renderDiff(diff, label)}\n`);
160
+ writeTextReport({ stdout, stderr, label, knipError, diff });
164
161
  }
165
162
 
166
163
  return exitCode;
167
164
  }
168
165
 
169
- async function main() {
170
- return runCli();
166
+ function gateExitCode(knipError, diff) {
167
+ if (knipError !== null) return EXIT.KNIP_FAILED;
168
+ return diff.added.length > 0 ? EXIT.ADDED : EXIT.CLEAN;
169
+ }
170
+
171
+ /** A failed knip run has no meaningful diff, so it prints the failure alone. */
172
+ function writeTextReport({ stdout, stderr, label, knipError, diff }) {
173
+ if (knipError) {
174
+ stderr.write(`[${label}] ❌ knip run failed: ${knipError}\n`);
175
+ stdout.write(`! knip run failed: ${knipError} (gate fail)\n`);
176
+ return;
177
+ }
178
+ stdout.write(`\n--- ${label} preview ---\n`);
179
+ stdout.write(`${renderDiff(diff, label)}\n`);
171
180
  }
172
181
 
173
- runAsCli(import.meta.url, main, {
182
+ runAsCli(import.meta.url, runCli, {
174
183
  source: 'dead-exports',
175
184
  propagateExitCode: true,
176
185
  errorPrefix: '[dead-exports] ❌ Fatal error',
@@ -192,7 +201,7 @@ runAsCli(import.meta.url, main, {
192
201
  ['--json', 'Emit the comparison envelope as JSON.'],
193
202
  ],
194
203
  notes: [
195
- 'Exit codes:\n 0 clean, or removals only\n 1 newly added unused exports',
204
+ 'Exit codes:\n 0 clean, or removals only\n 1 newly added unused exports\n 2 knip produced no report (spawn error, overflow, error exit, empty or unparseable output)',
196
205
  ],
197
206
  },
198
207
  });
@@ -8,7 +8,7 @@
8
8
  import fs from 'node:fs';
9
9
  import path from 'node:path';
10
10
  import { fileURLToPath } from 'node:url';
11
- import { minimatch } from 'minimatch';
11
+ import picomatch from 'picomatch';
12
12
  import { parseStandardCliArgs } from './lib/cli/standard-args.js';
13
13
  import { runAsCli } from './lib/cli-utils.js';
14
14
  import { Logger } from './lib/Logger.js';
@@ -155,7 +155,7 @@ function walkMarkdown(dirAbs, repoRoot, out) {
155
155
  /**
156
156
  * @param {string} rootAbs
157
157
  * @param {string[]} scanRoots
158
- * @param {string[]} [exclude] minimatch globs over repo-relative POSIX paths
158
+ * @param {string[]} [exclude] picomatch globs over repo-relative POSIX paths
159
159
  */
160
160
  export function discoverMarkdown(rootAbs, scanRoots, exclude = []) {
161
161
  const out = [];
@@ -166,7 +166,7 @@ export function discoverMarkdown(rootAbs, scanRoots, exclude = []) {
166
166
  const filtered = exclude.length
167
167
  ? out.filter((abs) => {
168
168
  const rel = path.relative(rootAbs, abs).split(path.sep).join('/');
169
- return !exclude.some((g) => minimatch(rel, g, { dot: true }));
169
+ return !exclude.some((g) => picomatch.isMatch(rel, g, { dot: true }));
170
170
  })
171
171
  : out;
172
172
  filtered.sort();
@@ -459,7 +459,7 @@ runAsCli(import.meta.url, main, {
459
459
  ],
460
460
  [
461
461
  '--exclude <glob>',
462
- 'Repeatable. minimatch glob; matching files are dropped from the scan.',
462
+ 'Repeatable. picomatch glob; matching files are dropped from the scan.',
463
463
  ],
464
464
  ],
465
465
  notes: [