mandrel 2.119.0 → 2.121.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 (47) hide show
  1. package/.agents/agents/acceptance-critic.md +4 -0
  2. package/.agents/agents/story-worker.md +1 -1
  3. package/.agents/docs/agentrc-reference.json +1 -0
  4. package/.agents/docs/configuration.md +18 -3
  5. package/.agents/schemas/acceptance-eval-verdict.schema.json +6 -1
  6. package/.agents/schemas/agentrc.schema.json +11 -2
  7. package/.agents/schemas/lifecycle/merge.unlanded.schema.json +2 -1
  8. package/.agents/schemas/story-deliver-terminal.schema.json +1 -0
  9. package/.agents/scripts/acceptance-eval.js +125 -13
  10. package/.agents/scripts/evidence-gate.js +15 -2
  11. package/.agents/scripts/lib/baselines/crap-preview-scan.js +1 -0
  12. package/.agents/scripts/lib/baselines/git-base.js +43 -0
  13. package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +29 -5
  14. package/.agents/scripts/lib/baselines/kinds/crap.js +7 -1
  15. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +81 -52
  16. package/.agents/scripts/lib/close-validation/projections/advisories.js +1 -0
  17. package/.agents/scripts/lib/close-validation/projections/crap.js +3 -0
  18. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  19. package/.agents/scripts/lib/config/gates/crap.schema.js +7 -0
  20. package/.agents/scripts/lib/config/quality.js +13 -6
  21. package/.agents/scripts/lib/config-settings-schema.js +1 -1
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  23. package/.agents/scripts/lib/observability/handoff-telemetry.js +1 -0
  24. package/.agents/scripts/lib/orchestrate/inventory.js +15 -0
  25. package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +65 -6
  26. package/.agents/scripts/lib/orchestration/check-baselines/phases/compare.js +34 -2
  27. package/.agents/scripts/lib/orchestration/check-baselines/phases/fail-detail.js +7 -2
  28. package/.agents/scripts/lib/orchestration/handoff-changed-tests.js +67 -0
  29. package/.agents/scripts/lib/orchestration/handoff-gates.js +2 -0
  30. package/.agents/scripts/lib/orchestration/handoff-suite-of-record.js +25 -10
  31. package/.agents/scripts/lib/orchestration/merge-block-class.js +1 -0
  32. package/.agents/scripts/lib/orchestration/merge-queue.js +155 -14
  33. package/.agents/scripts/lib/orchestration/preflight-lanes.js +2 -0
  34. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +131 -18
  35. package/.agents/scripts/lib/orchestration/story-handoff.js +24 -1
  36. package/.agents/scripts/lib/orchestration/ticket-validator.js +35 -0
  37. package/.agents/scripts/lib/orchestration/verify-credit.js +144 -0
  38. package/.agents/scripts/lib/validation-evidence.js +27 -0
  39. package/.agents/workflows/helpers/acceptance-self-eval.md +9 -1
  40. package/.agents/workflows/helpers/deliver-digest.md +7 -8
  41. package/.agents/workflows/helpers/deliver-reference.md +17 -0
  42. package/.agents/workflows/helpers/deliver-story-reference.md +1 -1
  43. package/.agents/workflows/helpers/plan-reference.md +3 -1
  44. package/docs/CHANGELOG.md +23 -0
  45. package/lib/cli/doctor-checks/suite-ownership.js +42 -0
  46. package/lib/cli/registry.js +6 -10
  47. package/package.json +1 -1
@@ -140,6 +140,10 @@ one `criteria[]` record per acceptance item, in acceptance-array order, with
140
140
  - `partial` — partially addressed, or addressed without the required evidence.
141
141
  - `unmet` — not addressed, or the evidence contradicts the claim.
142
142
 
143
+ Cite every scoped `verify[]` entry in some `verifyEvidence[]`; a `met`
144
+ over a non-`pass` item needs a `waiver`. The caller's gate call
145
+ (`--verdict <path> --cwd <workCwd>`) re-runs those entries itself.
146
+
143
147
  **Return the verdict file's absolute path to your caller — never invoke
144
148
  `acceptance-eval.js` yourself.** The caller calls the gate **once** per round;
145
149
  the round counter is Story-scoped, so a second call spends a round for nothing.
@@ -114,7 +114,7 @@ It writes the verdict skeleton — one empty record per `acceptance[]` item —
114
114
  and prints its path, the derived change set `files` and the `verdictOwner`.
115
115
  Under the default profile the owner is **you**: fill every record, scoring
116
116
  that `files` set — never one you re-derive — with `verify[]` output as
117
- evidence, and score it in one call (`--verdict <path>`). Under `strict` the
117
+ evidence, and score it in one call (`--verdict <path> --cwd <workCwd>`). Under `strict` the
118
118
  owner is a fresh critic
119
119
  ([`acceptance-self-eval.md`](../workflows/helpers/acceptance-self-eval.md));
120
120
  hand it that same `files` list. **proceed** → the handoff; **redraft** → fix,
@@ -152,6 +152,7 @@
152
152
  "newMethodCeiling": 30,
153
153
  "requireCoverage": true,
154
154
  "ignoreGlobs": [],
