mandrel 2.89.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 (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 +38 -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/board-backfill.js +253 -0
  14. package/.agents/scripts/check-arch-cycles.js +1 -5
  15. package/.agents/scripts/check-context-budget.js +1 -5
  16. package/.agents/scripts/check-cyclomatic.js +1 -5
  17. package/.agents/scripts/check-dead-exports.js +23 -14
  18. package/.agents/scripts/check-doc-links.js +4 -4
  19. package/.agents/scripts/check-test-temp-hygiene.js +29 -33
  20. package/.agents/scripts/coverage-capture.js +14 -6
  21. package/.agents/scripts/diagnose-friction.js +8 -10
  22. package/.agents/scripts/generate-workflows-doc.js +5 -0
  23. package/.agents/scripts/lib/audit-exceptions/adapters/index.js +2 -0
  24. package/.agents/scripts/lib/audit-exceptions/adapters/inline-suppressions.js +36 -27
  25. package/.agents/scripts/lib/audit-exceptions/adapters/shortcut-markers.js +70 -0
  26. package/.agents/scripts/lib/audit-exceptions/adapters/source-scan.js +26 -0
  27. package/.agents/scripts/lib/audit-to-stories/audit-lenses.js +1 -0
  28. package/.agents/scripts/lib/baseline-schema-registry.js +3 -5
  29. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +11 -28
  30. package/.agents/scripts/lib/baselines/components.js +5 -5
  31. package/.agents/scripts/lib/baselines/crap-preview-scan.js +4 -1
  32. package/.agents/scripts/lib/baselines/crap-updater-cli.js +6 -4
  33. package/.agents/scripts/lib/baselines/duplication-scanner.js +4 -10
  34. package/.agents/scripts/lib/baselines/kinds/crap.js +4 -2
  35. package/.agents/scripts/lib/baselines/kinds/duplication.js +4 -2
  36. package/.agents/scripts/lib/baselines/kinds/kind-factory.js +13 -6
  37. package/.agents/scripts/lib/baselines/refresh-service.js +10 -13
  38. package/.agents/scripts/lib/baselines/writer.js +4 -4
  39. package/.agents/scripts/lib/bdd-scenario-scanner.js +26 -31
  40. package/.agents/scripts/lib/bootstrap/gh-list.js +4 -5
  41. package/.agents/scripts/lib/bootstrap/gh-preflight.js +13 -8
  42. package/.agents/scripts/lib/child-exec.js +4 -4
  43. package/.agents/scripts/lib/claude/agents-projection.js +170 -0
  44. package/.agents/scripts/lib/claude/commands-projection.js +184 -0
  45. package/.agents/scripts/lib/close-validation/commands.js +28 -117
  46. package/.agents/scripts/lib/close-validation/gates.js +54 -48
  47. package/.agents/scripts/lib/close-validation/process.js +5 -1
  48. package/.agents/scripts/lib/close-validation/projections/crap.js +2 -1
  49. package/.agents/scripts/lib/close-validation/projections/maintainability.js +50 -15
  50. package/.agents/scripts/lib/config/agentrc-overlay.js +4 -7
  51. package/.agents/scripts/lib/config/commands.js +82 -7
  52. package/.agents/scripts/lib/config/explain.js +2 -1
  53. package/.agents/scripts/lib/config/gates/coverage.schema.js +39 -3
  54. package/.agents/scripts/lib/config/gates/crap-incremental-coverage.schema.js +1 -1
  55. package/.agents/scripts/lib/config/gates/crap.schema.js +5 -3
  56. package/.agents/scripts/lib/config/gates/duplication.schema.js +6 -11
  57. package/.agents/scripts/lib/config/gates/shared.js +2 -2
  58. package/.agents/scripts/lib/config/git-roots.js +120 -0
  59. package/.agents/scripts/lib/config/quality.js +46 -50
  60. package/.agents/scripts/lib/config/review-chain-default.js +4 -3
  61. package/.agents/scripts/lib/config/review-provider-clis.js +11 -0
  62. package/.agents/scripts/lib/config/temp-paths.js +3 -37
  63. package/.agents/scripts/lib/config-resolver.js +5 -9
  64. package/.agents/scripts/lib/config-settings-schema-delivery.js +2 -2
  65. package/.agents/scripts/lib/config-settings-schema-quality.js +3 -2
  66. package/.agents/scripts/lib/config-settings-schema.js +6 -7
  67. package/.agents/scripts/lib/coverage-baseline.js +2 -1
  68. package/.agents/scripts/lib/coverage-capture-affected.js +4 -3
  69. package/.agents/scripts/lib/coverage-capture-fullscope.js +3 -1
  70. package/.agents/scripts/lib/coverage-capture-passes.js +119 -34
  71. package/.agents/scripts/lib/coverage-capture-usage.js +1 -1
  72. package/.agents/scripts/lib/coverage-capture.js +80 -43
  73. package/.agents/scripts/lib/coverage-utils.js +34 -16
  74. package/.agents/scripts/lib/cpu-pool.js +2 -4
  75. package/.agents/scripts/lib/crap-engine.js +19 -1
  76. package/.agents/scripts/lib/crap-utils.js +2 -1
  77. package/.agents/scripts/lib/dead-exports-knip.js +29 -11
  78. package/.agents/scripts/lib/detect-package-manager.js +13 -0
  79. package/.agents/scripts/lib/feedback-loop/graduator-gh.js +4 -2
  80. package/.agents/scripts/lib/full-suite-lock.js +25 -9
  81. package/.agents/scripts/lib/gates/baseline-store.js +2 -10
  82. package/.agents/scripts/lib/generated/agentrc-validator.js +4 -1
  83. package/.agents/scripts/lib/gh-env.js +72 -0
  84. package/.agents/scripts/lib/gh-exec.js +26 -1
  85. package/.agents/scripts/lib/maintainability-utils.js +8 -8
  86. package/.agents/scripts/lib/npm-scripts.js +1 -1
  87. package/.agents/scripts/lib/observability/signal-validator.js +2 -6
  88. package/.agents/scripts/lib/observability/source-classifier.js +1 -0
  89. package/.agents/scripts/lib/observability/terse-result.js +2 -6
  90. package/.agents/scripts/lib/orchestration/board-access-latch.js +112 -0
  91. package/.agents/scripts/lib/orchestration/ci-rerun-guard.js +10 -13
  92. package/.agents/scripts/lib/orchestration/column-sync.js +107 -52
  93. package/.agents/scripts/lib/orchestration/deliver-recover.js +2 -1
  94. package/.agents/scripts/lib/orchestration/git-cleanup/phases/git-probes.js +3 -3
  95. package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js +2 -6
  96. package/.agents/scripts/lib/orchestration/light-suitability.js +5 -7
  97. package/.agents/scripts/lib/orchestration/pr-watch.js +7 -7
  98. package/.agents/scripts/lib/orchestration/project-meta-cache.js +2 -11
  99. package/.agents/scripts/lib/orchestration/project-meta-resolver.js +44 -17
  100. package/.agents/scripts/lib/orchestration/review-deposit.js +2 -9
  101. package/.agents/scripts/lib/orchestration/review-providers/callers-context.js +219 -0
  102. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +53 -5
  103. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +2 -2
  104. package/.agents/scripts/lib/orchestration/review-providers/llm-review.js +96 -0
  105. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  106. package/.agents/scripts/lib/orchestration/review-providers/native.js +13 -19
  107. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +3 -2
  108. package/.agents/scripts/lib/orchestration/review-providers/review-provider-factory.js +2 -0
  109. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +11 -3
  110. package/.agents/scripts/lib/orchestration/story-close/baseline-upward-writeback.js +2 -3
  111. package/.agents/scripts/lib/orchestration/story-close/format-autofix.js +41 -15
  112. package/.agents/scripts/lib/orchestration/story-deliver-terminal-schema.js +2 -4
  113. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +2 -13
  114. package/.agents/scripts/lib/orchestration/story-handoff.js +27 -6
  115. package/.agents/scripts/lib/orchestration/story-progress.js +3 -11
  116. package/.agents/scripts/lib/orchestration/ticketing/bulk.js +3 -5
  117. package/.agents/scripts/lib/orchestration/verify-credit.js +52 -28
  118. package/.agents/scripts/lib/single-story-sweep/protection-ctx.js +11 -11
  119. package/.agents/scripts/lib/single-story-sweep/protection.js +1 -9
  120. package/.agents/scripts/lib/single-story-sweep/sweep-lock.js +1 -5
  121. package/.agents/scripts/lib/source-extensions.js +30 -15
  122. package/.agents/scripts/lib/test-run-credit.js +1 -9
  123. package/.agents/scripts/lib/test-temp.js +22 -21
  124. package/.agents/scripts/lib/util/ajv.js +111 -0
  125. package/.agents/scripts/lib/util/atomic-write.js +30 -0
  126. package/.agents/scripts/lib/util/paths.js +51 -0
  127. package/.agents/scripts/lib/util/sleep.js +6 -0
  128. package/.agents/scripts/lib/util/slug.js +12 -0
  129. package/.agents/scripts/lib/validation-evidence.js +19 -40
  130. package/.agents/scripts/lib/worktree/lifecycle/force-drain.js +2 -1
  131. package/.agents/scripts/lib/worktree/lifecycle/pending-cleanup.js +10 -28
  132. package/.agents/scripts/lib/worktree/lifecycle/reap.js +2 -2
  133. package/.agents/scripts/lib/worktree/node-modules-strategy.js +21 -14
  134. package/.agents/scripts/lint-issue-body.js +2 -2
  135. package/.agents/scripts/plan-context.js +2 -7
  136. package/.agents/scripts/providers/github/auth.js +3 -3
  137. package/.agents/scripts/providers/github/board-add.js +18 -9
  138. package/.agents/scripts/providers/github/errors.js +3 -1
  139. package/.agents/scripts/providers/github/gh-token-diagnostics.js +10 -7
  140. package/.agents/scripts/providers/github/issues.js +6 -2
  141. package/.agents/scripts/providers/github/mappers.js +1 -5
  142. package/.agents/scripts/providers/github/projects-v2-graphql.js +26 -6
  143. package/.agents/scripts/providers/github/search-budget.js +3 -1
  144. package/.agents/scripts/resolve-doc-tiers.js +7 -20
  145. package/.agents/scripts/sync-agentrc.js +5 -14
  146. package/.agents/scripts/sync-claude-agents.js +38 -150
  147. package/.agents/scripts/sync-claude-commands.js +35 -218
  148. package/.agents/scripts/update-coverage-baseline.js +1 -1
  149. package/.agents/scripts/update-crap-baseline.js +1 -1
  150. package/.agents/scripts/update-duplication-baseline.js +2 -16
  151. package/.agents/scripts/validate-skills.js +6 -10
  152. package/.agents/skills/core/code-review-and-quality/SKILL.md +3 -18
  153. package/.agents/skills/core/documentation-and-adrs/SKILL.md +4 -14
  154. package/.agents/workflows/audit-exceptions.md +9 -0
  155. package/.agents/workflows/audit-lean.md +129 -0
  156. package/.agents/workflows/helpers/audit-lens-core.md +7 -0
  157. package/.agents/workflows/helpers/code-quality-guardrails.md +21 -0
  158. package/.agents/workflows/helpers/code-review.md +15 -1
  159. package/.agents/workflows/helpers/deliver-digest.md +1 -1
  160. package/.agents/workflows/helpers/deliver-reference.md +2 -2
  161. package/.agents/workflows/mandrel-plan.md +2 -2
  162. package/docs/CHANGELOG.md +48 -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 +124 -0
  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 +11 -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
@@ -1,226 +1,43 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- /**
4
- * Project `.agents/workflows/` and `.agents/local/workflows/` into a flat
5
- * `.claude/commands/` tree (one `/<name>` per top-level workflow). The payload
6
- * wins a name collision; both sources feed the orphan-reap set, so local
7
- * commands survive re-syncs. Flat commands, not a plugin tree, because the
8
- * plugin system is unavailable in some Claude Code hosts. `helpers/` is not
9
- * projected; `loops/` is the one recursed subdirectory (`/loops:<name>`).
10
- */
11
-
12
- // cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.
13
- import fs from 'node:fs';
14
- import path from 'node:path';
15
-
16
- import { syncCodexSkills } from './lib/codex/skills-projection.js';
17
- import { applyHeader, isCommandExcluded } from './lib/command-header.js';
3
+ /** Project the workflow set for Claude, then Codex, from `process.cwd()`. */
4
+
5
+ import {
6
+ CLAUDE_COMMANDS_DIR,
7
+ syncClaudeCommands,
8
+ } from './lib/claude/commands-projection.js';
9
+ import { runAsCli } from './lib/cli-utils.js';
10
+ import {
11
+ CODEX_SKILLS_DIR,
12
+ syncCodexSkills,
13
+ } from './lib/codex/skills-projection.js';
18
14
  import { Logger } from './lib/Logger.js';
19
- import { dirExists } from './lib/util/paths.js';
20
-
21
- // The root is cwd, never `__dirname/../..`: installed under node_modules that
22
- // climb lands on the package dir and would write commands inside it.
23
- const PROJECT_ROOT = process.cwd();
24
-
25
- // Test overrides; SYNC_CLAUDE_COMMANDS_SRC replaces the payload source only.
26
- const PAYLOAD_SRC =
27
- process.env.SYNC_CLAUDE_COMMANDS_SRC ??
28
- path.join(PROJECT_ROOT, '.agents', 'workflows');
29
- const LOCAL_SRC = path.join(PROJECT_ROOT, '.agents', 'local', 'workflows');
30
-
31
- const DEST_DIR =
32
- process.env.SYNC_CLAUDE_COMMANDS_DEST ??
33
- path.join(PROJECT_ROOT, '.claude', 'commands');
34
-
35
- export const HEADER =
36
- '<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/workflows/ -->\n<!-- Re-run: npm run sync:commands -->\n\n';
37
-
38
- export const LOCAL_HEADER =
39
- '<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/workflows/ -->\n<!-- Re-run: npm run sync:commands -->\n\n';
40
-
41
- /**
42
- * Remove any on-disk plugin projection and marketplace listing, which would
43
- * shadow the flat commands. Idempotent; skipped for fixture runs.
44
- *
45
- * @returns {void}
46
- */
47
- function reapPluginTree() {
48
- if (process.env.SYNC_CLAUDE_COMMANDS_DEST) return;
49
- const pluginRoot = path.join(PROJECT_ROOT, '.claude', 'plugins', 'mandrel');
50
- const marketplace = path.join(
51
- PROJECT_ROOT,
52
- '.claude',
53
- '.claude-plugin',
54
- 'marketplace.json',
55
- );
56
- for (const target of [pluginRoot, marketplace]) {
57
- try {
58
- fs.rmSync(target, { recursive: true, force: true });
59
- } catch (err) {
60
- Logger.warn(` skip reap ${target}: ${err.message}`);
61
- }
62
- }
63
- try {
64
- fs.rmdirSync(path.join(PROJECT_ROOT, '.claude', '.claude-plugin'));
65
- } catch {
66
- /* not empty or absent — leave it */
67
- }
68
- }
69
-
70
- reapPluginTree();
71
- fs.mkdirSync(DEST_DIR, { recursive: true });
72
-
73
- // The only recursed subdirectory; helpers/ holds path-included modules.
74
- const LOOPS_NS = 'loops';
75
-
76
- const isTopLevelWorkflow = (entry) =>
77
- entry.isFile() && entry.name.endsWith('.md');
78
-
79
- /**
80
- * `loops/README.md` is documentation, not a command.
81
- *
82
- * @param {import('node:fs').Dirent} entry
83
- * @returns {boolean}
84
- */
85
- const isLoopUnit = (entry) =>
86
- isTopLevelWorkflow(entry) && entry.name.toLowerCase() !== 'readme.md';
87
-
88
- /**
89
- * Keyed by `loops/<name>.md` so a unit never collides with a flat command.
90
- *
91
- * @param {string} dir A workflows source root.
92
- * @returns {Array<{dir: string, name: string, rel: string}>}
93
- */
94
- function enumerateLoopUnits(dir) {
95
- const loopsDir = path.join(dir, LOOPS_NS);
96
- if (!dirExists(loopsDir)) return [];
97
- return fs
98
- .readdirSync(loopsDir, { withFileTypes: true })
99
- .filter(isLoopUnit)
100
- .map((e) => ({
101
- dir,
102
- name: e.name,
103
- rel: `${LOOPS_NS}/${e.name}`,
104
- }));
105
- }
106
-
107
- // Payload first, so it wins a collision.
108
- const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
109
-
110
- /**
111
- * Named, not inline: an anonymous callback in this spawned-only script has no
112
- * coverage coordinates for the CRAP seat to resolve.
113
- *
114
- * @param {string} dir A workflows source root.
115
- * @returns {Array<{dir: string, name: string, rel: string}>}
116
- */
117
- function workflowEntriesIn(dir) {
118
- return [
119
- ...fs
120
- .readdirSync(dir, { withFileTypes: true })
121
- .filter(isTopLevelWorkflow)
122
- .map(function toWorkflowEntry(e) {
123
- return { dir, name: e.name, rel: e.name };
124
- }),
125
- ...enumerateLoopUnits(dir),
126
- ];
127
- }
128
15
 
129
- /** @type {Array<{dir: string, name: string, rel: string}>} */
130
- const entries = SRC_DIRS.flatMap(workflowEntriesIn);
131
-
132
- // A `command: false` workflow never enters `sourceSet`, so a stale copy is reaped.
133
- const byRel = new Map();
134
- for (const e of entries) {
135
- if (byRel.has(e.rel)) {
136
- Logger.warn(` shadowed ${e.rel} (local copy ignored; payload wins)`);
137
- continue;
138
- }
139
- if (isCommandExcluded(fs.readFileSync(path.join(e.dir, e.rel), 'utf8'))) {
140
- Logger.info(` excluded ${e.rel} (frontmatter command: false)`);
141
- continue;
142
- }
143
- byRel.set(e.rel, e);
144
- }
145
-
146
- // Any existing command not in this set is reaped.
147
- const sourceSet = new Set(byRel.keys());
148
-
149
- /**
150
- * @returns {string[]}
151
- */
152
- function listExistingCommands() {
153
- const flat = fs
154
- .readdirSync(DEST_DIR)
155
- .filter((f) => f.endsWith('.md'))
156
- .map((f) => f);
157
- const loopsDest = path.join(DEST_DIR, LOOPS_NS);
158
- const loops = dirExists(loopsDest)
159
- ? fs
160
- .readdirSync(loopsDest)
161
- .filter((f) => f.endsWith('.md'))
162
- .map((f) => `${LOOPS_NS}/${f}`)
163
- : [];
164
- return [...flat, ...loops];
165
- }
166
-
167
- for (const rel of listExistingCommands()) {
168
- if (!sourceSet.has(rel)) {
169
- fs.unlinkSync(path.join(DEST_DIR, rel));
170
- Logger.info(` removed ${rel} (no longer in workflows)`);
171
- }
172
- }
173
-
174
- // The header goes after any frontmatter, so `---` stays on line 1.
175
- let synced = 0;
176
- const resolvedEntries = Array.from(byRel.values());
177
-
178
- /**
179
- * @param {{ dir: string, rel: string }} entry
180
- * @returns {Promise<void>}
181
- */
182
- async function syncEntry({ dir, rel }) {
183
- const isLocal = dir === LOCAL_SRC;
184
- const header = isLocal ? LOCAL_HEADER : HEADER;
185
- const content = await fs.promises.readFile(path.join(dir, rel), 'utf8');
186
- const dest = path.join(DEST_DIR, rel);
187
- const target = applyHeader(content, header);
188
-
189
- await fs.promises.mkdir(path.dirname(dest), { recursive: true });
190
-
191
- // Skip identical content to avoid noisy git diffs.
192
- try {
193
- const existingContent = await fs.promises.readFile(dest, 'utf8');
194
- if (existingContent === target) return;
195
- } catch (err) {
196
- if (err.code !== 'ENOENT') throw err;
197
- }
198
-
199
- await fs.promises.writeFile(dest, target, 'utf8');
200
- synced++;
201
- Logger.info(` synced ${rel}`);
202
- }
203
-
204
- await Promise.all(resolvedEntries.map(syncEntry));
205
-
206
- Logger.info(
207
- `\n✔ ${synced} file(s) synced, ${sourceSet.size} total commands in .claude/commands/`,
208
- );
209
-
210
- // The Codex half: the same source set as Codex skills. A fixture run (a
211
- // DEST override) skips it unless SYNC_CODEX_SKILLS_DEST names its own target.
212
- const codexSkillsDest =
213
- process.env.SYNC_CODEX_SKILLS_DEST ??
214
- (process.env.SYNC_CLAUDE_COMMANDS_DEST ? null : undefined);
215
- if (codexSkillsDest !== null) {
216
- const codex = syncCodexSkills({
217
- projectRoot: PROJECT_ROOT,
218
- payloadSrc: PAYLOAD_SRC,
219
- localSrc: LOCAL_SRC,
220
- destDir: codexSkillsDest,
221
- log: (line) => Logger.info(line),
16
+ /** @returns {Promise<void>} */
17
+ async function main() {
18
+ // cwd, never `__dirname/../..`, which lands inside node_modules.
19
+ const projectRoot = process.cwd();
20
+ const log = (line) => Logger.info(line);
21
+ const claude = syncClaudeCommands({
22
+ projectRoot,
23
+ log,
24
+ warn: (line) => Logger.warn(line),
222
25
  });
223
26
  Logger.info(
224
- `✔ ${codex.written.length} file(s) synced, ${codex.total} total Codex skills in .agents/skills/workflows/`,
27
+ `\n✔ ${claude.written.length} file(s) synced, ${claude.total} total commands in ${CLAUDE_COMMANDS_DIR}/`,
28
+ );
29
+ const codex = syncCodexSkills({ projectRoot, log });
30
+ Logger.info(
31
+ `✔ ${codex.written.length} file(s) synced, ${codex.total} total Codex skills in ${CODEX_SKILLS_DIR}/`,
225
32
  );
226
33
  }
34
+
35
+ runAsCli(import.meta.url, main, {
36
+ source: 'sync-claude-commands',
37
+ usage: {
38
+ invocation: 'node .agents/scripts/sync-claude-commands.js',
39
+ summary:
40
+ 'Regenerate the .claude/commands/ projection of .agents/workflows/ (and .agents/local/workflows/), then the Codex skills under .agents/skills/workflows/.',
41
+ flags: [],
42
+ },
43
+ });
@@ -35,7 +35,7 @@ const USAGE = {
35
35
  ],
36
36
  ],
37
37
  notes: [
38
- 'Run `npm run test:coverage` first — this script never runs the suite itself.',
38
+ "Run the coverage gate's `captureScript` first (`delivery.quality.gates.coverage.captureScript`) — this script never runs the suite itself.",
39
39
  'Against an `affected`-stamped artifact only measured rows are rewritten; rows the scoped run skipped are kept.',
40
40
  ],
41
41
  };
@@ -55,7 +55,7 @@ const USAGE = {
55
55
  ],
56
56
  ],
57
57
  notes: [
58
- 'Run the CRAP capture script first — `npm run <delivery.quality.gates.crap.captureScript>`, default `npm run test:coverage` — without a coverage artifact the refresh refuses (exit 1) and leaves the baseline untouched.',
58
+ "Run the CRAP capture script first — `<pm> run <delivery.quality.gates.crap.captureScript>`, default the coverage gate's `captureScript` — without a coverage artifact the refresh refuses (exit 1) and leaves the baseline untouched.",
59
59
  ],
60
60
  };
