mandrel 2.25.0 → 2.26.0

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/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

package/.agents/skills/core/gates-and-baselines/SKILL.md

@@ -18,7 +18,7 @@ allowed_tools:
 - **No gate may be skipped.** Failing lint means fix lint, not disable the rule; a failing test means fix the code, not `.skip` or delete the test. Gates are ordered shift-left so cheap checks fail first, and CI failure output is fed back verbatim with the directive to reproduce and fix locally before re-pushing.
 - **Introducing a gate that asserts on pre-existing state** (doc-drift, lint-vocabulary, dependency-cycle, missing-coverage) MUST land green at merge: either advisory-first (report-only until the backlog is burned down) or with the populated baseline committed in the same change that turns the gate on. Never wire a gate into `requiredChecks` that lands red on latent findings nobody authored.
 - **Refresh a baseline only when the change is deliberate** — a rename/move, an operator-approved complexity bump, a signed-off perf delta, an intentional API-surface change. Never refresh to paper over an unintentional regression; fix the regression instead.
-- Run the kind-specific refresh (`npm run crap:update` / `npm run maintainability:update`; dead-exports and lighthouse have no npm script — regenerate the rows and edit `baselines/dead-exports*.json` / `baselines/lighthouse.json` directly) on the **Story branch**, not on `main`.
+- **Pick the refresh that matches why you are refreshing** — the two are different scopes, and the wrong one silently no-ops. `npm run <kind>:update` is **diff-scoped**: it re-scores only files changed in `origin/main..HEAD` and preserves every other row verbatim. That is what you want after changing code. `npm run <kind>:reanchor` is the same script with `--full-scope`: it re-scores every file in every target dir. That is what you want when the baseline is **stale** — a scorer-version bump, a coverage-shape change, accumulated drift — because a diff-scoped run would leave the stale rows exactly as they were and the staleness finding would re-fire. Kinds: `coverage`, `crap`, `maintainability`, `duplication`; dead-exports and lighthouse have no npm script — regenerate the rows and edit `baselines/dead-exports*.json` / `baselines/lighthouse.json` directly. Run either on the **Story branch**, not on `main`.
 - Verify the refresh diff is scoped to the relevant `baselines/<kind>.json` (plus cosmetic `package-lock.json` churn only). If unrelated files appear, STOP — the refresh is contaminated. Stage baseline files **explicitly** (`git add baselines/<kind>.json`); never `git add -A` in a refresh commit.
 - Commit-subject contract: a **Conventional-Commits** subject `chore(baselines): refresh <kind> snapshot for <reason>` — never an ad-hoc leading token like `baseline-refresh:` (commitlint and the planner validator reject it). The body is **mandatory** and non-empty: what changed, why the new floor is correct, and the Story that triggered it.
 - Add the machine-readable trailer `baseline-refresh: true` (git-trailer `Key: value` style) and `Story: #<storyId>` to the body whenever observability classification matters. Never pass `--no-verify`; the `commit-msg` hook (commitlint) MUST run and pass.
@@ -95,18 +95,24 @@ own as the parseable marker for any future reader.)
 
 ### Procedure
 
-| Kind            | Update command                   |
-| --------------- | -------------------------------- |
-| CRAP            | `npm run crap:update`            |
-| Maintainability | `npm run maintainability:update` |
-| Dead-exports    | edit `baselines/dead-exports.json` / `baselines/dead-exports-production.json` (rows are `(file, symbol)`; `check-dead-exports.js --json` prints the current rows) |
-| Lighthouse      | edit `baselines/lighthouse.json`  |
-
-1. **Run the matching update command** on the Story branch (HEAD must already be
-   the Story branch, not `main`).
+| Kind            | After a code change (diff-scoped)  | Stale baseline (full re-anchor)      |
+| --------------- | ---------------------------------- | ------------------------------------ |
+| CRAP            | `npm run crap:update`              | `npm run crap:reanchor`              |
+| Maintainability | `npm run maintainability:update`   | `npm run maintainability:reanchor`   |
+| Coverage        | `npm run coverage:update`          | `npm run coverage:reanchor`          |
+| Duplication     | `npm run duplication:update`       | `npm run duplication:reanchor`       |
+| Dead-exports    | edit `baselines/dead-exports.json` / `baselines/dead-exports-production.json` (rows are `(file, symbol)`; `check-dead-exports.js --json` prints the current rows) | same — no scope flag applies |
+| Lighthouse      | edit `baselines/lighthouse.json`   | same — no scope flag applies         |
+
+1. **Run the matching command for your reason** — left column after a code
+   change, right column for a stale baseline — on the Story branch (HEAD must
+   already be the Story branch, not `main`).
 2. **Verify the diff is scoped** to the relevant `baselines/<kind>.json` (and
    possibly cosmetic `package-lock.json` churn). Unrelated files → STOP, the
-   refresh is contaminated.
+   refresh is contaminated. Judge contamination by **which files** changed, not
+   how many rows moved inside the baseline: a `:reanchor` legitimately rewrites
+   most of its own file, so say in the commit body that the breadth is a
+   re-anchor and not a mass regression.
 3. **Author the commit.** Stage the baseline file(s) explicitly, then commit with
    the Conventional-Commits subject + body trailer above:
 

package/.agents/skills/skills.index.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-07-21T13:53:23.232Z",
+  "generatedAt": "2026-08-02T11:35:53.522Z",
   "generator": "generate-skills-index.js@1",
   "skills": [
     {
@@ -48,7 +48,7 @@
       "category": "core",
       "path": ".agents/skills/core/diagnose-friction/SKILL.md",
       "description": "Wrap a shell command with diagnostic capture. On failure, print static suggestions and append a structured `friction` record to the per-Story signals.ndjson stream. Use whenever a script in the orchestration loop invokes a tool whose failure shape we want the analyzer to attribute.",
-      "policyCapsuleBullets": 8,
+      "policyCapsuleBullets": 9,
       "allowedTools": ["Bash", "Read"],
       "vendor": null
     },