mandrel 2.90.0 → 2.92.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (175) hide show
  1. package/.agents/README.md +47 -7
  2. package/.agents/agents/story-worker.md +20 -0
  3. package/.agents/audit-checklists/lean.md +26 -0
  4. package/.agents/docs/agentrc-reference.json +5 -6
  5. package/.agents/docs/configuration.md +31 -30
  6. package/.agents/docs/workflows.md +7 -1
  7. package/.agents/instructions.md +3 -1
  8. package/.agents/runtime-deps.json +0 -2
  9. package/.agents/schemas/agentrc.schema.json +46 -45
  10. package/.agents/schemas/audit-rules.json +19 -0
  11. package/.agents/scripts/acceptance-eval.js +2 -6
  12. package/.agents/scripts/audit-exceptions.js +2 -4
  13. package/.agents/scripts/check-arch-cycles.js +1 -5
  14. package/.agents/scripts/check-context-budget.js +1 -5
  15. package/.agents/scripts/check-cyclomatic.js +1 -5
  16. package/.agents/scripts/check-dead-exports.js +23 -14
  17. package/.agents/scripts/check-doc-links.js +4 -4
  18. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  19. package/.agents/scripts/coverage-capture.js +14 -6
  20. package/.agents/scripts/diagnose-friction.js +8 -10
  21. package/.agents/scripts/generate-workflows-doc.js +5 -0
  22. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  24. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  25. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  26. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  27. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  28. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  29. package/.agents/scripts/lib/baselines/components.js +5 -5
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  32. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  33. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  34. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  36. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  37. package/.agents/scripts/lib/baselines/writer.js +4 -4
  38. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  39. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  40. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  41. package/.agents/scripts/lib/child-exec.js +4 -4
  42. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  43. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  44. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  45. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  46. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  47. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  48. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  49. package/.agents/scripts/lib/config/commands.js +82 -7
  50. package/.agents/scripts/lib/config/explain.js +2 -1
  51. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  52. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  53. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  54. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  55. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  56. package/.agents/scripts/lib/config/git-roots.js +120 -0
  57. package/.agents/scripts/lib/config/quality.js +46 -50
  58. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  59. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  60. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  61. package/.agents/scripts/lib/config-resolver.js +5 -9
  62. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  63. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  64. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  65. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  67. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  68. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  69. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  70. package/.agents/scripts/lib/coverage-capture.js +31 -20
  71. package/.agents/scripts/lib/coverage-utils.js +34 -16
  72. package/.agents/scripts/lib/cpu-pool.js +2 -4
  73. package/.agents/scripts/lib/crap-engine.js +19 -1
  74. package/.agents/scripts/lib/crap-utils.js +2 -1
  75. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  76. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  77. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  78. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  79. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  80. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  81. package/.agents/scripts/lib/gh-env.js +72 -0
  82. package/.agents/scripts/lib/gh-exec.js +26 -1
  83. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  84. package/.agents/scripts/lib/npm-scripts.js +1 -1
  85. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  86. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  87. package/.agents/scripts/lib/orchestration/board-access-latch.js +19 -8
  88. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  89. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  90. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  91. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  92. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  93. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  94. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  95. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  96. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  97. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  98. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  99. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  100. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  101. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  102. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  103. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  104. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  105. package/.agents/scripts/lib/orchestration/single-story-close/phases/finish.js +4 -1
  106. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +49 -83
  107. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  108. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  109. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  110. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  111. package/.agents/scripts/lib/orchestration/story-handoff.js +13 -5
  112. package/.agents/scripts/lib/orchestration/story-init-result.js +11 -0
  113. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  114. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  115. package/.agents/scripts/lib/orchestration/ticketing/transition.js +47 -21
  116. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  117. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  118. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  119. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  120. package/.agents/scripts/lib/source-extensions.js +30 -15
  121. package/.agents/scripts/lib/test-run-credit.js +1 -9
  122. package/.agents/scripts/lib/test-temp.js +22 -21
  123. package/.agents/scripts/lib/util/ajv.js +111 -0
  124. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  125. package/.agents/scripts/lib/util/paths.js +51 -0
  126. package/.agents/scripts/lib/util/sleep.js +6 -0
  127. package/.agents/scripts/lib/util/slug.js +12 -0
  128. package/.agents/scripts/lib/validation-evidence.js +19 -40
  129. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  130. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  131. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  132. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  133. package/.agents/scripts/lint-issue-body.js +2 -2
  134. package/.agents/scripts/plan-context.js +2 -7
  135. package/.agents/scripts/providers/github/auth.js +3 -3
  136. package/.agents/scripts/providers/github/errors.js +3 -1
  137. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  138. package/.agents/scripts/providers/github/issues.js +6 -2
  139. package/.agents/scripts/providers/github/mappers.js +1 -5
  140. package/.agents/scripts/providers/github/projects-v2-graphql.js +11 -3
  141. package/.agents/scripts/providers/github/search-budget.js +3 -1
  142. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  143. package/.agents/scripts/single-story-init.js +18 -14
  144. package/.agents/scripts/sync-agentrc.js +5 -14
  145. package/.agents/scripts/sync-claude-agents.js +38 -150
  146. package/.agents/scripts/sync-claude-commands.js +35 -218
  147. package/.agents/scripts/update-coverage-baseline.js +1 -1
  148. package/.agents/scripts/update-crap-baseline.js +1 -1
  149. package/.agents/scripts/update-duplication-baseline.js +2 -16
  150. package/.agents/scripts/validate-skills.js +6 -10
  151. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  152. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  153. package/.agents/workflows/audit-exceptions.md +9 -0
  154. package/.agents/workflows/audit-lean.md +129 -0
  155. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  156. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  157. package/.agents/workflows/helpers/code-review.md +15 -1
  158. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  159. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  160. package/.agents/workflows/helpers/deliver-story-reference.md +19 -8
  161. package/.agents/workflows/mandrel-plan.md +2 -2
  162. package/docs/CHANGELOG.md +42 -0
  163. package/lib/cli/doctor-checks/codex.js +6 -5
  164. package/lib/cli/doctor-checks/llm-review.js +102 -0
  165. package/lib/cli/doctor-checks/project-access.js +20 -10
  166. package/lib/cli/doctor-checks/sync-parity.js +65 -140
  167. package/lib/cli/doctor-checks/test-credit-path.js +69 -28
  168. package/lib/cli/doctor-checks/toolchain.js +5 -3
  169. package/lib/cli/registry.js +5 -0
  170. package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
  171. package/lib/migrations/index.js +6 -0
  172. package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
  173. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
  174. package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
  175. package/package.json +1 -3
