mandrel 2.23.0 → 2.25.0

package/.agents/scripts/lib/maintainability-engine.js

@@ -1,25 +1,80 @@
 import fs from 'node:fs';
 import escomplex from 'typhonjs-escomplex';
+import { install as installAstCompat } from './escomplex-ast-compat.js';
 import { transpileIfNeeded } from './transpile.js';
 
 /**
  * Calculates the maintainability score of a JavaScript source file or string.
  * Uses `typhonjs-escomplex` internally, which provides a maintainability index
  * based on the Halstead Volume, Cyclomatic Complexity, and Lines of Code.
+ *
+ * The kernel's code generator predates the Babel AST its own parser emits, so
+ * ordinary modern syntax (`?.`, `await` in a loop head, a regex in a loop
+ * head, object spread in a default parameter) aborts the whole analysis.
+ * `escomplex-ast-compat` repairs that before any scoring runs — see that
+ * module for the defect and the upstream status.
+ */
+installAstCompat();
+
+/**
+ * Sentinel score for a file the kernel cannot analyse.
+ *
+ * A real maintainability index never reaches 0 for runnable code — the
+ * escomplex floor is ~10–20 — so 0 has long been used as an out-of-band
+ * "unscorable" marker. That overload is the bug: consumers drop `mi === 0`
+ * rows, so an unscorable file silently vanishes from the baseline instead of
+ * being reported, and no amount of re-seeding can ever give it a row.
+ *
+ * Deliberately module-private. The numeric return is kept for backwards
+ * compatibility, but the *value* is not something a caller should branch on —
+ * that is the overload this change exists to stop propagating. Callers that
+ * need to tell "unscorable" from "genuinely terrible" read the `unscorable`
+ * flag from {@link scoreSource} / {@link scoreFile}.
+ */
+const UNSCORABLE = 0;
+
+/**
+ * Score a raw string, distinguishing "the kernel could not analyse this" from
+ * "this scored badly".
+ *
+ * @param {string} sourceCode The JavaScript source code.
+ * @returns {{ score: number, unscorable: boolean, reason: string|null }}
+ *   `score` is {@link UNSCORABLE} when `unscorable` is true; `reason` carries
+ *   the kernel's own error message so a consumer can report *why* rather than
+ *   just omitting the file.
+ */
+export function scoreSource(sourceCode) {
+  try {
+    const score = escomplex.analyzeModule(sourceCode)?.maintainability;
+    return Number.isFinite(score)
+      ? { score, unscorable: false, reason: null }
+      : unscorable(`kernel returned a non-finite index (${String(score)})`);
+  } catch (err) {
+    return unscorable(
+      `${err?.constructor?.name ?? 'Error'}: ${err?.message ?? 'unknown kernel failure'}`,
+    );
+  }
+}
+
+/**
+ * @param {string} reason
+ * @returns {{ score: number, unscorable: boolean, reason: string }}
  */
