@codyswann/lisa 3.33.8 → 3.35.0

package/plugins/lisa-copilot/rules/reference/automation-runbook-contract.md

@@ -120,6 +120,25 @@ recovery-required   Lost access to the tracker; filed #1812 with the one decisio
 policy-obsolete     No work has reached this queue in 30 days; proposed teardown in #1813.
 ```
 
+### `nothing-needed` states its denominator
+
+A queue-scanning loop that reports nothing is only as trustworthy as the set it looked at, and a
+summary of the form "scanned N items" hides the one thing worth checking: **which lanes N came
+from.** So a `nothing-needed` summary from a queue scanner names the lanes it swept, the count in
+each, and the total open — `Looked in every lane holding work that has not started — Backlog (20),
+Todo (17), Ready (2), Blocked (61) — 100 items checked out of 343 still open.`
+
+This is a measured requirement, not a style preference. One build lane reported 31 consecutive dry
+cycles over a queue holding 61 unswept rows, at least one of them buildable for ~15 hours. Every
+one of the 31 records was honest and every conclusion was false, because the scanner never said
+what its denominator was. **A missing run record is noisy on inspection; a wrong denominator is
+silent forever and looks exactly like a healthy dry queue.** Stating the swept set is what makes
+the second failure mode visible at all.
+
+The build-intake loop enforces this rather than requesting it: `automation-run-record.mjs` refuses
+a `nothing-needed` row for `intake-tickets` unless the call carries a `--denominator` built by
+`scripts/intake-prework-denominator.mjs`.
+
 **No silent exit.** Every run posts its outcome and its one-line summary before stopping —
 including the trivial early terminations (empty queue, nothing eligible, already-claimed) — so
 there is no silent exit for an operator to misread as health. A run that ends without a

package/plugins/lisa-copilot/scripts/automation-run-record.mjs

@@ -11,6 +11,8 @@ import path from "node:path";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
+import { assertDenominatorReported } from "./intake-prework-denominator.mjs";
+
 export const AUTOMATION_RUN_OUTCOMES = [
   "nothing-needed",
   "candidate-proposed",
@@ -33,6 +35,10 @@ export const DEFAULT_AUTOMATION_RUN_HISTORY_MAX_ENTRIES = 50;
  *   readonly run_id: string
  * }} AutomationRunRecord
  *
+ * `refs` above is the AUTHORED contract. A row already on disk whose `refs` is
+ * some other shape is round-tripped as stored rather than coerced — see
+ * {@link preserveStoredRefs}.
+ *
  * @typedef {{
  *   readonly projectRoot?: string
  *   readonly loopId: string
@@ -55,6 +61,15 @@ export const DEFAULT_AUTOMATION_RUN_HISTORY_MAX_ENTRIES = 50;
  * @returns {Promise<{ readonly path: string, readonly record: AutomationRunRecord, readonly records: readonly AutomationRunRecord[], readonly appended: boolean, readonly skippedCorruptLines: number, readonly maxEntries: number }>}
  */
 export async function recordAutomationRun(input) {
+  // Write path only. Stored rows are re-validated on read through
+  // `validateStoredRecord`, and a history written before this contract existed
+  // must stay readable — so the denominator gate lives here, where a NEW row is
+  // minted, and never on the read path.
+  assertDenominatorReported({
+    loopId: input.loopId,
+    outcome: input.outcome,
+    denominator: input.extras?.denominator,
+  });
   const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
   const maxEntries =
     input.maxEntries ??
@@ -74,14 +89,26 @@ export async function recordAutomationRun(input) {
     };
   }
 
-  const nextRecords = [...readResult.records, record].slice(-maxEntries);
+  // Prior rows are carried across as the RAW LINES they were read as, never
+  // re-serialised from the parsed form. Re-serialising is what let an append
+  // rewrite rows it did not author: a stored `refs` shape the writer did not
+  // recognise came back as `[]`, and a row that failed validation came back as
+  // nothing at all (#2682, #2578). Only the row being appended is serialised
+  // here, so an append can no longer be a fleet-wide migration nobody ran.
+  const nextEntries = [
+    ...readResult.entries,
+    { line: JSON.stringify(record), record },
+  ].slice(-maxEntries);
   await mkdir(path.dirname(filePath), { recursive: true });
-  await writeJsonlAtomically(filePath, nextRecords);
+  await writeJsonlAtomically(
+    filePath,
+    nextEntries.map(entry => entry.line)
+  );
 
   return {
     path: filePath,
     record,
-    records: nextRecords,
+    records: nextEntries.flatMap(entry => (entry.record ? [entry.record] : [])),
     appended: true,
     skippedCorruptLines: readResult.skippedCorruptLines,
     maxEntries,
@@ -126,8 +153,12 @@ export function automationRunRecordPath(projectRoot, loopId) {
 }
 
 /**
+ * Read a ledger, keeping every non-blank line verbatim alongside its parsed
+ * form. `records` is the validated view for consumers; `entries` is what the
+ * append path rewrites, so a row this module cannot parse or validate survives
+ * instead of being deleted by the next unrelated append (#2578).
  * @param {string} filePath
- * @returns {Promise<{ readonly records: readonly AutomationRunRecord[], readonly skippedCorruptLines: number }>}
+ * @returns {Promise<{ readonly records: readonly AutomationRunRecord[], readonly entries: readonly { readonly line: string, readonly record?: AutomationRunRecord }[], readonly skippedCorruptLines: number }>}
  */
 export async function readAutomationRunRecords(filePath) {
   let content = "";
@@ -135,12 +166,13 @@ export async function readAutomationRunRecords(filePath) {
     content = await readFile(filePath, "utf8");
   } catch (error) {
     if (error?.code === "ENOENT") {
-      return { records: [], skippedCorruptLines: 0 };
+      return { records: [], entries: [], skippedCorruptLines: 0 };
     }
     throw error;
   }
 
-  const records = [];
+  /** @type {{ readonly line: string, readonly record?: AutomationRunRecord }[]} */
+  const entries = [];
   let skippedCorruptLines = 0;
   for (const line of content.split(/\n/)) {
     if (!line.trim()) {
@@ -148,13 +180,21 @@ export async function readAutomationRunRecords(filePath) {
     }
     try {
       const parsed = JSON.parse(line);
-      records.push(validateStoredRecord(parsed));
+      entries.push({ line, record: validateStoredRecord(parsed) });
     } catch {
+      // Kept, not dropped. The caller rewrites the file from `entries`, so a
+      // row omitted here would be DELETED from disk by the next unrelated
+      // append (#2578). It stays exactly as read; only `records` excludes it.
+      entries.push({ line });
       skippedCorruptLines += 1;
     }
   }
 
-  return { records, skippedCorruptLines };
+  return {
+    records: entries.flatMap(entry => (entry.record ? [entry.record] : [])),
+    entries,
+    skippedCorruptLines,
+  };
 }
 
 /**
@@ -162,12 +202,58 @@ export async function readAutomationRunRecords(filePath) {
  * @returns {AutomationRunRecord}
  */
 function buildAutomationRunRecord(input) {
+  return assembleAutomationRunRecord(input, normalizeAuthoredRefs(input.refs));
+}
+
+/**
+ * `refs` as an author supplied it.
+ *
+ * A shape this module cannot store as written is REJECTED, not quietly
+ * emptied. Coercing to `[]` is how a caller could record a run whose evidence
+ * links were dropped while the write still reported success (#2682).
+ *
+ * @param {unknown} refs
+ * @returns {readonly string[]}
+ */
+function normalizeAuthoredRefs(refs) {
+  if (refs === undefined || refs === null) {
+    return [];
+  }
+  if (!Array.isArray(refs)) {
+    throw new Error(
+      `Automation run refs must be an array of strings; received ${typeof refs}.`
+    );
+  }
+  return refs.map(ref => String(ref));
+}
+
+/**
+ * `refs` as it was stored, round-tripped rather than coerced.
+ *
+ * A stored shape this module does not recognise — the object form
+ * `{tickets, prs, commits}` observed in the field — is returned unchanged.
+ * Coercing it to `[]` here destroyed the evidence links on every prior row at
+ * the next append: silently, retroactively, and irreversibly (#2682).
+ *
+ * @param {unknown} refs
+ * @returns {unknown}
+ */
+function preserveStoredRefs(refs) {
+  if (refs === undefined || refs === null) {
+    return [];
+  }
+  return Array.isArray(refs) ? refs.map(ref => String(ref)) : refs;
+}
+
+/**
+ * @param {RecordAutomationRunInput} input
+ * @param {unknown} refs - Already-resolved `refs` for this record.
+ * @returns {AutomationRunRecord}
+ */
+function assembleAutomationRunRecord(input, refs) {
   const loopId = normalizeLoopId(input.loopId);
   const summary = String(input.summary ?? "").trim();
   const runbook = String(input.runbook ?? "").trim();
-  const refs = Array.isArray(input.refs)
-    ? input.refs.map(ref => String(ref))
-    : [];
   const ts =
     input.ts instanceof Date
       ? input.ts.toISOString()
@@ -240,21 +326,23 @@ function validateStoredRecord(value) {
   if (!value || typeof value !== "object") {
     throw new Error("Automation run record must be an object.");
   }
-  return buildAutomationRunRecord({
-    ts: String(value.ts ?? ""),
-    loopId: String(value.loop_id ?? ""),
-    outcome: String(value.outcome ?? ""),
-    summary: String(value.summary ?? ""),
-    runbook: String(value.runbook ?? ""),
-    refs: Array.isArray(value.refs) ? value.refs.map(ref => String(ref)) : [],
-    runId: String(value.run_id ?? ""),
-    // Carry every unrecognised key forward. Without this, re-validating a
-    // stored record on read silently strips it, and the next append writes the
-    // stripped history back over the file (#2524).
-    extras: Object.fromEntries(
-      Object.entries(value).filter(([key]) => !KNOWN_RECORD_KEYS.has(key))
-    ),
-  });
+  return assembleAutomationRunRecord(
+    {
+      ts: String(value.ts ?? ""),
+      loopId: String(value.loop_id ?? ""),
+      outcome: String(value.outcome ?? ""),
+      summary: String(value.summary ?? ""),
+      runbook: String(value.runbook ?? ""),
+      runId: String(value.run_id ?? ""),
+      // Carry every unrecognised key forward. Without this, re-validating a
+      // stored record on read silently strips it, and the next append writes
+      // the stripped history back over the file (#2524).
+      extras: Object.fromEntries(
+        Object.entries(value).filter(([key]) => !KNOWN_RECORD_KEYS.has(key))
+      ),
+    },
+    preserveStoredRefs(value.refs)
+  );
 }
 
 /**
@@ -291,10 +379,10 @@ async function readJsonIfPresent(filePath) {
 
 /**
  * @param {string} filePath
- * @param {readonly AutomationRunRecord[]} records
+ * @param {readonly string[]} lines - Serialised rows, written verbatim.
  */
-async function writeJsonlAtomically(filePath, records) {
-  const content = `${records.map(record => JSON.stringify(record)).join("\n")}\n`;
+async function writeJsonlAtomically(filePath, lines) {
+  const content = `${lines.join("\n")}\n`;
   const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
   await writeFile(tempPath, content, "utf8");
   await rename(tempPath, filePath);
@@ -303,14 +391,19 @@ async function writeJsonlAtomically(filePath, records) {
 const CLI_USAGE = `Usage: node automation-run-record.mjs \\
   --loop-id <slug> --outcome <${AUTOMATION_RUN_OUTCOMES.join("|")}> \\
   --summary "<operator-readable one-liner>" --runbook <path> \\