61
61
 
@@ -11,6 +11,7 @@ import path from 'node:path';
11
11
  import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
12
12
  import { JSCPD_MISSING } from './lib/baselines/duplication-scanner.js';
13
13
  import { refreshBaseline } from './lib/baselines/refresh-service.js';
14
+ import { parseGateArgv } from './lib/cli-args.js';
14
15
  import { runAsCli } from './lib/cli-utils.js';
15
16
  import { getBaselineEpsilon } from './lib/config/quality.js';
16
17
  import { getQuality, resolveConfig } from './lib/config-resolver.js';
@@ -42,21 +43,6 @@ const USAGE = {
42
43
  ],
43
44
  };
44
45
 
45
- /**
46
- * @param {string[]} argv
47
- * @returns {{ baselinePath: string | undefined }}
48
- */
49
- function parseCliArgs(argv = process.argv.slice(2)) {
50
- const out = { baselinePath: undefined };
51
- for (let i = 0; i < argv.length; i += 1) {
52
- if (argv[i] === '--baseline' && argv[i + 1]) {
53
- out.baselinePath = argv[i + 1];
54
- i += 1;
55
- }
56
- }
57
- return out;
58
- }
59
-
60
46
  /**
61
47
  * @param {string[]} argv
62
48
  * @returns {boolean}
@@ -100,7 +86,7 @@ function resolveScopeSelection(argv) {
100
86
  */
101
87
  function resolveAbsBaselinePath(argv, gate) {
102
88
  const baselinePath =
103
- parseCliArgs(argv).baselinePath ??
89
+ parseGateArgv(argv, { strings: ['baseline'] }).baseline ??
104
90
  gate.baselinePath ??
105
91
  'baselines/duplication.json';
106
92
  return path.isAbsolute(baselinePath)
@@ -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