+function unscorable(reason) {
+  return { score: UNSCORABLE, unscorable: true, reason };
+}
+
 /**
  * Calculate score for a raw string of source code.
+ *
+ * Returns 0 for unscorable input, which is ambiguous by construction — see
+ * {@link UNSCORABLE}. Prefer {@link scoreSource} in new code.
+ *
  * @param {string} sourceCode The JavaScript source code.
  * @returns {number} Score between 0 and 171. Higher is better.
  */
 export function calculateForSource(sourceCode) {
-  try {
-    const result = escomplex.analyzeModule(sourceCode);
-    return result.maintainability;
-  } catch (_err) {
-    // Return 0 if the parser fails (e.g. invalid syntax)
-    return 0;
-  }
+  return scoreSource(sourceCode).score;
 }
 
 /**
@@ -34,17 +89,34 @@ export function calculateForSource(sourceCode) {
  *   be parsed (escomplex parse error or TS transpile failure).
  */
 export function calculateForFile(filePath) {
+  return scoreFile(filePath).score;
+}
+
+/**
+ * Score a file, distinguishing "unscorable" from "scored badly".
+ *
+ * The transpile-failure and kernel-failure cases are reported separately
+ * because they need different fixes: a transpile failure is usually the
+ * consumer's own syntax or `tsconfig`, whereas a kernel failure is the
+ * upstream generator gap described in `escomplex-ast-compat.js`.
+ *
+ * @param {string} filePath Path to the JS/TS source file.
+ * @returns {{ score: number, unscorable: boolean, reason: string|null }}
+ */
+export function scoreFile(filePath) {
+  let sourceCode;
   try {
-    const sourceCode = fs.readFileSync(filePath, 'utf-8');
-    const prepared = transpileIfNeeded(filePath, sourceCode);
-    if (prepared === null) return 0;
-    return calculateForSource(prepared);
+    sourceCode = fs.readFileSync(filePath, 'utf-8');
   } catch (err) {
     if (err.code === 'ENOENT') {
       throw new Error(`File not found: ${filePath}`);
     }
     throw err;
   }
+
+  const prepared = transpileIfNeeded(filePath, sourceCode);
+  if (prepared === null) return unscorable('TypeScript transpile failed');
+  return scoreSource(prepared);
 }
 
 /**

package/.agents/scripts/lib/maintainability-unscorable.js

@@ -0,0 +1,60 @@
+/**
+ * maintainability-unscorable.js — reporting for files the MI kernel cannot
+ * analyse.
+ *
+ * A file the kernel throws on has no maintainability index, so it gets no
+ * baseline row — a phantom `mi: 0` would poison the `min`/p50 rollup and let
+ * real regressions hide behind it. Dropping the row is therefore correct; doing
+ * it *silently* is not. Without a report, an unscorable file is
+ * indistinguishable from a file nobody added yet: the scorer emits nothing, the
+ * scope gate sees an absence it cannot explain, and re-seeding the baseline can
+ * never produce the missing row no matter how many times it runs.
+ *
+ * Kept separate from `maintainability-utils.js` so the scoring path stays about
+ * scoring and this stays about explaining.
+ */
+
+import { Logger } from './Logger.js';
+
+/**
+ * Report every unscorable file, then summarise.
+ *
+ * @param {Array<{ relPath: string, unscorable?: boolean, reason?: string|null }>} perFile
+ * @returns {number} how many files were unscorable, for the caller's own use.
+ */
+export function reportUnscorable(perFile) {
+  const unscorable = (perFile ?? []).filter((entry) => entry?.unscorable);
+  if (unscorable.length === 0) return 0;
+
+  for (const { relPath, reason } of unscorable) {
+    Logger.error(
+      `[Maintainability] UNSCORABLE ${relPath}: ${reason ?? 'unknown kernel failure'}`,
+    );
+  }
+  Logger.error(
+    `[Maintainability] ${unscorable.length} file(s) could not be scored and will have ` +
+      'no baseline row, so the maintainability gate cannot see them. If the cause is a ' +
+      'kernel AST gap, add a handler in lib/escomplex-ast-compat.js rather than an ' +
+      'allowlist entry.',
+  );
+  return unscorable.length;
+}
+
+/**
+ * Whether a per-file entry carries a real maintainability index and so belongs
+ * in the baseline.
+ *
+ * An unscorable entry carries the sentinel score, not an index — letting it
+ * through would write an `mi: 0` phantom and drag the rollup floor down with it
+ * (Story #2467). `score === null` is the separate I/O-failure case.
+ *
+ * Tests for a *number* rather than `score !== null`, because the latter passes
+ * anything absent: `undefined !== null` is true, so a missing entry or one with
+ * no `score` key at all would have been treated as scored.
+ *
+ * @param {{ score?: number|null, unscorable?: boolean }} entry
+ * @returns {boolean}
+ */
+export function isScored(entry) {
+  return typeof entry?.score === 'number' && !entry.unscorable;
+}

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

