mandrel 2.114.0 → 2.116.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.
- package/.agents/docs/agentrc-reference.json +1 -0
- package/.agents/docs/configuration.md +18 -4
- package/.agents/docs/workflows.md +2 -1
- package/.agents/schemas/agentrc.schema.json +54 -1
- package/.agents/scripts/acceptance-eval.js +2 -2
- package/.agents/scripts/ceremony-derive.js +15 -2
- package/.agents/scripts/closeout-audit.js +132 -0
- package/.agents/scripts/lib/baselines/crap-preview-scan.js +15 -8
- package/.agents/scripts/lib/baselines/crap-preview-touched.js +140 -0
- package/.agents/scripts/lib/baselines/crap-prune.js +86 -0
- package/.agents/scripts/lib/baselines/kinds/crap.js +12 -4
- package/.agents/scripts/lib/baselines/seat-missing.js +1 -1
- package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
- package/.agents/scripts/lib/config/gates/crap.schema.js +7 -0
- package/.agents/scripts/lib/config/quality.js +3 -0
- package/.agents/scripts/lib/config/temp-paths.js +12 -0
- package/.agents/scripts/lib/config-settings-schema-delivery.js +34 -0
- package/.agents/scripts/lib/coverage-capture-delta.js +26 -3
- package/.agents/scripts/lib/coverage-capture-own-fix.js +35 -19
- package/.agents/scripts/lib/coverage-capture.js +62 -14
- package/.agents/scripts/lib/crap-engine.js +3 -5
- package/.agents/scripts/lib/crap-utils.js +12 -2
- package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
- package/.agents/scripts/lib/git-branch-lifecycle.js +2 -1
- package/.agents/scripts/lib/observability/source-classifier.js +3 -0
- package/.agents/scripts/lib/orchestrate/classify.js +238 -0
- package/.agents/scripts/lib/orchestrate/conflicts.js +119 -0
- package/.agents/scripts/lib/orchestrate/inherited-failure.js +66 -0
- package/.agents/scripts/lib/orchestrate/inventory.js +388 -0
- package/.agents/scripts/lib/orchestrate/ledger.js +223 -0
- package/.agents/scripts/lib/orchestration/closeout-audit.js +511 -0
- package/.agents/scripts/lib/orchestration/handoff-gates.js +25 -8
- package/.agents/scripts/lib/orchestration/merge-queue.js +1 -1
- package/.agents/scripts/lib/orchestration/required-checks.js +12 -2
- package/.agents/scripts/lib/orchestration/story-handoff.js +131 -41
- package/.agents/scripts/orchestrate-inventory.js +70 -0
- package/.agents/scripts/orchestrate-ledger.js +141 -0
- package/.agents/scripts/single-story-init.js +43 -5
- package/.agents/scripts/story-handoff.js +6 -2
- package/.agents/workflows/helpers/deliver-digest.md +3 -3
- package/.agents/workflows/helpers/deliver-reference.md +31 -4
- package/.agents/workflows/mandrel-orchestrate.md +140 -0
- package/docs/CHANGELOG.md +21 -0
- package/package.json +1 -1
|
@@ -187,7 +187,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
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`. |
|
|
190
|
-
| `quality.gates.coverage.ownFixDeltaMaxFiles` | No | `integer` | `0` | Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no
|
|
190
|
+
| `quality.gates.coverage.ownFixDeltaMaxFiles` | No | `integer` | `0` | Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no test file: a changed test moves the rows of sources mandrel cannot name, so it refuses the split. A red capture keeps the last green stamp for this split alone. Rows outside the delta can go stale in either direction; validate against full captures before raising it. `10` is a reasonable start. |
|
|
191
191
|
| `quality.gates.crap` | No | `object` | — | CRAP (Change Risk Anti-Pattern) ratchet — per-method cyclomatic complexity joined against per-method coverage. |
|
|
192
192
|
| `quality.gates.crap.enabled` | No | `boolean` | `true` | When false, the checker exits 0 with a skip line and the gate is reported as `skipped`, never omitted. |
|
|
193
193
|
| `quality.gates.crap.baselinePath` | No | `string` | `"baselines/crap.json"` | Repo-root-relative path to the gate's committed baseline artifact. |
|
|
@@ -205,6 +205,7 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
205
205
|
| `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
206
|
| `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. |
|
|
207
207
|
| `quality.gates.crap.incrementalCoverage.baseRef` | No | `string` | — | Default git ref the changed-file set is computed against, for a caller that passes no `--ref`. A `--ref` the caller named wins over this value, so a caller that anchors another gate on the same ref — `.husky/pre-push`, which passes `--ref origin/main` and then previews `--changed-since origin/main` — resolves ONE scope for both steps (Story #5365). Omitted and unpassed, the default is `origin/<project.baseBranch>` (`origin/main` by default), so a local base branch that trails the remote cannot widen the set; a clone where that remote ref does not resolve falls back to the local base branch with a warning. |
|
|
208
|
+
| `quality.gates.crap.previewScope` | No | `"file"` \| `"touched-methods"` | `"file"` | What the CRAP preview judges in a changed file. `file` compares every method to its row. `touched-methods` compares only methods whose line range intersects a hunk of the diff against the base: other regressions print as informational rows and pass. New methods always face `newMethodCeiling`, and a method whose hunks cannot be read is judged. |
|
|
208
209
|
| `quality.gates.crap.coveragePath` | No | `string` \| `null` | `null` | 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. |
|
|
209
210
|
| `quality.gates.crap.captureScript` | No | `string` | — | `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`. |
|
|
210
211
|
| `quality.gates.maintainability` | No | `object` | — | Maintainability-index ratchet. Scores per file as the average over its methods, so deleting a small high-MI method can legitimately lower a file’s score. |
|
|
@@ -281,6 +282,14 @@ Everything `/mandrel-deliver` and `single-story-close` consume: worktree isolati
|
|
|
281
282
|
| `pullRequest.bodyTrailers` | No | `array<string>` | `[]` | Story #5875. Git-trailer keys close lifts from the Story branch commits into the PR body, for a consumer whose required check reads a body line (e.g. `Policy-impact`). For each key the last branch commit carrying `<Key>: <value>` as a trailer wins, and the line is appended after the auto-opened marker and before any `BREAKING CHANGE:` footer. A key no commit carries appends nothing and logs one info line. Workers record the value with `git commit --trailer`. Default [] leaves the body unchanged. |
|
|
282
283
|
| `handoff` | No | `object` | — | Story #5960. What `story-handoff.js` runs beyond close's own gates. |
|
|
283
284
|
| `handoff.postSeatChecks[]` | No | `array<object>` | `[]` | Story #5960. Consumer checks the handoff re-runs in its post-capture step, after the seat commits the Story's new baseline rows: each `{ cmd, args? }` runs in the worktree without a shell, with `MANDREL_HANDOFF_STEP=post-capture`, and a non-zero exit settles `fix-required`. Declare the check a consumer downgrades during `preflight` (keyed on `MANDREL_HANDOFF_STEP`) here, so a row the seat did not write still fails the handoff; while any is declared the preflight `lint` credit is withheld until they pass at HEAD. Skipped under a coverage deferral. Default [] runs nothing extra. Each item has: cmd, args. |
|
|
285
|
+
| `orchestrate` | No | `object` | — | Story #6040. Project facts `/mandrel-orchestrate` cannot derive: how this repository re-queues an ejected PR, and the release veto. Thresholds and authority defaults are constants, not config. |
|
|
286
|
+
| `orchestrate.requeueCommand` | No | `object` | — | Story #6040. `{ cmd, args? }` the inventory offers for an eligible ejected PR; `{pr}` in an arg is replaced by the PR number. Run without a shell, and only when the operator granted `requeue`. Unset, the inventory reports `command: null`. |
|
|
287
|
+
| `orchestrate.requeueCommand.cmd` | Yes | `string` | — | — |
|
|
288
|
+
| `orchestrate.requeueCommand.args` | No | `array<string>` | — | — |
|
|
289
|
+
| `orchestrate.releaseVeto` | No | `object` | — | Story #6040. `{ prLabel, cmd, args? }`: on a PR carrying `prLabel`, the inventory runs `cmd` (no shell, main checkout) and a non-zero exit holds a re-queue or auto-merge arm on that PR. Unset, no PR is vetoed. |
|
|
290
|
+
| `orchestrate.releaseVeto.prLabel` | Yes | `string` | — | — |
|
|
291
|
+
| `orchestrate.releaseVeto.cmd` | Yes | `string` | — | — |
|
|
292
|
+
| `orchestrate.releaseVeto.args` | No | `array<string>` | — | — |
|
|
284
293
|
| `routing` | No | `object` | — | v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313 and the derived-level ceremony routing in Story #5343. |
|
|
285
294
|
| `routing.roleScopedAgents` | No | `boolean` | `true` | Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full entry-doc (AGENTS.md or CLAUDE.md) @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate. |
|
|
286
295
|
| `routing.ceremonyProfile` | No | `"minimal"` \| `"standard"` \| `"strict"` | `"standard"` | Acceptance-ceremony depth — who authors the Story acceptance verdict. minimal and standard (default) = the inline self-eval, whatever the diff touches; strict = a fresh-context maker-blind critic. Review depth is a separate decision and still derives `deep` for any sensitive path (review-depth.js). |
|
|
@@ -551,12 +560,17 @@ only when **every** guard holds:
|
|
|
551
560
|
- the own part holds no coverage-determining config file;
|
|
552
561
|
- the own part touches at most `N` suite-input paths in the delta;
|
|
553
562
|
- no own commit deletes or renames a suite-input path;
|
|
554
|
-
-
|
|
555
|
-
`__tests__`, `spec` or `e2e` directory)
|
|
556
|
-
|
|
563
|
+
- the own part changes no test file (`*.test.*` / `*.spec.*`, or under a
|
|
564
|
+
`tests`, `test`, `__tests__`, `spec` or `e2e` directory): only the test
|
|
565
|
+
graph knows which sources a test reaches;
|
|
557
566
|
- no own commit is reachable from `origin/<baseBranch>` (that would be a
|
|
558
567
|
fast-forwarded base commit).
|
|
559
568
|
|
|
569
|
+
A red, killed or crashed capture restores the prior artifact and keeps the
|
|
570
|
+
last green stamp as a `.superseded` sibling. It never reads as fresh; it only
|
|
571
|
+
seeds this split, under the same guards, so the next own fix need not re-pay
|
|
572
|
+
the whole slice.
|
|
573
|
+
|
|
560
574
|
An eligible plan logs `needs an own-fix delta refresh — re-measuring <k>
|
|
561
575
|
file(s) changed since <sha> (<n> own file(s), <m> base file(s))` with
|
|
562
576
|
verdict `own-fix-delta-refresh`. A refusal logs the ordinary `delta refresh
|
|
@@ -51,7 +51,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
|
|
|
51
51
|
fails when it drifts from the on-disk workflow set. To change a command’s
|
|
52
52
|
description, edit the workflow file’s front-matter and regenerate.
|
|
53
53
|
|
|
54
|
-
## Commands (
|
|
54
|
+
## Commands (39)
|
|
55
55
|
|
|
56
56
|
| Command | Description |
|
|
57
57
|
| --- | --- |
|
|
@@ -86,6 +86,7 @@ description, edit the workflow file’s front-matter and regenerate.
|
|
|
86
86
|
| `/git-deliver` | Single ad-hoc delivery command for working-tree changes. Detects the git setup and escalates to the right terminal step — commit only, commit + push, or commit + push + open a PR with native auto-merge — picking the default from observable state and letting flags pin any level explicitly. Replaces the retired git-commit-all, git-push, and git-pr-all trio. |
|
|
87
87
|
| `/mandrel-deliver` | Unified delivery entry point. Takes Story ids or a plain-language prompt, derives which path the work belongs on, and lands it via the single deliver-story engine — story-<id> → PR → main. |
|
|
88
88
|
| `/mandrel-leverage` | Evidence-cited leverage review — draft five to twelve bets on how the project could be ~10x more useful, reliable or valuable, refute most of them with two maker-blind skeptics each, write the survivors, downgrades and refutations to temp/leverage/<run-id>/bets.md, and hand each survivor to /mandrel-plan behind a HITL gate. |
|
|
89
|
+
| `/mandrel-orchestrate` | One session that keeps every in-flight delivery moving — sweep the open PRs into exactly one state each, act only within the authority the operator recorded, message each owner once, close out every landed Story, and print the hand-back summary on stop. Reactive only; the host loop paces the sweeps. |
|
|
89
90
|
| `/mandrel-plan` | Unified planning entry point. Interrogate → author → persist. Emits one Story by default; splits into N>1 only under the default-single split policy. |
|
|
90
91
|
| `/mandrel-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the stabilized quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the dependency bump the CLI's closing report describes. |
|
|
91
92
|
| `/memory-consolidate` | Attended consolidation pass over this project's agent memory pool — merge duplicates, verify claims against the current tree, prune with operator confirmation, rewrite the index, and stamp the pool with the date and entry count the /mandrel-plan advisory measures its next nudge against. |
|
|
@@ -788,7 +788,7 @@
|
|
|
788
788
|
"type": "integer",
|
|
789
789
|
"minimum": 0,
|
|
790
790
|
"maximum": 50,
|
|
791
|
-
"description": "Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no
|
|
791
|
+
"description": "Opt-in own-fix delta refresh for `captureScope: affected`. `0` (default) keeps it off. `N >= 1` lets a delta that today's rule refuses for a Story overlap or a config file be re-measured as a delta when it splits, along HEAD's first-parent chain, into base-sync merges that pass today's rule and the Story's own non-merge commits touching at most `N` suite-input files, with no config file, no deleted or renamed suite input and no test file: a changed test moves the rows of sources mandrel cannot name, so it refuses the split. A red capture keeps the last green stamp for this split alone. Rows outside the delta can go stale in either direction; validate against full captures before raising it. `10` is a reasonable start.",
|
|
792
792
|
"default": 0
|
|
793
793
|
}
|
|
794
794
|
},
|
|
@@ -940,6 +940,12 @@
|
|
|
940
940
|
},
|
|
941
941
|
"additionalProperties": false
|
|
942
942
|
},
|
|
943
|
+
"previewScope": {
|
|
944
|
+
"type": "string",
|
|
945
|
+
"enum": ["file", "touched-methods"],
|
|
946
|
+
"description": "What the CRAP preview judges in a changed file. `file` compares every method to its row. `touched-methods` compares only methods whose line range intersects a hunk of the diff against the base: other regressions print as informational rows and pass. New methods always face `newMethodCeiling`, and a method whose hunks cannot be read is judged.",
|
|
947
|
+
"default": "file"
|
|
948
|
+
},
|
|
943
949
|
"coveragePath": {
|
|
944
950
|
"type": ["string", "null"],
|
|
945
951
|
"minLength": 1,
|
|
@@ -1694,6 +1700,53 @@
|
|
|
1694
1700
|
},
|
|
1695
1701
|
"additionalProperties": false
|
|
1696
1702
|
},
|
|
1703
|
+
"orchestrate": {
|
|
1704
|
+
"type": "object",
|
|
1705
|
+
"description": "Story #6040. Project facts `/mandrel-orchestrate` cannot derive: how this repository re-queues an ejected PR, and the release veto. Thresholds and authority defaults are constants, not config.",
|
|
1706
|
+
"properties": {
|
|
1707
|
+
"requeueCommand": {
|
|
1708
|
+
"type": "object",
|
|
1709
|
+
"properties": {
|
|
1710
|
+
"cmd": {
|
|
1711
|
+
"type": "string",
|
|
1712
|
+
"minLength": 1
|
|
1713
|
+
},
|
|
1714
|
+
"args": {
|
|
1715
|
+
"type": "array",
|
|
1716
|
+
"items": {
|
|
1717
|
+
"type": "string"
|
|
1718
|
+
}
|
|
1719
|
+
}
|
|
1720
|
+
},
|
|
1721
|
+
"required": ["cmd"],
|
|
1722
|
+
"additionalProperties": false,
|
|
1723
|
+
"description": "Story #6040. `{ cmd, args? }` the inventory offers for an eligible ejected PR; `{pr}` in an arg is replaced by the PR number. Run without a shell, and only when the operator granted `requeue`. Unset, the inventory reports `command: null`."
|
|
1724
|
+
},
|
|
1725
|
+
"releaseVeto": {
|
|
1726
|
+
"type": "object",
|
|
1727
|
+
"properties": {
|
|
1728
|
+
"prLabel": {
|
|
1729
|
+
"type": "string",
|
|
1730
|
+
"minLength": 1
|
|
1731
|
+
},
|
|
1732
|
+
"cmd": {
|
|
1733
|
+
"type": "string",
|
|
1734
|
+
"minLength": 1
|
|
1735
|
+
},
|
|
1736
|
+
"args": {
|
|
1737
|
+
"type": "array",
|
|
1738
|
+
"items": {
|
|
1739
|
+
"type": "string"
|
|
1740
|
+
}
|
|
1741
|
+
}
|
|
1742
|
+
},
|
|
1743
|
+
"required": ["prLabel", "cmd"],
|
|
1744
|
+
"additionalProperties": false,
|
|
1745
|
+
"description": "Story #6040. `{ prLabel, cmd, args? }`: on a PR carrying `prLabel`, the inventory runs `cmd` (no shell, main checkout) and a non-zero exit holds a re-queue or auto-merge arm on that PR. Unset, no PR is vetoed."
|
|
1746
|
+
}
|
|
1747
|
+
},
|
|
1748
|
+
"additionalProperties": false
|
|
1749
|
+
},
|
|
1697
1750
|
"routing": {
|
|
1698
1751
|
"type": "object",
|
|
1699
1752
|
"description": "v2 delivery-spawn routing: role-scoped boot contexts and the ceremony profile. The v1 singleDelivery epic-route kill-switch was removed in Stage 6; the freshCriticSampleRate sampling floor was retired in Story #5313 and the derived-level ceremony routing in Story #5343.",
|
|
@@ -22,7 +22,7 @@ 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
|
-
import { deriveCeremony } from './ceremony-derive.js';
|
|
25
|
+
import { deriveCeremony, resolveDefaultBaseRef } from './ceremony-derive.js';
|
|
26
26
|
import { runAsCli } from './lib/cli-utils.js';
|
|
27
27
|
import { getDeliveryRouting } from './lib/config/delivery-routing.js';
|
|
28
28
|
import { resolvedTempRoot } from './lib/config/temp-paths.js';
|
|
@@ -261,7 +261,7 @@ export async function initVerdictSkeleton({ storyId, cwd, config }, deps = {}) {
|
|
|
261
261
|
}
|
|
262
262
|
const ceremony = deriveCeremonyImpl({
|
|
263
263
|
storyId,
|
|
264
|
-
baseRef: config
|
|
264
|
+
baseRef: resolveDefaultBaseRef({ config, cwd }),
|
|
265
265
|
cwd,
|
|
266
266
|
ceremonyProfile: getDeliveryRouting(config).ceremonyProfile,
|
|
267
267
|
});
|
|
@@ -19,6 +19,7 @@ import { getDeliveryRouting } from './lib/config/delivery-routing.js';
|
|
|
19
19
|
import { resolveConfig } from './lib/config-resolver.js';
|
|
20
20
|
import { resolveCeremonyForRisk } from './lib/orchestration/ceremony-routing.js';
|
|
21
21
|
import { computeChangeSet } from './lib/orchestration/change-set.js';
|
|
22
|
+
import { resolveSharedBaseRef } from './lib/orchestration/review-base-ref.js';
|
|
22
23
|
import { deriveChangeLevel } from './lib/orchestration/review-depth.js';
|
|
23
24
|
|
|
24
25
|
const USAGE = {
|
|
@@ -30,7 +31,7 @@ const USAGE = {
|
|
|
30
31
|
['--story <id>', 'Story issue number; the head ref is story-<id>.'],
|
|
31
32
|
[
|
|
32
33
|
'--base <ref>',
|
|
33
|
-
'Base ref for the three-dot diff (default: project.baseBranch
|
|
34
|
+
'Base ref for the three-dot diff (default: origin/<project.baseBranch>, else project.baseBranch).',
|
|
34
35
|
],
|
|
35
36
|
[
|
|
36
37
|
'--cwd <path>',
|
|
@@ -39,6 +40,18 @@ const USAGE = {
|
|
|
39
40
|
],
|
|
40
41
|
};
|
|
41
42
|
|
|
43
|
+
/**
|
|
44
|
+
* The default change-set base: the remote ref handoff and close diff against,
|
|
45
|
+
* so a stale local base cannot score others' commits as the Story's.
|
|
46
|
+
*
|
|
47
|
+
* @param {{ config: object, cwd: string }} args
|
|
48
|
+
* @returns {string}
|
|
49
|
+
*/
|
|
50
|
+
export function resolveDefaultBaseRef({ config, cwd }) {
|
|
51
|
+
const baseBranch = config?.project?.baseBranch ?? 'main';
|
|
52
|
+
return resolveSharedBaseRef({ baseBranch, cwd }).ref ?? baseBranch;
|
|
53
|
+
}
|
|
54
|
+
|
|
42
55
|
/**
|
|
43
56
|
* @param {string[]} argv
|
|
44
57
|
* @returns {{ storyId: number|null, base: string|null, cwd: string|null }}
|
|
@@ -137,7 +150,7 @@ export async function runCeremonyDeriveCli(
|
|
|
137
150
|
const envelope = deriveCeremony(
|
|
138
151
|
{
|
|
139
152
|
storyId,
|
|
140
|
-
baseRef: base ?? config
|
|
153
|
+
baseRef: base ?? resolveDefaultBaseRef({ config, cwd: workCwd }),
|
|
141
154
|
cwd: workCwd,
|
|
142
155
|
ceremonyProfile: getDeliveryRouting(config).ceremonyProfile,
|
|
143
156
|
},
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* closeout-audit.js — report every landed Story whose close-out did not
|
|
5
|
+
* finish; `--execute` repairs each drifted check through its existing seam.
|
|
6
|
+
*
|
|
7
|
+
* Exit codes: 0 nothing drifted (or all repaired), 2 drift remains, 1 the
|
|
8
|
+
* audit itself could not run.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
import path from 'node:path';
|
|
12
|
+
import { parseArgs } from 'node:util';
|
|
13
|
+
|
|
14
|
+
import { runAsCli } from './lib/cli-utils.js';
|
|
15
|
+
import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
|
|
16
|
+
import {
|
|
17
|
+
buildProbes,
|
|
18
|
+
buildRepairs,
|
|
19
|
+
buildWithLock,
|
|
20
|
+
DEFAULT_SINCE_HOURS,
|
|
21
|
+
exitCodeFor,
|
|
22
|
+
listMergedStoryIds,
|
|
23
|
+
renderAudit,
|
|
24
|
+
runCloseoutAudit,
|
|
25
|
+
} from './lib/orchestration/closeout-audit.js';
|
|
26
|
+
import { createProvider } from './lib/provider-factory.js';
|
|
27
|
+
|
|
28
|
+
const USAGE = {
|
|
29
|
+
invocation:
|
|
30
|
+
'node .agents/scripts/closeout-audit.js [--story <id[,id…]>] [--since-hours <n>] [--execute] [--json] [--cwd <main-repo>]',
|
|
31
|
+
summary:
|
|
32
|
+
'Audit landed Stories for an unfinished close-out (state, board, branches, worktree, scratch). Dry-run unless --execute.',
|
|
33
|
+
flags: [
|
|
34
|
+
['--story <ids>', 'Audit exactly these Story ids (comma-separated).'],
|
|
35
|
+
[
|
|
36
|
+
'--since-hours <n>',
|
|
37
|
+
`Without --story: Stories whose story-<id> PR merged in the last n hours (default ${DEFAULT_SINCE_HOURS}).`,
|
|
38
|
+
],
|
|
39
|
+
[
|
|
40
|
+
'--execute',
|
|
41
|
+
'Repair each drifted check through its existing seam, then re-audit.',
|
|
42
|
+
],
|
|
43
|
+
['--json', 'Print one closeout-audit envelope on stdout.'],
|
|
44
|
+
['--cwd <path>', 'Main-repo checkout (default: project root).'],
|
|
45
|
+
],
|
|
46
|
+
notes: [
|
|
47
|
+
'Exit 0 nothing drifted, 2 drift remains, 1 the audit could not run.',
|
|
48
|
+
'An unknown check (probe could not run) is reported, never repaired.',
|
|
49
|
+
],
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
export function parseCloseoutArgv(argv) {
|
|
53
|
+
const { values } = parseArgs({
|
|
54
|
+
args: argv,
|
|
55
|
+
options: {
|
|
56
|
+
story: { type: 'string' },
|
|
57
|
+
'since-hours': { type: 'string' },
|
|
58
|
+
execute: { type: 'boolean', default: false },
|
|
59
|
+
json: { type: 'boolean', default: false },
|
|
60
|
+
cwd: { type: 'string' },
|
|
61
|
+
},
|
|
62
|
+
strict: true,
|
|
63
|
+
});
|
|
64
|
+
const storyIds = values.story
|
|
65
|
+
? values.story.split(',').map((s) => Number.parseInt(s.trim(), 10))
|
|
66
|
+
: null;
|
|
67
|
+
if (storyIds?.some((id) => !Number.isInteger(id) || id <= 0)) {
|
|
68
|
+
throw new Error(
|
|
69
|
+
`--story must be positive integer ids (got "${values.story}")`,
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
const sinceHours =
|
|
73
|
+
values['since-hours'] === undefined
|
|
74
|
+
? DEFAULT_SINCE_HOURS
|
|
75
|
+
: Number(values['since-hours']);
|
|
76
|
+
if (!(sinceHours > 0))
|
|
77
|
+
throw new Error('--since-hours must be a positive number');
|
|
78
|
+
return {
|
|
79
|
+
storyIds,
|
|
80
|
+
sinceHours,
|
|
81
|
+
execute: values.execute,
|
|
82
|
+
json: values.json,
|
|
83
|
+
cwd: path.resolve(values.cwd ?? PROJECT_ROOT),
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
const stderrLogger = {
|
|
88
|
+
info: (m) => process.stderr.write(`${m}\n`),
|
|
89
|
+
warn: (m) => process.stderr.write(`${m}\n`),
|
|
90
|
+
error: (m) => process.stderr.write(`${m}\n`),
|
|
91
|
+
};
|
|
92
|
+
|
|
93
|
+
/* node:coverage ignore next -- CLI wiring over the tested lib */
|
|
94
|
+
async function main() {
|
|
95
|
+
const args = parseCloseoutArgv(process.argv.slice(2));
|
|
96
|
+
const config = resolveConfig({ cwd: args.cwd });
|
|
97
|
+
const provider = createProvider(config);
|
|
98
|
+
const deps = { cwd: args.cwd, config, provider, logger: stderrLogger };
|
|
99
|
+
const storyIds =
|
|
100
|
+
args.storyIds ??
|
|
101
|
+
(await listMergedStoryIds({
|
|
102
|
+
baseBranch: config.project?.baseBranch ?? 'main',
|
|
103
|
+
sinceHours: args.sinceHours,
|
|
104
|
+
}));
|
|
105
|
+
const envelope = await runCloseoutAudit({
|
|
106
|
+
storyIds,
|
|
107
|
+
scope: args.storyIds
|
|
108
|
+
? { mode: 'explicit', storyIds, execute: args.execute }
|
|
109
|
+
: {
|
|
110
|
+
mode: 'window',
|
|
111
|
+
sinceHours: args.sinceHours,
|
|
112
|
+
storyIds,
|
|
113
|
+
execute: args.execute,
|
|
114
|
+
},
|
|
115
|
+
probes: buildProbes(deps),
|
|
116
|
+
repairs: buildRepairs(deps),
|
|
117
|
+
execute: args.execute,
|
|
118
|
+
withLock: buildWithLock(deps),
|
|
119
|
+
});
|
|
120
|
+
process.stdout.write(
|
|
121
|
+
args.json
|
|
122
|
+
? `${JSON.stringify(envelope, null, 2)}\n`
|
|
123
|
+
: renderAudit(envelope),
|
|
124
|
+
);
|
|
125
|
+
return exitCodeFor(envelope);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
runAsCli(import.meta.url, main, {
|
|
129
|
+
source: 'closeout-audit',
|
|
130
|
+
propagateExitCode: true,
|
|
131
|
+
usage: USAGE,
|
|
132
|
+
});
|
|
@@ -4,7 +4,6 @@
|
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
import path from 'node:path';
|
|
7
|
-
import { COVERAGE_CAPTURE_DEFAULTS } from '../config/gates/coverage.schema.js';
|
|
8
7
|
import { loadCoverage } from '../coverage-utils.js';
|
|
9
8
|
import {
|
|
10
9
|
KERNEL_VERSION,
|
|
@@ -13,6 +12,12 @@ import {
|
|
|
13
12
|
} from '../crap-utils.js';
|
|
14
13
|
import { CYCLOMATIC_CEILING } from '../cyclomatic-ceiling.js';
|
|
15
14
|
import { resolveCrapPreviewIncremental } from './crap-preview-incremental.js';
|
|
15
|
+
import {
|
|
16
|
+
outsideDiffDiagnostics,
|
|
17
|
+
previewCoveragePath,
|
|
18
|
+
previewNotRun,
|
|
19
|
+
resolveIsJudged,
|
|
20
|
+
} from './crap-preview-touched.js';
|
|
16
21
|
import { resolveCrapEnvOverrides } from './env-overrides.js';
|
|
17
22
|
import {
|
|
18
23
|
buildCrapReport,
|
|
@@ -57,12 +62,6 @@ export function listCyclomaticAdvisories(rows) {
|
|
|
57
62
|
}));
|
|
58
63
|
}
|
|
59
64
|
|
|
60
|
-
function loadPreviewCoverage(crap, cwd) {
|
|
61
|
-
const coveragePath =
|
|
62
|
-
crap.coveragePath ?? COVERAGE_CAPTURE_DEFAULTS.coveragePath;
|
|
63
|
-
return loadCoverage(path.resolve(cwd, coveragePath));
|
|
64
|
-
}
|
|
65
|
-
|
|
66
65
|
/**
|
|
67
66
|
* @param {{
|
|
68
67
|
* crap: object,
|
|
@@ -72,6 +71,7 @@ function loadPreviewCoverage(crap, cwd) {
|
|
|
72
71
|
* diffRef: string|null,
|
|
73
72
|
* baseline: { rows: object[] },
|
|
74
73
|
* baseBranch?: string,
|
|
74
|
+
* git?: Function,
|
|
75
75
|
* }} opts
|
|
76
76
|
* @returns {Promise<{ exitCode: number, envelope: object }>}
|
|
77
77
|
*/
|
|
@@ -83,19 +83,22 @@ export async function computeCrapPreviewScan({
|
|
|
83
83
|
diffRef,
|
|
84
84
|
baseline,
|
|
85
85
|
baseBranch,
|
|
86
|
+
git,
|
|
86
87
|
}) {
|
|
87
88
|
const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
|
|
88
89
|
const crapIgnoreGlobs = Array.isArray(crap.ignoreGlobs)
|
|
89
90
|
? crap.ignoreGlobs
|
|
90
91
|
: [];
|
|
91
92
|
const requireCoverage = crap.requireCoverage !== false;
|
|
92
|
-
const coverage = loadPreviewCoverage(crap, cwd);
|
|
93
93
|
// The configured tolerance keeps the preview aligned with the authoritative
|
|
94
94
|
// gate: deltas at or under it are demoted, not failed.
|
|
95
95
|
const { newMethodCeiling, tolerance } = resolveCrapEnvOverrides(
|
|
96
96
|
crap,
|
|
97
97
|
process.env,
|
|
98
98
|
);
|
|
99
|
+
const notRun = previewNotRun({ crap, targetDirs, cwd, scope, diffRef });
|
|
100
|
+
if (notRun) return notRun;
|
|
101
|
+
const coverage = loadCoverage(path.resolve(cwd, previewCoveragePath(crap)));
|
|
99
102
|
const incremental = resolveCrapPreviewIncremental({
|
|
100
103
|
crap,
|
|
101
104
|
diffRef,
|
|
@@ -118,6 +121,7 @@ export async function computeCrapPreviewScan({
|
|
|
118
121
|
baselineRows,
|
|
119
122
|
newMethodCeiling,
|
|
120
123
|
tolerance,
|
|
124
|
+
isJudged: resolveIsJudged({ crap, diffRef, baseBranch, cwd, git }),
|
|
121
125
|
});
|
|
122
126
|
const envelope = buildCrapReport({
|
|
123
127
|
compareResult: result,
|
|
@@ -128,6 +132,9 @@ export async function computeCrapPreviewScan({
|
|
|
128
132
|
scopeInfo: { scope, diffRef },
|
|
129
133
|
});
|
|
130
134
|
envelope.cyclomaticAdvisories = listCyclomaticAdvisories(scan.rows);
|
|
135
|
+
if (result.informational.length > 0) {
|
|
136
|
+
envelope.diagnostics = outsideDiffDiagnostics(result.informational);
|
|
137
|
+
}
|
|
131
138
|
const exitCode = hasCrapRegressions(result) ? 1 : 0;
|
|
132
139
|
return { exitCode, envelope };
|
|
133
140
|
}
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `crap.previewScope: touched-methods`: which regressions the preview judges,
|
|
3
|
+
* from the hunks of the diff against the base; and the preview's own absence
|
|
4
|
+
* when no fresh artifact exists.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import fs from 'node:fs';
|
|
8
|
+
import path from 'node:path';
|
|
9
|
+
import { COVERAGE_CAPTURE_DEFAULTS } from '../config/gates/coverage.schema.js';
|
|
10
|
+
import { COORDINATE_ORIGINAL } from '../crap-coordinates.js';
|
|
11
|
+
import { KERNEL_VERSION, resolveEscomplexVersion } from '../crap-utils.js';
|
|
12
|
+
import { gitSpawn } from '../git-utils.js';
|
|
13
|
+
import {
|
|
14
|
+
buildCrapReport,
|
|
15
|
+
compareCrap,
|
|
16
|
+
suppressVerdicts,
|
|
17
|
+
} from './kinds/crap.js';
|
|
18
|
+
import { isCaptureFresh } from './seat-missing.js';
|
|
19
|
+
|
|
20
|
+
export function previewCoveragePath(crap) {
|
|
21
|
+
return crap.coveragePath ?? COVERAGE_CAPTURE_DEFAULTS.coveragePath;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** Why the artifact cannot be joined, or `null` when it matches the tree. */
|
|
25
|
+
function coverageAbsence(crap, targetDirs, cwd) {
|
|
26
|
+
const coveragePath = previewCoveragePath(crap);
|
|
27
|
+
if (isCaptureFresh({ coveragePath, targetDirs }, { cwd })) return null;
|
|
28
|
+
return fs.existsSync(path.resolve(cwd, coveragePath))
|
|
29
|
+
? `${coveragePath} does not match the current tree`
|
|
30
|
+
: `no coverage artifact at ${coveragePath}`;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** The verdict-free report of a preview that scored nothing. */
|
|
34
|
+
function notRunResult({ reason, scope, diffRef, newMethodCeiling }) {
|
|
35
|
+
const envelope = buildCrapReport({
|
|
36
|
+
compareResult: compareCrap({ currentRows: [], baselineRows: [] }),
|
|
37
|
+
kernelVersion: KERNEL_VERSION,
|
|
38
|
+
escomplexVersion: resolveEscomplexVersion(),
|
|
39
|
+
newMethodCeiling,
|
|
40
|
+
scopeInfo: { scope, diffRef },
|
|
41
|
+
});
|
|
42
|
+
const diagnostic = {
|
|
43
|
+
name: 'crap-coverage-not-fresh',
|
|
44
|
+
message: `CRAP half did not run: ${reason}`,
|
|
45
|
+
};
|
|
46
|
+
return { exitCode: 0, envelope: suppressVerdicts(envelope, diagnostic) };
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** The not-run result when no artifact matches the tree, else `null`. */
|
|
50
|
+
export function previewNotRun({ crap, targetDirs, cwd, scope, diffRef }) {
|
|
51
|
+
const reason = coverageAbsence(crap, targetDirs, cwd);
|
|
52
|
+
if (!reason) return null;
|
|
53
|
+
const { newMethodCeiling } = crap;
|
|
54
|
+
return notRunResult({ reason, scope, diffRef, newMethodCeiling });
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* New-side line ranges per file of a `-U0` diff. Hunk bodies are skipped by
|
|
59
|
+
* count, so an added line reading `+++ b/x` opens no file.
|
|
60
|
+
*
|
|
61
|
+
* @param {string} text
|
|
62
|
+
* @returns {Map<string, Array<[number, number]>>}
|
|
63
|
+
*/
|
|
64
|
+
function parseDiffHunks(text) {
|
|
65
|
+
const hunks = new Map();
|
|
66
|
+
let ranges = null;
|
|
67
|
+
let body = 0;
|
|
68
|
+
for (const line of text.split(/\r?\n/)) {
|
|
69
|
+
if (body > 0) {
|
|
70
|
+
body -= 1;
|
|
71
|
+
continue;
|
|
72
|
+
}
|
|
73
|
+
if (line.startsWith('+++ ')) {
|
|
74
|
+
const file = /^\+\+\+ b\/(.+)$/.exec(line)?.[1];
|
|
75
|
+
ranges = file ? [] : null;
|
|
76
|
+
if (file) hunks.set(file, ranges);
|
|
77
|
+
continue;
|
|
78
|
+
}
|
|
79
|
+
const m = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/.exec(line);
|
|
80
|
+
if (!m) continue;
|
|
81
|
+
const [removed, start, added] = [m[1] ?? 1, m[2], m[3] ?? 1].map(Number);
|
|
82
|
+
body = removed + added;
|
|
83
|
+
// A pure deletion names the line before it.
|
|
84
|
+
ranges?.push([start, start + Math.max(added - 1, 0)]);
|
|
85
|
+
}
|
|
86
|
+
return hunks;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** The hunks of the diff from `ref`'s merge-base; `null` when unreadable. */
|
|
90
|
+
function readDiffHunks(ref, cwd, git) {
|
|
91
|
+
const base = git(cwd, 'merge-base', ref, 'HEAD');
|
|
92
|
+
if (base?.status !== 0) return null;
|
|
93
|
+
const diff = git(
|
|
94
|
+
cwd,
|
|
95
|
+
'diff',
|
|
96
|
+
'-U0',
|
|
97
|
+
'--no-color',
|
|
98
|
+
'--no-ext-diff',
|
|
99
|
+
'--src-prefix=a/',
|
|
100
|
+
'--dst-prefix=b/',
|
|
101
|
+
String(base.stdout).trim(),
|
|
102
|
+
);
|
|
103
|
+
return diff?.status === 0 ? parseDiffHunks(String(diff.stdout)) : null;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* The `compareCrap` predicate for `previewScope`. Fails closed: a row with
|
|
108
|
+
* no original-coordinate span, or a file with no readable hunks, is judged.
|
|
109
|
+
*
|
|
110
|
+
* @returns {((row: object) => boolean)|undefined}
|
|
111
|
+
*/
|
|
112
|
+
export function resolveIsJudged({
|
|
113
|
+
crap,
|
|
114
|
+
diffRef,
|
|
115
|
+
baseBranch,
|
|
116
|
+
cwd,
|
|
117
|
+
git = gitSpawn,
|
|
118
|
+
}) {
|
|
119
|
+
if (crap.previewScope !== 'touched-methods') return undefined;
|
|
120
|
+
const hunks = readDiffHunks(diffRef ?? `origin/${baseBranch}`, cwd, git);
|
|
121
|
+
if (!hunks) return undefined;
|
|
122
|
+
return (row) => {
|
|
123
|
+
const ranges = hunks.get(row.file);
|
|
124
|
+
if (
|
|
125
|
+
!ranges ||
|
|
126
|
+
row.coordinateSystem !== COORDINATE_ORIGINAL ||
|
|
127
|
+
!Number.isFinite(row.endLine)
|
|
128
|
+
) {
|
|
129
|
+
return true;
|
|
130
|
+
}
|
|
131
|
+
return ranges.some(([s, e]) => s <= row.endLine && e >= row.startLine);
|
|
132
|
+
};
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
export function outsideDiffDiagnostics(informational) {
|
|
136
|
+
return informational.map((v) => ({
|
|
137
|
+
name: 'crap-regression-outside-diff',
|
|
138
|
+
message: `informational: ${v.file}::${v.method} crap ${v.crap.toFixed(2)} > baseline ${v.baseline.toFixed(2)}, outside this diff's hunks`,
|
|
139
|
+
}));
|
|
140
|
+
}
|