mandrel 2.90.0 → 2.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (169) hide show
  1. package/.agents/README.md +47 -7
  2. package/.agents/agents/story-worker.md +20 -0
  3. package/.agents/audit-checklists/lean.md +26 -0
  4. package/.agents/docs/agentrc-reference.json +5 -6
  5. package/.agents/docs/configuration.md +31 -30
  6. package/.agents/docs/workflows.md +7 -1
  7. package/.agents/instructions.md +3 -1
  8. package/.agents/runtime-deps.json +0 -2
  9. package/.agents/schemas/agentrc.schema.json +46 -45
  10. package/.agents/schemas/audit-rules.json +19 -0
  11. package/.agents/scripts/acceptance-eval.js +2 -6
  12. package/.agents/scripts/audit-exceptions.js +2 -4
  13. package/.agents/scripts/check-arch-cycles.js +1 -5
  14. package/.agents/scripts/check-context-budget.js +1 -5
  15. package/.agents/scripts/check-cyclomatic.js +1 -5
  16. package/.agents/scripts/check-dead-exports.js +23 -14
  17. package/.agents/scripts/check-doc-links.js +4 -4
  18. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  19. package/.agents/scripts/coverage-capture.js +14 -6
  20. package/.agents/scripts/diagnose-friction.js +8 -10
  21. package/.agents/scripts/generate-workflows-doc.js +5 -0
  22. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  24. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  25. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  26. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  27. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  28. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  29. package/.agents/scripts/lib/baselines/components.js +5 -5
  30. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  31. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  32. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  33. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  34. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  36. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  37. package/.agents/scripts/lib/baselines/writer.js +4 -4
  38. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  39. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  40. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  41. package/.agents/scripts/lib/child-exec.js +4 -4
  42. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  43. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  44. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  45. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  46. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  47. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  48. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  49. package/.agents/scripts/lib/config/commands.js +82 -7
  50. package/.agents/scripts/lib/config/explain.js +2 -1
  51. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  52. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  53. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  54. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  55. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  56. package/.agents/scripts/lib/config/git-roots.js +120 -0
  57. package/.agents/scripts/lib/config/quality.js +46 -50
  58. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  59. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  60. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  61. package/.agents/scripts/lib/config-resolver.js +5 -9
  62. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  63. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  64. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  65. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  66. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  67. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  68. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  69. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  70. package/.agents/scripts/lib/coverage-capture.js +31 -20
  71. package/.agents/scripts/lib/coverage-utils.js +34 -16
  72. package/.agents/scripts/lib/cpu-pool.js +2 -4
  73. package/.agents/scripts/lib/crap-engine.js +19 -1
  74. package/.agents/scripts/lib/crap-utils.js +2 -1
  75. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  76. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  77. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  78. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  79. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  80. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  81. package/.agents/scripts/lib/gh-env.js +72 -0
  82. package/.agents/scripts/lib/gh-exec.js +26 -1
  83. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  84. package/.agents/scripts/lib/npm-scripts.js +1 -1
  85. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  86. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  87. package/.agents/scripts/lib/orchestration/board-access-latch.js +19 -8
  88. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  89. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  90. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  91. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  92. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  93. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  94. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  95. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  96. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  97. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  98. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  99. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  100. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  101. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  102. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  103. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  104. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  105. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  106. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  107. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  108. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  109. package/.agents/scripts/lib/orchestration/story-handoff.js +13 -5
  110. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  111. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  112. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  113. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  114. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  115. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  116. package/.agents/scripts/lib/source-extensions.js +30 -15
  117. package/.agents/scripts/lib/test-run-credit.js +1 -9
  118. package/.agents/scripts/lib/test-temp.js +22 -21
  119. package/.agents/scripts/lib/util/ajv.js +111 -0
  120. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  121. package/.agents/scripts/lib/util/paths.js +51 -0
  122. package/.agents/scripts/lib/util/sleep.js +6 -0
  123. package/.agents/scripts/lib/util/slug.js +12 -0
  124. package/.agents/scripts/lib/validation-evidence.js +19 -40
  125. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  126. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  127. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  128. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  129. package/.agents/scripts/lint-issue-body.js +2 -2
  130. package/.agents/scripts/plan-context.js +2 -7
  131. package/.agents/scripts/providers/github/auth.js +3 -3
  132. package/.agents/scripts/providers/github/errors.js +3 -1
  133. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  134. package/.agents/scripts/providers/github/issues.js +6 -2
  135. package/.agents/scripts/providers/github/mappers.js +1 -5
  136. package/.agents/scripts/providers/github/projects-v2-graphql.js +11 -3
  137. package/.agents/scripts/providers/github/search-budget.js +3 -1
  138. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  139. package/.agents/scripts/sync-agentrc.js +5 -14
  140. package/.agents/scripts/sync-claude-agents.js +38 -150
  141. package/.agents/scripts/sync-claude-commands.js +35 -218
  142. package/.agents/scripts/update-coverage-baseline.js +1 -1
  143. package/.agents/scripts/update-crap-baseline.js +1 -1
  144. package/.agents/scripts/update-duplication-baseline.js +2 -16
  145. package/.agents/scripts/validate-skills.js +6 -10
  146. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  147. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  148. package/.agents/workflows/audit-exceptions.md +9 -0
  149. package/.agents/workflows/audit-lean.md +129 -0
  150. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  151. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  152. package/.agents/workflows/helpers/code-review.md +15 -1
  153. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  154. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  155. package/.agents/workflows/mandrel-plan.md +2 -2
  156. package/docs/CHANGELOG.md +35 -0
  157. package/lib/cli/doctor-checks/codex.js +6 -5
  158. package/lib/cli/doctor-checks/llm-review.js +102 -0
  159. package/lib/cli/doctor-checks/project-access.js +20 -10
  160. package/lib/cli/doctor-checks/sync-parity.js +65 -140
  161. package/lib/cli/doctor-checks/test-credit-path.js +69 -28
  162. package/lib/cli/doctor-checks/toolchain.js +5 -3
  163. package/lib/cli/registry.js +5 -0
  164. package/lib/migrations/helpers/retire-agentrc-key.js +3 -3
  165. package/lib/migrations/index.js +6 -0
  166. package/lib/migrations/steps/2.91.0-move-shared-crap-capture-script.js +84 -0
  167. package/lib/migrations/steps/2.91.0-retire-duplication-formats.js +23 -0
  168. package/lib/migrations/steps/2.91.0-unset-null-lint-command.js +54 -0
  169. package/package.json +1 -3
