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
@@ -21,7 +21,7 @@ function normalizeLabels(issue) {
21
21
  * @param {object} issue
22
22
  * @returns {object}
23
23
  */
24
- function baseIssueFields(issue) {
24
+ export function baseIssueFields(issue) {
25
25
  const labels = normalizeLabels(issue);
26
26
  return {
27
27
  id: issue.number,
@@ -45,10 +45,6 @@ export function issueToTicket(issue) {
45
45
  };
46
46
  }
47
47
 
48
- export function issueToEpic(issue) {
49
- return baseIssueFields(issue);
50
- }
51
-
52
48
  export function subIssueNodeToTicket(node) {
53
49
  // Absent nodes are legitimate (childless Story, empty page entry).
54
50
  if (node == null) return null;
@@ -31,9 +31,17 @@ const opt = (name, id) => ({
31
31
  description: '',
32
32
  });
33
33
 
34
- export const isInsufficientScopes = (err) =>
35
- Boolean(err) &&
36
- SCOPES_RE.test(err.message ?? err.toString?.() ?? String(err));
34
+ // gh-exec keeps the refusal text in stderr behind a generic message.
35
+ export const errorTextMatches = (err, re) => {
36
+ if (!err) return false;
37
+ const texts = [err.message, err.stderr, err.stdout].filter(
38
+ (text) => typeof text === 'string',
39
+ );
40
+ if (texts.length === 0) texts.push(err.toString?.() ?? String(err));
41
+ return texts.some((text) => re.test(text));
42
+ };
43
+
44
+ export const isInsufficientScopes = (err) => errorTextMatches(err, SCOPES_RE);
37
45
  export const isScopesMissingEnvelope = (value) =>
38
46
  Boolean(value) && typeof value === 'object' && value.scopesMissing === true;
39
47
 
@@ -4,6 +4,8 @@
4
4
  * it before every call so all callers share one budget.
5
5
  */
6
6
 
7
+ import { defaultSleep } from '../../lib/util/sleep.js';
8
+
7
9
  /** GitHub's authenticated Search cap; cooldown applies when no reset is readable. */
8
10
  const SEARCH_BUDGET_DEFAULTS = Object.freeze({
9
11
  capacity: 30,
@@ -30,7 +32,7 @@ export function createSearchBudget({
30
32
  windowMs = SEARCH_BUDGET_DEFAULTS.windowMs,
31
33
  cooldownMs = SEARCH_BUDGET_DEFAULTS.cooldownMs,
32
34
  now = () => Date.now(),
33
- sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
35
+ sleep = defaultSleep,
34
36
  } = {}) {
35
37
  const refillPerMs = capacity / windowMs;
36
38
  let tokens = capacity;
@@ -5,6 +5,7 @@
5
5
  */
6
6
 
7
7
  import process from 'node:process';
8
+ import { parseGateArgv } from './lib/cli-args.js';
8
9
  import { runAsCli } from './lib/cli-utils.js';
9
10
  import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
10
11
  import { resolveDocTiers } from './lib/doc-tiers.js';
@@ -14,21 +15,11 @@ import { resolveDocTiers } from './lib/doc-tiers.js';
14
15
  * @returns {{ rootPath: string | null, json: boolean }}
15
16
  */
16
17
  export function parseArgv(argv = []) {
17
- let rootPath = null;
18
- let json = false;
19
- for (let i = 0; i < argv.length; i += 1) {
20
- const a = argv[i];
21
- if (a === '--root') {
22
- const next = argv[i + 1];
23
- if (next && !next.startsWith('--')) {
24
- rootPath = next;
25
- i += 1;
26
- }
27
- } else if (a === '--json') {
28
- json = true;
29
- }
30
- }
31
- return { rootPath, json };
18
+ const { root, json } = parseGateArgv(argv, {
19
+ strings: ['root'],
20
+ booleans: ['json'],
21
+ });
22
+ return { rootPath: root, json };
32
23
  }
33
24
 
34
25
  /**
@@ -59,11 +50,7 @@ export async function runCli(
59
50
  return 0;
60
51
  }
61
52
 
62
- async function main() {
63
- return runCli();
64
- }
65
-
66
- runAsCli(import.meta.url, main, {
53
+ runAsCli(import.meta.url, runCli, {
67
54
  source: 'resolve-doc-tiers',
68
55
  propagateExitCode: true,
69
56
  errorPrefix: '[resolve-doc-tiers] ❌ Fatal error',
@@ -9,6 +9,7 @@
9
9
  */
10
10
 
11
11
  import { fileURLToPath } from 'node:url';
12
+ import { parseGateArgv } from './lib/cli-args.js';
12
13
  import { respondToHelp } from './lib/cli-usage.js';
13
14
  import { formatSyncReport, syncAgentrc } from './lib/config/sync-agentrc.js';
14
15
  import { Logger } from './lib/Logger.js';
@@ -26,21 +27,11 @@ const USAGE = {
26
27
  ],
27
28
  };
28
29
 
29
- function parseArgs(argv) {
30
- const out = { cwd: null, quiet: false };
31
- for (let i = 0; i < argv.length; i += 1) {
32
- const a = argv[i];
33
- if (a === '--cwd' && i + 1 < argv.length) {
34
- out.cwd = argv[++i];
35
- } else if (a === '--quiet') {
36
- out.quiet = true;
37
- }
38
- }
39
- return out;
40
- }
41
-
42
30
  export function main(argv = process.argv.slice(2)) {
43
- const { cwd, quiet } = parseArgs(argv);
31
+ const { cwd, quiet } = parseGateArgv(argv, {
32
+ strings: ['cwd'],
33
+ booleans: ['quiet'],
34
+ });
44
35
  const projectRoot = cwd || process.cwd();
45
36
  const result = syncAgentrc({ projectRoot });
46
37
  const report = quiet
@@ -1,159 +1,47 @@
1
1
  #!/usr/bin/env node
2
2
 
3
- /**
4
- * Project `.agents/agents/` and `.agents/local/agents/` into a flat
5
- * `.claude/agents/` tree — the sibling of `sync-claude-commands.js`, with the
6
- * same payload-wins shadowing and orphan-reap. A role agent runs on its own
7
- * system prompt (no entry-doc `@`-import closure), which is the point of routing to it.
8
- * A `delivery.routing.agentModels` entry overrides the role's `model:` default.
9
- */
10
-
11
- // cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.
12
- import fs from 'node:fs';
13
- import path from 'node:path';
14
-
15
- import { syncCodexAgents } from './lib/codex/agents-projection.js';
16
- import { applyHeader } from './lib/command-header.js';
17
- import { applyAgentModel, getAgentModels } from './lib/config/agent-models.js';
3
+ /** Project the role agents for Claude, then Codex, from `process.cwd()`. */
4
+
5
+ import {
6
+ CLAUDE_AGENTS_DIR,
7
+ syncClaudeAgents,
8
+ } from './lib/claude/agents-projection.js';
9
+ import { runAsCli } from './lib/cli-utils.js';
10
+ import {
11
+ CODEX_AGENTS_DIR,
12
+ syncCodexAgents,
13
+ } from './lib/codex/agents-projection.js';
14
+ import { getAgentModels } from './lib/config/agent-models.js';
18
15
  import { resolveConfig } from './lib/config-resolver.js';
19
16
  import { Logger } from './lib/Logger.js';
20
- import { dirExists } from './lib/util/paths.js';
21
-
22
- // cwd, never `__dirname/../..`, which lands inside node_modules when installed.
23
- const PROJECT_ROOT = process.cwd();
24
-
25
- // Test overrides; SYNC_CLAUDE_AGENTS_SRC replaces the payload source only.
26
- const PAYLOAD_SRC =
27
- process.env.SYNC_CLAUDE_AGENTS_SRC ??
28
- path.join(PROJECT_ROOT, '.agents', 'agents');
29
- const LOCAL_SRC = path.join(PROJECT_ROOT, '.agents', 'local', 'agents');
30
-
31
- const DEST_DIR =
32
- process.env.SYNC_CLAUDE_AGENTS_DEST ??
33
- path.join(PROJECT_ROOT, '.claude', 'agents');
34
-
35
- export const HEADER =
36
- '<!-- AUTO-GENERATED — do not edit. Source of truth: .agents/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
37
-
38
- export const LOCAL_HEADER =
39
- '<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
40
-
41
- fs.mkdirSync(DEST_DIR, { recursive: true });
42
-
43
- const isTopLevelAgent = (entry) => entry.isFile() && entry.name.endsWith('.md');
44
17
 
45
- // Payload first, so it wins a collision.
46
- const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
47
-
48
- /**
49
- * Named, not inline: an anonymous callback in this spawned-only script has no
50
- * coverage coordinates for the CRAP seat to resolve.
51
- *
52
- * @param {string} dir
53
- * @returns {Array<{dir: string, name: string}>}
54
- */
55
- function agentEntriesIn(dir) {
56
- return fs
57
- .readdirSync(dir, { withFileTypes: true })
58
- .filter(isTopLevelAgent)
59
- .map(function toAgentEntry(e) {
60
- return { dir, name: e.name };
61
- });
62
- }
63
-
64
- const entries = SRC_DIRS.flatMap(agentEntriesIn);
65
-
66
- const byName = new Map();
67
- for (const e of entries) {
68
- if (byName.has(e.name)) {
69
- Logger.warn(` shadowed ${e.name} (local copy ignored; payload wins)`);
70
- continue;
71
- }
72
- byName.set(e.name, e);
73
- }
74
-
75
- // Any existing agent def not in this set is reaped.
76
- const sourceSet = new Set(byName.keys());
77
-
78
- /**
79
- * @returns {string[]}
80
- */
81
- function listExistingAgents() {
82
- try {
83
- return fs.readdirSync(DEST_DIR).filter((f) => f.endsWith('.md'));
84
- } catch {
85
- return [];
86
- }
87
- }
88
-
89
- for (const name of listExistingAgents()) {
90
- if (!sourceSet.has(name)) {
91
- fs.unlinkSync(path.join(DEST_DIR, name));
92
- Logger.info(` removed ${name} (no longer in .agents/agents)`);
93
- }
94
- }
95
-
96
- // Resolved once: an invalid override (an unknown role) fails the sync here.
97
- const agentModels = getAgentModels(resolveConfig({ cwd: PROJECT_ROOT }));
98
-
99
- /**
100
- * @param {string} name
101
- * @param {string} content
102
- * @returns {string}
103
- */
104
- function withModelOverride(name, content) {
105
- const model = agentModels[name.replace(/\.md$/, '')];
106
- return model ? applyAgentModel(content, model) : content;
107
- }
108
-
109
- let synced = 0;
110
-
111
- /**
112
- * The header goes after any frontmatter, so `---` stays on line 1.
113
- *
114
- * @param {{ dir: string, name: string }} entry
115
- * @returns {Promise<void>}
116
- */
117
- async function syncEntry({ dir, name }) {
118
- const isLocal = dir === LOCAL_SRC;
119
- const header = isLocal ? LOCAL_HEADER : HEADER;
120
- const content = await fs.promises.readFile(path.join(dir, name), 'utf8');
121
- const dest = path.join(DEST_DIR, name);
122
- const target = applyHeader(withModelOverride(name, content), header);
123
-
124
- try {
125
- const existingContent = await fs.promises.readFile(dest, 'utf8');
126
- if (existingContent === target) return;
127
- } catch (err) {
128
- if (err.code !== 'ENOENT') throw err;
129
- }
130
-
131
- await fs.promises.writeFile(dest, target, 'utf8');
132
- synced++;
133
- Logger.info(` synced ${name}`);
134
- }
135
-
136
- await Promise.all(Array.from(byName.values()).map(syncEntry));
137
-
138
- Logger.info(
139
- `\n✔ ${synced} file(s) synced, ${sourceSet.size} total agents in .claude/agents/`,
140
- );
141
-
142
- // The Codex half: the same roles as `.codex/agents/mandrel-<role>.toml`. A
143
- // fixture run (a DEST override) skips it unless SYNC_CODEX_AGENTS_DEST names
144
- // its own target.
145
- const codexAgentsDest =
146
- process.env.SYNC_CODEX_AGENTS_DEST ??
147
- (process.env.SYNC_CLAUDE_AGENTS_DEST ? null : undefined);
148
- if (codexAgentsDest !== null) {
149
- const codex = syncCodexAgents({
150
- projectRoot: PROJECT_ROOT,
151
- payloadSrc: PAYLOAD_SRC,
152
- localSrc: LOCAL_SRC,
153
- destDir: codexAgentsDest,
154
- log: (line) => Logger.info(line),
18
+ /** @returns {Promise<void>} */
19
+ async function main() {
20
+ // cwd, never `__dirname/../..`, which lands inside node_modules.
21
+ const projectRoot = process.cwd();
22
+ const log = (line) => Logger.info(line);
23
+ const claude = syncClaudeAgents({
24
+ projectRoot,
25
+ // Validated: an unknown role fails the sync.
26
+ agentModels: getAgentModels(resolveConfig({ cwd: projectRoot })),
27
+ log,
28
+ warn: (line) => Logger.warn(line),
155
29
  });
156
30
  Logger.info(
157
- `✔ ${codex.written.length} file(s) synced, ${codex.total} total Codex agents in .codex/agents/`,
31
+ `\n✔ ${claude.written.length} file(s) synced, ${claude.total} total agents in ${CLAUDE_AGENTS_DIR}/`,
32
+ );
33
+ const codex = syncCodexAgents({ projectRoot, log });
34
+ Logger.info(
35
+ `✔ ${codex.written.length} file(s) synced, ${codex.total} total Codex agents in ${CODEX_AGENTS_DIR}/`,
158
36
  );
159
37
  }
38
+
39
+ runAsCli(import.meta.url, main, {
40
+ source: 'sync-claude-agents',
41
+ usage: {
42
+ invocation: 'node .agents/scripts/sync-claude-agents.js',
43
+ summary:
44
+ 'Regenerate the .claude/agents/ projection of .agents/agents/ (and .agents/local/agents/), then the Codex agents under .codex/agents/.',
45
+ flags: [],
46
+ },
47
+ });
@@ -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)