@@ -0,0 +1,129 @@
1
+ ---
2
+ description: Audit whether code should exist at all — reinvented helpers, stdlib and platform re-implementations, single-implementation abstractions, dependencies carried for a few lines, and semantic near-copies — every finding grounded in a grep before it is judged.
3
+ ---
4
+
5
+ # Lean Code Audit
6
+
7
+ You are the Senior Developer who deletes fifty lines and writes one. Every
8
+ other lens asks whether code is correct, safe, or well-shaped; this one asks
9
+ whether it should exist: is the job already done by a helper elsewhere in the
10
+ codebase, by the standard library, or by the platform — and is the
11
+ abstraction, wrapper, or package around it earning its weight? The question
12
+ is cross-file by nature, so the lens is cumulative. The shared lens machinery
13
+ lives in [`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the
14
+ report to `{{auditResultsDir}}/audit-lean-results.md`. Dimension values:
15
+ `Reuse | Stdlib & Platform | YAGNI | Dependency Weight | Near-Copy`.
16
+ Extra finding fields: **Replacement:** (the concrete smaller form — an
17
+ existing path and symbol, a named API, or the inlined body) and **Lean:**
18
+ (`-N lines`, plus `-M dependencies` when a package goes).
19
+
20
+ > **Measure before you judge.** A lean finding is a claim that something is
21
+ > redundant, and redundancy is a fact about the rest of the tree. Every
22
+ > finding cites the grep that proves it (Step 0); a finding without that
23
+ > evidence is dropped, never downgraded.
24
+
25
+ ## Boundaries
26
+
27
+ Three lenses border this one. Report a finding **here** only when the fix is
28
+ "use what already exists" or "delete the layer"; defer the rest so the suite
29
+ never double-reports:
30
+
31
+ - `audit-clean-code` keeps dead code, complexity hotspots, the
32
+ maintainability index, and jscpd clone clusters. Its KISS and DRY bullets
33
+ are judged per file; this lens owns the cross-file question of whether the
34
+ code is already in the codebase or the platform.
35
+ - `audit-dependencies` keeps unused, outdated, and major-version-stale
36
+ packages. This lens reports a package only when it is used, but for so
37
+ little that a few lines or a platform API would replace it.
38
+ - `audit-exceptions` keeps `shortcut:` markers. A shortcut that names its
39
+ ceiling is a recorded decision, not a lean finding — unless the expected
40
+ load already crosses that ceiling, in which case cite the marker and report
41
+ the crossing.
42
+
43
+ ## Scope
44
+
45
+ Per the core's Scope interpretation:
46
+
47
+ ```text
48
+ {{changedFiles}}
49
+ ```
50
+
51
+ When the fence resolves to a file list, analyse those files as the
52
+ candidates, but run every Step 0 grep against the **whole tree** — the
53
+ existing helper a changed file reinvents usually lives outside the change
54
+ set. When the fence renders literally, run codebase-wide.
55
+
56
+ ## Execution strategy
57
+
58
+ Run this lens as one `subagent_type: auditor` dispatch per the core's
59
+ Execution strategy.
60
+
61
+ ## Step 0: Grep-grounding (mandatory — measure before you judge)
62
+
63
+ Each dimension has a mechanical precondition. Run it, and quote its output in
64
+ the finding's Current State:
65
+
66
+ - **Reuse:** a `git grep -n` hit on the existing helper that already does the
67
+ job, cited by path and symbol.
68
+ - **Stdlib & Platform:** the named standard-library or platform API that
69
+ replaces the custom code (e.g. `structuredClone`, `Array.prototype.at`,
70
+ `node:util` `parseArgs`, `URLSearchParams`), with the runtime version the
71
+ project already targets.
72
+ - **YAGNI:** an interface, factory, wrapper, or option with exactly one
73
+ implementation or zero setters, shown by `git grep -c` on the symbol.
74
+ - **Dependency Weight:** the package's import-site count —
75
+ `git grep -l -- "from '<pkg>'"` plus the `require('<pkg>')` form — and the
76
+ replacement of at most a few lines that would retire it.
77
+ - **Near-Copy:** two paths that do the same job, both cited. jscpd clones
78
+ belong to `audit-clean-code`; this dimension is the semantic copies jscpd
79
+ misses — same intent, different tokens.
80
+
81
+ Before calling anything unused or single-use, grep the **whole tree**,
82
+ including tests, fixtures, config files, and string references (dynamic
83
+ imports, registries keyed by name, CLI tables). A symbol with zero static
84
+ call sites but one string reference is used.
85
+
86
+ ## Step 1: Judge each candidate
87
+
88
+ ### Reuse
89
+
90
+ - **Reinvented helpers:** a local function that duplicates a shared utility
91
+ the codebase already exports — a date formatter, a retry loop, a path
92
+ normaliser, an env reader.
93
+ - **Parallel registries:** a second lookup table or constant list for data a
94
+ canonical source already owns.
95
+
96
+ ### Stdlib & Platform
97
+
98
+ - **Hand-rolled built-ins:** deep clone, array chunking, argument
99
+ parsing, query-string building, UUID generation, or `fetch` wrappers the
100
+ runtime already provides.
101
+ - **Polyfills past their target:** shims for features the declared engine
102
+ range has shipped natively.
103
+
104
+ ### YAGNI
105
+
106
+ - **Single-implementation abstractions:** an interface or base class with one
107
+ subclass, a factory that builds one type, a strategy map with one key.
108
+ - **Pass-through wrappers:** a function whose body forwards its arguments
109
+ unchanged to another.
110
+ - **Dead options:** a parameter or config key that no caller ever sets to a
111
+ non-default value.
112
+
113
+ ### Dependency Weight
114
+
115
+ - **Packages carried for a few lines:** a dependency imported at one or two
116
+ sites for a function the platform or a short local helper covers.
117
+
118
+ ### Near-Copy
119
+
120
+ - **Semantic duplicates:** two modules that solve the same problem with
121
+ different code — two slug generators, two YAML front-matter readers — where
122
+ one should call the other.
123
+
124
+ ## Report additions
125
+
126
+ Every finding carries the core skeleton plus **Replacement:** and **Lean:**.
127
+ The Executive Summary ends with the summed line
128
+ `Lean: -N lines, -M dependencies possible.`, totalled over the kept
129
+ findings, so a reader sees the size of the prize before the detail.
@@ -25,6 +25,13 @@ own body (e.g. performance's non-mutating measurements, quality's permitted
25
25
  committed-baseline reads, data-model's opt-in read-only database carve-out)
26
26
  refines this shared constraint for that lens only.
27
27
 
28
+ **Deliberate shortcuts are decisions.** In every lens, a `shortcut:` comment
29
+ that names a ceiling and a trigger
30
+ ([convention](code-quality-guardrails.md#deliberate-shortcuts)) is a decision,
31
+ not a finding, unless the lens can show the ceiling is already crossed at the
32
+ expected load. A marker with no trigger, or one whose trigger has fired, is
33
+ `/audit-exceptions`' finding, not the reading lens's.
34
+
28
35
  ## Scope interpretation (Story / plan-run mode) {#scope-interpretation}
29
36
 
30
37
  Each lens carries its own `{{changedFiles}}` fence — the substitution anchor
@@ -90,6 +90,27 @@ escomplex keys CRAP rows on `<file>::<methodName>`, so a rename produces a
90
90
  phantom new method + a phantom deleted method. Use the refresh tag to
91
91
  suppress the noise.
92
92
 
93
+ ## Deliberate shortcuts
94
+
95
+ A shortcut with a known limit is marked in a one-line code comment, after
96
+ the language's comment opener:
97
+
98
+ ```text
99
+ shortcut: <ceiling>, <trigger>
100
+ ```
101
+
102
+ The **ceiling** is the limit the simpler form holds to (a size, a load, a case
103
+ it does not handle). The **trigger** is when to upgrade: an ISO date, an issue
104
+ ref written `until #N` or `when #N lands`, or a measurable condition in words.
105
+ Every judging surface reads the marker the same way:
106
+
107
+ - **Decision**: ceiling and trigger named, trigger not fired. Leave it.
108
+ - **Rot**: a ceiling with no trigger. Nothing will ever say when to fix it.
109
+ - **Fired**: the date has passed or the issue has closed. Fix it now.
110
+
111
+ [`/audit-exceptions`](../audit-exceptions.md) lists every marker with its
112
+ verdict.
113
+
93
114
  ## When a number changes
94
115
 
95
116
  Update two places **in the same commit**:
@@ -74,7 +74,14 @@ How each tier changes the review protocol:
74
74
  - **`standard`** — the default: all three pillars at today's depth.
75
75
  - **`deep`** — all three pillars at full depth, **plus** an explicit second
76
76
  adversarial pass over the diff hunting for integration regressions and
77
- security-relevant edges before findings are finalized.
77
+ security-relevant edges before findings are finalized. At `deep` the
78
+ code-review provider also hands the reviewer a `<callers>` block: for each
79
+ symbol the diff defines or removes (`function`, `class`, `export const`,
80
+ `export { … }`), the lines **outside** the changed files that reference it
81
+ at `headRef`, found by a word-boundary `git grep` (capped at 20 symbols,
82
+ 25 lines per symbol, 30,000 characters). The directive tells the reviewer
83
+ to check every caller in that block against the new signature or shape —
84
+ the one bug class a diff alone cannot show.
78
85
 
79
86
  The LLM-backed review providers (code-review, codex, security-review,
80
87
  ultrareview) render the resolved `depth` into the prompt/instructions they emit so the underlying
@@ -112,6 +119,13 @@ The pipeline will:
112
119
  close-validation gate, so the review does not re-run it).