@@ -4,7 +4,8 @@ import { minimatch } from 'minimatch';
 import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
 import { POOL_SERIAL_THRESHOLD, runOnPool } from './cpu-pool.js';
 import { Logger } from './Logger.js';
-import { calculateForFile } from './maintainability-engine.js';
+import { scoreFile } from './maintainability-engine.js';
+import { isScored, reportUnscorable } from './maintainability-unscorable.js';
 
 const MAINTAINABILITY_WORKER_URL = new URL(
   './workers/maintainability-worker.js',
@@ -128,6 +129,13 @@ export function scanDirectory(dir, fileList = [], opts = {}) {
  * worker-side per-item failures surface as a `null` score that is
  * filtered out before assembly.
  *
+ * A file the kernel cannot analyse is also dropped — a phantom `mi: 0` row
+ * poisons the rollup — but it is **reported** on the way out, with the
+ * kernel's own error text, and the count is summarised at the end of the run.
+ * Silently omitting these is what let a file sit unmeasured indefinitely: the
+ * scorer emitted no row, so no amount of re-seeding could ever produce one,
+ * and nothing said so.
+ *
  * @param {string[]} paths
  * @returns {Promise<Record<string, number>>}
  */
@@ -142,7 +150,7 @@ export async function calculateAll(paths) {
   if (indexed.length < SERIAL_THRESHOLD) {
     perFile = indexed.map(({ abs, relPath }) => {
       try {
-        return { relPath, score: calculateForFile(abs) };
+        return { relPath, ...scoreFile(abs) };
       } catch (err) {
         Logger.error(
           `[Maintainability] Failed to process ${abs}: ${err.message}`,
@@ -166,7 +174,7 @@ export async function calculateAll(paths) {
       if (r.score === null && r.error) {
         Logger.error(`[Maintainability] Failed to process ${abs}: ${r.error}`);
       }
-      return { relPath, score: r.score };
+      return { relPath, ...r };
     });
   }
 
@@ -174,9 +182,10 @@ export async function calculateAll(paths) {
     a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0,
   );
 
+  reportUnscorable(perFile);
+
   const scores = {};
-  for (const { relPath, score } of perFile) {
-    if (score === null) continue;
+  for (const { relPath, score } of perFile.filter(isScored)) {
     scores[relPath] = score;
   }
   return scores;

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -75,6 +75,14 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
    * reflect code findings only.
    */
   TOOL_DEGRADED: 'tool-degraded',
+  /**
+   * The light delivery path refused a scope — a suitability-gate `ask-operator`
+   * or a blocked diff backstop. Story #4856 added it because neither rejection
+   * emitted anything, so an over-tight ceiling could only reach the framework
+   * as anecdote; the roll-up aggregating these by category is what makes the
+   * ceilings recalibratable from recorded evidence.
+   */
+  LIGHT_SCOPE_REJECTED: 'light-scope-rejected',
 });
 
 /** Cap on free-form reason text copied into a signal's `details`. */

package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js

@@ -17,6 +17,20 @@
  * from the cap enforcement path — a critic that always reports `round: 1`
  * can no longer defeat the bounded-loop guarantee.
  *
+ * ## Reading a verdict is not a round (Story #4874)
+ *
+ * Counting signals made *observation* costly: re-running the gate over an
+ * already-scored verdict — a resumed sub-agent re-reading its own verdict,
+ * an operator re-checking why the loop said `redraft` — appended another
+ * signal and advanced the derived round, so a `redraft` could escalate to
+ * `block` with no work in between. Every appended signal therefore carries
+ * a `details.verdictFingerprint` content-addressing the verdict it scored,
+ * and {@link resolveAcceptanceEvalRound} replays the round already recorded
+ * for that fingerprint instead of minting a new one. A replay is observably
+ * free: the round does not advance and no signal is appended. New work
+ * produces different verdict content, hence a new fingerprint, hence a
+ * genuine round.
+ *
  * ## The three terminal actions
  *
  *   - `proceed`  — every criterion is `met`. The Story may flip to
@@ -39,6 +53,7 @@
  * possible action is `block`.
  */
 
+import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
 import { runArtifactPath, signalsFile } from '../config/temp-paths.js';
@@ -112,7 +127,7 @@ function partitionCriteria(criteria) {
  *   The resolved (already-clamped) redraft ceiling from
  *   `getAcceptanceEval(config).maxRounds`.
  * @param {number} [args.round]
- *   The current round number, derived via `deriveAcceptanceEvalRound`.
+ *   The current round number, derived via `resolveAcceptanceEvalRound`.
  *   Defaults to 1 when absent or invalid.
  * @returns {{
  *   decision: 'proceed' | 'redraft' | 'block',
@@ -172,6 +187,7 @@ export function buildAcceptanceEvalSignal({
   outcome,
   phase = 'implement',
   clusterId = null,
+  verdictFingerprint = null,
 }) {
   return {
     kind: 'acceptance-eval',
@@ -186,6 +202,13 @@ export function buildAcceptanceEvalSignal({
     phase,
     emitter: { tool: 'acceptance-eval.js' },
     details: {
+      // Content address of the verdict this signal scored. The replay guard
+      // in `resolveAcceptanceEvalRound` matches on it, so a re-read of an
+      // already-scored verdict reuses its round instead of minting one.
+      ...(typeof verdictFingerprint === 'string' &&
+      verdictFingerprint.length > 0
+        ? { verdictFingerprint }
+        : {}),
       decision: outcome.decision,
       round: outcome.round,
       cap: outcome.cap,
@@ -201,29 +224,29 @@ export function buildAcceptanceEvalSignal({
 }
 
 /**
- * Derive the current acceptance-eval round for a Story by counting the
- * `acceptance-eval` signals already appended to the Story's
- * `signals.ndjson` (Story #4019). Round = prior-signal count + 1, so the
- * first run reports round 1 and each completed round (which appends one
- * signal via `acceptance-eval.js`) advances the derived round by one.
+ * Read the `acceptance-eval` records already appended to the Story's (or AC
+ * cluster's) `signals.ndjson`, in append order — the prior rounds
+ * {@link resolveAcceptanceEvalRound} counts from (Story #4019).
  *
- * The derivation is restart-safe: the ledger lives on disk, so a subagent
- * that dies mid-loop and restarts still observes every prior round. A
- * missing or malformed ledger degrades to round 1 (no prior rounds), and
- * malformed lines are skipped — observability corruption never wedges the
- * gate.
+ * The read is restart-safe: the ledger lives on disk, so a subagent that
+ * dies mid-loop and restarts still observes every prior round. A missing or
+ * unreadable ledger degrades to "no prior rounds" and malformed lines are
+ * skipped — observability corruption never wedges the gate.
  *
  * @param {object} args
  * @param {number|null} args.epicId   Parent Epic ID, or `null` for a
  *   standalone Story (routes to `<tempRoot>/standalone/stories/...`).
  * @param {number} args.storyId
+ * @param {string|null} [args.clusterId] AC-cluster id (Epic #4475 M4-B).
  * @param {object} [args.config]      Resolved config (tempRoot resolution).
  * @param {(p: string) => string} [args.readFile]  Injectable reader (tests).
  * @param {(eid: number|null, sid: number, config?: object) => string} [args.signalsPathResolver]
  *   Injectable path resolver (tests). Defaults to `signalsFile`.
- * @returns {number} The 1-based current round.
+ * @param {(eid: number, config?: object) => string} [args.epicSignalsPathResolver]
+ *   Injectable epic-stream path resolver (tests).
+ * @returns {object[]} The matching records, oldest first.
  */
-export function deriveAcceptanceEvalRound({
+function readPriorAcceptanceEvalRecords({
   epicId,
   storyId,
   clusterId = null,
@@ -249,10 +272,10 @@ export function deriveAcceptanceEvalRound({
       : readFile(signalsPathResolver(epicId ?? null, storyId, config));
   } catch (_err) {
     // No ledger yet → no prior rounds.
-    return 1;
+    return [];
   }
 
-  let priorRounds = 0;
+  const records = [];
   for (const line of String(text).split('\n')) {
     const trimmed = line.trim();
     if (trimmed === '') continue;
@@ -269,7 +292,77 @@ export function deriveAcceptanceEvalRound({
     } else if (record.storyId !== storyId) {
       continue;
     }
-    priorRounds += 1;
+    records.push(record);
   }
-  return priorRounds + 1;
+  return records;
+}
+
+/**
+ * Content-address a verdict so re-scoring the same verdict is recognisable
+ * as a re-read rather than a new round (Story #4874).
+ *
+ * The fingerprint covers exactly what the decision depends on — the ordered
+ * per-criterion `index` / `criterion` / `verdict` / `evidence` tuples — and
+ * deliberately nothing else: the verdict's self-reported `round`, its
+ * timestamp, and any authoring scratch must not make an unchanged
+ * evaluation look like a new one. Conversely, real rework changes at least
+ * one criterion's verdict or its evidence, so a genuine re-evaluation
+ * always fingerprints differently.
+ *
+ * @param {{ criteria?: Array<object> }} verdict
+ * @returns {string} 16 hex chars of a SHA-256 over the canonical form.
+ */
+export function computeVerdictFingerprint(verdict) {
+  const criteria = Array.isArray(verdict?.criteria) ? verdict.criteria : [];
+  const canonical = criteria.map((c) => [
+    Number.isInteger(c?.index) ? c.index : null,
+    typeof c?.criterion === 'string' ? c.criterion : '',
+    typeof c?.verdict === 'string' ? c.verdict : '',
+    typeof c?.evidence === 'string' ? c.evidence : '',
+  ]);
+  return createHash('sha256')
+    .update(JSON.stringify(canonical))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+/**
+ * Resolve the round a verdict should be scored under, distinguishing a
+ * genuine evaluation from a re-read of an already-scored verdict
+ * (Story #4874). A genuine round is `prior-signal count + 1`, so the first
+ * run reports round 1 and each completed round advances it by one.
+ *
+ * When the ledger already carries an `acceptance-eval` signal whose
+ * `details.verdictFingerprint` matches, this invocation is a **replay**: it
+ * reports that signal's round and tells the caller not to append a second
+ * one, so reading is observably free and cannot escalate a `redraft` into a
+ * `block`. Otherwise it is a genuine round and the counter advances exactly
+ * as the pre-#4874 count-based derivation always did.
+ *
+ * Signals written before this field existed carry no fingerprint; they can
+ * never match, so legacy ledgers keep their count-based behaviour.
+ *
+ * @param {object} args — {@link readPriorAcceptanceEvalRecords}'s arguments
+ *   plus:
+ * @param {string} args.verdictFingerprint
+ * @returns {{ round: number, replay: boolean }}
+ */
+export function resolveAcceptanceEvalRound(args) {
+  const { verdictFingerprint } = args;
+  const records = readPriorAcceptanceEvalRecords(args);
+  const priorIndex =
+    typeof verdictFingerprint === 'string' && verdictFingerprint.length > 0
+      ? records.findIndex(
+          (r) => r?.details?.verdictFingerprint === verdictFingerprint,
+        )
+      : -1;
+  if (priorIndex === -1) {
+    return { round: records.length + 1, replay: false };
+  }
+  const recorded = records[priorIndex]?.details?.round;
+  return {
+    round:
+      Number.isInteger(recorded) && recorded >= 1 ? recorded : priorIndex + 1,
+    replay: true,
+  };
 }