-  [--ref <url>]... [--run-id <id>] [--project-root <dir>]`;
+  [--ref <url>]... [--run-id <id>] [--project-root <dir>] \\
+  [--denominator '<json from buildIntakeDenominator()>']
+
+--denominator is REQUIRED for a "nothing-needed" run on a build-intake loop: a
+dry lane that does not say which lanes it looked in cannot be checked.`;
 
 /**
  * Translate a repeatable-flag argv into a {@link RecordAutomationRunInput}.
  *
  * Every flag takes a following value; `--ref` may repeat and accumulates into
- * `refs`. Unknown flags and value-less flags throw so a typo never silently
- * records the wrong thing.
+ * `refs`, and `--denominator` carries the swept-lane JSON into `extras`.
+ * Unknown flags and value-less flags throw so a typo never silently records the
+ * wrong thing.
  *
  * @param {readonly string[]} argv
  * @returns {RecordAutomationRunInput}
@@ -320,6 +413,8 @@ function parseAutomationRunRecordArgv(argv) {
   const single = {};
   /** @type {string[]} */
   const refs = [];
+  /** @type {Record<string, unknown>} */
+  const extras = {};
   const flags = {
     "--loop-id": "loopId",
     "--outcome": "outcome",
@@ -349,6 +444,10 @@ function parseAutomationRunRecordArgv(argv) {
       refs.push(takeValue());
       continue;
     }
+    if (flag === "--denominator") {
+      extras.denominator = parseDenominatorFlag(takeValue());
+      continue;
+    }
     const key = flags[flag];
     if (!key) {
       throw new Error(`Unknown flag "${flag}".`);
@@ -356,7 +455,21 @@ function parseAutomationRunRecordArgv(argv) {
     single[key] = takeValue();
   }
 
-  return { ...single, refs };
+  return { ...single, refs, extras };
+}
+
+/**
+ * @param {string} value
+ * @returns {unknown}
+ */
+function parseDenominatorFlag(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new Error(
+      "--denominator must be JSON produced by buildIntakeDenominator()."
+    );
+  }
 }
 
 /**

package/plugins/lisa-copilot/scripts/intake-blocker-reprobe.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Blocker re-probe gate for pre-work build-intake candidates.
+ *
+ * A blocker is a claim with a timestamp, not a fact. It is written once, and it
+ * decays the moment its condition goes true — a dependency lands on trunk, a
+ * CVE gets patched, a package publishes. Nothing in the old intake loop ever
+ * re-read one, so a discharged blocker held its item out of the queue forever.
+ *
+ * This module decides, per candidate, whether intake may select it. It never
+ * probes anything itself: the caller runs the probe and hands back the result,
+ * which keeps the decision auditable and testable apart from the network.
+ */
+
+import { isPreWorkLaneType } from "./intake-prework-denominator.mjs";
+
+/** Marker a writer stamps on an item a human deliberately parked. */
+export const HUMAN_GATE_MARKER = "[lisa-human-gate]";
+
+/** Default label naming a block only a human can clear. */
+export const DEFAULT_HUMAN_NEEDED_LABEL = "human-needed";
+
+/**
+ * @param {unknown} labels
+ * @returns {readonly string[]}
+ */
+function normalizeLabels(labels) {
+  return (Array.isArray(labels) ? labels : [])
+    .map(label =>
+      typeof label === "string"
+        ? label
+        : typeof label?.name === "string"
+          ? label.name
+          : ""
+    )
+    .map(label => label.trim().toLowerCase())
+    .filter(label => label.length > 0);
+}
+
+/**
+ * @param {{ labels?: unknown, body?: unknown, humanNeededLabel?: unknown }} input
+ * @returns {boolean}
+ */
+function isHumanGated(input) {
+  const configured = String(
+    input.humanNeededLabel ?? DEFAULT_HUMAN_NEEDED_LABEL
+  )
+    .trim()
+    .toLowerCase();
+  if (
+    configured.length > 0 &&
+    normalizeLabels(input.labels).includes(configured)
+  ) {
+    return true;
+  }
+
+  return String(input.body ?? "").includes(HUMAN_GATE_MARKER);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function trimmedString(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * @param {{ discharged?: unknown, evidence?: unknown }} probe
+ * @returns {{ selectable: boolean, reason: string, evidence: string }}
+ */
+function judgeProbe(probe) {
+  const evidence = trimmedString(probe.evidence);
+
+  if (probe.discharged !== true) {
+    return {
+      selectable: false,
+      reason: "blocker-holds",
+      evidence,
+    };
+  }
+  if (evidence.length === 0) {
+    return {
+      selectable: false,
+      reason: "blocker-discharge-unevidenced",
+      evidence,
+    };
+  }
+
+  return { selectable: true, reason: "blocker-discharged", evidence };
+}
+
+/**
+ * Decide whether a pre-work item may be selected as a build candidate.
+ *
+ * Order is load-bearing. The human gate is checked before anything else, so no
+ * probe result — however conclusive — can promote an item a human parked.
+ *
+ * @param {{
+ *   laneType?: unknown
+ *   labels?: unknown
+ *   body?: unknown
+ *   humanNeededLabel?: unknown
+ *   statedBlocker?: unknown
+ *   probe?: { discharged?: unknown, evidence?: unknown } | null
+ * }} input
+ * @returns {{ selectable: boolean, reason: string, humanGated: boolean, evidence: string }}
+ */
+export function classifyPreWorkCandidate(input = {}) {
+  if (isHumanGated(input)) {
+    return {
+      selectable: false,
+      reason: "human-gate",
+      humanGated: true,
+      evidence: "",
+    };
+  }
+  if (!isPreWorkLaneType(input.laneType)) {
+    return {
+      selectable: false,
+      reason: "not-pre-work",
+      humanGated: false,
+      evidence: "",
+    };
+  }
+  if (trimmedString(input.statedBlocker).length === 0) {
+    return {
+      selectable: true,
+      reason: "no-blocker",
+      humanGated: false,
+      evidence: "",
+    };
+  }
+  if (!input.probe || typeof input.probe !== "object") {
+    return {
+      selectable: false,
+      reason: "blocker-unprobed",
+      humanGated: false,
+      evidence: "",
+    };
+  }
+
+  return { ...judgeProbe(input.probe), humanGated: false };
+}
+
+/** Plain-English wording for each verdict, for the note left on the item. */
+const REASON_COPY = Object.freeze({
+  "human-gate": "A person parked this one on purpose, so intake left it alone.",
+  "not-pre-work": "This item is not sitting in a not-yet-started lane.",
+  "no-blocker": "No blocker was written on this item, so it is buildable.",
+  "blocker-unprobed":
+    "This item states a blocker that was not re-checked this cycle, so it stays put.",
+  "blocker-holds":
+    "The blocker was re-checked and still holds, so it stays put.",
+  "blocker-discharge-unevidenced":
+    "The blocker looked clear but no proof was recorded, so it stays put.",
+  "blocker-discharged":
+    "The blocker was re-checked and no longer applies, so this item is buildable again.",
+});
+
+/**
+ * Render the re-probe result to leave on the item, so the next cycle reads the
+ * answer instead of deriving it again.
+ *
+ * @param {{
+ *   statedBlocker?: unknown
+ *   checkedAt?: string | Date
+ * }} candidate
+ * @param {{ reason: string, evidence?: string }} verdict
+ * @returns {string}
+ */
+export function formatReprobeNote(candidate = {}, verdict) {
+  const checkedAt =
+    candidate.checkedAt instanceof Date
+      ? candidate.checkedAt.toISOString()
+      : trimmedString(candidate.checkedAt) || new Date().toISOString();
+  const lines = [
+    "**Blocker re-check**",
+    "",
+    `- What has to be true: ${trimmedString(candidate.statedBlocker) || "(none written on this item)"}`,
+    `- What we found: ${REASON_COPY[verdict.reason] ?? verdict.reason}`,
+  ];
+  const evidence = trimmedString(verdict.evidence);
+  if (evidence.length > 0) {
+    lines.push(`- Proof: ${evidence}`);
+  }
+  lines.push(`- Checked at: ${checkedAt}`);
+
+  return lines.join("\n");
+}