113
120
  - Post a structured summary report to the `[TICKET_ID]` issue.
114
121
 
122
+ **What the review did not check is posted, not silent.** A diff longer than
123
+ 200,000 characters is truncated for the model bug review, and a `<callers>`
124
+ block can hit a cap; each records a degradation (the unreviewed character and
125
+ file counts, or the dropped symbols) beside the parsed findings. Those land
126
+ in the **Degraded gates** section of the posted `verification-results`
127
+ comment — that section is where every unreviewed slice appears.
128
+
115
129
  ### Story scope runs no lens pass
116
130
 
117
131
  Close runs **no** audit-lens pass of its own (Story #5416 retired it: it
@@ -120,7 +120,7 @@ it in the **background**.
120
120
  **first**, ahead of this run and the push: close's base-sync then no-ops,
121
121
  so neither stamp goes stale.
122
122
  3. **One depositor**, by the predicate close registers `coverage-capture` on
123
- (one shared function) — CRAP gate enabled **and** a `test:coverage` script:
123
+ (one shared function) — coverage or CRAP gate on **and** a `captureScript`:
124
124
  - **Capture-active** →
125
125
  `node <main-repo>/.agents/scripts/coverage-capture.js --cwd <workCwd>`,
126
126
  behind the host full-suite lock. Signal: `Wrote content-digest capture
@@ -401,8 +401,8 @@ Digest § 5 states the rule and both invocations; this is what surrounds them.
401
401
  `test` deposit buys nothing there: close logs `no credited capture stamp
402
402
  covers this change set` and pays the whole suite on the serialized tail. The
403
403
  worker's capture writes the content-digest stamp in the worktree, and
404
- close's capture then exits on its freshness probe without spawning
405
- `test:coverage`. The stamp holds two digests — the scorable sources and
404
+ close's capture then exits on its freshness probe without spawning the
405
+ coverage gate's `captureScript`. The stamp (beside its artifact) holds two digests — the scorable sources and
406
406
  every suite input (all tracked and dirty paths but `baselines/` and the
407
407
  coverage directory) — so any later commit or base-sync outside baseline
408
408
  JSON spends it, and close re-captures.
@@ -36,8 +36,15 @@ foreign claim is stale — a foreign assignee is treated as a _live_ claim:
36
36
  the current owner. Coordinate with that operator, or pass **`--steal`** to
37
37
  forcibly transfer the claim once you have confirmed the other run is dead.
38
38
 
39
- `--dry-run` skips the lease (no assignee mutation). The matching release
40
- runs in `single-story-close.js` (Step 3).
39
+ `--dry-run` skips the lease (no assignee mutation). The claim lives for the
40
+ Story's whole delivery: it is released only by close's post-land tail once
41
+ the merge is confirmed (Step 3), or by init's own rollback when provisioning
42
+ fails or the `agent::executing` flip does not land — that flip is not
43
+ best-effort, so init exits non-zero rather than leave a ready Story assigned.
44
+ A blocked or failed close **keeps** the claim. The flip's Projects v2 outcome
45
+ is reported as `boardSync` in the init envelope; a Status that did not move
46
+ logs one warning naming the fix (`gh auth refresh -h github.com -s project`
47
+ for a token without the `project` scope).
41
48
 
42
49
  ### Branch reuse
43
50
 
@@ -339,12 +346,16 @@ The `single-story-close.js` script, in order:
339
346
  `blocked` or `failed` close keeps its working copy. A missing worktree is
340
347
  recreated from `story-<id>` before close's first git operation — and the
341
348
  `--wait` resume's — never falling back to the main checkout.
342
- 7. **Releases the Story lease** — a no-op when the operator no longer holds
343
- the claim, so a late close never yanks a live claim. Best-effort: a
344
- release failure is logged, not fatal, and reported as
345
- `leaseReleased: <boolean>`. The fail-closed lease never expires on its
346
- own, so a claim stranded by a failed release is cleared only by `--steal`
347
- or by de-assigning the ticket.
349
+ 7. **Releases the Story lease only after the merge is confirmed** — the
350
+ post-land tail's step, a no-op when the operator no longer holds the
351
+ claim, so a late close never yanks a live claim. Every other ending keeps
352
+ it: a red gate, a review-critical halt, a base-sync conflict, a blocked
353
+ GraphQL preflight, `pending` and `blocked` all leave the Story assigned,
354
+ because its label still says it is owned; the next close re-affirms the
355
+ claim as `already-held`. Best-effort: a release failure is logged, not
356
+ fatal, and reported as `leaseReleased: <boolean>`. The fail-closed lease
357
+ never expires on its own, so a claim stranded by a failed release is
358
+ cleared only by `--steal` or by de-assigning the ticket.
348
359
 
349
360
  The merge wait recovers on its own when `main` moves under the queued PR. A
350
361
  `DIRTY` PR is merged with `origin/<base>` in the Story worktree in that same
@@ -121,8 +121,8 @@ than one Story** (a split always earns operator eyes, `--force-review` or
121
121
  not), or when the operator asked to review (`--force-review`).
122
122
  Under `--yes`, auto-proceed.
123
123
 
124
- **One-for-one (tickets mode, one source → one Story)** — ask with
125
- AskUserQuestion: **Rewrite #N in place (Recommended)** or **File a new Story
124
+ **One-for-one (tickets mode, one source → one Story)** — ask the operator
125
+ (the host's question idiom, § 1.A): **Rewrite #N in place (Recommended)** or **File a new Story
126
126
  and close #N** (`--no-rewrite-source`). Under `--yes`, rewrite
127
127
  ([ref](helpers/plan-reference.md)).
128
128
 
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,48 @@ 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.92.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.91.0...mandrel-v2.92.0) (2026-10-18)
19
+
20
+
21
+ ### Fixed
22
+
23
+ * keep the Story assignee until the merge lands, and report every board-Status sync that did not happen ([#5784](https://github.com/dsj1984/mandrel/issues/5784)) ([#5785](https://github.com/dsj1984/mandrel/issues/5785)) ([8ca2b61](https://github.com/dsj1984/mandrel/commit/8ca2b611adb70a4bb53ec3b35dcdfe42dc1528bc))
24
+
25
+ ## [2.91.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.90.0...mandrel-v2.91.0) (2026-10-18)
26
+
27
+
28
+ ### Added
29
+
30
+ * **audit:** add the /audit-lean lens for grep-grounded reuse findings (refs [#5763](https://github.com/dsj1984/mandrel/issues/5763)) ([#5769](https://github.com/dsj1984/mandrel/issues/5769)) ([c770356](https://github.com/dsj1984/mandrel/commit/c77035646a1a697dc329d71bbf7b9513192a1b10))
31
+ * codex host parity: a first-available LLM review in the default chain, a doctor check that names it, and a host-mapping rule covering HITL questions and loop cadence ([#5741](https://github.com/dsj1984/mandrel/issues/5741)) ([#5752](https://github.com/dsj1984/mandrel/issues/5752)) ([4da251b](https://github.com/dsj1984/mandrel/commit/4da251b65395a4a84e3394ff7d9a5f172a3b8cf8))
32
+ * gate verdicts measure the change: CRAP joins module-scope arrows, duplication regresses on absolute lines, an untranspilable TS file is reported unscorable ([#5755](https://github.com/dsj1984/mandrel/issues/5755)) ([#5759](https://github.com/dsj1984/mandrel/issues/5759)) ([68197b2](https://github.com/dsj1984/mandrel/commit/68197b28b6467e387823b5ca4f18177143f90203))
33
+ * give the story-worker a smallest-complete-change ladder: reuse, stdlib, installed dep, one line, then the minimum, with the shortcut: comment form ([#5762](https://github.com/dsj1984/mandrel/issues/5762)) ([#5770](https://github.com/dsj1984/mandrel/issues/5770)) ([01c7020](https://github.com/dsj1984/mandrel/commit/01c70200295ba9d3eae08c7ccaf1ac84299d8e17))
34
+ * join each Story's landed diff size into the agent cost report so lines-per-Story and tokens-per-changed-line can be read before and after a worker rule changes ([#5766](https://github.com/dsj1984/mandrel/issues/5766)) ([#5772](https://github.com/dsj1984/mandrel/issues/5772)) ([9463d76](https://github.com/dsj1984/mandrel/commit/9463d763c4a530473598a90f370a8ca1522e14e6))
35
+ * make the close reviewer caller-aware at depth deep and record what it did not check: a callers block built from git grep, and a degradation whenever the diff or that block is truncated ([#5764](https://github.com/dsj1984/mandrel/issues/5764)) ([#5773](https://github.com/dsj1984/mandrel/issues/5773)) ([33b0cc6](https://github.com/dsj1984/mandrel/commit/33b0cc62fa91d6afcef8464ff3e633f648f98e14))
36
+ * one project.commands contract: a single resolver and defaults table, the coverage gate owns its capture script, capture spawns via the detected package manager ([#5737](https://github.com/dsj1984/mandrel/issues/5737)) ([#5750](https://github.com/dsj1984/mandrel/issues/5750)) ([0b1b171](https://github.com/dsj1984/mandrel/commit/0b1b171d23460ca595276a4e000a8a2435375427))
37
+ * one scorable-extension list drives the refresh predicates, the MI projection, native review and the duplication scanner; retire duplication.formats ([#5738](https://github.com/dsj1984/mandrel/issues/5738)) ([#5753](https://github.com/dsj1984/mandrel/issues/5753)) ([839b6cf](https://github.com/dsj1984/mandrel/commit/839b6cf715f4e8c352d25bf77d7ac5b2bb6e0a28))
38
+ * read `shortcut: <ceiling>, <trigger>` comments everywhere the framework judges code: an audit-exceptions adapter whose verdicts are the ledger, the shared lens rule, the guardrails convention, and one sentence for the close reviewer ([#5765](https://github.com/dsj1984/mandrel/issues/5765)) ([#5774](https://github.com/dsj1984/mandrel/issues/5774)) ([0c74524](https://github.com/dsj1984/mandrel/commit/0c745249ebac8a27c61865dbd44f8e71865990cc))
39
+
40
+
41
+ ### Fixed
42
+
43
+ * anchor .agentrc resolution on the working tree's git toplevel and apply GH_CONFIG_DIR at the gh boundary, not as a side effect of resolveConfig ([#5740](https://github.com/dsj1984/mandrel/issues/5740)) ([#5749](https://github.com/dsj1984/mandrel/issues/5749)) ([436844b](https://github.com/dsj1984/mandrel/commit/436844bc221dabe48946d86edf0ec0e7dddaff89))
44
+ * close out the Epic [#5744](https://github.com/dsj1984/mandrel/issues/5744) residue: runGh through child-exec, one provider-to-CLI source, and two test-timing band-aids replaced by root fixes ([#5756](https://github.com/dsj1984/mandrel/issues/5756)) ([#5757](https://github.com/dsj1984/mandrel/issues/5757)) ([3ffdcfc](https://github.com/dsj1984/mandrel/commit/3ffdcfc9b6773cb851ae8cb4be7f184271b12567))
45
+ * dead-exports gate exits non-zero when knip fails or overflows, instead of passing with zero rows ([#5736](https://github.com/dsj1984/mandrel/issues/5736)) ([#5745](https://github.com/dsj1984/mandrel/issues/5745)) ([d021612](https://github.com/dsj1984/mandrel/commit/d021612bcbbc456aa291f952278fed9513308b20))
46
+ * fix callers-context bogus symbols from prose: the deep review's declara… ([#5781](https://github.com/dsj1984/mandrel/issues/5781)) ([#5782](https://github.com/dsj1984/mandrel/issues/5782)) ([4e3c8fe](https://github.com/dsj1984/mandrel/commit/4e3c8fe0a0f227c5b8e20f9dfb62755d6f18de65))
47
+ * projects v2 scope detection recognises gh-exec classified errors, not just the fetch-path message ([#5735](https://github.com/dsj1984/mandrel/issues/5735)) ([#5746](https://github.com/dsj1984/mandrel/issues/5746)) ([95fe821](https://github.com/dsj1984/mandrel/commit/95fe821bca8b8bc1e33463dbe752d4f4a9cdc43f))
48
+ * ratchet child-process call sites on maxBuffer, not imports, and migrate the raw capture sites that can exceed 1 MiB ([#5739](https://github.com/dsj1984/mandrel/issues/5739)) ([#5751](https://github.com/dsj1984/mandrel/issues/5751)) ([ab7360d](https://github.com/dsj1984/mandrel/commit/ab7360dcd146f08386046c0f02592e950b7882a4))
49
+ * replace eight hand-rolled tmp-write-then-rename copies with one shared writeFileAtomic, and seven recursive directory walkers with one pruning walkFiles ([#5776](https://github.com/dsj1984/mandrel/issues/5776)) ([#5780](https://github.com/dsj1984/mandrel/issues/5780)) ([e927ad2](https://github.com/dsj1984/mandrel/commit/e927ad26d1c86b722701f4a54715e498fb6f4bed))
50
+ * **skills:** repair dead reference.md anchors in two skill capsules (refs [#4667](https://github.com/dsj1984/mandrel/issues/4667)) ([#5761](https://github.com/dsj1984/mandrel/issues/5761)) ([4c1752d](https://github.com/dsj1984/mandrel/commit/4c1752d5374fa23ad2f0297728589b5c7c689526))
51
+
52
+
53
+ ### Changed
54
+
55
+ * bring the Claude command and agent projectors to the Codex projector shape: injectable modules behind thin CLIs, no env-var test seams ([#5742](https://github.com/dsj1984/mandrel/issues/5742)) ([#5748](https://github.com/dsj1984/mandrel/issues/5748)) ([5d13fbc](https://github.com/dsj1984/mandrel/commit/5d13fbcf0a7a27e0534b782d3fb77074bd71b212))
56
+ * drop the minimatch and ajv-formats runtime dependencies: standardise globs on picomatch and register the two JSON-schema formats Mandrel uses through one shared Ajv factory ([#5775](https://github.com/dsj1984/mandrel/issues/5775)) ([#5778](https://github.com/dsj1984/mandrel/issues/5778)) ([a00800a](https://github.com/dsj1984/mandrel/commit/a00800a848033858dbfb70fe5eaaf057e1b4c27e))
57
+ * retire seven small lean findings: parseArgs for four hand-rolled argv loops, ten main() forwarders, three slug copies, two isPlainObject copies, inline sleeps, two storyIdFromBranch forwarders and the issueToEpic alias ([#5777](https://github.com/dsj1984/mandrel/issues/5777)) ([#5779](https://github.com/dsj1984/mandrel/issues/5779)) ([7f9d7f2](https://github.com/dsj1984/mandrel/commit/7f9d7f2fea54d8541c6bb3c8f017b94046b8dc84))
58
+ * revert the callback-free scorable-extension regex once the CRAP statement-span join is on main ([#5758](https://github.com/dsj1984/mandrel/issues/5758)) ([#5760](https://github.com/dsj1984/mandrel/issues/5760)) ([8655f3f](https://github.com/dsj1984/mandrel/commit/8655f3f1a603cb745acc7a41f6fdd90e7f9779a4))
59
+
18
60
  ## [2.90.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.89.0...mandrel-v2.90.0) (2026-10-16)
19
61
 
20
62
 
@@ -18,10 +18,11 @@ import {
18
18
  listGeneratedCodexSkills,
19
19
  } from '../../../.agents/scripts/lib/codex/skills-projection.js';
20
20
 
21
- // check: codex-skills-in-sync / codex-agents-in-sync
21
+ // check: codex-skills-in-sync / codex-agents-in-sync (and the Claude twins)
22
22
 
23
23
  /**
24
- * Compare a generated tree against what its projector would write now.
24
+ * Compare a generated tree against what its projector would write now,
25
+ * byte-for-byte. Shared by both hosts' parity checks.
25
26
  * `readEntry(name)` returns the on-disk text or null.
26
27
  *
27
28
  * @param {{
@@ -34,7 +35,7 @@ import {
34
35
  * }} spec
35
36
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
36
37
  */
37
- function projectionParity({
38
+ export function projectionParity({
38
39
  expected,
39
40
  onDisk,
40
41
  readEntry,
@@ -69,7 +70,7 @@ function projectionParity({
69
70
  * @param {string} file
70
71
  * @returns {string | null}
71
72
  */
72
- function readTextOrNull(file) {
73
+ export function readTextOrNull(file) {
73
74
  try {
74
75
  return fs.readFileSync(file, 'utf8');
75
76
  } catch {
@@ -79,7 +80,7 @@ function readTextOrNull(file) {
79
80
 
80
81
  /**
81
82
  * Parity of `.agents/skills/workflows/` against the workflow set — the Codex
82
- * twin of `commands-in-sync`, byte-for-byte rather than by name.
83
+ * twin of `commands-in-sync`.
83
84
  *
84
85
  * @param {{ projectRoot?: string, cwd?: () => string }} [opts]
85
86
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -0,0 +1,102 @@
1
+ // lib/cli/doctor-checks/llm-review.js — Doctor check: llm-review-provider.
2
+
3
+ import fs from 'node:fs';
4
+ import path from 'node:path';
5
+ import { applyLocalOverlay } from '../../../.agents/scripts/lib/config/agentrc-overlay.js';
6
+ import { DEFAULT_REVIEW_PROVIDERS } from '../../../.agents/scripts/lib/config/review-chain-default.js';
7
+ import { REVIEW_PROVIDER_CLIS } from '../../../.agents/scripts/lib/config/review-provider-clis.js';
8
+ import { readJsonSafe } from './read-json.js';
9
+ import { spawn } from './spawn.js';
10
+
11
+ const NATIVE_ONLY_ADVISORY =
12
+ 'close runs native only — install claude or codex, or pin codeReview.providers';
13
+
14
+ /**
15
+ * `delivery.codeReview.providers` from `.agentrc.json` with
16
+ * `.agentrc.local.json` merged over it; unset or empty is the default chain.
17
+ *
18
+ * @param {string} projectRoot
19
+ * @param {{ readFileSync: Function }} fsImpl
20
+ * @returns {{ entries: ReadonlyArray<object>, pinned: boolean }}
21
+ */
22
+ function readReviewChain(projectRoot, fsImpl) {
23
+ const committed =
24
+ readJsonSafe(path.join(projectRoot, '.agentrc.json'), fsImpl) ?? {};
25
+ let effective = committed;
26
+ try {
27
+ effective = applyLocalOverlay({ fsImpl, projectRoot, committed }).effective;
28
+ } catch {
29
+ // An unparseable overlay is the config check's to report.
30
+ }
31
+ const providers = effective?.delivery?.codeReview?.providers;
32
+ return Array.isArray(providers) && providers.length > 0
33
+ ? { entries: providers, pinned: true }
34
+ : { entries: DEFAULT_REVIEW_PROVIDERS, pinned: false };
35
+ }
36
+
37
+ /**
38
+ * Which CLI will serve each LLM provider in the effective review chain.
39
+ * Fails only for a pinned non-optional provider whose CLI is missing — the
40
+ * same hard failure close would hit at construction.
41
+ *
42
+ * @param {{
43
+ * projectRoot?: string,
44
+ * cwd?: () => string,
45
+ * runner?: (cmd: string, args: string[], opts?: object) => { status: number|null },
46
+ * fsImpl?: { readFileSync: Function, existsSync: Function },
47
+ * platform?: string,
48
+ * }} [opts]
49
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
50
+ */
51
+ export function runLlmReviewProvider({
52
+ projectRoot,
53
+ cwd,
54
+ runner = spawn,
55
+ fsImpl = fs,
56
+ platform = process.platform,
57
+ } = {}) {
58
+ const root = projectRoot ?? (cwd ?? (() => process.cwd()))();
59
+ const { entries, pinned } = readReviewChain(root, fsImpl);
60
+ const seen = new Map();
61
+ const onPath = (cli) => {
62
+ if (!seen.has(cli)) {
63
+ const r = runner(cli, ['--version'], {
64
+ shell: platform === 'win32',
65
+ timeout: 5000,
66
+ });
67
+ seen.set(cli, r?.status === 0);
68
+ }
69
+ return seen.get(cli);
70
+ };
71
+
72
+ const served = [];
73
+ const missing = [];
74
+ for (const entry of entries) {
75
+ const clis = entry?.manualPrompt ? null : REVIEW_PROVIDER_CLIS[entry?.name];
76
+ if (!clis) continue;
77
+ const cli = clis.find(onPath);
78
+ if (cli) served.push(`${entry.name} via ${cli}`);
79
+ else if (entry.optional !== true) missing.push(entry.name);
80
+ }
81
+
82
+ if (missing.length > 0) {
83
+ return {
84
+ ok: false,
85
+ detail: `codeReview.providers pins ${missing.join(', ')} without optional: true, but its CLI is not on PATH — close would fail at review`,
86
+ remedy:
87
+ 'Install the missing CLI (`claude` or `codex`), mark the entry `optional: true`, or remove it from codeReview.providers.',
88
+ };
89
+ }
90
+ if (served.length === 0) {
91
+ return {
92
+ ok: true,
93
+ detail: pinned
94
+ ? 'the pinned codeReview.providers chain runs no LLM review on this host'
95
+ : NATIVE_ONLY_ADVISORY,
96
+ };
97
+ }
98
+ return {
99
+ ok: true,
100
+ detail: `${pinned ? 'pinned' : 'default'} chain reviews with ${served.join(', ')}`,
101
+ };
102
+ }
@@ -3,6 +3,8 @@
3
3
  import fs from 'node:fs';
4
4
  import path from 'node:path';
5
5
 
6
+ import { applyLocalOverlay } from '../../../.agents/scripts/lib/config/agentrc-overlay.js';
7
+ import { runGh } from '../../../.agents/scripts/lib/gh-exec.js';
6
8
  import { isInsufficientScopes } from '../../../.agents/scripts/providers/github/projects-v2-graphql.js';
7
9
  import { readJsonSafe } from './read-json.js';
8
10
  import { spawn } from './spawn.js';
@@ -14,19 +16,16 @@ const GH_AUTH_RE = /gh auth login|not logged in|Bad credentials|HTTP 401/i;
14
16
 
15
17
  /**
16
18
  * `github.projectNumber` / `github.owner` from `.agentrc.json`, with
17
- * `.agentrc.local.json` winning per key.
19
+ * `.agentrc.local.json` deep-merged over it (the resolver's one overlay).
18
20
  *
19
21
  * @param {string} projectRoot
20
22
  * @param {{ readFileSync: Function }} fsImpl
21
23
  * @returns {{ projectNumber: number|null, owner: string|null }}
22
24
  */
23
25
  function readBoardConfig(projectRoot, fsImpl) {
24
- const base = readJsonSafe(path.join(projectRoot, '.agentrc.json'), fsImpl);
25
- const local = readJsonSafe(
26
- path.join(projectRoot, '.agentrc.local.json'),
27
- fsImpl,
28
- );
29
- const github = { ...(base?.github ?? {}), ...(local?.github ?? {}) };
26
+ const committed =
27
+ readJsonSafe(path.join(projectRoot, '.agentrc.json'), fsImpl) ?? {};
28
+ const github = effectiveConfig(fsImpl, projectRoot, committed).github ?? {};
30
29
  const n = Number(github.projectNumber);
31
30
  return {
32
31
  projectNumber: Number.isInteger(n) && n > 0 ? n : null,
@@ -35,6 +34,15 @@ function readBoardConfig(projectRoot, fsImpl) {
35
34
  };
36
35
  }
37
36
 
37
+ /** The overlay merged over `committed`; an unparseable overlay is ignored here (the config check reports it). */
38
+ function effectiveConfig(fsImpl, projectRoot, committed) {
39
+ try {
40
+ return applyLocalOverlay({ fsImpl, projectRoot, committed }).effective;
41
+ } catch {
42
+ return committed;
43
+ }
44
+ }
45
+
38
46
  /** One rung's query: `organization` / `user` by login, else `viewer`. */
39
47
  function rungArgs(root, owner, projectNumber) {
40
48
  const query = owner
@@ -52,9 +60,11 @@ function rungArgs(root, owner, projectNumber) {
52
60
  * @returns {'found'|'miss'|'scope'|'defer'}
53
61
  */
54
62
  function probeRung(runner, root, owner, projectNumber) {
55
- const r = runner('gh', rungArgs(root, owner, projectNumber), {
56
- timeout: 20_000,
57
- });
63
+ const r = runGh(
64
+ rungArgs(root, owner, projectNumber),
65
+ { timeout: 20_000 },
66
+ runner,
67
+ );
58
68
  if (r.error) return 'defer';
59
69
  const output = `${r.stdout ?? ''}\n${r.stderr ?? ''}`;
60
70
  if (isInsufficientScopes({ message: output })) return 'scope';