mandrel 1.62.0 → 1.63.0

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

@@ -4,7 +4,7 @@ import { loadCoverage as defaultLoadCoverage } from '../../../coverage-utils.js'
 import { calculateCrapForSource } from '../../../crap-engine.js';
 import { formatNumber } from './_bullet-format.js';
 import {
-  createSnapshotStore,
+  createDriftDetector,
   walkComponentRegressions,
 } from './component-drift.js';
 
@@ -117,16 +117,7 @@ export function createCrapDriftDetector(opts = {}) {
   const ceiling = Number.isFinite(opts.ceiling)
     ? opts.ceiling
     : DEFAULT_CEILING;
-  const baselineDir = opts.baselineDir ?? '.agents/state';
-  const baselinePath = path.join(cwd, baselineDir, BASELINE_FILENAME);
   const logger = opts.logger ?? null;
-  const store = createSnapshotStore({
-    fs,
-    baselinePath,
-    metadata: { ceiling, threshold },
-  });
-
-  let baseline = null;
 
   function methodKey(method, startLine) {
     return `${method}@${startLine}`;
@@ -187,46 +178,33 @@ export function createCrapDriftDetector(opts = {}) {
     }
   }
 
-  return {
-    get baselinePath() {
-      return baselinePath;
-    },
-
-    captureBaseline() {
-      const coverageMap = readCoverageMap();
-      const snapshot = {};
-      for (const f of files) {
-        const methods = scoreFile(f, coverageMap);
-        if (!methods) continue;
-        snapshot[f] = {};
-        for (const [key, row] of Object.entries(methods)) {
-          snapshot[f][key] = row.crap;
-        }
+  return createDriftDetector({
+    fs,
+    cwd,
+    files: opts.files,
+    baselineDir: opts.baselineDir,
+    baselineFilename: BASELINE_FILENAME,
+    metadata: { ceiling, threshold },
+    beforeScore: readCoverageMap,
+    scoreFile,
+    captureScore: (methods) => {
+      const persisted = {};
+      for (const [key, row] of Object.entries(methods)) {
+        persisted[key] = row.crap;
       }
-      baseline = snapshot;
-      store.persist(snapshot);
-      return snapshot;
-    },
-
-    loadBaseline() {
-      baseline = store.load();
-      return baseline;
+      return persisted;
     },
-
-    async detect() {
-      if (!baseline) return [];
-      const coverageMap = readCoverageMap();
+    async detect({ baseline, scoreFile: score }) {
       const bullets = [];
-      const base = baseline;
       // Union of files watched and files present in baseline, so methods that
       // appeared since the snapshot (new files) are still checked, and methods
       // that disappeared from baseline-only files don't get us stuck iterating
       // anything spurious.
-      const fileSet = new Set([...files, ...Object.keys(base)]);
+      const fileSet = new Set([...files, ...Object.keys(baseline)]);
       for (const relPath of fileSet) {
-        const currentMethods = scoreFile(relPath, coverageMap);
+        const currentMethods = score(relPath);
         if (!currentMethods) continue;
-        const fileBaseline = base[relPath] ?? {};
+        const fileBaseline = baseline[relPath] ?? {};
         for (const [key, row] of Object.entries(currentMethods)) {
           const prev = fileBaseline[key];
           const crossed =
@@ -245,5 +223,5 @@ export function createCrapDriftDetector(opts = {}) {
       }
       return bullets;
     },
-  };
+  });
 }

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

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { calculateForSource } from '../../../maintainability-engine.js';
 import { formatNumber } from './_bullet-format.js';
 import {
-  createSnapshotStore,
+  createDriftDetector,
   walkComponentRegressions,
 } from './component-drift.js';
 
@@ -75,16 +75,10 @@ export function detectComponentRegressions(params = {}) {
 export function createMaintainabilityDriftDetector(opts = {}) {
   const fs = opts.fs ?? nodeFs;
   const cwd = opts.cwd ?? process.cwd();
-  const files = Array.isArray(opts.files) ? [...opts.files] : [];
   const calculate = opts.calculate ?? calculateForSource;
   const threshold = Number.isFinite(opts.threshold)
     ? opts.threshold
     : DEFAULT_THRESHOLD;
-  const baselineDir = opts.baselineDir ?? '.agents/state';
-  const baselinePath = path.join(cwd, baselineDir, BASELINE_FILENAME);
-  const store = createSnapshotStore({ fs, baselinePath });
-
-  let baseline = null;
 
   function scoreFile(relPath) {
     try {
@@ -97,32 +91,18 @@ export function createMaintainabilityDriftDetector(opts = {}) {
     }
   }
 
-  return {
-    get baselinePath() {
-      return baselinePath;
-    },
-
-    captureBaseline() {
-      const snapshot = {};
-      for (const f of files) {
-        const s = scoreFile(f);
-        if (s != null) snapshot[f] = s;
-      }
-      baseline = snapshot;
-      store.persist(snapshot);
-      return snapshot;
-    },
-
-    loadBaseline() {
-      baseline = store.load();
-      return baseline;
-    },
-
-    async detect() {
-      if (!baseline) return [];
+  return createDriftDetector({
+    fs,
+    cwd,
+    files: opts.files,
+    baselineDir: opts.baselineDir,
+    baselineFilename: BASELINE_FILENAME,
+    scoreFile,
+    captureScore: (score) => score,
+    async detect({ baseline, scoreFile: score }) {
       const bullets = [];
       for (const [relPath, baseScore] of Object.entries(baseline)) {
-        const current = scoreFile(relPath);
+        const current = score(relPath);
         if (current == null) continue;
         const drop = baseScore - current;
         if (drop >= threshold) {
@@ -133,5 +113,5 @@ export function createMaintainabilityDriftDetector(opts = {}) {
       }
       return bullets;
     },
-  };
+  });
 }

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

@@ -136,17 +136,57 @@ export function parseLedger(text) {
  *   - Failed: N
  *   - …
  */
-export function render(ledger, opts = {}) {
-  const records = Array.isArray(ledger) ? ledger : parseLedger(ledger);
+/**
+ * Index the ledger records into the two maps `render` needs: the `emitted`
+ * record per seqId and the terminal (`completed`/`failed`) record per seqId.
+ * Story #4075 — extracted from `render` so the orchestrating body stays flat.
+ */
+function indexLedgerRecords(records) {
   const emittedBySeq = new Map();
-  const terminalBySeq = new Map(); // seqId -> 'completed' | 'failed' record
+  const terminalBySeq = new Map();
   for (const rec of records) {
     if (!rec || typeof rec !== 'object') continue;
     if (rec.kind === 'emitted') emittedBySeq.set(rec.seqId, rec);
     else if (rec.kind === 'completed' || rec.kind === 'failed')
       terminalBySeq.set(rec.seqId, rec);
   }
+  return { emittedBySeq, terminalBySeq };
+}
 
+/**
+ * Compute the `(durationMs)` / `(pending)` chunk for one emitted event,
+ * given its terminal record (or undefined when still in flight).
+ */
+export function formatDurationChunk(emit, terminal) {
+  if (!terminal) return '(pending)';
+  const start = new Date(emit.ts).getTime();
+  const end = new Date(terminal.ts).getTime();
+  if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
+    return `(${end - start}ms)`;
+  }
+  return '';
+}
+
+/**
+ * Render a single per-event line for the phase section.
+ */
+function formatEventLine(emit, terminal) {
+  const failedMarker =
+    terminal && terminal.kind === 'failed' ? ' ⚠️ FAILED' : '';
+  const parts = [
+    formatClock(emit.ts),
+    emit.event,
+    formatDurationChunk(emit, terminal),
+    summarizePayload(emit.payload),
+  ].filter(Boolean);
+  return parts.join('  ') + failedMarker;
+}
+
+/**
+ * Group emitted events into ordered phase buckets, each carrying its
+ * rendered per-event lines. Phase order is first-seen by ascending seqId.
+ */
+function buildPhaseLines(emittedBySeq, terminalBySeq) {
   const phaseOrder = [];
   const phaseLines = new Map();
   for (const emit of [...emittedBySeq.values()].sort(
@@ -157,79 +197,76 @@ export function render(ledger, opts = {}) {
       phaseLines.set(phase, []);
       phaseOrder.push(phase);
     }
+    phaseLines
+      .get(phase)
+      .push(formatEventLine(emit, terminalBySeq.get(emit.seqId)));
+  }
+  return { phaseOrder, phaseLines };
+}
+
+/**
+ * Compute the wall-clock span (`maxEnd - minStart`) of a single phase, or
+ * `null` when no finite span can be derived.
+ */
+function computePhaseSpanMs(phase, emittedBySeq, terminalBySeq) {
+  let minStart = Infinity;
+  let maxEnd = -Infinity;
+  for (const emit of emittedBySeq.values()) {
+    if (phaseFor(emit.event) !== phase) continue;
+    const start = new Date(emit.ts).getTime();
+    if (Number.isFinite(start) && start < minStart) minStart = start;
     const terminal = terminalBySeq.get(emit.seqId);
-    let durationMs = '';
     if (terminal) {
-      const start = new Date(emit.ts).getTime();
       const end = new Date(terminal.ts).getTime();
-      if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
-        durationMs = `(${end - start}ms)`;
-      }
-    } else {
-      durationMs = '(pending)';
+      if (Number.isFinite(end) && end > maxEnd) maxEnd = end;
     }
-    const summary = summarizePayload(emit.payload);
-    const failedMarker =
-      terminal && terminal.kind === 'failed' ? ' ⚠️ FAILED' : '';
-    const parts = [
-      formatClock(emit.ts),
-      emit.event,
-      durationMs,
-      summary,
-    ].filter(Boolean);
-    phaseLines.get(phase).push(parts.join('  ') + failedMarker);
   }
+  return Number.isFinite(minStart) && Number.isFinite(maxEnd)
+    ? maxEnd - minStart
+    : null;
+}
 
-  const lines = [];
-  const epicId = opts.epicId ? `epic ${opts.epicId}` : 'epic';
-  lines.push(`# Lifecycle — ${epicId}`);
-  lines.push('');
-  for (const phase of phaseOrder) {
-    lines.push(`## ${phase}`);
-    lines.push('');
-    for (const l of phaseLines.get(phase)) {
-      lines.push(l);
-    }
-    lines.push('');
-  }
-  // Summary block
+/**
+ * Build the trailing `## Summary` block lines.
+ */
+function buildSummaryLines(phaseOrder, emittedBySeq, terminalBySeq) {
   const totalEvents = emittedBySeq.size;
   const failedCount = [...terminalBySeq.values()].filter(
     (r) => r.kind === 'failed',
   ).length;
-  const completedCount = totalEvents - failedCount;
   const phaseDurations = [];
   for (const phase of phaseOrder) {
-    const seqIds = [...emittedBySeq.values()]
-      .filter((e) => phaseFor(e.event) === phase)
-      .map((e) => e.seqId);
-    if (seqIds.length === 0) continue;
-    let minStart = Infinity;
-    let maxEnd = -Infinity;
-    for (const sid of seqIds) {
-      const e = emittedBySeq.get(sid);
-      const t = terminalBySeq.get(sid);
-      const start = new Date(e.ts).getTime();
-      if (Number.isFinite(start) && start < minStart) minStart = start;
-      if (t) {
-        const end = new Date(t.ts).getTime();
-        if (Number.isFinite(end) && end > maxEnd) maxEnd = end;
-      }
-    }
-    if (Number.isFinite(minStart) && Number.isFinite(maxEnd)) {
-      phaseDurations.push(`  - ${phase}: ${maxEnd - minStart}ms`);
-    }
+    const spanMs = computePhaseSpanMs(phase, emittedBySeq, terminalBySeq);
+    if (spanMs !== null) phaseDurations.push(`  - ${phase}: ${spanMs}ms`);
   }
-  lines.push('## Summary');
-  lines.push('');
-  lines.push(`- Events: ${totalEvents}`);
-  lines.push(`- Completed: ${completedCount}`);
-  lines.push(`- Failed: ${failedCount}`);
+  const lines = [
+    '## Summary',
+    '',
+    `- Events: ${totalEvents}`,
+    `- Completed: ${totalEvents - failedCount}`,
+    `- Failed: ${failedCount}`,
+  ];
   if (phaseDurations.length > 0) {
-    lines.push('- Phase durations:');
-    for (const pd of phaseDurations) lines.push(pd);
+    lines.push('- Phase durations:', ...phaseDurations);
   }
   lines.push('');
+  return lines;
+}
+
+export function render(ledger, opts = {}) {
+  const records = Array.isArray(ledger) ? ledger : parseLedger(ledger);
+  const { emittedBySeq, terminalBySeq } = indexLedgerRecords(records);
+  const { phaseOrder, phaseLines } = buildPhaseLines(
+    emittedBySeq,
+    terminalBySeq,
+  );
+
+  const epicId = opts.epicId ? `epic ${opts.epicId}` : 'epic';
+  const lines = [`# Lifecycle — ${epicId}`, ''];
+  for (const phase of phaseOrder) {
+    lines.push(`## ${phase}`, '', ...phaseLines.get(phase), '');
+  }
+  lines.push(...buildSummaryLines(phaseOrder, emittedBySeq, terminalBySeq));
   return lines.join('\n');
 }
 

package/.agents/scripts/lib/orchestration/model-attribution.js

@@ -151,6 +151,76 @@ const VALID_SOURCES = new Set(['sdk-metadata', 'env', 'unknown']);
 const ISO_8601_RE =
   /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
 
+/**
+ * Per-field validators for {@link validateModelAttributionPayload}. Each
+ * returns an array of error strings for its field (empty when the field is
+ * valid), so the top-level validator collapses to a flat-map over the field
+ * list — no per-field branching in the orchestrating body. Story #4075
+ * (CLI-orchestration CC reduction): keeps each validator pure and
+ * single-responsibility.
+ */
+function validateKind(payload) {
+  return payload.kind === MODEL_ATTRIBUTION_TYPE
+    ? []
+    : [`kind must be "${MODEL_ATTRIBUTION_TYPE}"`];
+}
+
+function validateTicketId(payload) {
+  return Number.isInteger(payload.ticketId) && payload.ticketId > 0
+    ? []
+    : ['ticketId must be a positive integer'];
+}
+
+function validateModel(payload) {
+  const { model } = payload;
+  if (!model || typeof model !== 'object' || Array.isArray(model)) {
+    return ['model must be an object'];
+  }
+  const errors = [];
+  if (typeof model.id !== 'string' || model.id.length === 0) {
+    errors.push('model.id must be a non-empty string');
+  }
+  if (
+    model.family !== undefined &&
+    (typeof model.family !== 'string' || model.family.length === 0)
+  ) {
+    errors.push('model.family, when present, must be a non-empty string');
+  }
+  return errors;
+}
+
+function validateSource(payload) {
+  return typeof payload.source === 'string' && VALID_SOURCES.has(payload.source)
+    ? []
+    : [`source must be one of: ${[...VALID_SOURCES].join(', ')}`];
+}
+
+function validateRecordedAt(payload) {
+  return typeof payload.recordedAt === 'string' &&
+    ISO_8601_RE.test(payload.recordedAt)
+    ? []
+    : ['recordedAt must be an ISO-8601 timestamp string'];
+}
+
+function validateSdkMetadata(payload) {
+  const { sdkMetadata } = payload;
+  if (sdkMetadata === undefined) return [];
+  const valid =
+    sdkMetadata !== null &&
+    typeof sdkMetadata === 'object' &&
+    !Array.isArray(sdkMetadata);
+  return valid ? [] : ['sdkMetadata, when present, must be an object'];
+}
+
+const PAYLOAD_FIELD_VALIDATORS = Object.freeze([
+  validateKind,
+  validateTicketId,
+  validateModel,
+  validateSource,
+  validateRecordedAt,
+  validateSdkMetadata,
+]);
+
 /**
  * Hand-rolled validator matching
  * `.agents/schemas/model-attribution.schema.json`. Returns
@@ -168,7 +238,6 @@ const ISO_8601_RE =
  * @returns {{ ok: true } | { ok: false, errors: string[] }}
  */
 export function validateModelAttributionPayload(payload) {
-  const errors = [];
   if (
     payload === null ||
     typeof payload !== 'object' ||
@@ -176,50 +245,9 @@ export function validateModelAttributionPayload(payload) {
   ) {
     return { ok: false, errors: ['payload must be a plain object'] };
   }
-  if (payload.kind !== MODEL_ATTRIBUTION_TYPE) {
-    errors.push(`kind must be "${MODEL_ATTRIBUTION_TYPE}"`);
-  }
-  if (!Number.isInteger(payload.ticketId) || payload.ticketId <= 0) {
-    errors.push('ticketId must be a positive integer');
-  }
-  if (
-    !payload.model ||
-    typeof payload.model !== 'object' ||
-    Array.isArray(payload.model)
-  ) {
-    errors.push('model must be an object');
-  } else {
-    if (typeof payload.model.id !== 'string' || payload.model.id.length === 0) {
-      errors.push('model.id must be a non-empty string');
-    }
-    if (
-      payload.model.family !== undefined &&
-      (typeof payload.model.family !== 'string' ||
-        payload.model.family.length === 0)
-    ) {
-      errors.push('model.family, when present, must be a non-empty string');
-    }
-  }
-  if (
-    typeof payload.source !== 'string' ||
-    !VALID_SOURCES.has(payload.source)
-  ) {
-    errors.push(`source must be one of: ${[...VALID_SOURCES].join(', ')}`);
-  }
-  if (
-    typeof payload.recordedAt !== 'string' ||
-    !ISO_8601_RE.test(payload.recordedAt)
-  ) {
-    errors.push('recordedAt must be an ISO-8601 timestamp string');
-  }
-  if (
-    payload.sdkMetadata !== undefined &&
-    (payload.sdkMetadata === null ||
-      typeof payload.sdkMetadata !== 'object' ||
-      Array.isArray(payload.sdkMetadata))
-  ) {
-    errors.push('sdkMetadata, when present, must be an object');
-  }
+  const errors = PAYLOAD_FIELD_VALIDATORS.flatMap((validate) =>
+    validate(payload),
+  );
   return errors.length ? { ok: false, errors } : { ok: true };
 }
 

package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js

@@ -24,10 +24,102 @@
  *     this value (security-review defaults to `'security'`); when
  *     omitted, `category` is only set when present (codex behavior).
  *
+ * Story #4074 — the parser body was a CC-30 ternary thicket. The
+ * per-field branching now lives in three small, independently-testable
+ * pure helpers (`unwrapEnvelope`, `coerceString`, `buildFinding`), so the
+ * orchestration body collapses to: unwrap → `Array.isArray` guard →
+ * `map(buildFinding).filter(Boolean)`.
+ *
  * @typedef {import('./types.js').Finding}  Finding
  * @typedef {import('./types.js').Severity} Severity
  */
 
+/**
+ * Unwrap up to two layers of envelope around a findings array.
+ *
+ * Accepts a bare array unchanged, an object with a `findings` array, or
+ * either shape nested one level deep under a `result` / `data` key. The
+ * second pass resolves `{ result: { findings: [] } }`-style
+ * double-envelopes. Anything that does not resolve to an array is
+ * returned as-is for the caller's `Array.isArray` guard to reject.
+ *
+ * @param {unknown} parsed
+ * @returns {unknown}
+ */
+export function unwrapEnvelope(parsed) {
+  let value = parsed;
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    if (Array.isArray(value.findings)) value = value.findings;
+    else if (value.result !== undefined) value = value.result;
+    else if (value.data !== undefined) value = value.data;
+  }
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    if (Array.isArray(value.findings)) value = value.findings;
+  }
+  return value;
+}
+
+/**
+ * Coerce a value to a non-empty trimmed string, or null.
+ *
+ * Returns the trimmed string when `value` is a string with
+ * non-whitespace content; otherwise null.
+ *
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function coerceString(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Build a single `Finding` from a raw entry, or null when the entry is
+ * unusable (not an object, or missing a title/body).
+ *
+ * `title` is trimmed; `body` falls back to a non-empty `message` alias
+ * and is preserved verbatim (untrimmed) to match the historical
+ * behavior. `category` is set from the entry when present, else from
+ * `defaultCategory` when supplied. `file` / `line` are included only
+ * when present and well-formed.
+ *
+ * @param {unknown} entry
+ * @param {{
+ *   mapSeverity: (raw: unknown) => Severity,
+ *   defaultCategory?: string,
+ * }} options
+ * @returns {Finding | null}
+ */
+export function buildFinding(entry, { mapSeverity, defaultCategory }) {
+  if (!entry || typeof entry !== 'object') return null;
+
+  const title = coerceString(entry.title);
+  const body = coerceString(entry.body)
+    ? entry.body
+    : coerceString(entry.message)
+      ? entry.message
+      : null;
+  if (!title || !body) return null;
+
+  /** @type {Finding} */
+  const finding = { severity: mapSeverity(entry.severity), title, body };
+
+  const category =
+    typeof entry.category === 'string' && entry.category.length > 0
+      ? entry.category
+      : defaultCategory;
+  if (category !== undefined) finding.category = category;
+
+  if (typeof entry.file === 'string' && entry.file.length > 0) {
+    finding.file = entry.file;
+  }
+  if (Number.isInteger(entry.line) && entry.line > 0) {
+    finding.line = entry.line;
+  }
+  return finding;
+}
+
 /**
  * Parse a provider's raw stdout into `Finding[]`.
  *
@@ -52,54 +144,10 @@ export function parseProviderFindings(rawStdout, options) {
     throw new Error(`${errorPrefix}: ${err?.message ?? err}`);
   }
 
-  // Unwrap a single layer of envelope when present.
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-    else if (parsed.result !== undefined) parsed = parsed.result;
-    else if (parsed.data !== undefined) parsed = parsed.data;
-  }
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-  }
-
-  if (!Array.isArray(parsed)) return [];
+  const unwrapped = unwrapEnvelope(parsed);
+  if (!Array.isArray(unwrapped)) return [];
 
-  /** @type {Finding[]} */
-  const findings = [];
-  for (const entry of parsed) {
-    if (!entry || typeof entry !== 'object') continue;
-    const title =
-      typeof entry.title === 'string' && entry.title.trim().length > 0
-        ? entry.title.trim()
-        : null;
-    const body =
-      typeof entry.body === 'string' && entry.body.trim().length > 0
-        ? entry.body
-        : typeof entry.message === 'string' && entry.message.trim().length > 0
-          ? entry.message
-          : null;
-    if (!title || !body) continue;
-
-    /** @type {Finding} */
-    const finding = {
-      severity: mapSeverity(entry.severity),
-      title,
-      body,
-    };
-    const category =
-      typeof entry.category === 'string' && entry.category.length > 0
-        ? entry.category
-        : defaultCategory;
-    if (category !== undefined) {
-      finding.category = category;
-    }
-    if (typeof entry.file === 'string' && entry.file.length > 0) {
-      finding.file = entry.file;
-    }
-    if (Number.isInteger(entry.line) && entry.line > 0) {
-      finding.line = entry.line;
-    }
-    findings.push(finding);
-  }
-  return findings;
+  return unwrapped
+    .map((entry) => buildFinding(entry, { mapSeverity, defaultCategory }))
+    .filter(Boolean);
 }