mandrel 2.54.0 → 2.56.0

package/.agents/scripts/lib/orchestration/planning/memory-pool-advisory.js

@@ -34,13 +34,31 @@
  * simply stays silent and only the age arm can speak, until the next pass
  * writes a baseline.
  *
+ * **The index byte arm (Story #5285).** Age and growth both measure the
+ * *pool*; neither measures the one artifact a session actually loads. The
+ * harness reads `MEMORY.md` into every session under a hard byte cap and
+ * **truncates** past it, so an index over that cap loses its tail entries
+ * silently — the pointers are on disk, indexed, and unreachable. That is a
+ * loss in progress, not a hygiene forecast, so this arm is independent of the
+ * other two: it fires on a fresh, zero-growth pool whose index has simply
+ * outgrown the cap. It measures the index file's size, never the pool's, and
+ * a pass that rewrites long index lines short clears it without pruning a
+ * single entry.
+ *
+ * **A future-dated stamp is no stamp.** `lastConsolidatedAt` ahead of `now`
+ * cannot describe a pass that happened — it is a clock skew, a hand-edit, or
+ * a timezone bug. Scored as-is it yields a negative age that silences the age
+ * arm *forever*, which is the loudest possible failure for an advisory whose
+ * only job is to speak up. It reads as unstamped instead, so the
+ * never-consolidated reason fires and the next real pass overwrites it.
+ *
  * Detection is filesystem-only — no child processes, no `gh` probes, no
  * network. Every failure path fails soft to "no pool, no recommendation": the
  * advisory can degrade the nudge, never a plan.
  *
  * Test seams: `cwd`, `env`, `fsImpl` (node:fs-compatible `statSync` /
- * `readdirSync` / `readFileSync`), `now`, and the two thresholds
- * (`staleAfterDays`, `growthDelta`).
+ * `readdirSync` / `readFileSync`), `now`, and the three thresholds
+ * (`staleAfterDays`, `growthDelta`, `indexByteCeiling`).
  *
  * `buildMemoryPoolAdvisory` is the **only** export: the helpers below have no
  * caller outside this module, and exporting one solely for a test would add a
@@ -59,6 +77,16 @@ const STALE_AFTER_DAYS = 30;
 /** Recommend a pass once this many entries were written since the last one. */
 const GROWTH_DELTA = 25;
 
+/**
+ * Recommend a pass once `MEMORY.md` exceeds this many bytes.
+ *
+ * 24576 (24 KiB) is the harness's own index cap — the point past which it
+ * truncates the file it loads into a session, making every entry after the
+ * cut unreachable. The default is the cap itself rather than a margin under
+ * it: the arm reports a loss that has already started, not one approaching.
+ */
+const INDEX_BYTE_CEILING = 24_576;
+
 /** Stamp file written by `/memory-consolidate` after its operator gate. */
 const STAMP_FILENAME = '.consolidation-stamp.json';
 
@@ -109,6 +137,28 @@ function resolveMemoryPoolDir({ cwd, env = process.env, homedir } = {}) {
   );
 }
 
+/**
+ * Run one filesystem probe, falling back on any failure.
+ *
+ * Every read here is fail-soft by design — the advisory may degrade its nudge
+ * but never a plan — so all four probes had the same try/catch shape wrapped
+ * around one expression. One helper states the rule once; a new probe cannot
+ * forget it, and a `catch` that ever needs to do more than fall back would
+ * have to be written out, which is the signal it deserves.
+ *
+ * @template T
+ * @param {() => T} read
+ * @param {T|null} [fallback]
+ * @returns {T|null}
+ */
+function probe(read, fallback = null) {
+  try {
+    return read();
+  } catch {
+    return fallback;
+  }
+}
+
 /**
  * The growth baseline a stamp records: its entry count, or `null` when it
  * records none. `null` is *unmeasured*, never zero — a zero baseline would
@@ -125,8 +175,11 @@ function readBaseline(count) {
  * Read the consolidation stamp.
  *
  * `at` is the ISO timestamp of the last pass, or `null` when there was none:
- * a missing, unreadable, unparseable or date-less stamp is indistinguishable
- * from "never consolidated" — all four mean the same thing to the advisory.
+ * a missing, unreadable, unparseable, date-less or **future-dated** stamp is
+ * indistinguishable from "never consolidated" — all five mean the same thing
+ * to the advisory. A future date is the one that has to be caught here rather
+ * than downstream: it is arithmetically valid, so the age arm would score it
+ * as a negative age and stay silent for as long as the clock stays behind it.
  * A stamp whose date is unusable carries no baseline either, so `baseline`
  * follows it to `null` rather than describing a pass that cannot be dated.
  *
@@ -135,23 +188,40 @@ function readBaseline(count) {
  * only) and on a malformed count, which reads as *unmeasured growth*, never
  * as zero growth: a `0` baseline would score the whole pool as new.
  *
+ * @param {{ poolDir: string, fsImpl: object, now: Date|string|number }} args
  * @returns {{ at: string|null, baseline: number|null }}
  */
