mandrel 2.24.0 → 2.26.0

package/.agents/scripts/story-plan.js

@@ -32,6 +32,7 @@ import {
   rankDuplicateCandidates,
   readTechStackSummary,
   shouldRefine,
+  synthesizeContractSections,
   validateStoryBody,
 } from './lib/story-plan.js';
 
@@ -40,7 +41,8 @@ Usage:
   story-plan.js --emit-context (--seed "<seed>" | --seed-file <file>) \\
     [--refine | --no-refine] [--pretty]
 
-  story-plan.js --body <file> [--dry-run]
+  story-plan.js --body <file> [--acceptance <file>] [--verify <file>] \\
+    [--dry-run]
 
   story-plan.js --help
 
@@ -48,9 +50,18 @@ Modes:
   --emit-context   Build the host-LLM authoring envelope and print it as
                    JSON on stdout. Use this first; the host LLM authors a
                    draft body using the envelope and the body template.
-  --body <file>    Persist a pre-authored body. Validates shape (required
-                   sections, no Epic: ref, AC checklist non-empty) and
-                   calls \`gh issue create\` with type::story.
+  --body <file>    Persist a pre-authored body. Validates shape (## Goal
+                   and ## Changes present, no Epic: ref, an acceptance +
+                   verify contract) and calls \`gh issue create\` with
+                   type::story.
+  --acceptance <file>
+                   JSON string[] of the Story's top-level acceptance
+                   criteria. Authored once here — NOT mirrored into the
+                   body by hand; the \`## Acceptance\` section is
+                   synthesized from it, matching the story-author prompt.
+  --verify <file>  JSON string[] of the Story's top-level verify entries,
+                   each ending in a (unit|contract|e2e|validate) tier.
+                   Synthesized into \`## Verify\` the same way.
   --dry-run        With --body: print the body and the gh argv that would
                    be invoked, then exit 0. No GitHub mutations.
 
@@ -101,8 +112,13 @@ async function fetchOpenStories(provider) {
  * array; the caller decides whether to execute it (persist) or print
  * it (--dry-run).
  */
-function renderGhArgv({ title, bodyPath, labels }) {
-  const argv = ['issue', 'create', '--title', title, '--body-file', bodyPath];
+function renderGhArgv({ title, bodyPath, labels, body = null }) {
+  // `--body-file` streams the authored file untouched; an inline `--body` is
+  // used only when persist synthesized sections into it (Story #4874), so the
+  // file on disk is no longer what gets created.
+  const source =
+    typeof body === 'string' ? ['--body', body] : ['--body-file', bodyPath];
+  const argv = ['issue', 'create', '--title', title, ...source];
   for (const label of labels) {
     argv.push('--label', label);
   }
@@ -180,6 +196,31 @@ async function runEmitContext({
   write(`${json}\n`);
 }
 
+/**
+ * Read an optional top-level contract array (`--acceptance` / `--verify`)
+ * from a JSON file. Absent flag → an empty list, so the flags stay optional
+ * for a body that already carries its own sections.
+ *
+ * @param {string|undefined} filePath
+ * @param {'acceptance'|'verify'} label
+ * @returns {Promise<string[]>}
+ */
+async function readContractList(filePath, label) {
+  if (!filePath) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(
+      `Cannot read --${label} file "${filePath}": ${err.message}`,
+    );
+  }
+  if (!Array.isArray(parsed) || parsed.some((v) => typeof v !== 'string')) {
+    throw new Error(`--${label} file "${filePath}" must be a JSON string[].`);
+  }
+  return parsed;
+}
+
 async function runPersist({
   values,
   provider,
@@ -193,17 +234,30 @@ async function runPersist({
   if (!bodyPath) {
     throw new Error('--body <file> is required in persist mode.');
   }
-  const body = await readFile(bodyPath, 'utf8');
-  const validation = validateStoryBody(body);
+  const authored = await readFile(bodyPath, 'utf8');
+  const contract = {
+    acceptance: await readContractList(values.acceptance, 'acceptance'),
+    verify: await readContractList(values.verify, 'verify'),
+  };
+  const validation = validateStoryBody(authored, contract);
   if (!validation.ok) {
     throw new Error(
       `Drafted body failed validation:\n  - ${validation.errors.join('\n  - ')}`,
     );
   }
 
+  // Story #4874: the author writes acceptance[] / verify[] once, at the
+  // ticket's top level, and persist renders their sections — never the
+  // author by hand.
+  const body = synthesizeContractSections(authored, contract);
   const title = extractTitle(body);
   const labels = [TYPE_LABELS.STORY];
-  const argv = renderGhArgv({ title, bodyPath, labels });
+  const argv = renderGhArgv({
+    title,
+    bodyPath,
+    labels,
+    body: body === authored ? null : body,
+  });
 
   if (dryRun) {
     Logger.info('--- DRY RUN ---');
@@ -255,6 +309,8 @@ async function main() {
       seed: { type: 'string' },
       'seed-file': { type: 'string' },
       body: { type: 'string' },
+      acceptance: { type: 'string' },
+      verify: { type: 'string' },
       refine: { type: 'boolean', default: false },
       'no-refine': { type: 'boolean', default: false },
       pretty: { type: 'boolean', default: false },

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

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-// cli-opt-out: top-level main()-driven CLI invoked via npm run coverage:update; no runAsCli() wrapper required.
 /**
  * Refresh `baselines/coverage.json` from the most recent
  * `coverage/coverage-final.json`. Run this when you intentionally add,
@@ -22,6 +21,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
 import {
   buildScopePredicate,
@@ -31,6 +31,32 @@ 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.
+ */
+const USAGE = {
+  invocation:
+    'node .agents/scripts/update-coverage-baseline.js [--full-scope | --diff-scope <ref>]',
+  summary:
+    'Score → write the coverage baseline from the coverage-final.json already on disk. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
+  flags: [
+    [
+      '--full-scope',
+      'Rescore every file in every target dir (no out-of-scope merge).',
+    ],
+    [
+      '--diff-scope <ref>',
+      'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
+    ],
+  ],
+  notes: [
+    'Run `npm run test:coverage` first — this script never runs the suite itself.',
+  ],
+};
+
 const require = createRequire(import.meta.url);
 
 function loadC8Scope(cwd) {
@@ -123,7 +149,11 @@ function main() {
   });
 }
 
-main().catch((err) => {
-  Logger.error(`[Coverage] ❌ Fatal error: ${err?.message ?? err}`);
-  process.exit(1);
+runAsCli(import.meta.url, main, {
+  source: 'coverage-baseline',
+  usage: USAGE,
+  onError: (err) => {
+    Logger.error(`[Coverage] ❌ Fatal error: ${err?.message ?? err}`);
+    process.exitCode = 1;
+  },
 });

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

@@ -5,6 +5,7 @@ import './lib/runtime-deps/ensure-installed.js';
 import path from 'node:path';
 import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
 import {
   getBaselines,
@@ -44,6 +45,40 @@ import { Logger } from './lib/Logger.js';
  * "no baseline yet".
  */
 
+/**
+ * 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.
+ */
+const USAGE = {
+  invocation:
+    'node .agents/scripts/update-crap-baseline.js [--baseline <path>] [--coverage <path>] [--full-scope | --diff-scope <ref>]',
+  summary:
+    'Scan → score → write the CRAP baseline. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
+  flags: [
+    [
+      '--baseline <path>',
+      'Write to this path instead of `delivery.quality.baselines.crap.path`.',
+    ],
+    [
+      '--coverage <path>',
+      'Read coverage from this path (default `coverage/coverage-final.json`).',
+    ],
+    [
+      '--full-scope',
+      'Rescore every file in every target dir (no out-of-scope merge).',
+    ],
+    [
+      '--diff-scope <ref>',
+      'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
+    ],
+  ],
+  notes: [
+    'Run `npm run test:coverage` first — without a coverage artifact every file is skipped.',
+  ],
+};
+
 function parseCliArgs(argv = process.argv.slice(2)) {
   const out = {
     baselinePath: undefined,
@@ -183,8 +218,11 @@ async function main() {
   );
 }
 
-// cli-opt-out: top-level main().catch predates runAsCli; never imported elsewhere so the auto-run risk is moot.
-main().catch((err) => {
-  Logger.error(`[CRAP] ❌ Fatal error: ${err?.stack ?? err?.message ?? err}`);
-  process.exit(1);
+runAsCli(import.meta.url, main, {
+  source: 'crap-baseline',
+  usage: USAGE,
+  onError: (err) => {
+    Logger.error(`[CRAP] ❌ Fatal error: ${err?.stack ?? err?.message ?? err}`);
+    process.exitCode = 1;
+  },
 });

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

@@ -1,57 +1,97 @@
+/**
+ * update-duplication-baseline.js — manual refresh CLI for the
+ * code-duplication (DRY) baseline (Story #3664).
+ *
+ * Story #4944: this CLI is now a thin wrapper around
+ * `refreshBaseline({ kind: 'duplication' })` from
+ * `.agents/scripts/lib/baselines/refresh-service.js`, completing the Epic
+ * #2173 migration — duplication was the last kind still assembling its own
+ * writer call via the legacy `buildWriterScopeArgs` path. Scope resolution,
+ * prior-envelope reading, epsilon damping, envelope assembly, and
+ * persistence all flow through the unified service.
+ *
+ * The migration is what makes this CLI's documented surface true. Before it,
+ * `--full-scope` was advertised and parsed by nobody, and the no-flag default
+ * was a full rewrite rather than the diff-scoped refresh the usage text
+ * described.
+ *
+ * Surface:
+ *
+ *   - `--baseline <path>`: write somewhere other than the configured
+ *     `delivery.quality.gates.duplication.baselinePath`.
+ *   - `--diff-scope <ref>`: scope the refresh to files changed between
+ *     `<ref>` and HEAD. Out-of-scope rows are preserved verbatim from the
+ *     prior on-disk baseline.
+ *   - `--full-scope`: regenerate every row (no out-of-scope merge).
+ *   - With no scope flag: scope is derived from `git diff --name-only
+ *     origin/main..HEAD` (the service's default `baseRef..headRef`), matching
+ *     `update-crap-baseline.js` / `update-maintainability-baseline.js` /
+ *     `update-coverage-baseline.js`.
+ *
+ * **Scope is a write-side filter here, not a scan-side one.** jscpd detects
+ * clones pairwise, so the scan always covers the whole target tree even in
+ * diff mode — see `buildDefaultDuplicationScorer` in the refresh service for
+ * why narrowing the scan would drop clones between a changed file and an
+ * unchanged one. What a scope flag narrows is which rows the refresh is
+ * allowed to rewrite.
+ *
+ * Exits non-zero only when the scanner itself crashes. An empty result (no
+ * detected clones) still writes an envelope with `rows: []` so downstream
+ * `check-baselines` can tell "intentional empty baseline" apart from "no
+ * baseline yet".
+ */
+
 // 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).
 import './lib/runtime-deps/ensure-installed.js';
-import { createRequire } from 'node:module';
 import path from 'node:path';
-import { buildWriterScopeArgs } from './lib/baselines/diff-scope-cli.js';
-import { scanDuplication } from './lib/baselines/duplication-scanner.js';
-import { write, writeFile } from './lib/baselines/writer.js';
+import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
+import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
 import { getQuality, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 
 /**
- * CLI: scan → score → save the code-duplication (DRY) baseline (Story #3664).
- *
- * Writes the canonical duplication baseline at the path resolved from
- * `delivery.quality.gates.duplication.baselinePath` (default
- * `baselines/duplication.json`), or the path supplied via `--baseline <path>`.
- * Output is a deterministic, kernel-stamped envelope produced by the shared
- * writer — every row path is canonicalised, the per-kind rollup math runs,
- * and the envelope is schema-validated before persisting.
- *
- * Mirrors `update-crap-baseline.js`: thin CLI shell + shared writer funnel.
- * The duplication scan delegates to jscpd's `detectClones` (a pure clone
- * detector with no test coupling), wrapped by `scanDuplication` so the
- * parse→envelope path is unit-testable with the scanner mocked.
- *
- * Exits non-zero only when the scanner itself crashes. An empty result (no
- * detected clones) still writes an envelope with `rows: []` so downstream
- * `check-baselines` can tell "intentional empty baseline" apart from "no
- * baseline yet".
+ * 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.
  */
-
-const require = createRequire(import.meta.url);
+const USAGE = {
+  invocation:
+    'node .agents/scripts/update-duplication-baseline.js [--baseline <path>] [--full-scope | --diff-scope <ref>]',
+  summary:
+    'Scan → score → write the code-duplication (DRY) baseline. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
+  flags: [
+    [
+      '--baseline <path>',
+      'Write to this path instead of `delivery.quality.gates.duplication.baselinePath`.',
+    ],
+    [
+      '--full-scope',
+      'Rescan every file in every target dir (no out-of-scope merge).',
+    ],
+    [
+      '--diff-scope <ref>',
+      'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
+    ],
+  ],
+  notes: [
+    'Backed by jscpd; the scan reads the working tree and runs no test suite.',
+    'Clone detection is pairwise, so the scan always covers the whole target tree — a scope flag narrows which rows are rewritten, not what is scanned.',
+  ],
+};
 
 /**
- * Resolve jscpd's `detectClones` lazily. The jscpd ESM entrypoint has a
- * broken transitive `colors/safe` specifier under Node's strict ESM
- * resolver, so we load the CJS build via `createRequire`. Isolated here so
- * the rest of the module stays import-pure and testable.
+ * Parse `--baseline <path>` — the one flag this CLI does not share with its
+ * siblings. The scope flags are parsed by the shared helpers so their
+ * contract stays identical across the four update CLIs.
  *
- * @returns {(opts: object) => Promise<Array<object>>}
+ * @param {string[]} argv
+ * @returns {{ baselinePath: string | undefined }}
  */
-function resolveDetectClones() {
-  const jscpd = require('jscpd');
-  if (typeof jscpd.detectClones !== 'function') {
-    throw new Error(
-      "[Duplication] jscpd.detectClones is not available — run 'npm install'",
-    );
-  }
-  return jscpd.detectClones;
-}
-
 function parseCliArgs(argv = process.argv.slice(2)) {
   const out = { baselinePath: undefined };
   for (let i = 0; i < argv.length; i += 1) {
@@ -63,6 +103,16 @@ function parseCliArgs(argv = process.argv.slice(2)) {
   return out;
 }
 
+/**
+ * Parse `--full-scope` (boolean opt-out flag).
+ *
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+function parseFullScopeFlag(argv = []) {
+  return argv.includes('--full-scope');
+}
+
 /**
  * Resolve the duplication gate block from the merged quality config. The
  * flattened legacy bag does not expose a `duplication` accessor (the kind
@@ -76,59 +126,135 @@ function resolveDuplicationGate(config) {
   return gates.duplication ?? {};
 }
 
-async function main() {
-  const args = parseCliArgs();
-  const config = resolveConfig();
-  const gate = resolveDuplicationGate(config);
-  const targetDirs = Array.isArray(gate.targetDirs) ? gate.targetDirs : [];
-  const ignoreGlobs = Array.isArray(gate.ignoreGlobs) ? gate.ignoreGlobs : [];
-  const baselinePath =
-    args.baselinePath ?? gate.baselinePath ?? 'baselines/duplication.json';
-
-  Logger.info('[Duplication] Updating baseline...');
-  Logger.info(`[Duplication] Target dirs: ${targetDirs.join(', ')}`);
-
-  const rows = await scanDuplication({
-    targetDirs,
-    cwd: process.cwd(),
-    ignoreGlobs,
-    detect: resolveDetectClones(),
-  });
+/**
+ * Resolve the mutually-exclusive scope selection from argv.
+ *
+ * Split out of `main` deliberately: nothing in this file is reachable from a
+ * test (the CLI is only ever spawned with `--help`, which `runAsCli`
+ * short-circuits), so every function here scores CRAP at zero coverage —
+ * `c² + c`. A single `main` carrying all the branching lands at c=8 → 72,
+ * well over the 30 ceiling. Small single-purpose helpers keep each row far
+ * below it without hiding any logic.
+ *
+ * @param {string[]} argv
+ * @returns {{ fullScope: boolean, diffScopeRef: string | null }}
+ * @throws {Error} when both scope flags are supplied.
+ */
+function resolveScopeSelection(argv) {
+  const diffScopeRef = parseDiffScopeFlag(argv);
+  const fullScope = parseFullScopeFlag(argv);
+  if (fullScope && diffScopeRef !== null) {
+    throw new Error(
+      '[Duplication] --full-scope is incompatible with --diff-scope; pick one',
+    );
+  }
+  return { fullScope, diffScopeRef };
+}
 
-  const absBaselinePath = path.isAbsolute(baselinePath)
+/**
+ * Resolve the absolute path the refreshed envelope is written to:
+ * `--baseline <path>` wins, then the configured gate path, then the
+ * framework default.
+ *
+ * @param {string[]} argv
+ * @param {object} gate resolved duplication gate block
+ * @returns {string} absolute path
+ */
+function resolveAbsBaselinePath(argv, gate) {
+  const baselinePath =
+    parseCliArgs(argv).baselinePath ??
+    gate.baselinePath ??
+    'baselines/duplication.json';
+  return path.isAbsolute(baselinePath)
     ? baselinePath
     : path.resolve(process.cwd(), baselinePath);
+}
 
-  // Route through the shared writer: canonicalise paths, run the per-kind
-  // rollup, stamp `$schema` / `kernelVersion` / `generatedAt`, and validate
-  // against the duplication schema before persisting. Epsilon is applied by
-  // default so unchanged code with stale env produces a zero-row diff.
-  const scopeArgs = buildWriterScopeArgs({
-    kind: 'duplication',
-    absBaselinePath,
-    epsilon: getBaselineEpsilon('duplication', config),
-    logger: Logger,
-    logTag: '[Duplication]',
-  });
-  const envelope = write({
+/**
+ * Announce which scope the refresh resolved to, so an operator reading the
+ * log can tell a narrowed refresh from a full rewrite without re-deriving it.
+ *
+ * @param {{ fullScope: boolean, diffScopeRef: string | null }} selection
+ */
+function logScopeDecision({ fullScope, diffScopeRef }) {
+  if (fullScope) {
+    Logger.info(
+      '[Duplication] --full-scope: regenerating every row (out-of-scope merge disabled).',
+    );
+  } else if (diffScopeRef) {
+    Logger.info(
+      `[Duplication] --diff-scope ${diffScopeRef}: narrowing to changed files; out-of-scope rows preserved verbatim.`,
+    );
+  }
+}
+
+/**
+ * Assemble the `refreshBaseline` option bag for the resolved selection.
+ *
+ * No `scorer` is injected — the service resolves the canonical default
+ * duplication scorer, which reads `gates.duplication.targetDirs` /
+ * `ignoreGlobs` off the same resolved config this CLI reads.
+ *
+ * @param {{ fullScope: boolean, diffScopeRef: string | null, absBaselinePath: string, epsilon: number }} args
+ * @returns {object} options for `refreshBaseline`
+ */
+function buildRefreshOpts({
+  fullScope,
+  diffScopeRef,
+  absBaselinePath,
+  epsilon,
+}) {
+  const refreshOpts = {
     kind: 'duplication',
-    rows,
-    ...scopeArgs,
-  });
-  writeFile(absBaselinePath, envelope);
+    writePath: absBaselinePath,
+    epsilon,
+  };
+  if (fullScope) {
+    refreshOpts.fullScope = true;
+  } else if (diffScopeRef) {
+    // The CLI's documented `--diff-scope <ref>` semantics are `<ref>...HEAD`
+    // (three-dot). The service derives via two-dot `baseRef..headRef`; pass
+    // the ref as `baseRef` so the derivation runs through the same execFile
+    // seam the sibling CLIs use.
+    refreshOpts.baseRef = diffScopeRef;
+  }
+  // No flag → scopeFiles=null + fullScope=false → service derives the diff
+  // via `origin/main..HEAD` (its default baseRef/headRef).
+  return refreshOpts;
+}
 
-  Logger.info(
-    `[Duplication] Scanned ${rows.length} file(s) with detected duplication; wrote ${envelope.rows.length} row(s).`,
+async function main() {
+  const argv = process.argv.slice(2);
+  const selection = resolveScopeSelection(argv);
+  const config = resolveConfig();
+  const absBaselinePath = resolveAbsBaselinePath(
+    argv,
+    resolveDuplicationGate(config),
   );
+
+  Logger.info('[Duplication] Updating baseline...');
+  logScopeDecision(selection);
+
+  const result = await refreshBaseline(
+    buildRefreshOpts({
+      ...selection,
+      absBaselinePath,
+      epsilon: getBaselineEpsilon('duplication', config),
+    }),
+  );
+
   Logger.info(
-    `[Duplication] ✅ Baseline updated (kernelVersion=${envelope.kernelVersion}). Wrote to ${absBaselinePath}.`,
+    `[Duplication] ✅ Baseline updated (kernelVersion=${result.envelope.kernelVersion}, wrote=${result.wrote}, scope=${result.scope.mode}, rows=${result.envelope.rows.length}). Wrote to ${absBaselinePath}.`,
   );
 }
 
-// cli-opt-out: top-level main().catch predates runAsCli; never imported elsewhere so the auto-run risk is moot.
-main().catch((err) => {
-  Logger.error(
-    `[Duplication] ❌ Fatal error: ${err?.stack ?? err?.message ?? err}`,
-  );
-  process.exit(1);
+runAsCli(import.meta.url, main, {
+  source: 'duplication-baseline',
+  usage: USAGE,
+  onError: (err) => {
+    Logger.error(
+      `[Duplication] ❌ Fatal error: ${err?.stack ?? err?.message ?? err}`,
+    );
+    process.exitCode = 1;
+  },
 });

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

@@ -43,10 +43,34 @@ import './lib/runtime-deps/ensure-installed.js';
 import path from 'node:path';
 import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
+import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
 import { getBaselines, resolveConfig } from './lib/config-resolver.js';
 import { Logger } from './lib/Logger.js';
 
+/**
+ * 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.
+ */
+const USAGE = {
+  invocation:
+    'node .agents/scripts/update-maintainability-baseline.js [--full-scope | --diff-scope <ref>]',
+  summary:
+    'Score → write the maintainability baseline. With no scope flag the refresh is scoped to the files changed in `origin/main..HEAD`; out-of-scope rows are preserved verbatim.',
+  flags: [
+    [
+      '--full-scope',
+      'Rescore every file in every target dir (no out-of-scope merge).',
+    ],
+    [
+      '--diff-scope <ref>',
+      'Scope the refresh to files changed between <ref> and HEAD. Incompatible with --full-scope.',
+    ],
+  ],
+};
+
 /**
  * Parse `--full-scope` (boolean opt-out flag).
  *
@@ -119,8 +143,11 @@ async function main() {
   );
 }
 
-// cli-opt-out: top-level main().catch predates runAsCli; never imported elsewhere so the auto-run risk is moot.
-main().catch((err) => {
-  Logger.error(`[Maintainability] ❌ Fatal error: ${err.message}`);
-  process.exit(1);
+runAsCli(import.meta.url, main, {
+  source: 'maintainability-baseline',
+  usage: USAGE,
+  onError: (err) => {
+    Logger.error(`[Maintainability] ❌ Fatal error: ${err.message}`);
+    process.exitCode = 1;
+  },
 });

package/.agents/scripts/validate-docs-freshness.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+/* node:coverage ignore file -- top-level docs-freshness gate shell; the tested logic lives in lib/docs-freshness.js */
 
 /**
  * .agents/scripts/validate-docs-freshness.js — Documentation Freshness Gate

package/.agents/skills/core/diagnose-friction/SKILL.md

@@ -15,6 +15,7 @@ allowed_tools:
 ## Policy Capsule
 
 - Invoke via the wrapping CLI `node .agents/scripts/diagnose-friction.js --story <id> [--epic <id>] --cmd <command args...>`; this is the single supported entry point.
+- `--cmd` takes the command as **separate argv words** — the CLI spawns them with no shell. Quoting the whole command as one string (`--cmd "npm run lint"`) makes the entire string the executable name, so the spawn fails ENOENT. That is a usage error in your own invocation, not friction: the CLI refuses it with a usage message and appends **no** ledger row. Re-run it unquoted.
 - Pass the wrapped command's stdout and stderr through **unchanged** — never reformat, redact, or buffer in a way that loses the original failure shape.
 - Never mutate the wrapped command's exit code. The Skill observes; the caller decides whether the failure is fatal.
 - Operate as **best-effort observation**: a write failure on the signals stream MUST NOT halt the runner. A missing signal is preferable to a stalled wave.
@@ -39,7 +40,9 @@ that want to dispatch via the Skill tool rather than spawn the CLI.
 
 ## Inputs
 
-- `--cmd <command args...>` — the command to invoke and observe.
+- `--cmd <command args...>` — the command to invoke and observe, passed as
+  separate argv words. A single whitespace-containing argument is rejected as
+  a quoting mistake before anything is spawned or recorded.
 - `--story <id>` / `--epic <id>` (optional) — when resolved, the Skill
   appends a `friction` signal to
   `temp/run-<eid>/stories/story-<sid>/signals.ndjson` on non-zero exit