155
+ "untestableWiringGlobs": [],
155
156
  "incrementalCoverage": {
156
157
  "skipWhenUnchanged": true,
157
158
  "baselineJoin": false
@@ -86,7 +86,7 @@ Project identity, filesystem roots, planner docs context, and the commands the c
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 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. |
88
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`). Mandatory: `null` is rejected. |
89
- | `commands.testChanged` | No | `string` \| `null` | — | Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files, or no incoming path is a suite input. The overlap rule ignores baseline (`baselines/`) and coverage-directory paths, and paths matching `delivery.quality.gates.coverage.nonInputGlobs`; those globs never change the incoming count or the emptiness rule, and a config file refuses under either value of `captureHandlesConfigChanges`. It is also the skip-branch first-credit depositor: when coverage-capture is active but takes its incremental skip (no changed file under `crap.targetDirs`), handoff and close run it keyed on the `origin/<baseBranch>` merge-base, credited as the full suite. It MUST therefore select any test that reads a non-module input by path (a docs registry, a fixture file) — `--changed` cannot see that edge, so a break only such a test catches surfaces only where the full suite runs later. Prefer reading `MANDREL_CHANGED_SINCE` from the env over the argv token, so the spawned argv stays constant and declarable in `delivery.execution.workloads[]`. Absent or `null` keeps the full re-run and the full skip-branch suite. |
89
+ | `commands.testChanged` | No | `string` \| `null` | — | Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files, or no incoming path is a suite input. The overlap rule ignores baseline (`baselines/`) and coverage-directory paths, and paths matching `delivery.quality.gates.coverage.nonInputGlobs`; those globs never change the incoming count or the emptiness rule, and a config file refuses under either value of `captureHandlesConfigChanges`. It is also the skip-branch first-credit depositor: when coverage-capture is active but takes its incremental skip (no changed file under `crap.targetDirs`), handoff and close run it keyed on the `origin/<baseBranch>` merge-base, credited as the full suite. It MUST therefore select any test that reads a non-module input by path (a docs registry, a fixture file) — `--changed` cannot see that edge, so a break only such a test catches surfaces only where the full suite runs later. Prefer reading `MANDREL_CHANGED_SINCE` from the env over the argv token, so the spawned argv stays constant and declarable in `delivery.execution.workloads[]`. It is also the handoff's changed-tests guard under `delivery.quality.gates.coverage.suiteOfRecord: ci` (see § Deferring coverage to CI). Absent or `null` keeps the full re-run and the full skip-branch suite. |
90
90
  | `commands.typecheck` | No | `string` \| `null` | `"npm run typecheck"` | 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. |
91
91
  | `commands.lint` | No | `string` \| `null` | `"npm run lint"` | 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. |
92
92
  | `commands.formatCheck` | No | `string` \| `null` | `"npx biome format ."` | Non-mutating format verification run as a close-validation gate. An explicit `null` disables the gate (skip reason `format-disabled`). |
@@ -183,7 +183,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
183
183
  | `quality.gates.coverage.captureScope` | No | `"full"` \| `"affected"` | `"full"` | 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. |
184
184
  | `quality.gates.coverage.timeoutMs` | No | `integer` | `600000` | Kill bound (ms) for one full-suite run — the coverage capture, the close-validation full-suite gate and the full-suite lock-wait budget all read it. The clock starts at spawn, never while queued on the host lock; a suite that signals `MANDREL_SUITE_READY_FILE` gets a fresh bound for its test phase, so worst-case wall is lock wait + 2 × timeoutMs. On expiry the run exits 124 so callers can tell a hang from a failure. |
185
185
  | `quality.gates.coverage.onOverBudget` | No | `"block"` \| `"defer-to-ci"` | `"block"` | What handoff and close do when the capture script — or the `test` command (`project.commands.test`, or `testChanged` on the skip branch and the delta re-credit) — exits 76: the consumer-declared signal that the selected slice is over this host's budget and no test ran. `block` (default) stops the handoff (`blocked`) and fails close, naming this key. `defer-to-ci` settles the coverage gate as deferred to CI: no artifact is written or stamped and no credit is recorded, the coverage-reading gates (CRAP preview, coverage and CRAP baselines) are skipped, and handoff and close proceed — the terminal envelope and the PR body say coverage was deferred. Set it only when the consumer's CI runs the deferred suite with a coverage floor. A timeout (124) is never deferred, under either value. |
186
- | `quality.gates.coverage.suiteOfRecord` | No | `"local"` \| `"ci"` | `"local"` | Where the coverage capture runs. `local` (default) changes nothing. `ci` — meant for a small host's `.agentrc.local.json` — makes CI the coverage and CRAP ratchet of record: handoff and close settle the coverage gate as deferred (reason `suite-of-record-ci`) without spawning the capture, the PR body carries the `Coverage-deferred:` key line, and confirm-merge waits for `ciRatchetCheck` to go green. Requires `ciRatchetCheck`; without it handoff blocks and close fails. |
186
+ | `quality.gates.coverage.suiteOfRecord` | No | `"local"` \| `"ci"` | `"local"` | Where the coverage capture runs. `local` (default) changes nothing. `ci` — meant for a small host's `.agentrc.local.json` — makes CI the coverage and CRAP ratchet of record: handoff and close settle the coverage gate as deferred (reason `suite-of-record-ci`) without spawning the capture, the PR body carries the `Coverage-deferred:` key line, and confirm-merge waits for `ciRatchetCheck` to go green. When `project.commands.testChanged` is set, the handoff first runs it as a changed-tests guard. Requires `ciRatchetCheck`; without it handoff blocks and close fails. |
187
187
  | `quality.gates.coverage.ciRatchetCheck` | No | `string` \| `null` | `null` | Name of the consumer's CI check (check-run or status context) that runs `coverage-ratchet.js` on a deferred PR. Required by `suiteOfRecord: ci`; when set, confirm-merge holds `agent::done` on a PR carrying the `Coverage-deferred:` key line until this check is green on the PR head. Default `null`. |
188
188
  | `quality.gates.coverage.nonInputGlobs` | No | `array<string>` | `[]` | Repo-relative picomatch globs naming paths no test reads. A matching path is dropped from both sides of the coverage delta-refresh overlap check and from the re-measured set — a delta of only matching, baseline and coverage-directory paths restamps without a run — and from the overlap check of close's `test` delta re-credit (its incoming count and emptiness test are unchanged). It never changes the suite-input filter, the tree digest or stamp freshness. Default `[]`: nothing is built in, so Markdown counts as an input unless declared here. |
189
189
  | `quality.gates.coverage.captureHandlesConfigChanges` | No | `boolean` | `false` | Declares that the affected capture script, given `MANDREL_COVERAGE_BASE_REF`, widens its own selection when a coverage-determining config file (`package.json`, a lockfile, `tsconfig*.json`, a test-runner config) changes. When `true`, such a file in the coverage delta no longer refuses the delta refresh. Close's `test` delta re-credit refuses on a config file under either value. Default `false`. |
@@ -201,6 +201,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
201
201
  | `quality.gates.crap.requireCoverage` | No | `boolean` | `true` | When true, the gate refuses to score without a coverage artifact rather than silently reporting complexity-only rows. |
202
202
  | `quality.gates.crap.minMethodResolutionRate` | No | `number` | — | Fail-closed floor on the per-method coverage JOIN (Story #4775): the fraction of methods that must resolve a coverage entry, counted only over files that HAVE one, before `update-crap-baseline.js` will persist. A broken join is silent by construction — unresolved methods are simply absent — so the updater refuses rather than writing a thin baseline and logging it as success. Not enforced below 25 joinable methods, where a diff-scoped run’s rate is noise. Default 0.75; a healthy repo resolves ~98%. |
203
203
  | `quality.gates.crap.ignoreGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from CRAP discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217). |
