mandrel 2.70.0 → 2.72.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 (79) hide show
  1. package/.agents/README.md +8 -9
  2. package/.agents/agents/acceptance-critic.md +1 -0
  3. package/.agents/agents/auditor.md +1 -0
  4. package/.agents/agents/plan-critic.md +1 -0
  5. package/.agents/agents/story-worker.md +63 -64
  6. package/.agents/docs/agentrc-reference.json +2 -1
  7. package/.agents/docs/configuration.md +7 -8
  8. package/.agents/rules/git-conventions-reference.md +2 -2
  9. package/.agents/schemas/agentrc.schema.json +19 -2
  10. package/.agents/schemas/story-deliver-terminal.schema.json +10 -1
  11. package/.agents/scripts/acceptance-eval.js +194 -15
  12. package/.agents/scripts/deliver-run.js +92 -43
  13. package/.agents/scripts/lib/audit-suite/index.js +1 -1
  14. package/.agents/scripts/lib/audit-suite/story-checklist.js +65 -0
  15. package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js +2 -2
  16. package/.agents/scripts/lib/bootstrap/issue-forms-template.js +1 -1
  17. package/.agents/scripts/lib/cli-args.js +22 -0
  18. package/.agents/scripts/lib/close-validation/gates.js +17 -3
  19. package/.agents/scripts/lib/config/agent-models.js +117 -0
  20. package/.agents/scripts/lib/config-settings-schema-delivery.js +13 -1
  21. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +1 -1
  23. package/.agents/scripts/lib/git/sync-from-base.js +89 -17
  24. package/.agents/scripts/lib/label-taxonomy.js +13 -3
  25. package/.agents/scripts/lib/notifications/notifier.js +11 -15
  26. package/.agents/scripts/lib/observability/close-telemetry.js +19 -3
  27. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  28. package/.agents/scripts/lib/orchestration/cancelled-run-discount.js +129 -0
  29. package/.agents/scripts/lib/orchestration/code-review.js +2 -2
  30. package/.agents/scripts/lib/orchestration/deliver-recover.js +166 -34
  31. package/.agents/scripts/lib/orchestration/file-assumptions.js +45 -11
  32. package/.agents/scripts/lib/orchestration/plan-context.js +17 -10
  33. package/.agents/scripts/lib/orchestration/plan-persist/changes-repair.js +130 -24
  34. package/.agents/scripts/lib/orchestration/plan-persist/run-plan-persist.js +19 -16
  35. package/.agents/scripts/lib/orchestration/plan-persist/story-ops.js +1 -0
  36. package/.agents/scripts/lib/orchestration/plan-persist/summary.js +4 -3
  37. package/.agents/scripts/lib/orchestration/pr-watch.js +14 -3
  38. package/.agents/scripts/lib/orchestration/resolve-stories.js +10 -2
  39. package/.agents/scripts/lib/orchestration/review-providers/native.js +5 -165
  40. package/.agents/scripts/lib/orchestration/single-story-close/failed-terminal.js +14 -2
  41. package/.agents/scripts/lib/orchestration/single-story-close/phases/auto-merge.js +45 -0
  42. package/.agents/scripts/lib/orchestration/single-story-close/phases/base-sync.js +162 -58
  43. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +58 -6
  44. package/.agents/scripts/lib/orchestration/single-story-close/phases/merge-wait-recovery.js +296 -0
  45. package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js +20 -4
  46. package/.agents/scripts/lib/orchestration/single-story-close/phases/post-land.js +52 -6
  47. package/.agents/scripts/lib/orchestration/single-story-close/phases/pull-request.js +2 -2
  48. package/.agents/scripts/lib/orchestration/single-story-close/phases/story-branch-catch-up.js +50 -0
  49. package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-reap.js +64 -52
  50. package/.agents/scripts/lib/orchestration/single-story-close/phases/worktree-restore.js +133 -0
  51. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +187 -74
  52. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +46 -6
  53. package/.agents/scripts/lib/orchestration/story-handoff.js +849 -0
  54. package/.agents/scripts/lib/orchestration/story-init-result.js +83 -0
  55. package/.agents/scripts/lib/orchestration/task-body-validator.js +35 -5
  56. package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js +1 -1
  57. package/.agents/scripts/lib/orchestration/ticket-validator.js +20 -2
  58. package/.agents/scripts/lib/single-story/confirm-merge.js +44 -7
  59. package/.agents/scripts/lib/story-body/story-body.js +40 -5
  60. package/.agents/scripts/lib/templates/decomposer-prompts.js +33 -36
  61. package/.agents/scripts/pr-watch-with-update.js +5 -0
  62. package/.agents/scripts/single-story-close.js +8 -0
  63. package/.agents/scripts/single-story-confirm-merge.js +34 -3
  64. package/.agents/scripts/single-story-init.js +17 -32
  65. package/.agents/scripts/story-handoff.js +112 -0
  66. package/.agents/scripts/sync-claude-agents.js +58 -27
  67. package/.agents/workflows/helpers/acceptance-self-eval.md +24 -18
  68. package/.agents/workflows/helpers/code-review.md +3 -3
  69. package/.agents/workflows/helpers/deliver-digest.md +79 -80
  70. package/.agents/workflows/helpers/deliver-light.md +9 -7
  71. package/.agents/workflows/helpers/deliver-reference.md +38 -22
  72. package/.agents/workflows/helpers/deliver-story-reference.md +39 -18
  73. package/.agents/workflows/helpers/deliver-story.md +30 -23
  74. package/.agents/workflows/helpers/plan-reference.md +24 -9
  75. package/.agents/workflows/helpers/worktree-lifecycle.md +5 -5
  76. package/docs/CHANGELOG.md +31 -0
  77. package/lib/cli/registry.js +7 -0
  78. package/package.json +4 -3
  79. package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js +0 -272