@@ -11,8 +11,6 @@
11
11
  import fs from 'node:fs';
12
12
  import path from 'node:path';
13
13
  import { fileURLToPath } from 'node:url';
14
- import Ajv from 'ajv';
15
- import addFormats from 'ajv-formats';
16
14
  import { parseStandardCliArgs } from './lib/cli/standard-args.js';
17
15
  import { runAsCli } from './lib/cli-utils.js';
18
16
  import { Logger } from './lib/Logger.js';
@@ -28,6 +26,7 @@ import {
28
26
  LOCAL_SKILLS_SEGMENTS,
29
27
  PAYLOAD_SKILLS_SEGMENTS,
30
28
  } from './lib/skills/walk-skill-files.js';
29
+ import { createAjv } from './lib/util/ajv.js';
31
30
 
32
31
  const MIN_CAPSULE_BULLETS = 5;
33
32
  const MAX_CAPSULE_BULLETS = 12;
@@ -92,22 +91,19 @@ function loadManifestSchema(repoRoot) {
92
91
  return JSON.parse(fs.readFileSync(fallback, 'utf8'));
93
92
  }
94
93
 
95
- function createAjv() {
96
- const AjvCtor = Ajv.default ?? Ajv;
97
- const ajv = new AjvCtor({ allErrors: true, strict: false });
98
- const addFormatsFn = addFormats.default ?? addFormats;
99
- addFormatsFn(ajv);
100
- return ajv;
94
+ /** One option bag for both skill-schema validators. */
95
+ function createSkillsAjv() {
96
+ return createAjv({ allErrors: true, strict: false });
101
97
  }
102
98
 
103
99
  function buildValidator(repoRoot) {
104
- const ajv = createAjv();
100
+ const ajv = createSkillsAjv();
105
101
  const schema = loadSkillSchema(repoRoot);
106
102
  return ajv.compile(schema);
107
103
  }
108
104
 
109
105
  function buildManifestValidator(repoRoot) {
110
- const ajv = createAjv();
106
+ const ajv = createSkillsAjv();
111
107
  const schema = loadManifestSchema(repoRoot);
112
108
  return ajv.compile(schema);
113
109
  }
@@ -23,28 +23,13 @@ description:
23
23
  ## Long-form reference — read on demand
24
24
 
25
25
  The capsule above is the contract and the whole always-read surface of this
26
- skill. The long-form material behind it — patterns, worked examples,
27
- checklists, and rationalizations — lives in the on-demand sibling
26
+ skill. The project-specific material behind it — the finding-severity table and
27
+ the post-green refactor pass — lives in the on-demand sibling
28
28
  [`reference.md`](reference.md), matching the split the always-on rules already
29
29
  use ([`rules/git-conventions.md`](../../../rules/git-conventions.md) ⇄
30
30
  [`git-conventions-reference.md`](../../../rules/git-conventions-reference.md)).
31
31
  Activating this skill costs the capsule; open a section below only when the
32
32
  task actually engages it.
33
33
 
34
- - [Overview](reference.md#overview)
35
- - [When to Use](reference.md#when-to-use)
36
- - [The Five-Axis Review](reference.md#the-five-axis-review)
37
- - [Change Sizing](reference.md#change-sizing)
38
- - [Change Descriptions](reference.md#change-descriptions)
39
- - [Review Process](reference.md#review-process)
40
- - [Multi-Model Review Pattern](reference.md#multi-model-review-pattern)
41
- - [Dead Code Hygiene](reference.md#dead-code-hygiene)
42
- - [Review Speed](reference.md#review-speed)
43
- - [Handling Disagreements](reference.md#handling-disagreements)
44
- - [Honesty in Review](reference.md#honesty-in-review)
45
- - [Dependency Discipline](reference.md#dependency-discipline)
46
- - [The Review Checklist](reference.md#the-review-checklist)
47
- - [Common Rationalizations](reference.md#common-rationalizations)
48
- - [Red Flags](reference.md#red-flags)
34
+ - [Finding-Severity Table](reference.md#finding-severity-table)
49
35
  - [Post-Green Refactor Pass](reference.md#post-green-refactor-pass)
50
- - [Verification](reference.md#verification)
@@ -20,23 +20,13 @@ description:
20
20
  ## Long-form reference — read on demand
21
21
 
22
22
  The capsule above is the contract and the whole always-read surface of this
23
- skill. The long-form material behind it — patterns, worked examples,
24
- checklists, and rationalizations — lives in the on-demand sibling
23
+ skill. The project-specific material behind it — the decisions-log layouts and
24
+ the prune/archive procedure — lives in the on-demand sibling
25
25
  [`reference.md`](reference.md), matching the split the always-on rules already
26
26
  use ([`rules/git-conventions.md`](../../../rules/git-conventions.md) ⇄
27
27
  [`git-conventions-reference.md`](../../../rules/git-conventions-reference.md)).
28
28
  Activating this skill costs the capsule; open a section below only when the
29
29
  task actually engages it.
30
30
 
31
- - [Overview](reference.md#overview)
32
- - [When to Use](reference.md#when-to-use)
33
- - [Architecture Decision Records (ADRs)](reference.md#architecture-decision-records-adrs)
34
- - [Inline Documentation](reference.md#inline-documentation)
35
- - [API Documentation](reference.md#api-documentation)
36
- - [README Structure](reference.md#readme-structure)
37
- - [Changelog Maintenance](reference.md#changelog-maintenance)
38
- - [Pruning & Archiving](reference.md#pruning-archiving)
39
- - [Documentation for Agents](reference.md#documentation-for-agents)
40
- - [Common Rationalizations](reference.md#common-rationalizations)
41
- - [Red Flags](reference.md#red-flags)
42
- - [Verification](reference.md#verification)
31
+ - [Decisions-log layouts](reference.md#decisions-log-layouts)
32
+ - [Pruning & Archiving](reference.md#pruning--archiving)
@@ -81,6 +81,7 @@ sole evidence base. Cite its fields by name:
81
81
  | `delegated[]` | `surface`, `lens`, `reason` |
82
82
  | `clusters[]` | `adapter`, `category`, `rule`, `count`, `byVerdict`, `files` |
83
83
  | `records[]` | `file`, `line`, `surface`, `target`, `rule`, `justification`, `ticketRefs`, `expires`, `addedAt`, `introduced`, `verdict`, `verdictBasis`, `probeBasis`, `permanentHint` |
84
+ | Shortcut markers | `adapter: shortcut-markers`, `surface: shortcut-marker`, `target` (the ceiling), `rule` (`has-trigger` / `no-trigger`), `justification` (the trigger) |
84
85
 
85
86
  `verdict` is the engine's mechanical call, first match wins: `dead` (a probe
86
87
  proved it exempts nothing), `expired` (its stated date is past), `orphaned`
@@ -150,6 +151,14 @@ judgment is the fifth, plus severity and routing.
150
151
  justification that states a lasting reason is legitimately forever. Count
151
152
  it in the inventory; never file it.
152
153
 
154
+ **Shortcut markers are the deferral ledger.** Each `shortcut: <ceiling>,
155
+ <trigger>` comment
156
+ ([convention](helpers/code-quality-guardrails.md#deliberate-shortcuts)) is one
157
+ record, and its verdict is the action: `live` (basis `trigger-named`) is a
158
+ decision, so leave it; `expired` or `orphaned` means the trigger fired, so fix
159
+ the shortcut now; `unjustified` means no trigger, so add one or fix it. This
160
+ report is the ledger `/audit-to-stories` consumes.
161
+
153
162
  **`unknown` is not `dead`.** An undecided probe is never evidence of
154
163
  obsolescence. List `unknown` records under Undecided (below) and file one
155
164
  only when you can show the answer from the code yourself.
@@ -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.
@@ -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,41 @@ 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.91.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.90.0...mandrel-v2.91.0) (2026-10-18)
19
+
20
+
21
+ ### Added
22
+
23
+ * **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))
24
+ * 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))
25
+ * 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))
26
+ * 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))
27
+ * 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))
28
+ * 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))
29
+ * 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))
30
+ * 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))
31
+ * 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))
32
+
33
+
34
+ ### Fixed
35
+
36
+ * 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))
37
+ * 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))
38
+ * 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))
39
+ * 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))
40
+ * 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))
41
+ * 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))
42
+ * 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))
43
+ * **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))
44
+
45
+
46
+ ### Changed
47
+
48
+ * 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))
49
+ * 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))
50
+ * 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))
51
+ * 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))
52
+
18
53
  ## [2.90.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.89.0...mandrel-v2.90.0) (2026-10-16)
19
54
 
20
55
 
@@ -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';