mandrel 1.69.0 → 1.71.0

package/.agents/scripts/lib/bootstrap/quality-bootstrap.js

@@ -242,7 +242,7 @@ export function ensureQualityNpmScripts(ctx) {
  * underneath the project config at read time, so a key whose intended
  * value equals the framework default would be written redundantly — and
  * would then be flagged `[REDUNDANT]` by the sync-agentrc helper on the
- * next /agents-update. Default-aware seeding keeps the two helpers from
+ * next /mandrel-update. Default-aware seeding keeps the two helpers from
  * contradicting each other.
  *
  * Returns `{ merged, addedKeys[] }` so the caller can report exactly

package/.agents/scripts/lib/config/baselines.js

@@ -38,23 +38,3 @@ export function getBaselines(config) {
     maintainability: merge('maintainability'),
   };
 }
-
-/**
- * Legacy entry point retained for backward-compatible imports. Story #1737
- * retired the standalone `baselines.*` block; this helper now translates
- * `{ lint: { path }, ... }` input onto synthetic `gates.<tier>.baselinePath`.
- *
- * @param {object|undefined} userBlock
- */
-export function resolveBaselines(userBlock) {
-  const block = userBlock ?? {};
-  return getBaselines({
-    quality: {
-      gates: {
-        lint: { baselinePath: block.lint?.path },
-        crap: { baselinePath: block.crap?.path },
-        maintainability: { baselinePath: block.maintainability?.path },
-      },
-    },
-  });
-}

package/.agents/scripts/lib/config/defaults.js

@@ -9,7 +9,7 @@
  * (tests/config/full-agentrc-runtime-parity.test.js) keeps the two in
  * lockstep.
  *
- * Story #1995: the `/agents-update` sync helper consults this module
+ * Story #1995: the `/mandrel-update` sync helper consults this module
  * (not the template directly) to decide whether a project value is
  * "just the default" and therefore safe to omit from `.agentrc.json`.
  *

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

@@ -16,7 +16,7 @@
  *      untouched. Operators who want a leaner config can prune the
  *      redundant keys by hand.
  *
- * Outcome: after `/agents-update`, `.agentrc.json` contains only keys
+ * Outcome: after `/mandrel-update`, `.agentrc.json` contains only keys
  * that materially diverge from framework defaults, plus the
  * consumer-identity keys with no sensible framework default (owner,
  * repo, operatorHandle).

package/.agents/scripts/lib/config/temp-paths.js

@@ -56,8 +56,6 @@
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 
-let _resolveConfig;
-
 /**
  * Cache the resolved main-checkout root per spawn cwd so the
  * `git rev-parse` shell-out runs at most once per distinct working
@@ -136,20 +134,6 @@ function anchorTempRoot(tempRoot) {
   return root ? path.join(root, tempRoot) : tempRoot;
 }
 
-/**
- * Lazy import of `resolveConfig` to side-step a circular module graph
- * (`config-resolver.js` re-exports from this directory and importing it
- * eagerly would resolve `temp-paths.js` before `lib/config/limits.js` is
- * ready). The resolver itself caches per-root, so the inner call is cheap.
- */
-async function getResolveConfig() {
-  if (!_resolveConfig) {
-    const mod = await import('../config-resolver.js');
-    _resolveConfig = mod.resolveConfig;
-  }
-  return _resolveConfig;
-}
-
 /**
  * Synchronous tempRoot extraction. Accepts the canonical full resolved
  * config (`{ project, ... }`) and reads `project.paths.tempRoot`.
@@ -172,21 +156,6 @@ export function tempRootFrom(config) {
     : 'temp';
 }
 
-/**
- * Async tempRoot resolver. When the caller cannot pass a config bag, this
- * loads the project's `.agentrc.json` via `resolveConfig` (cached per
- * root). Most `.agents/scripts` consumers should prefer the synchronous
- * variant by threading their already-resolved config through.
- *
- * @param {{ cwd?: string }} [opts]
- * @returns {Promise<string>}
- */
-export async function tempRootAsync(opts) {
-  const resolveConfig = await getResolveConfig();
-  const resolved = resolveConfig({ cwd: opts?.cwd });
-  return tempRootFrom(resolved);
-}
-
 const epicId = (id) => {
   if (!Number.isInteger(id) || id <= 0) {
     throw new Error(

package/.agents/scripts/lib/config-resolver.js

@@ -199,7 +199,7 @@ function applyDefaults(raw) {
     // `#/$defs/qa`). It needs no default-layering — the harness resolver
     // (`resolveQaContract`) owns normalization and required-field
     // enforcement — it only needs to survive the reshape so
-    // `/qa-run-harness` Step 0 can read it off the resolved wrapper.
+    // `/qa-run` Step 0 can read it off the resolved wrapper.
     ...(raw.qa !== undefined ? { qa: raw.qa } : {}),
   };
 }

package/.agents/scripts/lib/crap-utils.js

@@ -13,6 +13,10 @@ import { scanDirectory } from './maintainability-utils.js';
 import { resolveTsTranspilerVersion, transpileIfNeeded } from './transpile.js';
 
 const CRAP_WORKER_URL = new URL('./workers/crap-worker.js', import.meta.url);
+const COMBINED_MI_CRAP_WORKER_URL = new URL(
+  './workers/combined-mi-crap-worker.js',
+  import.meta.url,
+);
 
 // Pool-vs-serial cutover — single-sourced in cpu-pool.js (see the
 // POOL_SERIAL_THRESHOLD docstring for the tuning rationale).
@@ -472,3 +476,280 @@ async function scoreFilesViaPool(queue, coverage) {
     return { item, result: r };
   });
 }