@@ -173,9 +173,23 @@ anything a plan authored.
173
173
  is then a dry-run **warning**, not a rejection. `deletes` stays explicit —
174
174
  a bare path can never express a removal — and a `deletes` naming a path
175
175
  absent at base is the one `changes[]` shape still refused.
176
- - **Keep `## Spec` at contract-level prose** — interfaces, invariants,
177
- load-bearing constraints; no per-file behavior narration — and as long as
178
- the work needs. There is no word or token budget.
176
+ - **`## Spec` decides.** Every load-bearing mechanism is chosen there with
177
+ its why; a choice is left to the deliverer only when it is genuinely not
178
+ load-bearing. It stays contract-level — no per-file behavior narration —
179
+ and as long as the work needs. There is no word or token budget.
180
+ - **`## Context` is the handoff.** An optional text section after `## Spec`:
181
+ entry points (file + symbol), the pattern to mirror, the test file or
182
+ harness to extend, known traps, the scoped test command — verified facts,
183
+ tersely, never a walkthrough. Backticked repo paths in it are probed at
184
+ persist and **warn** when absent at base.
185
+ - **`references[]` names the read-first files.** Author the files the
186
+ deliverer should read before editing. A bare path is the default: persist
187
+ derives `exists` by probing base and warns, never refuses, on an absent one.
188
+ - **Slicing checkpoints may end `— verify: <exact command>`** — encouraged
189
+ past two checkpoints, so each stage is proven before the next starts.
190
+
191
+ Context, References and checkpoint verify commands are advisory like
192
+ `changes[]`; `acceptance[]` / `verify[]` stay the only binding contract.
179
193
 
180
194
  A faithfully-filled skeleton — placeholders replaced, pre-resolved entries
181
195
  kept — passes the persist ticket validators with no round-trip.
@@ -183,10 +197,10 @@ kept — passes the persist ticket validators with no round-trip.
183
197
  ### Authored entry shape
184
198
 
185
199
  Each `stories.json` entry: `slug` (`^[a-z0-9][a-z0-9-]*$`), `type: "story"`,
