mandrel 2.56.0 → 2.57.0

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

@@ -24,198 +24,31 @@
  *
  * Output: human-readable text by default; pass `--json` for the raw
  * report envelope.
+ *
+ * **Shell only (Story #5316).** Nothing imports this file, so nothing here is
+ * reachable from a test — which is why every function it used to hold scored
+ * the CRAP formula's untested maximum. Argv parsing, report rendering,
+ * progress logging and the run orchestration now live under
+ * `lib/test-isolate/`, beside the `list-files` / `parse-tap` / `runner`
+ * modules that were always there. Keep this file a shell: anything with a
+ * branch in it belongs next door, where a test can reach it.
  */
 
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runAsCli } from './lib/cli-utils.js';
-import { resolveTestFiles } from './lib/test-isolate/list-files.js';
-import { diagnoseIsolation } from './lib/test-isolate/runner.js';
+import { runTestIsolate } from './lib/test-isolate/run-isolate.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..');
 
-/**
- * @param {string[]} argv
- */
-export function parseIsolateArgv(argv) {
-  const options = {
-    pattern: undefined,
-    workers: undefined,
-    maxBisectDepth: 8,
-    maxBisectTargets: 5,
-    suiteConcurrency: 8,
-    json: false,
-    quiet: false,
-  };
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--workers' && argv[i + 1]) {
-      options.workers = Number(argv[++i]);
-    } else if (arg === '--max-bisect-depth' && argv[i + 1]) {
-      options.maxBisectDepth = Number(argv[++i]);
-    } else if (arg === '--max-bisect-targets' && argv[i + 1]) {
-      options.maxBisectTargets = Number(argv[++i]);
-    } else if (arg === '--suite-concurrency' && argv[i + 1]) {
-      options.suiteConcurrency = Number(argv[++i]);
-    } else if (arg === '--json') {
-      options.json = true;
-    } else if (arg === '--quiet') {
-      options.quiet = true;
-    } else if (!arg.startsWith('--') && !options.pattern) {
-      options.pattern = arg;
-    }
-  }
-  return options;
-}
-
-/**
- * @param {import('./lib/test-isolate/runner.js').IsolateReport} report
- */
-export function renderReport(report) {
-  const lines = [];
-  lines.push('');
-  lines.push('=== test-isolate diagnostic report ===');
-  lines.push(`Files scanned:  ${report.files.length}`);
-  lines.push(`Wall duration:  ${(report.durationMs / 1000).toFixed(1)}s`);
-  lines.push('');
-
-  if (report.flippers.length === 0) {
-    lines.push('✓ No flippers detected — every file that passed alone');
-    lines.push('  also passed in the full suite run.');
-  } else {
-    lines.push(`✗ ${report.flippers.length} flipper(s) detected:`);
-    for (const f of report.flippers) {
-      lines.push(`  - ${f}`);
-    }
-    lines.push('');
-    if (report.bisections.length > 0) {
-      lines.push('Likely polluters (bisection suspects):');
-      for (const b of report.bisections) {
-        const tag = b.inconclusive ? ' [inconclusive]' : '';
-        lines.push(`  ${b.file}${tag}`);
-        for (const s of b.suspects) {
-          lines.push(`    ← ${s}`);
-        }
-      }
-    }
-  }
-
-  lines.push('');
-  if (report.envMutators.length === 0) {
-    lines.push('✓ No env-var leaks detected across isolated runs.');
-  } else {
-    lines.push(
-      `⚠ ${report.envMutators.length} file(s) left process.env mutated:`,
-    );
-    for (const m of report.envMutators) {
-      const parts = [];
-      if (m.envDiff.added.length > 0) {
-        parts.push(`added=[${m.envDiff.added.join(', ')}]`);
-      }
-      if (m.envDiff.removed.length > 0) {
-        parts.push(`removed=[${m.envDiff.removed.join(', ')}]`);
-      }
-      if (m.envDiff.changed.length > 0) {
-        parts.push(`changed=[${m.envDiff.changed.join(', ')}]`);
-      }
-      lines.push(`  ${m.file}`);
-      lines.push(`    ${parts.join(' ')}`);
-    }
-  }
-
-  lines.push('');
-  return lines.join('\n');
-}
-
-/**
- * Programmatic entry — wired up by the CLI and exported for tests.
- *
- * @param {object} [opts]
- * @param {string[]} [opts.argv]
- * @param {string} [opts.repoRoot]
- * @param {(line: string) => void} [opts.onLog]
- * @returns {Promise<{ exitCode: number, report: import('./lib/test-isolate/runner.js').IsolateReport }>}
- */
-export async function runTestIsolate({
-  argv = process.argv.slice(2),
-  repoRoot = ROOT,
-  onLog = (s) => process.stdout.write(`${s}\n`),
-} = {}) {
-  const options = parseIsolateArgv(argv);
-  const files = resolveTestFiles({
-    pattern: options.pattern,
-    repoRoot,
-  });
-  if (files.length === 0) {
-    onLog(
-      `[test-isolate] no test files matched pattern: ${options.pattern ?? '<default>'}`,
-    );
-    return { exitCode: 0, report: emptyReport() };
-  }
-
-  if (!options.quiet) {
-    onLog(`[test-isolate] scanning ${files.length} file(s)...`);
-  }
-  const report = await diagnoseIsolation({
-    repoRoot,
-    files,
-    workers: options.workers,
-    suiteConcurrency: options.suiteConcurrency,
-    maxBisectDepth: options.maxBisectDepth,
-    maxBisectTargets: options.maxBisectTargets,
-    onProgress: options.quiet
-      ? undefined
-      : (stage, payload) => {
-          if (stage === 'isolated:start') {
-            onLog(`[test-isolate] isolated phase: ${payload.count} file(s)`);
-          } else if (stage === 'isolated:done') {
-            onLog('[test-isolate] isolated phase: done');
-          } else if (stage === 'suite:start') {
-            onLog(`[test-isolate] suite phase: ${payload.count} file(s)`);
-          } else if (stage === 'suite:done') {
-            onLog('[test-isolate] suite phase: done');
-          } else if (stage === 'bisect:start') {
-            onLog(`[test-isolate] bisecting flipper: ${payload.target}`);
-          } else if (stage === 'bisect:done') {
-            const list = payload.suspects.slice(0, 3).join(', ');
-            const more =
-              payload.suspects.length > 3
-                ? ` (+${payload.suspects.length - 3} more)`
-                : '';
-            onLog(`[test-isolate]   suspects: ${list}${more}`);
-          }
-        },
-  });
-
-  if (options.json) {
-    onLog(JSON.stringify(report, null, 2));
-  } else {
-    onLog(renderReport(report));
-  }
-
-  const exitCode =
-    report.flippers.length === 0 && report.envMutators.length === 0 ? 0 : 1;
-  return { exitCode, report };
-}
-
-function emptyReport() {
-  return {
-    pattern: null,
-    files: [],
-    isolated: [],
-    suite: [],
-    flippers: [],
-    bisections: [],
-    envMutators: [],
-    durationMs: 0,
-  };
-}
-
 runAsCli(
   import.meta.url,
   async () => {
-    const { exitCode } = await runTestIsolate();
+    const { exitCode } = await runTestIsolate({
+      argv: process.argv.slice(2),
+      repoRoot: ROOT,
+    });
     if (exitCode !== 0) process.exit(exitCode);
   },
   { source: 'test-isolate' },

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

@@ -19,7 +19,10 @@
 
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
+import {
+  buildCoverageUpdaterScorer,
+  resolveCoverageUpdaterScope,
+} from './lib/baselines/coverage-updater-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
@@ -57,90 +60,42 @@ const USAGE = {
   ],
 };
 
