mandrel 2.59.0 → 2.61.0

package/.agents/scripts/sync-agentrc.js

@@ -1,27 +1,9 @@
 #!/usr/bin/env node
 
 /**
- * sync-agentrc.js — default-aware `.agentrc.json` reconciliation (Story #1995).
- *
- * Replaces the manual procedure formerly described in
- * `.agents/workflows/helpers/mandrel-sync-config.md`. Invoked by
- * `/mandrel-update` Step 3 after the package upgrade re-materializes `.agents/`.
- *
- * Contract:
- *   - Validates the project config against the framework schema. On
- *     failure, prints diagnostics and exits 1.
- *   - Never auto-fills optional keys from `.agents/docs/agentrc-reference.json`.
- *     The runtime layers framework defaults at read time, so an absent
- *     key resolves to the framework default without being written.
- *   - For every project leaf whose value equals the framework default,
- *     prints an informational `[REDUNDANT]` advisory. The project file
- *     is never modified.
- *
- * Exit codes:
- *   0 — Config is valid (advisories may still appear).
- *   1 — Config is missing, malformed, or fails schema validation.
- *
- * The flag contract lives in `USAGE` below — `--help` is the one home for it.
+ * Validate `.agentrc.json` and flag leaves that restate a framework default.
+ * Never writes the file: defaults are layered at read time, so absent keys
+ * need no filling. Flags and exit codes live in `USAGE`.
  */
 
 import { fileURLToPath } from 'node:url';

package/.agents/scripts/sync-claude-agents.js