+
+/**
+ * In-process combined scorer: parse `abs` exactly once via `analyzeOnce` and
+ * derive BOTH the module MI score and the per-method CRAP rows. The reference
+ * implementation for the combined worker, used directly below
+ * `SERIAL_THRESHOLD` (matching the serial fast paths of `calculateAll` and
+ * `scanAndScore`).
+ *
+ * Return shape mirrors `combined-mi-crap-worker.js`:
+ *   - `miScore` — `null` on read failure (MI dropped by the host), `0` on
+ *     transpile-null / parse-error (parity with `calculateForFile` /
+ *     `calculateForSource`), otherwise the module maintainability index.
+ *   - `crapRows` — `null` on read/transpile/parse failure (CRAP drops the
+ *     file), `[]` when coverage-skipped, otherwise the scored method rows.
+ *   - `skippedFileNoCoverage` / `skippedMethodsNoCoverage` — CRAP counters.
+ */
+function scoreFileCombinedSerial({ abs, relPath, requireCoverage }, coverage) {
+  const entry = findCoverageEntry(coverage, relPath);
+  let source;
+  try {
+    source = fs.readFileSync(abs, 'utf-8');
+  } catch {
+    return {
+      relPath,
+      miScore: null,
+      skippedFileNoCoverage: false,
+      crapRows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const prepared = transpileIfNeeded(abs, source);
+  if (prepared === null) {
+    return {
+      relPath,
+      miScore: 0,
+      skippedFileNoCoverage: false,
+      crapRows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const {
+    miScore,
+    crapRows: rawCrapRows,
+    parseError,
+  } = analyzeOnce(prepared, entry);
+  if (parseError) {
+    return {
+      relPath,
+      miScore: 0,
+      skippedFileNoCoverage: false,
+      crapRows: null,
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  if (requireCoverage && entry === null) {
+    return {
+      relPath,
+      miScore,
+      skippedFileNoCoverage: true,
+      crapRows: [],
+      skippedMethodsNoCoverage: 0,
+    };
+  }
+  const crapRows = [];
+  let skippedMethodsNoCoverage = 0;
+  for (const mr of rawCrapRows) {
+    if (mr.crap === null || mr.coverage === null) {
+      skippedMethodsNoCoverage += 1;
+      continue;
+    }
+    crapRows.push({
+      method: mr.method,
+      startLine: mr.startLine,
+      cyclomatic: mr.cyclomatic,
+      coverage: mr.coverage,
+      crap: mr.crap,
+    });
+  }
+  return {
+    relPath,
+    miScore,
+    skippedFileNoCoverage: false,
+    crapRows,
+    skippedMethodsNoCoverage,
+  };
+}
+
+async function scoreFilesCombinedViaPool(queue, coverage) {
+  const enrichedQueue = queue.map((item) => ({
+    ...item,
+    coverageEntry: findCoverageEntry(coverage, item.relPath),
+  }));
+  const results = await runOnPool(COMBINED_MI_CRAP_WORKER_URL, enrichedQueue, {
+    workerData: {},
+  });
+  return results.map((r, i) => {
+    const item = queue[i];
+    if (!r || r.__cpuPoolError) {
+      Logger.warn(
+        `[crap-utils] combined worker pool error for ${item.relPath}: ${r?.message ?? 'unknown'}`,
+      );
+      return { item, result: null };
+    }
+    return { item, result: r };
+  });
+}
+
+/**
+ * Combined MI + CRAP single-pass scan. Walks the shared `targetDirs` once (or
+ * reuses `preScannedFiles`), dispatches every file through ONE worker that
+ * calls `analyzeOnce` a single time, and returns BOTH the maintainability
+ * score map and the CRAP scan result.
+ *
+ * This collapses the two independent escomplex passes the full-tree baseline
+ * regenerator used to run (`calculateAll` → maintainability worker, then
+ * `scanAndScore` → CRAP worker) into one parse per file. The outputs are
+ * shaped to be drop-in equivalents of the two passes they replace, so the
+ * downstream envelope projection + writer logic stays byte-identical:
+ *
+ *   - `miScores` — `Record<relPath, number>` keyed exactly as `calculateAll`
+ *     keys its result (`path.relative(cwd, abs)`, POSIX-normalised), with
+ *     read-failure files (`miScore === null`) dropped. Parity target:
+ *     `calculateAll(files)`.
+ *   - `crap` — `{ rows, scannedFiles, skippedFilesNoCoverage,
+ *     skippedMethodsNoCoverage }`, identical in shape and content to
+ *     `scanAndScore({ targetDirs, coverage, ... })`. The rows are
+ *     CRAP-sorted (file → startLine → method) so the result matches
+ *     `scanAndScore` even before the writer re-sorts.
+ *
+ * The `requireCoverage`, `scopeFiles`, `ignoreGlobs`, and `preScannedFiles`
+ * semantics match `scanAndScore` exactly — coverage gating, scope filtering,
+ * and the single-walk reuse path behave the same. Files dropped from CRAP by
+ * the coverage gate STILL contribute their MI score (the MI pass never
+ * required coverage), preserving the two-pass behaviour where MI scores every
+ * file in the target dirs.
+ *
+ * @param {{
+ *   targetDirs: string[],
+ *   coverage: object|null,
+ *   requireCoverage?: boolean,
+ *   cwd?: string,
+ *   scopeFiles?: Set<string>|string[]|null,
+ *   ignoreGlobs?: string[],
+ *   preScannedFiles?: string[]|null,
+ * }} params
+ * @returns {Promise<{
+ *   miScores: Record<string, number>,
+ *   crap: {
+ *     rows: Array<{
+ *       file: string, method: string, startLine: number,
+ *       cyclomatic: number, coverage: number, crap: number,
+ *     }>,
+ *     scannedFiles: number,
+ *     skippedFilesNoCoverage: number,
+ *     skippedMethodsNoCoverage: number,
+ *   },
+ * }>}
+ */
+export async function scanAndScoreCombined({
+  targetDirs,
+  coverage,
+  requireCoverage = true,
+  cwd = process.cwd(),
+  scopeFiles = null,
+  ignoreGlobs = [],
+  preScannedFiles = null,
+}) {
+  if (!Array.isArray(targetDirs)) {
+    throw new TypeError('scanAndScoreCombined: targetDirs must be an array');
+  }
+  const scopeSet =
+    scopeFiles == null
+      ? null
+      : scopeFiles instanceof Set
+        ? scopeFiles
+        : new Set(scopeFiles);
+
+  // Single directory walk (or reuse the caller's pre-walked list), mirroring
+  // scanAndScore so the file discovery is byte-identical between paths.
+  const files = preScannedFiles != null ? [...preScannedFiles] : [];
+  if (preScannedFiles == null) {
+    for (const dir of targetDirs) {
+      const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+      scanDirectory(abs, files, { cwd, ignoreGlobs });
+    }
+  }
+  files.sort();
+
+  // Build the work queue. Each item carries both the canonicalised relPath
+  // (CRAP's key + scope filter, matching scanAndScore) and the raw relPath
+  // (MI's key, matching calculateAll's `path.relative(cwd, p)` shape).
+  const queue = [];
+  for (const abs of files) {
+    const rawRel = path.relative(cwd, abs).replace(/\\/g, '/');
+    const relPath = canonicalisePath(rawRel);
+    if (scopeSet && !scopeSet.has(relPath)) continue;
+    queue.push({ abs, relPath, miRel: rawRel, requireCoverage });
+  }
+  const scannedFiles = queue.length;
+
+  const perFile =
+    queue.length < SERIAL_THRESHOLD
+      ? queue.map((item) => ({
+          item,
+          result: scoreFileCombinedSerial(item, coverage),
+        }))
+      : await scoreFilesCombinedViaPool(queue, coverage);
+
+  // MI assembly — mirror calculateAll: drop read-failure files (miScore
+  // null), key by the raw relative path, then sort ascending so the returned
+  // object is insertion-order-stable.
+  const miEntries = [];
+  // CRAP assembly — mirror scanAndScore: file-level skip counter, drop
+  // read/transpile/parse failures, accumulate method rows.
+  const crapRows = [];
+  let skippedFilesNoCoverage = 0;
+  let skippedMethodsNoCoverage = 0;
+
+  for (const { item, result } of perFile) {
+    if (!result) continue; // unrecoverable per-file failure: drop silently
+
+    // MI side.
+    if (result.miScore !== null) {
+      miEntries.push({ relPath: item.miRel, score: result.miScore });
+    }
+
+    // CRAP side.
+    if (result.skippedFileNoCoverage) {
+      skippedFilesNoCoverage += 1;
+      continue;
+    }
+    if (result.crapRows === null) {
+      if (result.error) {
+        Logger.warn(
+          `[crap-utils] failed to score ${item.relPath}: ${result.error}`,
+        );
+      }
+      continue;
+    }
+    skippedMethodsNoCoverage += result.skippedMethodsNoCoverage ?? 0;
+    for (const mr of result.crapRows) {
+      crapRows.push({
+        file: item.relPath,
+        method: mr.method,
+        startLine: mr.startLine,
+        cyclomatic: mr.cyclomatic,
+        coverage: mr.coverage,
+        crap: mr.crap,
+      });
+    }
+  }
+
+  miEntries.sort((a, b) =>
+    a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0,
+  );
+  const miScores = {};
+  for (const { relPath, score } of miEntries) {
+    miScores[relPath] = score;
+  }
+
+  crapRows.sort((a, b) => {
+    if (a.file !== b.file) return a.file < b.file ? -1 : 1;
+    if (a.startLine !== b.startLine) return a.startLine - b.startLine;
+    if (a.method !== b.method) return a.method < b.method ? -1 : 1;
+    return 0;
+  });
+
+  return {
+    miScores,
+    crap: {
+      rows: crapRows,
+      scannedFiles,
+      skippedFilesNoCoverage,
+      skippedMethodsNoCoverage,
+    },
+  };
+}

package/.agents/scripts/lib/orchestration/dispatch-engine.js

@@ -27,8 +27,6 @@ import { buildManifest } from './manifest-builder.js';
 import { STATE_LABELS } from './ticketing.js';
 
 export const AGENT_DONE_LABEL = STATE_LABELS.DONE;
-export const AGENT_EXECUTING_LABEL = STATE_LABELS.EXECUTING;
-export const AGENT_READY_LABEL = STATE_LABELS.READY;
 
 /* node:coverage ignore next */
 export function ensureBranch(branchName, baseBranch) {

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter/composition.js

@@ -37,20 +37,6 @@ export function escapePipes(s) {
   return String(s).replace(/\|/g, '\\|');
 }
 
-/**
- * Render a millisecond duration as a compact human-readable string. Used
- * in the wave-elapsed header to keep the snapshot tight.
- */
-export function formatElapsed(ms) {
-  const s = Math.max(0, Math.floor(ms / 1000));
-  const h = Math.floor(s / 3600);
-  const m = Math.floor((s % 3600) / 60);
-  const sec = s % 60;
-  if (h) return `${h}h ${m}m`;
-  if (m) return `${m}m ${sec}s`;
-  return `${sec}s`;
-}
-
 /**
  * Derive the high-level state classification for a single ticket. Reads
  * the canonical `agent::*` label set first, then falls back to the GitHub
@@ -69,35 +55,6 @@ export function deriveState(ticket, AGENT_LABELS) {
   return 'unknown';
 }
 
-/**
- * Build the markdown table for the per-poll progress snapshot. Switches
- * between a 3-column (ID / State / Title) and a 4-column (Wave / ID /
- * State / Title) form depending on whether any row carries a wave index —
- * the wider form fires when the reporter has a plan set and is rendering
- * every wave instead of just the current one.
- */
-export function renderProgressTable(rows) {
-  const includeWaveCol = rows.some((r) => Number.isInteger(r.wave));
-  if (includeWaveCol) {
-    return [
-      '| Wave | ID | State | Title |',
-      '|---|---|---|---|',
-      ...rows.map(
-        (r) =>
-          `| ${r.wave + 1} | #${r.id} | ${STATE_EMOJI[r.state] ?? ''} ${r.state} | ${escapePipes(r.title)} |`,
-      ),
-    ].join('\n');
-  }
-  return [
-    '| ID | State | Title |',
-    '|---|---|---|',
-    ...rows.map(
-      (r) =>
-        `| #${r.id} | ${STATE_EMOJI[r.state] ?? ''} ${r.state} | ${escapePipes(r.title)} |`,
-    ),
-  ].join('\n');
-}
-
 /**
  * Declarative descriptor table that drives the Notable bullet block. Each
  * descriptor names a row state, the emoji prefix to render, and the
@@ -196,47 +153,6 @@ export async function renderNotable({ rows, detectors = [], wave, logger }) {
   return items.join('\n');
 }
 
-/**
- * Compose the full per-poll snapshot body. Pure with respect to the
- * supplied state — the caller passes the resolved `rows`, the plan/wave
- * context, the optional aggregated phase-timings block, and the now()
- * clock; the renderer assembles header + table + Notable + phase-timings.
- */
-export async function renderProgressBody({
-  rows,
-  plan,
-  currentWave,
-  epicStartedAt,
-  now,
-  detectors,
-  phaseSummariesBlock,
-  logger,
-}) {
-  const done = rows.filter((r) => r.state === 'done').length;
-  const total = rows.length;
-  const totalWaves = plan?.length ?? currentWave?.totalWaves ?? '?';
-  const currentWaveNum = currentWave
-    ? currentWave.index + 1
-    : (plan?.length ?? '?');
-  const waveLabel = `Wave ${currentWaveNum}/${totalWaves}`;
-  const elapsedSrc = epicStartedAt ?? currentWave?.startedAt ?? null;
-  const elapsed = elapsedSrc
-    ? ` · ${formatElapsed(now() - new Date(elapsedSrc))} elapsed`
-    : '';
-
-  const header = `### 📊 Progress — ${waveLabel} · ${done}/${total} closed${elapsed}`;
-  const table = renderProgressTable(rows);
-  const notable = await renderNotable({
-    rows,
-    detectors,
-    wave: currentWave,
-    logger,
-  });
-  const parts = [header, '', table, '', '**Notable**', notable];
-  if (phaseSummariesBlock) parts.push('', phaseSummariesBlock);
-  return parts.join('\n');
-}
-
 /**
  * Render and upsert the rolled-up `epic-run-progress` comment on the Epic.
  *

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter/signals.js

@@ -67,10 +67,9 @@ export const PHASE_ORDER = [
 ];
 
 /**
- * Emoji prefix per high-level state. Shared between the per-poll table
- * (`composition.renderProgressTable`) and the rolled-up Epic table
- * (`composition.upsertEpicRunProgress`) so operators see the same icon
- * in both surfaces.
+ * Emoji prefix per high-level state. Consumed by the rolled-up Epic table
+ * (`composition.upsertEpicRunProgress`) so operators see a consistent icon
+ * per state across the progress surface.
  */
 export const STATE_EMOJI = {
   done: '✅',

package/.agents/scripts/lib/orchestration/lifecycle/trace-logger.js

@@ -353,7 +353,3 @@ export class TraceLogger {
     });
   }
 }
-
-export function createTraceLogger(opts) {
-  return new TraceLogger(opts);
-}