+/** CommonJS `require`, for the `.c8rc.cjs` scope config below. */
 const require = createRequire(import.meta.url);
 
+/**
+ * Load the c8 include/exclude scope. Kept in the CLI rather than the extracted
+ * scorer because it is the one genuinely environment-bound step — a CJS
+ * `require` of a config file resolved against the working tree — and the
+ * scorer takes it as a seam so a test never touches the real `.c8rc.cjs`.
+ */
 function loadC8Scope(cwd) {
   return require(path.resolve(cwd, '.c8rc.cjs'));
 }
 
-function parseFullScopeFlag(argv = []) {
-  return argv.includes('--full-scope');
-}
-
 function main() {
-  const argv = process.argv.slice(2);
-  const diffScopeRef = parseDiffScopeFlag(argv);
-  const fullScope = parseFullScopeFlag(argv);
   const cwd = process.cwd();
+  const { fullScope, diffScopeRef } = resolveCoverageUpdaterScope(
+    process.argv.slice(2),
+  );
   Logger.info('[Coverage] Updating baseline from coverage-final.json...');
 
-  if (fullScope && diffScopeRef !== null) {
-    throw new Error(
-      '[Coverage] --full-scope is incompatible with --diff-scope; pick one',
-    );
-  }
-
-  // Build the per-kind scorer the service will invoke. The scorer receives
-  // `(files, { fullScope })` and returns rows in the `{path, lines,
-  // branches, functions}` shape the writer expects.
-  const scorer = (files, opts) => {
-    const effectiveCwd = opts?.cwd ?? cwd;
-    let raw;
-    try {
-      raw = readCoverageFinal(effectiveCwd);
-    } catch (err) {
-      Logger.error(`[Coverage] ❌ ${err.message}`);
-      return [];
-    }
-
-    const c8Config = loadC8Scope(effectiveCwd);
-    const c8Scope = buildScopePredicate({
-      include: c8Config.include ?? [],
-      exclude: c8Config.exclude ?? [],
-    });
-    const scores = scoreCoverageFinal({
-      raw,
-      cwd: effectiveCwd,
-      scope: c8Scope,
-    });
-
-    // In diff mode, further narrow to the service-resolved in-scope file list.
-    const inScope =
-      !opts?.fullScope && Array.isArray(files) && files.length > 0
-        ? new Set(files)
-        : null;
-
-    const rows = Object.entries(scores)
-      .filter(([relPath]) => inScope === null || inScope.has(relPath))
-      .map(([relPath, score]) => ({
-        path: relPath,
-        lines: score?.lines ?? 0,
-        branches: score?.branches ?? 0,
-        functions: score?.functions ?? 0,
-      }));
-
-    const fileCount = Object.keys(scores).length;
-    Logger.info(
-      `[Coverage] Scored ${fileCount} file(s)${inScope ? ` (${rows.length} in scope)` : ''}.`,
-    );
-    return rows;
-  };
-
   const absBaselinePath = path.resolve(cwd, COVERAGE_BASELINE_PATH);
-  const epsilon = getBaselineEpsilon('coverage', null);
   const refreshOpts = {
     kind: 'coverage',
     writePath: absBaselinePath,
-    epsilon,
-    scorer,
+    epsilon: getBaselineEpsilon('coverage', null),
+    scorer: buildCoverageUpdaterScorer(cwd, {
+      readCoverage: readCoverageFinal,
+      loadScope: loadC8Scope,
+      buildScope: buildScopePredicate,
+      score: scoreCoverageFinal,
+    }),
   };
-  if (fullScope) {
-    refreshOpts.fullScope = true;
-  } else if (diffScopeRef) {
-    refreshOpts.baseRef = diffScopeRef;
-  }
-  // No flag → scopeFiles=null + fullScope=false → service derives the diff
-  // via `origin/main..HEAD` (its default baseRef/headRef).
+  // No flag -> scopeFiles=null + fullScope=false -> the service derives the
+  // diff via `origin/main..HEAD` (its default baseRef/headRef).
+  if (fullScope) refreshOpts.fullScope = true;
+  else if (diffScopeRef) refreshOpts.baseRef = diffScopeRef;
 
   return refreshBaseline(refreshOpts).then((result) => {
     Logger.info(

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

@@ -2,8 +2,11 @@
 // 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 path from 'node:path';
-import { parseDiffScopeFlag } from './lib/baselines/diff-scope-cli.js';
+import {
+  buildCrapUpdaterScorer,
+  parseCrapUpdaterArgs,
+  resolveCrapUpdaterOptions,
+} from './lib/baselines/crap-updater-cli.js';
 import { refreshBaseline } from './lib/baselines/refresh-service.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { getBaselineEpsilon } from './lib/config/quality.js';
@@ -14,10 +17,8 @@ import {
 } from './lib/config-resolver.js';
 import { loadCoverage } from './lib/coverage-utils.js';
 import {
-  checkResolutionFloor,
   resolveEscomplexVersion,
   resolveTsTranspilerVersion,
-  scanAndScore,
 } from './lib/crap-utils.js';
 
 import { Logger } from './lib/Logger.js';
@@ -79,139 +80,34 @@ const USAGE = {
   ],
 };
 
-function parseCliArgs(argv = process.argv.slice(2)) {
-  const out = {
-    baselinePath: undefined,
-    coveragePath: undefined,
-    fullScope: false,
-    diffScopeRef: null,
-  };
-  for (let i = 0; i < argv.length; i += 1) {
-    if (argv[i] === '--baseline' && argv[i + 1]) {
-      out.baselinePath = argv[i + 1];
-      i += 1;
-    } else if (argv[i] === '--coverage' && argv[i + 1]) {
-      out.coveragePath = argv[i + 1];
-      i += 1;
-    } else if (argv[i] === '--full-scope') {
-      out.fullScope = true;
-    }
-  }
-  out.diffScopeRef = parseDiffScopeFlag(argv);
-  return out;
-}
-
 async function main() {
-  const args = parseCliArgs();
   const config = resolveConfig();
-  const crap = getQuality(config).crap;
-  const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
-  const requireCoverage = crap.requireCoverage !== false;
-  const minMethodResolutionRate = crap.minMethodResolutionRate ?? 0.75;
-  const coveragePath =
-    args.coveragePath ?? crap.coveragePath ?? 'coverage/coverage-final.json';
-  const baselinePath = args.baselinePath ?? getBaselines(config).crap.path;
-  const ignoreGlobs = Array.isArray(crap.ignoreGlobs) ? crap.ignoreGlobs : [];
+  const options = resolveCrapUpdaterOptions(
+    parseCrapUpdaterArgs(process.argv.slice(2)),
+    { crap: getQuality(config).crap, baselines: getBaselines(config) },
+  );
 
   Logger.info('[CRAP] Updating baseline...');
-  Logger.info(`[CRAP] Target dirs: ${targetDirs.join(', ')}`);
+  Logger.info(`[CRAP] Target dirs: ${options.targetDirs.join(', ')}`);
   Logger.info(
-    `[CRAP] Coverage source: ${coveragePath}${requireCoverage ? ' (required)' : ' (optional)'}`,
+    `[CRAP] Coverage source: ${options.coveragePath}${options.requireCoverage ? ' (required)' : ' (optional)'}`,
   );
 
-  const absBaselinePath = path.isAbsolute(baselinePath)
-    ? baselinePath
-    : path.resolve(process.cwd(), baselinePath);
-
-  if (args.fullScope && args.diffScopeRef !== null) {
-    throw new Error(
-      '[CRAP] --full-scope is incompatible with --diff-scope; pick one',
-    );
-  }
-
-  // Build the per-kind scorer the service will invoke. The scorer receives
-  // `(files, { fullScope, cwd })`:
-  //   - fullScope === true:  walk all target dirs; scopeFiles=null passed to scanAndScore.
-  //   - fullScope === false: score only the diff-derived in-scope files.
-  const scorer = async (files, opts) => {
-    const effectiveCwd = opts?.cwd ?? process.cwd();
-    const coverageAbs = path.isAbsolute(coveragePath)
-      ? coveragePath
-      : path.resolve(effectiveCwd, coveragePath);
-    const coverage = loadCoverage(coverageAbs);
-    if (!coverage && requireCoverage) {
-      Logger.warn(
-        `[CRAP] ⚠ No coverage artifact at ${coveragePath}. All files will be skipped under requireCoverage=true.`,
-      );
-      Logger.warn(
-        "[CRAP] ⚠ Run 'npm run test:coverage' before 'npm run crap:update'.",
-      );
-      return [];
-    }
-    const scopeFiles = opts?.fullScope ? null : (files ?? null);
-    const {
-      rows,
-      scannedFiles,
-      skippedFilesNoCoverage,
-      skippedMethodsNoCoverage,
-      resolution,
-    } = await scanAndScore({
-      targetDirs,
-      coverage,
-      requireCoverage,
-      cwd: effectiveCwd,
-      ignoreGlobs,
-      scopeFiles,
-    });
-
-    Logger.info(`[CRAP] Scanned ${scannedFiles} file(s).`);
-    if (skippedFilesNoCoverage > 0) {
-      Logger.info(
-        `[CRAP] Skipped ${skippedFilesNoCoverage} file(s) without coverage entries.`,
-      );
-    }
-    if (skippedMethodsNoCoverage > 0) {
-      Logger.info(
-        `[CRAP] Skipped ${skippedMethodsNoCoverage} method(s) whose per-method coverage was unresolved.`,
-      );
-    }
-    if (resolution) {
-      Logger.info(
-        `[CRAP] Method resolution: ${resolution.resolvedMethods}/${resolution.joinableMethods} ` +
-          `(${(resolution.rate * 100).toFixed(1)}%) in files with coverage.`,
-      );
-    }
-    // Fail closed BEFORE the service persists anything — a thin baseline is
-    // never written and then apologised for.
-    const refusal = checkResolutionFloor(resolution, minMethodResolutionRate);
-    if (refusal) throw new Error(refusal);
-
-    return (rows ?? []).filter(
-      (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),
-    );
-  };
-
-  const epsilon = getBaselineEpsilon('crap', config);
   const refreshOpts = {
     kind: 'crap',
-    writePath: absBaselinePath,
-    epsilon,
-    scorer,
+    writePath: options.absBaselinePath,
+    epsilon: getBaselineEpsilon('crap', config),
+    scorer: buildCrapUpdaterScorer(options, { loadCoverage }),
   };
-  if (args.fullScope) {
-    refreshOpts.fullScope = true;
-  } else if (args.diffScopeRef) {
-    refreshOpts.baseRef = args.diffScopeRef;
-  }
-  // No flag → scopeFiles=null + fullScope=false → service derives the diff
-  // via `origin/main..HEAD` (its default baseRef/headRef).
+  // No flag -> scopeFiles=null + fullScope=false -> the service derives the
+  // diff via `origin/main..HEAD` (its default baseRef/headRef).
+  if (options.fullScope) refreshOpts.fullScope = true;
+  else if (options.diffScopeRef) refreshOpts.baseRef = options.diffScopeRef;
 
   const result = await refreshBaseline(refreshOpts);
 
-  const escomplexVersion = resolveEscomplexVersion();
-  const tsTranspilerVersion = resolveTsTranspilerVersion();
   Logger.info(
-    `[CRAP] ✅ Baseline updated (kernelVersion=${result.envelope.kernelVersion}, escomplexVersion=${escomplexVersion}, tsTranspilerVersion=${tsTranspilerVersion}). Wrote to ${absBaselinePath}.`,
+    `[CRAP] ✅ Baseline updated (kernelVersion=${result.envelope.kernelVersion}, escomplexVersion=${resolveEscomplexVersion()}, tsTranspilerVersion=${resolveTsTranspilerVersion()}). Wrote to ${options.absBaselinePath}.`,
   );
   Logger.info(
     `[CRAP] Wrote ${result.envelope.rows.length} row(s). scope=${result.scope.mode}, wrote=${result.wrote}.`,

package/.agents/skills/core/scope-triage/SKILL.md

@@ -15,10 +15,10 @@ description:
   is a single path that emits **one Story by default**.
 - This skill is an optional **split advisory**: should the author keep one
   Story, or does the seed clear the default-single split policy?
-- Anchor sizing judgment to `DEFAULT_MODEL_CAPACITY` and
-  `DELIVERABLE_GRANULARITY_GUIDANCE` in
+- Anchor sizing judgment to `DELIVERABLE_GRANULARITY_GUIDANCE` in
   [`ticket-validator-sizing.js`](../../../scripts/lib/orchestration/ticket-validator-sizing.js).
-  Do not restate numeric thresholds.
+  There is no numeric threshold to restate — Story #5312 deleted the
+  plan-time capacity ceilings.
 - Lead with **cohesion**: one Story is one coherent change with one reason
   to exist. Coupled work stays one Story and uses `## Slicing` for
   intra-session checkpoints.

package/.agents/workflows/audit-clean-code.md

@@ -46,7 +46,8 @@ run the tools first.
    `check-baselines.js` gate enforces. Treat any per-file MI drop beyond
    `delivery.quality.gates.maintainability.tolerance` (default 0.5pt) as a
    grounded must-fix finding, and any cyclomatic reading over the
-   `codingGuardrails` ceilings (flag > 8, must-fix > 12) as measured, not
+   `codingGuardrails.cyclomaticFlag` (> 8) or the fixed ratchet ceiling
+   (≥ 12, reported by `quality:preview` as an advisory) as measured, not
    guessed.
 
 2. **Committed baselines (codebase-wide mode).** Read the committed metric
@@ -98,8 +99,8 @@ Analyze the repository with a focus on:
   from
   [`helpers/code-quality-guardrails.md`](helpers/code-quality-guardrails.md):
   cyclomatic complexity > 8 (`delivery.quality.codingGuardrails.cyclomaticFlag`)
-  is **flag in review** (annotate or split); > 12
-  (`codingGuardrails.cyclomaticMustFix`) is **must-fix** before the work merges.
+  is **flag in review** (annotate or split); ≥ 12 is the fixed ratchet
+  ceiling `check-cyclomatic.js` enforces on new breaches.
   A per-file MI drop beyond the configured
   `delivery.quality.gates.maintainability.tolerance` (default 0.5pt) requires
   a refactor in the same Story rather than a baseline bump.