204
+ | `quality.gates.crap.untestableWiringGlobs` | No | `array<string>` | `[]` | Minimatch glob patterns matched against the canonicalised repo-relative path of a wholly uncovered file. A new method in a matching file meets `newMethodCeiling` on its complexity alone, for CLI wiring (argv, spawn, `main()`) that no test can load. Every other uncovered file is judged on its measured CRAP. Default `[]`. |
204
205
  | `quality.gates.crap.incrementalCoverage` | No | `object` | — | 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). |
205
206
  | `quality.gates.crap.incrementalCoverage.skipWhenUnchanged` | No | `boolean` | `true` | Skip the capture entirely when no changed file under `crap.targetDirs` versus `baseRef` was touched. The only measured saving, and gate-semantics-neutral. Defaults to true. |
206
207
  | `quality.gates.crap.incrementalCoverage.baselineJoin` | No | `boolean` | `false` | Let the CRAP join resolve a method in a file the diff did not touch from its committed baseline row instead of requiring fresh coverage for it. A gate loosening, not a saving — defaults to false. |
@@ -672,6 +673,16 @@ place.
672
673
  depositor; under the `test` depositor it changes nothing. It needs
673
674
  `ciRatchetCheck`. Without one the handoff settles `blocked`
674
675
  (`ci-ratchet-undeclared`) and close fails, both naming the two keys.
676
+ - **The changed-tests guard.** Under `suiteOfRecord: "ci"`, when
677
+ `project.commands.testChanged` is set, the handoff's credited-run step runs
678
+ it in the Story worktree (keyed on the `origin/<baseBranch>` merge-base)
679
+ before it settles the deferral. It takes no full-suite lock and deposits no
680
+ `test` or coverage credit; the deferral and the PR marker are unchanged.
681
+ Exit 0 settles deferred; exit 76 skips the guard and settles deferred; any
682
+ other exit settles `fix-required` with cause `changed-tests` and pushes
683
+ nothing. `timeoutMs` bounds it, and a timeout is `fix-required` too. A
684
+ held-review CRITICAL aborts it, as it aborts a credited run. A re-run at a
685
+ HEAD whose guard passed skips it. Unset, no test runs before the PR.
675
686
  - **`delivery.close.revalidateAfterBaseSync: "ci"`.** After a conflict-free
676
687
  base merge, close defers the capture (with `typecheck` and `lint`) to the
677
688
  checks in `delivery.close.revalidateCiChecks`, reason `base-sync-ci`. It
@@ -718,7 +729,11 @@ place.
718
729
  - **Doctor.** `mandrel doctor`'s `coverage-ratchet` check reads
719
730
  `.agentrc.json` with `.agentrc.local.json` over it. It fails when
720
731
  `suiteOfRecord` is `ci`, or `onOverBudget` is `defer-to-ci`, and
721
- `ciRatchetCheck` is unset.
732
+ `ciRatchetCheck` is unset. Its `suite-ownership` advisory never fails:
733
+ with `ciRatchetCheck` set and the posture local it reports the suite owned
734
+ by both the handoff and CI, naming `suiteOfRecord: "ci"` and
735
+ `project.commands.testChanged`; under `ci` without `testChanged` it reports
736
+ that no test runs before the PR.
722
737
  - **Nothing sticks.** A deferral writes no artifact, stamp or credit, so a
723
738
  later run on a bigger host captures, seats and scores as usual.
724
739
  - **A timeout is not a deferral.** Exit 124 can hide a hang, so it keeps its
@@ -74,11 +74,16 @@
74
74
  "outcome": {
75
75
  "type": "string",
76
76
  "enum": ["pass", "fail", "skipped"],
77
- "description": "Result of the verify[] command. `skipped` is permitted only with a stated reason and never for a criterion marked `met`."
77
+ "description": "Result of the verify[] command. A `met` criterion carrying a non-`pass` item without a `waiver` is refused before scoring."
78
78
  },