-function readStamp({ poolDir, fsImpl }) {
-  const unstamped = { at: null, baseline: null };
-  try {
-    const raw = fsImpl.readFileSync(path.join(poolDir, STAMP_FILENAME), 'utf8');
-    const parsed = JSON.parse(raw);
-    const at = parsed.lastConsolidatedAt;
-    // `Date.parse` rejects the empty string as NaN, so this one test covers
-    // both an absent date and an unusable one.
-    if (typeof at !== 'string' || Number.isNaN(Date.parse(at))) {
-      return unstamped;
-    }
-    return { at, baseline: readBaseline(parsed.entryCount) };
-  } catch {
-    return unstamped;
+function readStamp({ poolDir, fsImpl, now }) {
+  const parsed = probe(() =>
+    JSON.parse(fsImpl.readFileSync(path.join(poolDir, STAMP_FILENAME), 'utf8')),
+  );
+  const at = parsed?.lastConsolidatedAt;
+  // `Date.parse` rejects the empty string as NaN, so one test covers both an
+  // absent date and an unusable one; `> now` covers the future-dated stamp.
+  // Equality is not the future, so a stamp written this instant still counts.
+  const at_ms = typeof at === 'string' ? Date.parse(at) : Number.NaN;
+  if (Number.isNaN(at_ms) || at_ms > new Date(now).getTime()) {
+    return { at: null, baseline: null };
   }
+  return { at, baseline: readBaseline(parsed.entryCount) };
+}
+
+/**
+ * The index file's size in bytes.
+ *
+ * `null` when it cannot be stat'd — an absent or unreadable `MEMORY.md`
+ * leaves the byte arm silent rather than guessing a size, on the same
+ * fail-soft rule every other probe here follows. Stat'd rather than read:
+ * the arm needs the length, never the content, and this module deliberately
+ * never reads a memory's text.
+ *
+ * @returns {number|null}
+ */
+function readIndexBytes({ poolDir, fsImpl }) {
+  const size = probe(
+    () => fsImpl.statSync(path.join(poolDir, INDEX_FILENAME)).size,
+  );
+  return Number.isFinite(size) ? size : null;
 }
 
 /**
@@ -160,13 +230,13 @@ function readStamp({ poolDir, fsImpl }) {
  * @returns {number|null} `null` when the directory cannot be listed
  */
 function countEntries({ poolDir, fsImpl }) {
-  try {
-    return fsImpl
-      .readdirSync(poolDir)
-      .filter((name) => name.endsWith('.md') && name !== INDEX_FILENAME).length;
-  } catch {
-    return null;
-  }
+  return probe(
+    () =>
+      fsImpl
+        .readdirSync(poolDir)
+        .filter((name) => name.endsWith('.md') && name !== INDEX_FILENAME)
+        .length,
+  );
 }
 
 /**
@@ -176,7 +246,8 @@ function countEntries({ poolDir, fsImpl }) {
  * and not others, which is the failure mode a per-branch object literal has.
  *
  * @param {object} fields
- * @returns {{ present: boolean, entryCount: number, lastConsolidatedAt: string|null,
+ * @returns {{ present: boolean, entryCount: number, indexBytes: number|null,
+ *            lastConsolidatedAt: string|null,
  *            entriesSinceConsolidation: number|null, recommend: boolean,
  *            reasons: string[] }}
  */
@@ -184,6 +255,7 @@ function envelope(fields) {
   return {
     present: false,
     entryCount: 0,
+    indexBytes: null,
     lastConsolidatedAt: null,
     entriesSinceConsolidation: null,
     recommend: false,
@@ -197,14 +269,23 @@ function envelope(fields) {
  * the quiet verdict; the caller turns it into `recommend` and supplies the
  * standing-down sentence, so every arm lives in one place.
  *
- * The two arms are independent and both are reported when both fire.
+ * The three arms are independent and every one that fires is reported.
  *
  * @param {{ stamp: { at: string|null, baseline: number|null },
- *           growth: number|null, now: Date|string|number,
- *           staleAfterDays: number, growthDelta: number }} args
+ *           growth: number|null, indexBytes: number|null,
+ *           now: Date|string|number, staleAfterDays: number,
+ *           growthDelta: number, indexByteCeiling: number }} args
  * @returns {string[]}
  */
-function collectReasons({ stamp, growth, now, staleAfterDays, growthDelta }) {
+function collectReasons({
+  stamp,
+  growth,
+  indexBytes,
+  now,
+  staleAfterDays,
+  growthDelta,
+  indexByteCeiling,
+}) {
   const reasons = [];
 
   if (stamp.at === null) {
@@ -229,6 +310,13 @@ function collectReasons({ stamp, growth, now, staleAfterDays, growthDelta }) {
     );
   }
 
+  // `indexBytes === null` is an unreadable index, not a small one.
+  if (indexBytes !== null && indexBytes > indexByteCeiling) {
+    reasons.push(
+      `${INDEX_FILENAME} is ${indexBytes} bytes, ${indexBytes - indexByteCeiling} over the ${indexByteCeiling}-byte index ceiling — the index is truncated at the cap, so every entry listed after the cut is invisible to every session`,
+    );
+  }
+
   return reasons;
 }
 
@@ -241,9 +329,9 @@ function collectReasons({ stamp, growth, now, staleAfterDays, growthDelta }) {
  */
 function quietReason({ growth, growthDelta }) {
   if (growth === null) {
-    return 'memory pool is within the freshness threshold; growth is unmeasured until the next /memory-consolidate stamps an entry count';
+    return 'memory pool is within the freshness and index-size thresholds; growth is unmeasured until the next /memory-consolidate stamps an entry count';
   }
-  return `memory pool is within both thresholds — ${growth} entries written since the last consolidation (under the ${growthDelta}-entry growth delta)`;
+  return `memory pool is within every threshold — ${growth} entries written since the last consolidation (under the ${growthDelta}-entry growth delta)`;
 }
 
 /**
@@ -261,7 +349,9 @@ function quietReason({ growth, growthDelta }) {
  * @param {Date|string|number} [opts.now]
  * @param {number} [opts.staleAfterDays]
  * @param {number} [opts.growthDelta]
- * @returns {{ present: boolean, entryCount: number, lastConsolidatedAt: string|null,
+ * @param {number} [opts.indexByteCeiling]
+ * @returns {{ present: boolean, entryCount: number, indexBytes: number|null,
+ *            lastConsolidatedAt: string|null,
  *            entriesSinceConsolidation: number|null, recommend: boolean,
  *            reasons: string[] }}
  */
@@ -273,6 +363,7 @@ export function buildMemoryPoolAdvisory({
   now = new Date(),
   staleAfterDays = STALE_AFTER_DAYS,
   growthDelta = GROWTH_DELTA,
+  indexByteCeiling = INDEX_BYTE_CEILING,
 } = {}) {
   const absent = (reason) => envelope({ reasons: [reason] });
 
@@ -283,12 +374,7 @@ export function buildMemoryPoolAdvisory({
     );
   }
 
-  let isDir = false;
-  try {
-    isDir = fsImpl.statSync(poolDir).isDirectory();
-  } catch {
-    isDir = false;
-  }
+  const isDir = probe(() => fsImpl.statSync(poolDir).isDirectory(), false);
   if (!isDir) {
     return absent(`no memory pool at ${poolDir} — nothing to consolidate`);
   }
@@ -298,14 +384,16 @@ export function buildMemoryPoolAdvisory({
     return absent(`memory pool at ${poolDir} could not be listed`);
   }
 
-  const stamp = readStamp({ poolDir, fsImpl });
+  const stamp = readStamp({ poolDir, fsImpl, now });
   // Reported raw: a pruning pass can leave this negative, and saying the pool
   // shrank by 7 is more use to the operator than clamping it to zero.
   const growth = stamp.baseline === null ? null : entryCount - stamp.baseline;
+  const indexBytes = readIndexBytes({ poolDir, fsImpl });
 
   const found = {
     present: true,
     entryCount,
+    indexBytes,
     lastConsolidatedAt: stamp.at,
     entriesSinceConsolidation: growth,
   };
@@ -321,9 +409,11 @@ export function buildMemoryPoolAdvisory({
   const reasons = collectReasons({
     stamp,
     growth,
+    indexBytes,
     now,
     staleAfterDays,
     growthDelta,
+    indexByteCeiling,
   });
 
   return envelope({

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -40,6 +40,13 @@ import { resolveStoryDispatchMode } from './complexity-gate.js';
 /** Labels/state that mean a blocker no longer gates its dependents. */
 const DONE_LABEL = 'agent::done';
 
+/**
+ * The lifecycle-label prefix a deliverable Story carries. Any `agent::*` label
+ * will do — the resolver is not a state machine and does not care WHICH state a
+ * Story is in, only that it has been through the step that assigns one.
+ */
+const AGENT_LABEL_PREFIX = 'agent::';
+
 /**
  * Module-private: `toStoryRecord` and `isSatisfiedBlocker` are its only
  * callers. The ancestor exported it with no external consumer, which is how
@@ -64,9 +71,12 @@ function normalizeIssueLabels(issue) {
  *
  * @param {object} issue
  * @param {number} [requestedId] The id the operator asked for, for error text.
+ * @param {{ allowUnlabelled?: boolean }} [options] `allowUnlabelled` waives the
+ *   `agent::*` guard below — the deliberate escape hatch for delivering a Story
+ *   whose state label is absent for a reason the operator knows about.
  * @returns {{ id, title, body, url, labels, state, assignees }}
  */
-export function toStoryRecord(issue, requestedId) {
+export function toStoryRecord(issue, requestedId, { allowUnlabelled } = {}) {
   const id = Number(issue?.number ?? issue?.id ?? requestedId);
   if (!Number.isInteger(id) || id <= 0) {
     throw new Error(
@@ -88,6 +98,9 @@ export function toStoryRecord(issue, requestedId) {
         `v2 is Story-only — re-plan it as a v2 Story or finish it on a pre-v2 checkout.`,
     );
   }
+  // Last, so the two shape refusals above — not a Story at all, and a v1 body —
+  // keep naming their own remedy rather than being masked by a missing label.
+  assertDispatchable(id, labels, allowUnlabelled);
   return {
     id,
     title: String(issue?.title ?? ''),
@@ -106,6 +119,36 @@ export function toStoryRecord(issue, requestedId) {
   };
 }
 
+/**
+ * Refuse a Story that has never been through planning.
+ *
+ * The audit sweep files Stories deliberately WITHOUT an `agent::*` label: their
+ * bodies are audit prose — a symptom and a recommendation — not a scoped change
+ * with acceptance criteria a worker can verify against, and the sweep's runbook
+ * says so. But `/mandrel-deliver` takes ids, and nothing downstream re-checked the
+ * label, so naming a freshly-filed audit Story dispatched a worker at an
+ * unenriched body: the run then either invented its own acceptance criteria or
+ * blocked several minutes in, having taken the Story's lease and flipped it to
+ * `agent::executing` on the way.
+ *
+ * The label is the cheap, honest signal that the enrich step ran — no state
+ * machine is consulted, only that SOME `agent::*` label exists.
+ *
+ * @param {number} id
+ * @param {string[]} labels
+ * @param {boolean} [allowUnlabelled]
+ */
+function assertDispatchable(id, labels, allowUnlabelled) {
+  if (allowUnlabelled) return;
+  if (labels.some((l) => l.startsWith(AGENT_LABEL_PREFIX))) return;
+  throw new Error(
+    `[resolve-stories] Issue #${id} carries no "${AGENT_LABEL_PREFIX}*" label, so it has not been ` +
+      `through planning — an audit sweep files Stories without one on purpose (its runbook's ` +
+      `"Enrich before you deliver" step). Route it through /mandrel-plan first, which applies ` +
+      `agent::ready once the finding is a scoped slice. Pass --allow-unlabelled to deliver it as-is.`,
+  );
+}
+
 /**
  * A blocker stops gating once its issue is closed or carries `agent::done`.
  *

package/.agents/scripts/lib/orchestration/review-providers/native.js

@@ -372,11 +372,25 @@ export async function analyzeChangedFiles(
 /**
  * Pure: turn a lint summary into Finding(s). Lint errors collapse into a
  * single high-risk finding (the structured comment shows the count); lint
- * warnings collapse into a single suggestion. An `executionFailed` summary
- * produces **zero** findings (Story #4699): a runner that could not execute
- * is an operational degradation, not a code finding — the provider routes it
- * to friction telemetry instead so severity counts reflect code findings
- * only.
+ * warnings collapse into a single suggestion.
+ *
+ * **Findings come from the parsed counts, never from the execution flag**
+ * (Story #5282). `executionFailed` is the OR across the biome and markdownlint
+ * surfaces, so gating findings on it let *one* absent runner discard the
+ * *other* surface's real errors — and since the code surface's disk probe
+ * (#5193) degrades in every checkout without `node_modules/.bin/biome`, that
+ * was the default state of a consumer checkout: markdownlint errors reached
+ * neither the findings nor the severity tally while the outcome read clean
+ * apart from a degradation line.
+ *
+ * Story #4699's intent is preserved exactly, because it was never about the
+ * flag: a degradation is still not a `Finding` — it has no counts to report,
+ * so a surface that could not execute contributes `parsed: false` and zero
+ * counts and produces nothing here, while travelling on the degradation and
+ * friction-telemetry channels under its own name. A summary that explicitly
+ * reports `parsed: false` therefore yields no findings whatever its counts
+ * claim; a summary omitting `parsed` (an injected or pre-#4839 shape) is
+ * scored on its counts as before.
  *
  * @param {{ errors: number, warnings: number, parsed?: boolean, skipped?: boolean, mode?: string, executionFailed?: boolean, evidenceSkipped?: boolean }} lintSummary
  * @returns {Finding[]}
@@ -385,7 +399,7 @@ export function buildLintFindings(lintSummary) {
   if (lintSummary.mode === 'off') return [];
   if (lintSummary.evidenceSkipped) return [];
   if (lintSummary.skipped) return [];
-  if (lintSummary.executionFailed) return [];
+  if (lintSummary.parsed === false) return [];
   const findings = [];
   if (lintSummary.errors > 0) {
     findings.push({
@@ -428,6 +442,7 @@ async function runLintPhase({
       mode: 'off',
       executionFailed: false,
       degradations: [],
+      surfaces: [],
     };
   }
   logger?.info?.(
@@ -592,15 +607,19 @@ export function createNativeProvider(deps = {}) {
         // Story #4839 — telemetry alone left the review's own verdict unable to
         // distinguish "lint ran and found nothing" from "lint never ran", so
         // the same degradation is also recorded on the outcome channel. It is
-        // still never a `Finding`: the friction emission below is unchanged and
-        // severity counts remain code-findings-only.
+        // still never a `Finding`: the friction emission below is unchanged.
+        //
+        // Story #5282 — this branch is about the degraded surface only. A
+        // sibling surface that *did* run still contributes its parsed counts
+        // to `buildLintFindings` below, so a degradation here no longer
+        // suppresses the other surface's errors.
         recordedDegradations = buildLintDegradations(lintSummary);
         logger?.warn?.(
           `[native-review] Lint runner could not execute (${recordedDegradations
             .map((d) => `${d.surface}: ${d.reason}`)
             .join(
               '; ',
-            )}) — reported as a degraded gate on the review outcome and recorded as friction telemetry; no finding emitted. Verify with the canonical \`npm run lint\` before merging.`,
+            )}) — reported as a degraded gate on the review outcome and recorded as friction telemetry; the degradation itself is never a finding, and any surface that did run still reports its own errors. Verify with the canonical \`npm run lint\` before merging.`,
         );
         try {
           await emitToolDegradationFn({
@@ -622,8 +641,9 @@ export function createNativeProvider(deps = {}) {
 
       // Canonical ordering: critical (maintainability) first, then high
       // (lint errors), then medium (size/volume warnings), then suggestion
-      // (lint warnings). An execution failure contributes to none of these
-      // tiers — it travels on the degradation channel. The renderer
+      // (lint warnings). An execution failure contributes no counts of its
+      // own to these tiers — it travels on the degradation channel — but it
+      // no longer suppresses a sibling surface's. The renderer
       // re-bucketizes by severity tier, so this order only matters for
       // stability of fixture outputs.
       return [

package/.agents/scripts/lib/orchestration/review-providers/scoped-lint.js

@@ -289,36 +289,38 @@ export function parseLintOutput(result) {
  * one degradation record naming itself. Merging *summaries* rather than raw
  * output is what stops one runner's failure from becoming the other's verdict.
  *
+ * The OR is deliberately lossy — it answers "did any surface fail?", which is
+ * the only question the degradation channel asks. Story #5282 added the
+ * `surfaces[]` rows so a consumer can ask the *other* questions the OR cannot
+ * answer: which surface the merged counts came from, and — via each row's
+ * `parsed` and `executionFailed` — whether an absent biome or a biome run that
+ * simply reported nothing is behind a zero. Consumers that read the flat
+ * counts are unaffected; the rows are additive.
+ *
  * @param {Array<{ surface: string, summary: ReturnType<typeof parseLintOutput> }>} surfaces
  */
 function mergeSurfaceSummaries(surfaces) {
-  let errors = 0;
-  let warnings = 0;
-  let parsed = false;
-  let executionFailed = false;
-  const degradations = [];
-
-  for (const { surface, summary } of surfaces) {
-    errors += summary.errors;
-    warnings += summary.warnings;
-    if (summary.parsed) parsed = true;
-    if (summary.executionFailed) {
-      executionFailed = true;
-      degradations.push({
-        surface,
-        reason: summary.reason ?? DEGRADATION_REASONS.UNPARSEABLE_OUTPUT,
-      });
-    }
-  }
+  const rows = surfaces.map(({ surface, summary }) => ({
+    surface,
+    parsed: summary.parsed,
+    errors: summary.errors,
+    warnings: summary.warnings,
+    executionFailed: summary.executionFailed,
+    reason: summary.reason ?? DEGRADATION_REASONS.UNPARSEABLE_OUTPUT,
+  }));
+  const total = (field) => rows.reduce((sum, row) => sum + row[field], 0);
 
   return {
-    errors,
-    warnings,
-    parsed,
-    executionFailed,
+    errors: total('errors'),
+    warnings: total('warnings'),
+    parsed: rows.some((row) => row.parsed),
+    executionFailed: rows.some((row) => row.executionFailed),
     skipped: false,
     mode: 'changed-only',
-    degradations,
+    degradations: rows
+      .filter((row) => row.executionFailed)
+      .map(({ surface, reason }) => ({ surface, reason })),
+    surfaces: rows.map(({ reason, ...row }) => row),
   };
 }
 
@@ -329,7 +331,7 @@ function mergeSurfaceSummaries(surfaces) {
  * @param {string} cwd
  * @param {typeof spawnLintRunner} [runnerFn]
  * @param {{ existsFn?: (p: string) => boolean }} [deps]  Test seam for runner resolution.
- * @returns {{ errors: number, warnings: number, parsed: boolean, skipped: boolean, mode: 'changed-only'|'off', executionFailed: boolean, degradations: Array<{ surface: string, reason: string }> }}
+ * @returns {{ errors: number, warnings: number, parsed: boolean, skipped: boolean, mode: 'changed-only'|'off', executionFailed: boolean, degradations: Array<{ surface: string, reason: string }>, surfaces: Array<{ surface: string, parsed: boolean, errors: number, warnings: number, executionFailed: boolean }> }}
  */
 export function runScopedLint(
   changedFiles,
@@ -348,6 +350,7 @@ export function runScopedLint(
       mode: 'changed-only',
       executionFailed: false,
       degradations: [],
+      surfaces: [],
     };
   }