@@ -1,34 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * Projects .agents/agents/ (and .agents/local/agents/ when present) into a flat
- * `.claude/agents/` tree so Claude Code exposes each role definition as a
- * role-scoped sub-agent (`subagent_type: <name>`). Exact sibling of
- * `sync-claude-commands.js` — same header, same local-shadow policy, same
- * orphan-reap, same prune-exempt handling for the consumer-authored
- * `.agents/local/agents/` source. Two source directories are enumerated in
- * order:
- *
- *   1. PAYLOAD_SRC  — `.agents/agents/`  (the installed Mandrel payload)
- *   2. LOCAL_SRC    — `.agents/local/agents/`  (consumer-authored, prune-exempt)
- *
- * The payload directory wins on basename collision: if both sources supply
- * `foo.md`, the payload copy is projected and the local copy is ignored with a
- * `shadowed` warning. Because both sources are unioned into `sourceSet`, local
- * agent defs are also protected from the orphan-reap — they survive
- * `npm install`, `mandrel sync`, and `mandrel update` with no manual re-sync.
- *
- * Only top-level `.md` files project (`.claude/agents/<name>.md`). Unlike the
- * commands sync there is no `loops/` namespace and no plugin tree to reap — the
- * agent surface is flat.
- *
- * A `.claude/agents/<name>.md` runs on its **own** system prompt — it does NOT
- * inherit the `CLAUDE.md` @-import closure — so a spawn routed to a role agent
- * stops re-paying the always-loaded context (issue #4478). The role defs
- * @-import `security-baseline.md` so the inviolable security MUSTs stay
- * single-sourced.
- *
- * Usage:  node .agents/scripts/sync-claude-agents.js
+ * Project `.agents/agents/` and `.agents/local/agents/` into a flat
+ * `.claude/agents/` tree — the sibling of `sync-claude-commands.js`, with the
+ * same payload-wins shadowing and orphan-reap. A role agent runs on its own
+ * system prompt (no `CLAUDE.md` closure), which is the point of routing to it.
  */
 
 // cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.
@@ -38,21 +14,10 @@ import path from 'node:path';
 import { applyHeader } from './lib/command-header.js';
 import { Logger } from './lib/Logger.js';
 
-// Resolve the project root from the invocation cwd — the consumer project where
-// `.agents/` is materialized and where Claude Code loads `.claude/agents/`.
-// It MUST NOT use `__dirname/../..`: in an npm-installed consumer this script
-// runs from `node_modules/mandrel/.agents/scripts/`, so that climb lands on the
-// package dir and the defs would be written *inside node_modules* rather than
-// the consumer. Every real invocation runs with cwd at the project root
-// (`npm run sync:agents`, the prepare hook). Tests drive fixture trees via the
-// SYNC_CLAUDE_AGENTS_SRC/DEST overrides below.
+// cwd, never `__dirname/../..`, which lands inside node_modules when installed.
 const PROJECT_ROOT = process.cwd();
 
-// Env-var overrides exist so the sync logic can be exercised against a fixture
-// agents tree in isolation. When unset, behaviour is unchanged — the script
-// defaults to the real agents / .claude/agents directories. SYNC_CLAUDE_AGENTS_SRC
-// overrides the PAYLOAD source only; LOCAL_SRC is always derived from the project
-// root so fixture tests can isolate the payload source.
+// Test overrides; SYNC_CLAUDE_AGENTS_SRC replaces the payload source only.
 const PAYLOAD_SRC =
   process.env.SYNC_CLAUDE_AGENTS_SRC ??
   path.join(PROJECT_ROOT, '.agents', 'agents');
@@ -69,8 +34,6 @@ export const LOCAL_HEADER =
   '<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/agents/ -->\n<!-- Re-run: npm run sync:agents -->\n\n';
 
 /**
- * Return true when the given directory path exists and is accessible.
- *
  * @param {string} dir
  * @returns {boolean}
  */
@@ -84,11 +47,9 @@ function dirExists(dir) {
 
 fs.mkdirSync(DEST_DIR, { recursive: true });
 
-// Top-level .md files project flat. Subdirectories are skipped.
 const isTopLevelAgent = (entry) => entry.isFile() && entry.name.endsWith('.md');
 
-// Enumerate sources: payload first, then local (if it exists). Payload wins on
-// basename collision — a consumer must not silently shadow a core role def.
+// Payload first, so it wins a collision.
 const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
 
 /** @type {Array<{dir: string, name: string}>} */
@@ -99,7 +60,6 @@ const entries = SRC_DIRS.flatMap((dir) =>
     .map((e) => ({ dir, name: e.name })),
 );
 
-// Collision policy: payload wins, warn on a shadowed local file.
 const byName = new Map();
 for (const e of entries) {
   if (byName.has(e.name)) {
@@ -109,13 +69,10 @@ for (const e of entries) {
   byName.set(e.name, e);
 }
 
-// sourceSet drives the orphan-reap: any existing agent def not in this set is
-// removed.
+// Any existing agent def not in this set is reaped.
 const sourceSet = new Set(byName.keys());
 
 /**
- * List the `.md` agent defs currently on disk in the destination.
- *
  * @returns {string[]}
  */
 function listExistingAgents() {
@@ -133,9 +90,7 @@ for (const name of listExistingAgents()) {
   }
 }
 
-// Copy each role def, injecting the auto-generated header after any leading
-// frontmatter (so the `---` block stays on line 1 and Claude Code parses the
-// agent's name/description). Use a distinct header comment for local-origin files.
+// The header goes after any frontmatter, so `---` stays on line 1.
 let synced = 0;
 const resolvedEntries = Array.from(byName.values());
 await Promise.all(
@@ -146,7 +101,6 @@ await Promise.all(
     const dest = path.join(DEST_DIR, name);
     const target = applyHeader(content, header);
 
-    // Skip write if content is already identical (avoid noisy git diffs).
     try {
       const existingContent = await fs.promises.readFile(dest, 'utf8');
       if (existingContent === target) return;

package/.agents/scripts/sync-claude-commands.js

@@ -1,46 +1,12 @@
 #!/usr/bin/env node
 
 /**
- * Projects .agents/workflows/ (and .agents/local/workflows/ when present) into
- * a flat `.claude/commands/` tree so Claude Code exposes each workflow as a
- * bare `/<name>` slash command. Two source directories are enumerated in order:
- *
- *   1. PAYLOAD_SRC  — `.agents/workflows/`  (the installed Mandrel payload)
- *   2. LOCAL_SRC    — `.agents/local/workflows/`  (consumer-authored, prune-exempt)
- *
- * The payload directory wins on basename collision: if both sources supply
- * `foo.md`, the payload copy is projected and the local copy is ignored with a
- * `shadowed` warning. Because both sources are unioned into `sourceSet`, local
- * commands are also protected from the orphan-reap — they survive
- * `npm install`, `mandrel sync`, and `mandrel update` with no manual re-sync.
- *
- * Flat projection (reverts the #3576 plugin cutover): the plugin command tree
- * (`.claude/plugins/mandrel/`) and the repo-local marketplace
- * (`.claude/.claude-plugin/marketplace.json`) are NOT written, because the
- * plugin system is unavailable in some Claude Code environments (`/plugin` not
- * present), which left the namespaced `/mandrel:<name>` commands unreachable.
- * Flat `.claude/commands/*.md` is the surface that loads across every
- * environment (CLI, IDE, GUI, web, SDK). On a machine that previously synced
- * the plugin tree, this script reaps it on the next run (see reapPluginTree).
- *
- * Top-level .md files project flat (`/<name>`). The
- * `.agents/workflows/helpers/` subdirectory holds path-included modules
- * (e.g. epic-code-review, epic-retro) that parent workflows read by
- * relative path — they are intentionally **not** exposed as commands, so
- * helpers/ is skipped.
- *
- * The `.agents/workflows/loops/` subdirectory is the **one** exception to
- * the skip-subdirectories rule (Story #4289, Epic #4284). Each loop unit
- * there projects to `.claude/commands/loops/<name>.md`, preserving the
- * subpath so Claude Code namespaces it as `/loops:<name>` (matching Claude
- * Code's subdirectory-command namespacing). Hosts that flatten
- * subdirectory commands surface the same file as the flat fallback
- * `/loops-<name>` (i.e. `loops-<name>` in the command tree) — the
- * projection writes the namespaced path; the flat form is the documented
- * host-side fallback, not a second on-disk copy. No subdirectory other
- * than `loops/` is recursed.
- *
- * Usage:  node .agents/scripts/sync-claude-commands.js
+ * Project `.agents/workflows/` and `.agents/local/workflows/` into a flat
+ * `.claude/commands/` tree (one `/<name>` per top-level workflow). The payload
+ * wins a name collision; both sources feed the orphan-reap set, so local
+ * commands survive re-syncs. Flat commands, not a plugin tree, because the
+ * plugin system is unavailable in some Claude Code hosts. `helpers/` is not
+ * projected; `loops/` is the one recursed subdirectory (`/loops:<name>`).
  */
 
 // cli-opt-out: top-level-await script with no main() function — runAsCli wraps an async main, which doesn't apply here.
@@ -50,27 +16,11 @@ import path from 'node:path';
 import { applyHeader, isCommandExcluded } from './lib/command-header.js';
 import { Logger } from './lib/Logger.js';
 
-// Resolve the project root from the invocation cwd — the consumer project where
-// `.agents/` is materialized and where Claude Code loads `.claude/commands/`.
-// It MUST NOT use `__dirname/../..`: in an npm-installed consumer this script
-// runs from `node_modules/mandrel/.agents/scripts/`, so that climb
-// lands on the package dir and the commands would be written *inside
-// node_modules* rather than the consumer — leaving `/<name>` commands
-// unloadable and the `commands-in-sync` doctor check (which resolves the same
-// consumer root via cwd — Story #3588) reporting "N not synced". Every real
-// invocation runs with cwd at the project root: `npm run sync:commands`, the
-// UserPromptSubmit hook, and `mandrel sync-commands` (which inherits the
-// caller's cwd). Tests drive fixture trees via the SYNC_CLAUDE_COMMANDS_SRC/DEST
-// overrides below.
+// The root is cwd, never `__dirname/../..`: installed under node_modules that
+// climb lands on the package dir and would write commands inside it.
 const PROJECT_ROOT = process.cwd();
 
-// Env-var overrides exist so the sync logic can be exercised against a
-// fixture workflow tree in isolation (regression test for the Epic #1185
-// frontmatter pass-through contract). When unset, behaviour is unchanged
-// — the script defaults to the real workflows / commands directories.
-// SYNC_CLAUDE_COMMANDS_SRC overrides the PAYLOAD source only; the LOCAL_SRC
-// is always derived from the project root so fixture tests can isolate the
-// payload source while still allowing LOCAL_SRC to be present if needed.
+// Test overrides; SYNC_CLAUDE_COMMANDS_SRC replaces the payload source only.
 const PAYLOAD_SRC =
   process.env.SYNC_CLAUDE_COMMANDS_SRC ??
   path.join(PROJECT_ROOT, '.agents', 'workflows');
@@ -87,8 +37,6 @@ export const LOCAL_HEADER =
   '<!-- AUTO-GENERATED from .agents/local/ — do not edit. Source of truth: .agents/local/workflows/ -->\n<!-- Re-run: npm run sync:commands -->\n\n';
 
 /**
- * Return true when the given directory path exists and is accessible.
- *
  * @param {string} dir
  * @returns {boolean}
  */
@@ -101,14 +49,8 @@ function dirExists(dir) {
 }
 
 /**
- * Reap the generated plugin projection (the #3576 surface) so the namespaced
- * `/mandrel:<name>` commands and the repo-local marketplace stop shadowing the
- * flat `/<name>` commands. This is the cutover-back step on existing machines:
- * the plugin tree is no longer written, but a developer who synced under #3576
- * still has it on disk. Removing `.claude/plugins/mandrel/` and the marketplace
- * listing is idempotent and never blocks the flat sync.
- *
- * Skipped when SYNC_CLAUDE_COMMANDS_DEST is set (fixture runs own their tree).
+ * Remove any on-disk plugin projection and marketplace listing, which would
+ * shadow the flat commands. Idempotent; skipped for fixture runs.
  *
  * @returns {void}
  */
@@ -128,7 +70,6 @@ function reapPluginTree() {
       Logger.warn(`  skip reap ${target}: ${err.message}`);
     }
   }
-  // Remove the now-empty .claude-plugin/ dir (ignore if absent or non-empty).
   try {
     fs.rmdirSync(path.join(PROJECT_ROOT, '.claude', '.claude-plugin'));
   } catch {
@@ -139,22 +80,14 @@ function reapPluginTree() {
 reapPluginTree();
 fs.mkdirSync(DEST_DIR, { recursive: true });
 
-// The only namespaced subdirectory we recurse. Every other subdirectory
-// (notably helpers/) is skipped — those hold path-included modules, not
-// slash commands. Loop units under workflows/loops/ project into
-// .claude/commands/loops/ so Claude Code namespaces them as /loops:<name>
-// (Story #4289).
+// The only recursed subdirectory; helpers/ holds path-included modules.
 const LOOPS_NS = 'loops';
 
-// Top-level .md files project flat. Subdirectories are skipped here and the
-// only one re-introduced is loops/ (handled by enumerateLoopUnits below).
 const isTopLevelWorkflow = (entry) =>
   entry.isFile() && entry.name.endsWith('.md');
 
 /**
- * `README.md` (any case) under `loops/` is namespace documentation, not a
- * loop unit — it carries no `loop:` frontmatter and must not project as a
- * `/loops:README` command. Exclude it from the loop-unit enumeration.
+ * `loops/README.md` is documentation, not a command.
  *
  * @param {import('node:fs').Dirent} entry
  * @returns {boolean}
@@ -163,13 +96,9 @@ const isLoopUnit = (entry) =>
   isTopLevelWorkflow(entry) && entry.name.toLowerCase() !== 'readme.md';
 
 /**
- * Enumerate the loop units under a source dir's `loops/` subdirectory.
- * Returns entries keyed by the namespaced relative path
- * (`loops/<name>.md`) so they never collide with a flat top-level command
- * of the same basename and so the reap can track them distinctly. The
- * directory's `README.md` is skipped — it is documentation, not a command.
+ * Keyed by `loops/<name>.md` so a unit never collides with a flat command.
  *
- * @param {string} dir — a workflows source root (payload or local).
+ * @param {string} dir A workflows source root.
  * @returns {Array<{dir: string, name: string, rel: string}>}
  */
 function enumerateLoopUnits(dir) {
@@ -185,10 +114,7 @@ function enumerateLoopUnits(dir) {
     }));
 }
 
-// Enumerate sources: payload first, then local (if it exists). Payload wins
-// on relative-path collision — a consumer must not silently shadow a core
-// command. Each entry carries its destination-relative path (`rel`): a bare
-// basename for flat top-level commands, `loops/<name>.md` for loop units.
+// Payload first, so it wins a collision.
 const SRC_DIRS = [PAYLOAD_SRC, LOCAL_SRC].filter(dirExists);
 
 /** @type {Array<{dir: string, name: string, rel: string}>} */
@@ -200,12 +126,7 @@ const entries = SRC_DIRS.flatMap((dir) => [
   ...enumerateLoopUnits(dir),
 ]);
 
-// Collision policy: payload wins, warn on a shadowed local file. Keyed by the
-// destination-relative path so a flat `foo.md` and a `loops/foo.md` are
-// distinct entries. A workflow whose frontmatter carries `command: false`
-// (#4482 — dual-use audit lens files with a host-native standalone
-// equivalent) is excluded from projection entirely: it never enters
-// `sourceSet`, so any previously projected copy is reaped below.
+// A `command: false` workflow never enters `sourceSet`, so a stale copy is reaped.
 const byRel = new Map();
 for (const e of entries) {
   if (byRel.has(e.rel)) {
@@ -219,15 +140,10 @@ for (const e of entries) {
   byRel.set(e.rel, e);
 }
 
-// sourceSet drives the orphan-reap: any existing command not in this set is
-// removed. Keyed by destination-relative path so loop units are reaped from
-// the loops/ namespace and flat commands from the root.
+// Any existing command not in this set is reaped.
 const sourceSet = new Set(byRel.keys());
 
 /**
- * List the destination-relative paths of every projected command currently
- * on disk: flat `*.md` at the root plus `loops/*.md` in the namespace.
- *
  * @returns {string[]}
  */
 function listExistingCommands() {
@@ -252,11 +168,7 @@ for (const rel of listExistingCommands()) {
   }
 }
 
-// Copy each workflow, injecting the auto-generated header after any leading
-// frontmatter (so the `---` block stays on line 1 and Claude Code parses the
-// command description). Use a distinct header comment for local-origin files.
-// Parallelised so the ~30-file sync doesn't serialise on per-file fs latency
-// (noticeable on Windows where each syscall pays a larger fixed cost).
+// The header goes after any frontmatter, so `---` stays on line 1.
 let synced = 0;
 const resolvedEntries = Array.from(byRel.values());
 await Promise.all(
@@ -267,11 +179,9 @@ await Promise.all(
     const dest = path.join(DEST_DIR, rel);
     const target = applyHeader(content, header);
 
-    // Ensure the namespace subdirectory exists before writing a loop unit.
     await fs.promises.mkdir(path.dirname(dest), { recursive: true });
 
-    // Skip write if content is already identical (avoid noisy git diffs).
-    // Use try/catch over existsSync+readFile so we only pay one syscall.
+    // Skip identical content to avoid noisy git diffs.
     try {
       const existingContent = await fs.promises.readFile(dest, 'utf8');
       if (existingContent === target) return;

package/.agents/scripts/test-wrapper.js

@@ -2,35 +2,9 @@
 /* node:coverage ignore file */
 
 /**
- * test-wrapper.js — npm-test preflight gate.
- *
- * Story #1289 wires the self-healing checks registry in front of
- * `npm test` so the suite refuses to start in a known-bad state (e.g.
- * core.bare flipped on the main checkout, missing `.env` / `.mcp.json`
- * bootstrap files, etc.). The wrapper runs
- * `runChecks({ scope: 'npm-test', autoFix: true })` against the assembled
- * state probe; on any surviving blocker it prints a `id · summary ·
- * fixCommand` table and exits with code 2 (the project-wide "preflight
- * refused" reservation).
- *
- * On a clean preflight npm continues to `.agents/scripts/run-tests.js`, which
- * execs the underlying Node test runner and cleans test-reserved temp
- * artefacts afterward. This wrapper itself adds no top-level npm dependencies.
- *
- * Wiring: `package.json` points `pretest` at this script. The `test`
- * script remains the node --test invocation so `npm test` still picks up
- * `pretest` automatically per npm lifecycle rules. A failed pretest aborts
- * the lifecycle without invoking the test runner — exit code 2 propagates
- * out through npm.
- *
- * Bypass: set `SKIP_PREFLIGHT=1` to skip the gate entirely (used by the
- * `coverage` script which manages its own preflight separately, and by
- * any debugging session that needs the suite to run despite a known
- * blocker the operator is iterating on).
- *
- * Usage:
- *   node .agents/scripts/test-wrapper.js              # full preflight + test
- *   SKIP_PREFLIGHT=1 node .agents/scripts/test-wrapper.js  # skip gate
+ * `pretest` preflight: runs the self-healing checks (scope `npm-test`) so the
+ * suite refuses to start in a known-bad state; a surviving blocker exits 2,
+ * which aborts the npm lifecycle. `SKIP_PREFLIGHT=1` bypasses it.
  */
 
 import { runAsCli } from './lib/cli-utils.js';
@@ -40,7 +14,6 @@ import {
   runPreflight,
 } from './lib/preflight-runner.js';
 
-/** Default Logger adapter — same shape preflight-runner uses. */
 const DEFAULT_LOGGER = {
   info: (msg) => Logger.info(msg),
   warn: (msg) => Logger.warn(msg),
@@ -48,17 +21,11 @@ const DEFAULT_LOGGER = {
 };
 
 /**
- * Run the npm-test preflight gate. Exported so unit tests can drive it
- * directly with an inline registry, without actually spawning the test
- * runner. Returns `{ status: 'ok' | 'blocked' }` plus the findings/fixed
- * arrays from the runner.
- *
  * @param {object} [opts]
  * @param {string} [opts.cwd=process.cwd()]
- * @param {object} [opts.probes]   Test-only probe injection.
- * @param {object} [opts.registry] Test-only inline registry — bypasses
- *   `loadRegistry()`.
- * @param {string} [opts.dir]      Test-only fixture directory.
+ * @param {object} [opts.probes]   Test-only.
+ * @param {object} [opts.registry] Test-only.
+ * @param {string} [opts.dir]      Test-only.
  * @param {{ info?: Function, warn?: Function, error?: Function }} [opts.logger]
  * @returns {Promise<{ status: 'ok' | 'blocked', findings: Array, fixed: Array }>}
  */
@@ -89,7 +56,6 @@ export async function runTestWrapperPreflight({
 runAsCli(
   import.meta.url,
   async () => {
-    // Operator bypass for iterative debugging — see the file header.
     if (process.env.SKIP_PREFLIGHT === '1') {
       Logger.warn(
         '[npm-test] SKIP_PREFLIGHT=1 — bypassing preflight checks (debugging mode).',
@@ -98,9 +64,6 @@ runAsCli(
     }
     const result = await runTestWrapperPreflight();
     if (result.status === 'blocked') {
-      // The wrapper never spawns the test runner on a blocked preflight.
-      // Exit code 2 propagates out through `npm run pretest` and short-
-      // circuits the `npm test` lifecycle before the test command runs.
       process.exit(PREFLIGHT_REFUSED_EXIT_CODE);
     }
   },

package/.agents/scripts/update-coverage-baseline.js

@@ -1,20 +1,8 @@
 #!/usr/bin/env node
 /**
- * Refresh `baselines/coverage.json` from the most recent
- * `coverage/coverage-final.json`. Run this when you intentionally add,
- * remove, or change scope of `.agents/scripts/**` files and the
- * resulting per-file coverage shifts are expected.
- *
- * Story #3658 (Epic #2173): this CLI is now a thin wrapper around
- * `refreshBaseline({ kind: 'coverage' })` from
- * `.agents/scripts/lib/baselines/refresh-service.js`. All scoring, scope
- * resolution, envelope assembly, and persistence flows through the unified
- * service.
- *
- * The script does NOT run the test suite itself — invoke
- * `npm run test:coverage` first (or rely on its prior run-on-disk
- * artifact). This keeps the refresh idempotent and lets operators
- * inspect coverage output before locking it in.
+ * Refresh the coverage baseline from the `coverage-final.json` on disk via
+ * `refreshBaseline({ kind: 'coverage' })`. Never runs the suite, so the
+ * refresh is idempotent and the output can be inspected first.
  */
 
 import { createRequire } from 'node:module';
@@ -34,12 +22,7 @@ import {
 } from './lib/coverage-baseline.js';
 import { Logger } from './lib/Logger.js';
 
-/**
- * Usage block for `--help`. This CLI *writes* on invocation, so the help
- * branch must short-circuit before `main` runs rather than inside it —
- * `runAsCli` answers help first, which makes "a usage probe never mutates a
- * baseline" structural instead of a check `main` has to remember.
- */
+/** `runAsCli` answers `--help` before `main`, so a usage probe never writes. */
 const USAGE = {
   invocation:
     'node .agents/scripts/update-coverage-baseline.js [--full-scope | --diff-scope <ref>]',
@@ -84,7 +67,7 @@ function main() {
   const refreshOpts = {
     kind: 'coverage',
     writePath: absBaselinePath,
-    epsilon: getBaselineEpsilon('coverage', null),
+    epsilon: getBaselineEpsilon('coverage'),
     scorer: buildCoverageUpdaterScorer(cwd, {
       readCoverage: readCoverageFinal,
       loadScope: loadC8Scope,

package/.agents/scripts/update-crap-baseline.js

@@ -1,6 +1,4 @@
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
+// Must be the first import: fails fast before any third-party import loads.
 import './lib/runtime-deps/ensure-installed.js';
 import {
   buildCrapUpdaterScorer,
@@ -24,34 +22,13 @@ import {
 import { Logger } from './lib/Logger.js';
 
 /**
- * CLI: scan → score → save the CRAP baseline.
- *
- * Story #3658 (Epic #2173): this CLI is now a thin wrapper around
- * `refreshBaseline({ kind: 'crap' })` from
- * `.agents/scripts/lib/baselines/refresh-service.js`. All scoring, scope
- * resolution, envelope assembly, and persistence flows through the unified
- * service.
- *
- * Writes the canonical CRAP baseline at the path resolved from
- * `delivery.quality.baselines.crap.path` (default `baselines/crap.json`),
- * or the path supplied via `--baseline <path>`. Output is a deterministic,
- * kernel-stamped envelope. Files without coverage entries are skipped (not
- * scored as 0%) when `requireCoverage: true` — their count and names are
- * logged so the operator can tell the difference between "unscorable" and
- * "safe zero".
- *
- * Exits non-zero only when the scanner itself crashes. An empty result (no
- * coverage at all, no scored methods) still writes an envelope with `rows: []`
- * so downstream `check-crap` can tell "intentional empty baseline" apart from
- * "no baseline yet".
+ * Refresh the CRAP baseline via `refreshBaseline({ kind: 'crap' })`. Under
+ * `requireCoverage` an uncovered file is skipped and logged, never scored as
+ * 0%. An empty result still writes `rows: []`, so an intentional empty
+ * baseline differs from a missing one.
  */
 
-/**
- * Usage block for `--help` (Story #4872). This CLI *writes* on invocation, so
- * the help branch must short-circuit before `main` runs rather than inside it —
- * `runAsCli` answers help first, which makes "a usage probe never mutates a
- * baseline" structural instead of a check `main` has to remember.
- */
+/** `runAsCli` answers `--help` before `main`, so a usage probe never writes. */
 const USAGE = {
   invocation:
     'node .agents/scripts/update-crap-baseline.js [--baseline <path>] [--coverage <path>] [--full-scope | --diff-scope <ref>]',
@@ -96,7 +73,7 @@ async function main() {
   const refreshOpts = {
     kind: 'crap',
     writePath: options.absBaselinePath,
-    epsilon: getBaselineEpsilon('crap', config),
+    epsilon: getBaselineEpsilon('crap'),
     scorer: buildCrapUpdaterScorer(options, { loadCoverage }),
   };
   // No flag -> scopeFiles=null + fullScope=false -> the service derives the