79
79
  "detail": {
80
80
  "type": ["string", "null"],
81
81
  "description": "Optional excerpt of command output or the reason a command was skipped."
82
+ },
83
+ "waiver": {
84
+ "type": "string",
85
+ "minLength": 1,
86
+ "description": "Why a `met` criterion stands over this item's non-pass outcome or a failing gate run of the command. Never suppresses the gate's check that every scoped verify[] entry is cited."
82
87
  }
83
88
  },
84
89
  "additionalProperties": false
@@ -91,7 +91,7 @@
91
91
  "type": "string",
92
92
  "pattern": "([;&|`]|\\$\\()"
93
93
  },
94
- "description": "Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files, or no incoming path is a suite input. The overlap rule ignores baseline (`baselines/`) and coverage-directory paths, and paths matching `delivery.quality.gates.coverage.nonInputGlobs`; those globs never change the incoming count or the emptiness rule, and a config file refuses under either value of `captureHandlesConfigChanges`. It is also the skip-branch first-credit depositor: when coverage-capture is active but takes its incremental skip (no changed file under `crap.targetDirs`), handoff and close run it keyed on the `origin/<baseBranch>` merge-base, credited as the full suite. It MUST therefore select any test that reads a non-module input by path (a docs registry, a fixture file) — `--changed` cannot see that edge, so a break only such a test catches surfaces only where the full suite runs later. Prefer reading `MANDREL_CHANGED_SINCE` from the env over the argv token, so the spawned argv stays constant and declarable in `delivery.execution.workloads[]`. Absent or `null` keeps the full re-run and the full skip-branch suite."
94
+ "description": "Optional changed-tests command for the delta re-credit: when close's base sync merged sibling landings into a branch whose pre-sync head holds `test` credit, close's `test` gate runs this instead of the full suite, with the credited commit in the `MANDREL_CHANGED_SINCE` environment variable and in place of a literal `$MANDREL_CHANGED_SINCE` argument (e.g. `pnpm vitest run --changed $MANDREL_CHANGED_SINCE`; no shell runs it), and a green run re-credits the merged tree. Ineligible when coverage-capture runs the suite, an incoming path is a coverage-config file or one of the Story's own files, or no incoming path is a suite input. The overlap rule ignores baseline (`baselines/`) and coverage-directory paths, and paths matching `delivery.quality.gates.coverage.nonInputGlobs`; those globs never change the incoming count or the emptiness rule, and a config file refuses under either value of `captureHandlesConfigChanges`. It is also the skip-branch first-credit depositor: when coverage-capture is active but takes its incremental skip (no changed file under `crap.targetDirs`), handoff and close run it keyed on the `origin/<baseBranch>` merge-base, credited as the full suite. It MUST therefore select any test that reads a non-module input by path (a docs registry, a fixture file) — `--changed` cannot see that edge, so a break only such a test catches surfaces only where the full suite runs later. Prefer reading `MANDREL_CHANGED_SINCE` from the env over the argv token, so the spawned argv stays constant and declarable in `delivery.execution.workloads[]`. It is also the handoff's changed-tests guard under `delivery.quality.gates.coverage.suiteOfRecord: ci` (see § Deferring coverage to CI). Absent or `null` keeps the full re-run and the full skip-branch suite."
95
95
  },
96
96
  "typecheck": {
97
97
  "type": ["string", "null"],
@@ -758,7 +758,7 @@
758
758
  "suiteOfRecord": {
759
759
  "type": "string",
760
760
  "enum": ["local", "ci"],
761
- "description": "Where the coverage capture runs. `local` (default) changes nothing. `ci` — meant for a small host's `.agentrc.local.json` — makes CI the coverage and CRAP ratchet of record: handoff and close settle the coverage gate as deferred (reason `suite-of-record-ci`) without spawning the capture, the PR body carries the `Coverage-deferred:` key line, and confirm-merge waits for `ciRatchetCheck` to go green. Requires `ciRatchetCheck`; without it handoff blocks and close fails.",
761
+ "description": "Where the coverage capture runs. `local` (default) changes nothing. `ci` — meant for a small host's `.agentrc.local.json` — makes CI the coverage and CRAP ratchet of record: handoff and close settle the coverage gate as deferred (reason `suite-of-record-ci`) without spawning the capture, the PR body carries the `Coverage-deferred:` key line, and confirm-merge waits for `ciRatchetCheck` to go green. When `project.commands.testChanged` is set, the handoff first runs it as a changed-tests guard. Requires `ciRatchetCheck`; without it handoff blocks and close fails.",
762
762
  "default": "local"
763
763
  },
764
764
  "ciRatchetCheck": {
@@ -918,6 +918,15 @@
918
918
  "description": "Minimatch glob patterns matched against the canonicalised repo-relative path of each discovered file. Files matching any pattern are excluded from CRAP discovery before scoring. Orthogonal to `components` (grouping) — a file excluded here never appears in any component bucket. Absent or empty preserves the existing IGNORED_DIRS-only behaviour (Story #3217).",
919
919
  "default": []
920
920
  },
921
+ "untestableWiringGlobs": {
922
+ "type": "array",
923
+ "items": {
924
+ "type": "string",
925
+ "minLength": 1
926
+ },
927
+ "description": "Minimatch glob patterns matched against the canonicalised repo-relative path of a wholly uncovered file. A new method in a matching file meets `newMethodCeiling` on its complexity alone, for CLI wiring (argv, spawn, `main()`) that no test can load. Every other uncovered file is judged on its measured CRAP. Default `[]`.",
928
+ "default": []
929
+ },
921
930
  "incrementalCoverage": {
922
931
  "type": "object",
923
932
  "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).",
@@ -32,7 +32,8 @@
32
32
  "predicate-refused",
33
33
  "advisory-gate-red",
34
34
  "advisory-gate-inconclusive",
35
- "merge-queue-rest-unsupported"
35
+ "merge-queue-rest-unsupported",
36
+ "queue-ejected"
36
37
  ]
37
38
  },