186
- `title`, `body` (`goal`, optional `spec`, `changes[]` — a **bare path string**
187
- by default, or `{path, assumption}` with
188
- `creates|refactors-existing|deletes` to pin one, `non_goals`,
189
- `reason_to_exist`), top-level `acceptance[]`, `verify[]` (each a **bare
200
+ `title`, `body` (`goal`, optional `slicing` / `spec` / `context`, `changes[]`
201
+ — a **bare path string** by default, or `{path, assumption}` with
202
+ `creates|refactors-existing|deletes` to pin one, optional `references[]` and
203
+ `non_goals`), top-level `acceptance[]`, `verify[]` (each a **bare
190
204
  command** — there is no tier suffix), and `depends_on[]` (a sibling slug, or
191
205
  `#<id>` for an existing open Story).
192
206
 
@@ -368,7 +382,8 @@ Commit subjects are not scanned — the `commit-msg` hook and
368
382
  **Warnings — listed, then the persist proceeds:** a `creates` on a path that
369
383
  exists at base or a `refactors-existing` on one that does not (including a
370
384
  path the base branch deleted or renamed, named with the removing commit), a
371
- goal or acceptance path absent at base, an empty `verify[]`, a source id
385
+ goal, acceptance or `## Context` path absent at base, a bare `references[]`
386
+ entry absent at base, an empty `verify[]`, a source id
372
387
  assigned to the primary Story by default, a `verify[]` command naming an
373
388
  absent test file, an `open-question` in a body (`Flag if…`, `TBD`, a trailing
374
389
  `?`), and a `pinned-identifier` in an acceptance item — a backticked bare symbol
@@ -376,7 +391,7 @@ that is not a path, a label, a kebab token, a flag or a command, which the
376
391
  advisory `changes[]` is free to reshape out from under the criterion. The
377
392
  list also names every **repair** the run applied — a plain-string bullet or a
378
393
  trailing parenthetical rewritten into `{ path, assumption }` by probing base,
379
- and an `AC-<n>:` handle normalised off an acceptance item. The same list rides
394
+ a bare reference present at base derived as `exists`, and an `AC-<n>:` handle normalised off an acceptance item. The same list rides
380
395
  the result envelope as `warnings[]` and `repairs[]`, carried from the
381
396
  write-free pass onto the chained run's envelope.
382
397
 
@@ -50,9 +50,9 @@ root, and shell-metacharacter injection in `root`.
50
50
  | **Sweep** | Operator-driven (`WorktreeManager.sweepStaleLocks`) | Stale `*.lock` files under `.git/` (older than 5 min) are removed before GC. |
51
51
  | **GC** | Operator-driven (`WorktreeManager.gc`) | Orphan `.worktrees/story-*` whose Stories are closed are reaped if clean. |
52
52
  | **Force-drain** | Operator-driven (`drain-pending-cleanup.js`) | Retries `.worktrees/.pending-cleanup.json` (`git worktree remove` then `fs.rm`); Windows-only escalation enumerates user-mode handle holders and `taskkill`s them before re-trying. |
53
- | **Ensure** | `single-story-init.js` (entry for `/mandrel-deliver`) | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch. |
53
+ | **Ensure** | `single-story-init.js` (entry for `/mandrel-deliver`); close and the `--wait` resume when it is missing | `git worktree add .worktrees/story-<id>/` on the `story-<id>` branch (fetched from origin when no local ref remains). |
54
54
  | **Run** | During Story execution | Agent runs inside the worktree; HEAD/reflog activity is isolated. |
55
- | **Reap** | After successful Story merge (in `single-story-close`) | `git worktree remove` — refuses to delete dirty trees or unmerged branches. |
55
+ | **Reap** | After a confirmed merge, in the post-land tail (`tail.worktreeReap`) | `git worktree remove`, before the local ref reap — refuses a dirty tree. A `pending`, `blocked` or `failed` close keeps the worktree. |
56
56
 
57
57
  The `WorktreeManager` (`.agents/scripts/lib/worktree-manager.js`) is the single
58
58
  authority for `ensure`, `reap`, `list`, `isSafeToRemove`, `gc`, `prune`, and
@@ -86,7 +86,7 @@ epic-runner. The lifecycle surfaces that do run automatically are:
86
86
  | Entry point | Script / caller | What it cleans |
87
87
  | --------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
88
88
  | Story init (`/mandrel-deliver <storyId>`) | `single-story-init.js` boot sweep (`sweepMergedStoryBranches`) | Merged/closed `story-*` branches (local + origin) from prior runs; it then creates only its own worktree. |
89
- | Story close (`/mandrel-deliver` close) | `single-story-close.js` worktree-reap phase (`WorktreeManager.reap`) | The per-Story worktree; on a Windows EBUSY-class lock the entry is deferred into `.worktrees/.pending-cleanup.json`. |
89
+ | Story land (close's wait, or `--wait`) | The post-land tail's worktree-reap step (`WorktreeManager.reap`) | The per-Story worktree; on a Windows EBUSY-class lock the entry is deferred into `.worktrees/.pending-cleanup.json`. |
90
90
  | Drain pending-cleanup (operator) | `drain-pending-cleanup.js` (run directly — see below) | The pending-cleanup ledger, with optional Windows handle-holder escalation. This is the only path that drains the ledger. |
91
91
 
92
92
  Operator takeaway: if worktrees or stale locks accumulate, run
@@ -95,8 +95,8 @@ Operator takeaway: if worktrees or stale locks accumulate, run
95
95
 
96
96
  ## Draining the pending-cleanup ledger
97
97
 
98
- `.worktrees/.pending-cleanup.json` accumulates entries when
99
- `single-story-close.js` cannot remove a worktree on Windows because of
98
+ `.worktrees/.pending-cleanup.json` accumulates entries when the
99
+ post-land tail cannot remove a worktree on Windows because of
100
100
  an EBUSY-class lock. If the holder is a long-lived user-mode process (a
101
101
  stranded test runner, a lingering biome/tsc, a node REPL), the lock
102
102
  never clears and the entry pins.
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,37 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.72.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.71.0...mandrel-v2.72.0) (2026-10-01)
19
+
20
+
21
+ ### Added
22
+
23
+ * close keeps the worktree until land, self-syncs a DIRTY PR, re-arms a disarmed PR, and recover names both ([#5533](https://github.com/dsj1984/mandrel/issues/5533)) ([#5537](https://github.com/dsj1984/mandrel/issues/5537)) ([5e0fd9c](https://github.com/dsj1984/mandrel/commit/5e0fd9c8e2bcc7984188db291f20d3171c234c69))
24
+
25
+
26
+ ### Fixed
27
+
28
+ * pr-watch ignores a required check from a concurrency-cancelled run while a live run on the same head exists ([#5534](https://github.com/dsj1984/mandrel/issues/5534)) ([#5535](https://github.com/dsj1984/mandrel/issues/5535)) ([caa2d6a](https://github.com/dsj1984/mandrel/commit/caa2d6ab935dd70d2ba40b3b8e952e4587a1ef1e))
29
+
30
+ ## [2.71.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.70.0...mandrel-v2.71.0) (2026-09-30)
31
+
32
+
33
+ ### Added
34
+
35
+ * close resolves baseline-only merge conflicts, hands other conflicts back to the delivering agent, and retries a failed done-label write instead of blocking for a human ([#5520](https://github.com/dsj1984/mandrel/issues/5520)) ([#5527](https://github.com/dsj1984/mandrel/issues/5527)) ([2e56566](https://github.com/dsj1984/mandrel/commit/2e565668bf0f02fc0c84b71779a50bec72ff84f4))
36
+ * deliver: the worker's tail is one story-handoff command that hands fixable failures back instead of blocking, the worker never writes agent::closing, and self-eval starts from a verdict skeleton ([#5518](https://github.com/dsj1984/mandrel/issues/5518)) ([#5524](https://github.com/dsj1984/mandrel/issues/5524)) ([74d2ef2](https://github.com/dsj1984/mandrel/commit/74d2ef2411efcb6a5a116401af5a52448cbd78fe))
37
+ * notify on agent::blocked, refuse agent::review-spec Stories at delivery, drop the native reviewer's duplicate lint pass, and correct the drift the SDLC review found ([#5517](https://github.com/dsj1984/mandrel/issues/5517)) ([#5523](https://github.com/dsj1984/mandrel/issues/5523)) ([7330307](https://github.com/dsj1984/mandrel/commit/7330307013a1678287dd0192a3f9042abca92432))
38
+ * plan: author Stories as a grounded handoff — decided Spec, References, a probed Context section and verifiable Slicing checkpoints, in a prompt no longer than today's ([#5516](https://github.com/dsj1984/mandrel/issues/5516)) ([#5522](https://github.com/dsj1984/mandrel/issues/5522)) ([f7b8388](https://github.com/dsj1984/mandrel/commit/f7b8388524737cf230eaa6a3bf19860b45d10ce5))
39
+ * role agents declare a model default, delivery.routing.agentModels overrides it per role, and close records the dispatched worker's model ([#5519](https://github.com/dsj1984/mandrel/issues/5519)) ([#5526](https://github.com/dsj1984/mandrel/issues/5526)) ([39a93d8](https://github.com/dsj1984/mandrel/commit/39a93d86942c2814cdea5b0074e7f352e3db832e))
40
+ * story-handoff preflight runs the standalone ratchets CI's baselines job runs, so a dead-export or cycle is fix-required at handoff instead of a CI red ([#5528](https://github.com/dsj1984/mandrel/issues/5528)) ([#5530](https://github.com/dsj1984/mandrel/issues/5530)) ([23c44d0](https://github.com/dsj1984/mandrel/commit/23c44d062b9a771373bf82b32ea7a70839af6446))
41
+
42
+
43
+ ### Fixed
44
+
45
+ * **agents:** stop story-worker flipping agent::closing at hand-off (refs [#5515](https://github.com/dsj1984/mandrel/issues/5515)) ([#5521](https://github.com/dsj1984/mandrel/issues/5521)) ([1f5b564](https://github.com/dsj1984/mandrel/commit/1f5b5649747b9dad826205f9819bc12738bbe55e))
46
+ * **deps:** clear brace-expansion, fast-uri, and markdown-it advisories ([#5508](https://github.com/dsj1984/mandrel/issues/5508)) ([fd97225](https://github.com/dsj1984/mandrel/commit/fd972259f111390d9ca1515d1a5cde45995c1709)), closes [#5507](https://github.com/dsj1984/mandrel/issues/5507)
47
+ * story-handoff: a non-fast-forward push rejection is fix-required, not blocked ([#5525](https://github.com/dsj1984/mandrel/issues/5525)) ([#5529](https://github.com/dsj1984/mandrel/issues/5529)) ([332389c](https://github.com/dsj1984/mandrel/commit/332389c03fcaf9497b134d4574ae7a1a712d62b6))
48
+
18
49
  ## [2.70.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.69.0...mandrel-v2.70.0) (2026-09-29)
19
50
 
20
51
 
@@ -868,6 +868,10 @@ const TEST_CREDIT_DEPOSIT_COMMAND =
868
868
  const COVERAGE_CAPTURE_COMMAND =
869
869
  'node .agents/scripts/coverage-capture.js --cwd <workCwd>';
870
870
 
871
+ /** The worker's one tail command; it runs whichever depositor applies. */
872
+ const STORY_HANDOFF_COMMAND =
873
+ 'node .agents/scripts/story-handoff.js --story <storyId> --cwd <workCwd>';
874
+
871
875
  const TEST_CREDIT_REMEDY = `run the suite through the depositor instead of bare \`npm test\`: ${TEST_CREDIT_DEPOSIT_COMMAND}`;
872
876
 
873
877
  const PRE_PUSH_REMEDY =
@@ -1010,6 +1014,9 @@ function describePrePushHook(projectRoot, readFileImpl) {
1010
1014
  function runTestCreditPath({ projectRoot, readFile = fs.readFileSync } = {}) {
1011
1015
  const root = projectRoot ?? process.cwd();
1012
1016
  const parts = [
1017
+ {
1018
+ detail: `the worker's \`${STORY_HANDOFF_COMMAND}\` runs the credited run close reads`,
1019
+ },
1013
1020
  describeCreditedRun({
1014
1021
  scripts: readProjectScripts(root, readFile),
1015
1022
  crapEnabled: isCrapEnabled(root, readFile),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.70.0",
3
+ "version": "2.72.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",
@@ -85,7 +85,7 @@
85
85
  "author": "",
86
86
  "license": "MIT",
87
87
  "bin": {
88
- "mandrel": "./bin/mandrel.js"
88
+ "mandrel": "bin/mandrel.js"
89
89
  },
90
90
  "type": "module",
91
91
  "bugs": {
@@ -141,11 +141,12 @@
141
141
  "peerDependencies.@cucumber/gherkin": "OPTIONAL peer, mirroring the `typescript` precedent, and deliberately NOT a runtime dependency. `check-gherkin-corpus.js` is the only consumer and it is opt-in behind `qa.gherkinLint`, so a consumer with no BDD tier must gain nothing from an upgrade. The devDependency alongside it is what lets this repository's own suite drive the real parser. The gate resolves it through a require path anchored at the consumer project — `.agents/` reaches a consumer by plain file copy, so a bare specifier would resolve against the consumer's module chain, which under a non-hoisting linker need not hold it.",
142
142
  "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.3.2 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended. The floor has since been raised twice for advisories against the pinned range itself (most recently to ^4.3.2 for GHSA-2883-xcg3-v3hh, whose fix is 4.3.2) — raising it is safe and does NOT touch the coupling above; check-pinned-override-notes.js now fails the build if this sentence and the pin disagree.",
143
143
  "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions.",
144
+ "overrides.markdown-it": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT markdown-it 14.1.1, which carries GHSA-253c-mchw-3w2r (moderate — quadratic linkify paths block the event loop). The advisory’s vulnerable range is everything < 14.3.1, so this tree-wide ^14.3.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.23.3, a breaking bump coupled to the js-yaml major above; do not take it. `npm run lint` is what must be re-run if this pin moves.",
144
145
  "overrides.smol-toml": "Load-bearing: markdownlint-cli2 0.22.1 declares an EXACT smol-toml 1.6.1, which carries GHSA-7w5x-hrqm-74c2 (high — denial of service via malformed TOML). The advisory’s vulnerable range is everything <= 1.7.0, so no lockfile-only resolution reaches a patched version and this tree-wide ^1.7.1 pin is what clears it. npm’s own `audit fix --force` instead proposes markdownlint-cli2 0.21.0 — a DOWNGRADE presented as a breaking change; do not take it. An npm override wins over a transitive package’s own exact pin, so markdownlint-cli2 runs against a minor it never declared: `npm run lint` was confirmed green under the forced version and is what must be re-run if this pin moves. knip declares ^1.6.1 and is satisfied natively. smol-toml is NOT a direct dependency, so unlike overrides.js-yaml there is no lockstep duplicate range to keep in sync."
145
146
  },
146
147
  "overrides": {
147
148
  "js-yaml": "^4.3.2",
148
- "markdown-it": "^14.2.0",
149
+ "markdown-it": "^14.3.1",
149
150
  "smol-toml": "^1.7.1"
150
151
  }
151
152
  }
@@ -1,272 +0,0 @@
1
- /**
2
- * review-providers/scoped-lint.js — scoped biome + markdownlint over the
3
- * changed surface. Runners resolve on disk before spawning (`npx --no biome`
4
- * exits 0 silently when biome is absent), and each surface is classified
5
- * independently so one failure cannot become the other's verdict.
6
- */
7
-
8
- import { spawnSync } from 'node:child_process';
9
- import { existsSync } from 'node:fs';
10
- import path from 'node:path';
11
-
12
- const CODE_EXTENSIONS = /\.(js|mjs|cjs|jsx|ts|tsx|json|jsonc)$/i;
13
-
14
- /**
15
- * npx's unresolvable-bin output: the legacy message or current npm's E404.
16
- * Matching the E404 code, not any `npm error` line, keeps genuine runner
17
- * errors out.
18
- */
19
- const NPX_UNRESOLVABLE =
20
- /could not determine executable to run|npm (?:error|ERR!)\s+code\s+E404/i;
21
-
22
- /** Biome's exit-1 when every path is config-excluded: an empty scope, not a failure. */
23
- const BIOME_EMPTY_SCOPE = /No files were processed in the specified paths/i;
24
-
25
- /**
26
- * Markdown runners in preference order, each with its own argument shape:
27
- * cli2 rejects `--ignore`, which cli v1 takes.
28
- */
29
- const MARKDOWN_RUNNERS = Object.freeze([
30
- Object.freeze({ bin: 'markdownlint-cli2', extraArgs: Object.freeze([]) }),
31
- Object.freeze({
32
- bin: 'markdownlint',
33
- extraArgs: Object.freeze(['--ignore', 'node_modules']),
34
- }),
35
- ]);
36
-
37
- const CODE_RUNNERS = Object.freeze([
38
- Object.freeze({ bin: 'biome', extraArgs: Object.freeze([]) }),
39
- ]);
40
-
41
- const DEGRADATION_REASONS = Object.freeze({
42
- RUNNER_NOT_INSTALLED: 'runner-not-installed',
43
- RUNNER_NOT_RESOLVABLE: 'runner-not-resolvable',
44
- UNPARSEABLE_OUTPUT: 'unparseable-output',
45
- });
46
-
47
- /**
48
- * Spawn one lint runner through `npx --no` (never install on the fly).
49
- *
50
- * @param {string} bin
51
- * @param {string[]} args
52
- * @param {string} cwd
53
- * @returns {{ status: number, stdout: string, stderr: string }}
54
- */
55
- function spawnLintRunner(bin, args, cwd) {
56
- const result = spawnSync('npx', ['--no', bin, ...args], {
57
- cwd,
58
- encoding: 'utf-8',
59
- shell: process.platform === 'win32',
60
- });
61
- return {
62
- status: result.status ?? 1,
63
- stdout: result.stdout ?? '',
64
- stderr: result.stderr ?? '',
65
- };
66
- }
67
-
68
- /**
69
- * First candidate installed under `<cwd>/node_modules/.bin`, else `null`.
70
- * Deliberately local-only: a global runner reads as absent and degrades
71
- * honestly rather than trusting an unresolved spawn.
72
- *
73
- * @param {ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>} candidates
74
- * @param {string} cwd
75
- * @param {(p: string) => boolean} existsFn Injected for testing.
76
- * @returns {{ bin: string, extraArgs: ReadonlyArray<string> }|null}
77
- */
78
- function resolveRunner(candidates, cwd, existsFn) {
79
- for (const candidate of candidates) {
80
- const base = path.join(cwd, 'node_modules', '.bin', candidate.bin);
81
- if (existsFn(base)) return candidate;
82
- if (
83
- process.platform === 'win32' &&
84
- (existsFn(`${base}.cmd`) || existsFn(`${base}.ps1`))
85
- ) {
86
- return candidate;
87
- }
88
- }
89
- return null;
90
- }
91
-
92
- /**
93
- * Zero counts with `executionFailed: true`, so it can never read as clean.
94
- *
95
- * @returns {ReturnType<typeof parseLintOutput>}
96
- */
97
- function unresolvedRunnerSummary() {
98
- return {
99
- errors: 0,
100
- warnings: 0,
101
- parsed: false,
102
- executionFailed: true,
103
- emptyScope: false,
104
- reason: DEGRADATION_REASONS.RUNNER_NOT_INSTALLED,
105
- };
106
- }
107
-
108
- /**
109
- * Resolve one surface's runner and, only if it resolved, spawn and classify it.
110
- *
111
- * @param {{
112
- * label: string,
113
- * candidates: ReadonlyArray<{ bin: string, extraArgs: ReadonlyArray<string> }>,
114
- * buildArgs: (runner: { bin: string, extraArgs: ReadonlyArray<string> }) => string[],
115
- * cwd: string,
116
- * runnerFn: typeof spawnLintRunner,
117
- * existsFn: (p: string) => boolean,
118
- * }} args
119
- * @returns {{ surface: string, summary: ReturnType<typeof parseLintOutput> }}
120
- */
121
- function runSurface({ label, candidates, buildArgs, cwd, runnerFn, existsFn }) {
122
- const runner = resolveRunner(candidates, cwd, existsFn);
123
- if (runner === null) {
124
- return { surface: label, summary: unresolvedRunnerSummary() };
125
- }
126
- return {
127
- surface: runner.bin,
128
- summary: parseLintOutput(runnerFn(runner.bin, buildArgs(runner), cwd)),
129
- };
130
- }
131
-
132
- /**
133
- * @param {string[]} changedFiles
134
- * @returns {{ code: string[], md: string[] }}
135
- */
136
- export function partitionFilesForLint(changedFiles) {
137
- const code = [];
138
- const md = [];
139
- for (const f of changedFiles) {
140
- if (CODE_EXTENSIONS.test(f)) code.push(f);
141
- else if (/\.md$/i.test(f)) md.push(f);
142
- }
143
- return { code, md };
144
- }
145
-
146
- /**
147
- * A non-zero exit matching no reporter format is `executionFailed`, except
148
- * biome's empty-scope exit.
149
- *
150
- * @param {{ status?: number, stdout?: string, stderr?: string }} result
151
- * @returns {{ errors: number, warnings: number, parsed: boolean, executionFailed: boolean, emptyScope: boolean, reason: string|null }}
152
- */
153
- export function parseLintOutput(result) {
154
- const combined = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
155
-
156
- let errors = 0;
157
- let warnings = 0;
158
- let parsed = false;
159
-
160
- for (const m of combined.matchAll(/Found\s+(\d+)\s+error/gi)) {
161
- errors += Number(m[1]);
162
- parsed = true;
163
- }
164
- for (const m of combined.matchAll(/Found\s+(\d+)\s+warning/gi)) {
165
- warnings += Number(m[1]);
166
- parsed = true;
167
- }
168
- const mdSummary = combined.match(/Summary:\s+(\d+)\s+error/i);
169
- if (mdSummary) {
170
- errors += Number(mdSummary[1]);
171
- parsed = true;
172
- }
173
-
174
- const failedExit = !parsed && (result.status ?? 0) !== 0;
175
- const emptyScope = failedExit && BIOME_EMPTY_SCOPE.test(combined);
176
- const executionFailed = failedExit && !emptyScope;
177
- const reason = executionFailed
178
- ? NPX_UNRESOLVABLE.test(combined)
179
- ? DEGRADATION_REASONS.RUNNER_NOT_RESOLVABLE
180
- : DEGRADATION_REASONS.UNPARSEABLE_OUTPUT
181
- : null;
182
-
183
- return { errors, warnings, parsed, executionFailed, emptyScope, reason };
184
- }
185
-
186
- /**
187
- * Counts add and `executionFailed` is the OR; `surfaces[]` keeps what the
188
- * lossy OR cannot answer.
189
- *
190
- * @param {Array<{ surface: string, summary: ReturnType<typeof parseLintOutput> }>} surfaces
191
- */
192
- function mergeSurfaceSummaries(surfaces) {
193
- const rows = surfaces.map(({ surface, summary }) => ({
194
- surface,
195
- parsed: summary.parsed,
196
- errors: summary.errors,
197
- warnings: summary.warnings,
198
- executionFailed: summary.executionFailed,
199
- reason: summary.reason ?? DEGRADATION_REASONS.UNPARSEABLE_OUTPUT,
200
- }));
201
- const total = (field) => rows.reduce((sum, row) => sum + row[field], 0);
202
-
203
- return {
204
- errors: total('errors'),
205
- warnings: total('warnings'),
206
- parsed: rows.some((row) => row.parsed),
207
- executionFailed: rows.some((row) => row.executionFailed),
208
- skipped: false,
209
- mode: 'changed-only',
210
- degradations: rows
211
- .filter((row) => row.executionFailed)
212
- .map(({ surface, reason }) => ({ surface, reason })),
213
- surfaces: rows.map(({ reason, ...row }) => row),
214
- };
215
- }
216
-
217
- /**
218
- * @param {string[]} changedFiles
219
- * @param {string} cwd
220
- * @param {typeof spawnLintRunner} [runnerFn]
221
- * @param {{ existsFn?: (p: string) => boolean }} [deps]
222
- * @returns {{ errors: number, warnings: number, parsed: boolean, skipped: boolean, mode: 'changed-only'|'off', executionFailed: boolean, degradations: Array<{ surface: string, reason: string }>, surfaces: Array<{ surface: string, parsed: boolean, errors: number, warnings: number, executionFailed: boolean }> }}
223
- */
224
- export function runScopedLint(
225
- changedFiles,
226
- cwd,
227
- runnerFn = spawnLintRunner,
228
- deps = {},
229
- ) {
230
- const { existsFn = existsSync } = deps;
231
- const { code, md } = partitionFilesForLint(changedFiles);
232
- if (code.length === 0 && md.length === 0) {
233
- return {
234
- errors: 0,
235
- warnings: 0,
236
- parsed: false,
237
- skipped: true,
238
- mode: 'changed-only',
239
- executionFailed: false,
240
- degradations: [],
241
- surfaces: [],
242
- };
243
- }
244
-
245
- const surfaces = [];
246
- if (code.length > 0) {
247
- surfaces.push(
248
- runSurface({
249
- label: 'biome',
250
- candidates: CODE_RUNNERS,
251
- buildArgs: (runner) => ['lint', ...code, ...runner.extraArgs],
252
- cwd,
253
- runnerFn,
254
- existsFn,
255
- }),
256
- );
257
- }
258
- if (md.length > 0) {
259
- surfaces.push(
260
- runSurface({
261
- label: 'markdownlint',
262
- candidates: MARKDOWN_RUNNERS,
263
- buildArgs: (runner) => [...md, ...runner.extraArgs],
264
- cwd,
265
- runnerFn,
266
- existsFn,
267
- }),
268
- );
269
- }
270
-
271
- return mergeSurfaceSummaries(surfaces);
272
- }