38
39
  "reason": { "type": "string", "minLength": 1 },
@@ -159,6 +159,7 @@
159
159
  "advisory-gate-red",
160
160
  "advisory-gate-inconclusive",
161
161
  "merge-queue-rest-unsupported",
162
+ "queue-ejected",
162
163
  "merged-flip-failed"
163
164
  ]
164
165
  },
@@ -35,10 +35,14 @@ import {
35
35
  computeVerdictFingerprint,
36
36
  decideAcceptanceEval,
37
37
  resolveAcceptanceEvalRound,
38
+ scoreVerifyRuns,
38
39
  } from './lib/orchestration/acceptance-eval-decision.js';
39
40
  import {
41
+ classifyVerifyEntries,
40
42
  FULL_SUITE_SHAPE_WARNING,
41
43
  isFullSuiteCommand,
44
+ normalizeVerifyCommand,
45
+ runScopedVerifyEntry,
42
46
  } from './lib/orchestration/verify-credit.js';
43
47
  import { createProvider } from './lib/provider-factory.js';
44
48
  import { parse as parseStoryBody } from './lib/story-body/story-body.js';
@@ -123,29 +127,40 @@ const MERGE_CONTRACT =
123
127
  'before scoring.';
124
128
 
125
129
  /**
126
- * The Story body's `acceptance[]` items, in order; any failure yields `null`.
130
+ * One parsed Story body list (`acceptance`, `verify`); `null` when the body
131
+ * cannot be read, `[]` when the list is absent.
127
132
  *
133
+ * @param {'acceptance'|'verify'} field
128
134
  * @param {{ storyId: number, config: object }} args
129
135
  * @param {{ createProviderFn?: typeof createProvider, parseBodyFn?: typeof parseStoryBody }} [deps]
130
136
  * @returns {Promise<string[]|null>}
131
137
  */
132
- export async function readStoryAcceptance(
138
+ async function readStoryBodyList(
139
+ field,
133
140
  { storyId, config },
134
141
  { createProviderFn = createProvider, parseBodyFn = parseStoryBody } = {},
135
142
  ) {
136
143
  try {
137
144
  const ticket = await createProviderFn(config).getTicket(storyId);
138
- const body = typeof ticket?.body === 'string' ? ticket.body : null;
139
- if (body === null) return null;
140
- const acceptance = parseBodyFn(body)?.body?.acceptance;
141
- return Array.isArray(acceptance) && acceptance.length > 0
142
- ? acceptance
143
- : null;
145
+ if (typeof ticket?.body !== 'string') return null;
146
+ const list = parseBodyFn(ticket.body)?.body?.[field];
147
+ return Array.isArray(list) ? list : [];
144
148
  } catch {
145
149
  return null;
146
150
  }
147
151
  }
148
152
 
153
+ /** The Story body's `acceptance[]` items, in order; any failure yields `null`. */
154
+ export async function readStoryAcceptance(args, deps) {
155
+ const acceptance = await readStoryBodyList('acceptance', args, deps);
156
+ return acceptance?.length > 0 ? acceptance : null;
157
+ }
158
+
159
+ /** The Story body's `verify[]` entries; `null` when the body is unreadable. */
160
+ export function readStoryVerify(args, deps) {
161
+ return readStoryBodyList('verify', args, deps);
162
+ }
163
+
149
164
  /**
150
165
  * The Story body's `acceptance[]` count; any failure yields `null`, never a
151
166
  * manufactured count.
@@ -364,6 +379,51 @@ export function assertCriteriaCoverage(verdict, expectedCriteria) {
364
379
  );
365
380
  }
366
381
 
382
+ /**
383
+ * Reject, consuming no round, an uncited required `verify[]` entry or a `met`
384
+ * criterion on non-pass evidence without a `waiver`.
385
+ */
386
+ export function assertVerifyEvidence(verdict, required) {
387
+ const criteria = verdict?.criteria ?? [];
388
+ const cited = new Set(
389
+ criteria.flatMap((c) =>
390
+ (c?.verifyEvidence ?? []).map((e) => normalizeVerifyCommand(e?.command)),
391
+ ),
392
+ );
393
+ const uncited = required.filter((command) => !cited.has(command));
394
+ const unwaived = criteria
395
+ .filter(
396
+ (c) =>
397
+ c?.verdict === 'met' &&
398
+ (c.verifyEvidence ?? []).some((e) => e.outcome !== 'pass' && !e.waiver),
399
+ )
400
+ .map((c) => c.index);
401
+ const problems = [
402
+ ...(uncited.length > 0
403
+ ? [
404
+ `verify[] entr(ies) no criterion's verifyEvidence cites: ${uncited.map((c) => `\`${c}\``).join(', ')}`,
405
+ ]
406
+ : []),
407
+ ...(unwaived.length > 0
408
+ ? [
409
+ `met criteria at index ${unwaived.join(', ')} carry non-pass verifyEvidence with no waiver`,
410
+ ]
411
+ : []),
412
+ ];
413
+ if (problems.length === 0) return;
414
+ throw new Error(
415
+ `acceptance-eval: ${problems.join('; ')}. No round was consumed.`,
416
+ );
417
+ }
418
+
419
+ /** A Story with scoped entries is scored only with a worktree to run them in. */
420
+ export function assertScoringCwd(scoped, cwd) {
421
+ if (scoped.length === 0 || cwd) return;
422
+ throw new Error(
423
+ `Usage: acceptance-eval: the Story has ${scoped.length} scoped verify[] entr(ies) the gate must run — pass --cwd <workCwd>. No round was consumed.`,
424
+ );
425
+ }
426
+
367
427
  /**
368
428
  * Distinct full-suite commands in the verdict's `verify[]` evidence — a
369
429
  * misshapen `verify[]` that re-pays (or silently skips) the one credited
@@ -411,6 +471,8 @@ function warnOnFullSuiteVerify(verdict, logger) {
411
471
  * @param {boolean} args.emitSignal
412
472
  * @param {number} [args.round] — override (tests); otherwise derived from the
413
473
  * signals ledger, never from the verdict's self-reported round.
474
+ * @param {Array<object>} [args.verifyRuns] — the gate's own scoped runs.
475
+ * @param {string|null} [args.headSha] — HEAD of `--cwd`.
414
476
  * @param {object} [deps]
415
477
  * @param {Function} [deps.appendSignalFn]
416
478
  * @param {Function} [deps.resolveRoundFn]
@@ -418,7 +480,7 @@ function warnOnFullSuiteVerify(verdict, logger) {
418
480
  * @returns {Promise<{ envelope: object, exitCode: number }>}
419
481
  */
420
482
  export async function runAcceptanceEval(
421
- { storyId, verdict, config, emitSignal, round },
483
+ { storyId, verdict, config, emitSignal, round, verifyRuns = [], headSha },
422
484
  deps = {},
423
485
  ) {
424
486
  const {
@@ -427,7 +489,7 @@ export async function runAcceptanceEval(
427
489
  fingerprintFn = computeVerdictFingerprint,
428
490
  } = deps;
429
491
  const { maxRounds } = getAcceptanceEval(config);
430
- const verdictFingerprint = fingerprintFn(verdict);
492
+ const verdictFingerprint = fingerprintFn(verdict, { verifyRuns, headSha });
431
493
  // An already-scored verdict replays its round and appends nothing.
432
494
  const resolved = resolveRoundFn({
433
495
  epicId: null,
@@ -442,6 +504,7 @@ export async function runAcceptanceEval(
442
504
  verdict,
443
505
  maxRounds,
444
506
  round: resolvedRound,
507
+ verifyRuns,
445
508
  });
446
509
 
447
510
  let signalEmitted = false;
@@ -490,6 +553,7 @@ export async function runAcceptanceEval(
490
553
  verdict: c.verdict,
491
554
  evidence: c.evidence,
492
555
  })),
556
+ verifyRuns: scoreVerifyRuns(verdict, verifyRuns).verifyRuns,
493
557
  signalEmitted,
494
558
  replay,
495
559
  verdictFingerprint,
@@ -499,11 +563,40 @@ export async function runAcceptanceEval(
499
563
  return { envelope, exitCode };
500
564
  }
501
565
 
566
+ /** Check the verdict's verify evidence, then run the scoped entries. */
567
+ async function resolveVerifyGate({
568
+ storyId,
569
+ config,
570
+ cwd,
571
+ verdict,
572
+ readVerifyImpl,
573
+ readHeadImpl,
574
+ logger,
575
+ deps,
576
+ }) {
577
+ const entries = await readVerifyImpl({ storyId, config });
578
+ if (entries === null) {
579
+ logger.warn?.(
580
+ '[acceptance-eval] ⚠ the Story verify[] could not be read — the verify evidence check and gate runs are skipped for this round.',
581
+ );
582
+ return { verifyRuns: [], headSha: null };
583
+ }
584
+ const { required, scoped } = classifyVerifyEntries(entries);
585
+ const workCwd = cwd ? path.resolve(cwd) : null;
586
+ assertScoringCwd(scoped, workCwd);
587
+ assertVerifyEvidence(verdict, required);
588
+ const runEntry = deps.runEntryImpl ?? runScopedVerifyEntry;
589
+ return {
590
+ verifyRuns: scoped.map((command) => runEntry(command, { cwd: workCwd })),
591
+ headSha: workCwd ? readHeadImpl(workCwd) : null,
592
+ };
593
+ }
594
+
502
595
  /** @param {number|null} storyId */
503
596
  function requireStoryId(storyId) {
504
597
  if (storyId) return;
505
598
  throw new Error(
506
- 'Usage: node acceptance-eval.js --story <id> --verdict <path> [--expected-criteria <n>] [--no-signal]',
599
+ 'Usage: node acceptance-eval.js --story <id> --verdict <path> --cwd <workCwd> [--expected-criteria <n>] [--no-signal]',
507
600
  );
508
601
  }
509
602
 
@@ -534,6 +627,9 @@ async function runInitCli({ storyId, cwd, resolveConfigImpl, logger, deps }) {
534
627
  * validateVerdictImpl?: typeof validateVerdict,
535
628
  * runAcceptanceEvalImpl?: typeof runAcceptanceEval,
536
629
  * readAcceptanceCountImpl?: typeof readStoryAcceptanceCount,
630
+ * readVerifyImpl?: typeof readStoryVerify,
631
+ * runEntryImpl?: typeof runScopedVerifyEntry,
632
+ * readHeadImpl?: typeof readHeadSha,
537
633
  * initSkeletonImpl?: typeof initVerdictSkeleton,
538
634
  * logger?: { info: Function, warn?: Function },
539
635
  * }} [deps]
@@ -549,6 +645,8 @@ export async function runAcceptanceEvalCli(
549
645
  validateVerdictImpl = validateVerdict,
550
646
  runAcceptanceEvalImpl = runAcceptanceEval,
551
647
  readAcceptanceCountImpl = readStoryAcceptanceCount,
648
+ readVerifyImpl = readStoryVerify,
649
+ readHeadImpl = readHeadSha,
552
650
  logger = Logger,
553
651
  } = deps;
554
652
  const { storyId, init, cwd, verdictPath, expectedCriteria, emitSignal } =
@@ -606,11 +704,22 @@ export async function runAcceptanceEvalCli(
606
704
  // From the validated verdict, so it fires even with an injected scorer.
607
705
  warnOnFullSuiteVerify(verdict, logger);
608
706
 
707
+ const gate = await resolveVerifyGate({
708
+ storyId,
709
+ config,
710
+ cwd,
711
+ verdict,
712
+ readVerifyImpl,
713
+ readHeadImpl,
714
+ logger,
715
+ deps,
716
+ });
609
717
  const { envelope, exitCode } = await runAcceptanceEvalImpl({
610
718
  storyId,
611
719
  verdict,
612
720
  config,
613
721
  emitSignal,
722
+ ...gate,
614
723
  });
615
724
 
616
725
  logger.info(JSON.stringify(envelope));
@@ -640,7 +749,7 @@ runAsCli(import.meta.url, main, {
640
749
  source: 'acceptance-eval',
641
750
  usage: {
642
751
  invocation:
643
- 'node .agents/scripts/acceptance-eval.js --story <id> (--init [--cwd <workCwd>] | --verdict <path> [--expected-criteria <n>] [--no-signal])',
752
+ 'node .agents/scripts/acceptance-eval.js --story <id> (--init [--cwd <workCwd>] | --verdict <path> --cwd <workCwd> [--expected-criteria <n>] [--no-signal])',
644
753
  summary:
645
754
  "Score an authored acceptance verdict against the Story's acceptance[] criteria and emit the bounded loop's proceed / redraft / block decision; --init writes the verdict skeleton to fill first.",
646
755
  flags: [
@@ -649,7 +758,10 @@ runAsCli(import.meta.url, main, {
649
758
  '--init',
650
759
  'Write the verdict skeleton (one empty record per acceptance[] item, the next round, HEAD) under <tempRoot>/scratch/story-<id>/ and print its path, the derived change set `files` and the `verdictOwner`. Scoring a skeleton with an unfilled record is refused without consuming a round.',
651
760
  ],
652
- ['--cwd <workCwd>', 'Worktree the --init change set is derived in.'],
761
+ [
762
+ '--cwd <workCwd>',
763
+ 'Worktree the --init change set is derived in, and the one the scoring call runs each scoped Story verify[] entry in (required when the Story has any). A criterion citing a failing run is scored unmet unless its verifyEvidence item carries a `waiver`.',
764
+ ],
653
765
  ['--verdict <path>', 'Path to the authored verdict JSON (required).'],
654
766
  [
655
767
  '--expected-criteria <n>',
@@ -31,6 +31,7 @@ import {
31
31
  runSupervisedSuite,
32
32
  } from './lib/supervised-suite.js';
33
33
  import {
34
+ dirtyTreeReason,
34
35
  hashCommandConfig,
35
36
  recordPass,
36
37
  shouldSkip,
@@ -123,6 +124,15 @@ function resolveEvidenceKeys({ spawnCwd, gitSpawnFn, useEvidence }) {
123
124
  };
124
125
  }
125
126
 
127
+ /** Evidence applies only with a HEAD and a tree matching it. */
128
+ function evidenceUsable({ gate, headSha, spawnCwd, gitSpawnFn, logger }) {
129
+ if (!headSha) return false;
130
+ const reason = dirtyTreeReason(spawnCwd, gitSpawnFn);
131
+ if (!reason) return true;
132
+ logger.info(`[evidence-gate] ⚠ ${gate} evidence bypassed (${reason})`);
133
+ return false;
134
+ }
135
+
126
136
  /**
127
137
  * @param {object} params
128
138
  * @param {number} params.scopeId
@@ -182,8 +192,11 @@ export async function runEvidenceGate(params, deps = {}) {
182
192
  gitSpawnFn,
183
193
  useEvidence,
184
194
  });
195
+ const credited =
196
+ useEvidence &&
197
+ evidenceUsable({ gate, headSha, spawnCwd, gitSpawnFn, logger });
185
198
 
186
- if (useEvidence && headSha) {
199
+ if (credited) {
187
200
  const verdict = shouldSkipFn(
188
201
  {
189
202
  storyId: scopeId,
@@ -224,7 +237,7 @@ export async function runEvidenceGate(params, deps = {}) {
224
237
  }
225
238
 
226
239
  logger.info(`[evidence-gate] ✓ ${gate} passed`);
227
- if (useEvidence && headSha) {
240
+ if (credited) {
228
241
  try {
229
242
  recordPassFn(
230
243
  {
@@ -127,6 +127,7 @@ export async function computeCrapPreviewScan({
127
127
  newMethodCeiling,
128
128
  tolerance,
129
129
  isJudged: resolveIsJudged({ crap, diffRef, baseBranch, cwd, git }),
130
+ untestableWiringGlobs: crap.untestableWiringGlobs,
130
131
  });
131
132
  const envelope = buildCrapReport({
132
133
  compareResult: result,
@@ -179,6 +179,49 @@ export function readRangeCommitsTouchingFile(baseRef, file, opts = {}) {
179
179
  .filter((commit) => commit !== null && commit.sha.length > 0);
180
180
  }
181
181
 
182
+ /**
183
+ * Renames in `<baseRef>...HEAD` as new path → old path. Uncached: depends on
184
+ * live HEAD. An empty map on any failure leaves the compare unchanged.
185
+ *
186
+ * @param {string} baseRef
187
+ * @param {{ cwd?: string }} [opts]
188
+ * @returns {Map<string, string>}
189
+ */
190
+ export function readRenamesFromGit(baseRef, opts = {}) {
191
+ if (!isNonEmptyString(baseRef)) return new Map();
192
+ return parseRenames(tryRunGit(renameArgs(baseRef), opts));
193
+ }
194
+
195
+ function renameArgs(baseRef) {
196
+ return [
197
+ 'diff',
198
+ '--name-status',
199
+ '-M',
200
+ '--diff-filter=R',
201
+ `${baseRef}...HEAD`,
202
+ ];
203
+ }
204
+
205
+ function tryRunGit(args, opts) {
206
+ try {
207
+ return runGit(args, opts);
208
+ } catch {
209
+ return null;
210
+ }
211
+ }
212
+
213
+ function parseRenames(result) {
214
+ const renames = new Map();
215
+ if (result?.status !== 0) return renames;
216
+ for (const line of stdoutOf(result).split('\n')) addRename(renames, line);
217
+ return renames;
218
+ }
219
+
220
+ function addRename(renames, line) {
221
+ const [status, from, to] = line.trim().split('\t');
222
+ if (status?.startsWith('R') && from && to) renames.set(to, from);
223
+ }
224
+
182
225
  /**
183
226
  * Test-only.
184
227
  *
@@ -1,5 +1,8 @@
1
1
  /** The gate `compareCrap` applies to a method with no baseline row. A leaf. */
2
2
 
3
+ import picomatch from 'picomatch';
4
+ import { canonicalizeBaselinePath } from '../path-canon.js';
5
+
3
6
  /**
4
7
  * Files whose every measured method is at 0% coverage (no test loads them).
5
8
  * `coverage: null` rows do not vote: unmeasured is not zero.
@@ -23,19 +26,40 @@ export function deriveUncoveredFiles(currentRows) {
23
26
 
24
27
  /**
25
28
  * The score a new method meets the ceiling with: measured CRAP, or complexity
26
- * `c` alone in a wholly uncovered file. At zero coverage CRAP is `c² + c`,
27
- * which caps untestable wiring (argv, spawn, `main()`) at `c ≈ 5` and forces
28
- * fragmentation. Gate-only: the persisted row keeps the measured CRAP.
29
+ * `c` alone in a wholly uncovered file listed in `untestableWiringGlobs`. At
30
+ * zero coverage CRAP is `c² + c`, which caps untestable wiring (argv, spawn,
31
+ * `main()`) at `c ≈ 5`. Gate-only: the persisted row keeps the measured CRAP.
29
32
  *
30
33
  * @param {{file: string, crap: number, cyclomatic?: number}} row
31
34
  * @param {Set<string>} uncoveredFiles
35
+ * @param {string[]} [untestableWiringGlobs]
32
36
  * @returns {number}
33
37
  */
34
- export function newMethodGateScore(row, uncoveredFiles) {
35
- if (!uncoveredFiles.has(row.file)) return row.crap;
38
+ export function newMethodGateScore(
39
+ row,
40
+ uncoveredFiles,
41
+ untestableWiringGlobs = [],
42
+ ) {
43
+ const relieved =
44
+ uncoveredFiles.has(row.file) &&
45
+ isUntestableWiring(row.file, untestableWiringGlobs);
46
+ return relieved ? complexityScore(row) : row.crap;
47
+ }
48
+
49
+ function complexityScore(row) {
36
50
  return Number.isFinite(row.cyclomatic) ? row.cyclomatic : row.crap;
37
51
  }
38
52
 
53
+ function isUntestableWiring(file, globs) {
54
+ return globs.length > 0 && matchesAny(file, globs);
55
+ }
56
+
57
+ function matchesAny(file, globs) {
58
+ return picomatch.isMatch(canonicalizeBaselinePath(file), globs, {
59
+ dot: true,
60
+ });
61
+ }
62
+
39
63
  /**
40
64
  * `gateScore` is set only when it differs from `crap`, so the printer names
41
65
  * the number that actually failed.
@@ -273,10 +273,12 @@ export function compareCrap({
273
273
  newMethodCeiling,
274
274
  tolerance,
275
275
  isJudged = () => true,
276
+ untestableWiringGlobs = [],
276
277
  }) {
277
278
  const rows = currentRows ?? [];
278
279
  const state = {
279
280
  uncoveredFiles: deriveUncoveredFiles(currentRows),
281
+ untestableWiringGlobs,
280
282
  newMethodCeiling,
281
283
  tolerance: Number.isFinite(tolerance) ? tolerance : 0,
282
284
  isJudged,
@@ -338,7 +340,11 @@ function scorePair(state, idx, row, baseline, kind) {
338
340
 
339
341
  /** A current row with no baseline row: the new-method ceiling. */
340
342
  function scoreNewMethod(state, idx, row) {
341
- const gateScore = newMethodGateScore(row, state.uncoveredFiles);
343
+ const gateScore = newMethodGateScore(
344
+ row,
345
+ state.uncoveredFiles,
346
+ state.untestableWiringGlobs,
347
+ );
342
348
  if (gateScore > state.newMethodCeiling + state.tolerance) {
343
349
  state.newViolations += 1;
344
350
  state.verdicts[idx] = buildNewViolation(