@biffo/cli 0.241.1 → 0.242.0

package/_skeletons/plugin-template/AGENTS.md

@@ -139,6 +139,20 @@ it deliberately and say so in a comment; never steal a fresh one.
   the deploy cannot fall off the bottom of a short `gh run list` — and when
   something is red it names the **first** failing commit, not the newest.
 
+- **When a check dies without a failure, adjudicate it before you re-run:**
+
+  ```bash
+  sh scripts/biffo.sh runner-drop-forensics --repo <owner/repo> --run <run-id>
+  ```
+
+  The self-hosted fleet runs on spot capacity, so a job can be killed mid-step
+  and report `failure` with every remaining step at `conclusion: null` — which
+  reads exactly like a real defect and sends you diagnosing your own change.
+  This matches the run against the fleet's eviction record and tells you which
+  it was. Of the 22 runner-killed jobs it was validated against, **17 were in
+  satellites** — which is why it ships in the CLI rather than only upstream
+  (#1240).
+
 - **Check whether the branch was already failing before diagnosing your own
   change.** A red deploy has no audience: the author who broke it has moved on,
   and every later merge fails on damage it did not cause. On 2026-08-02 that

package/_skeletons/sibling-template/AGENTS.md

@@ -139,6 +139,20 @@ it deliberately and say so in a comment; never steal a fresh one.
   the deploy cannot fall off the bottom of a short `gh run list` — and when
   something is red it names the **first** failing commit, not the newest.
 
+- **When a check dies without a failure, adjudicate it before you re-run:**
+
+  ```bash
+  sh scripts/biffo.sh runner-drop-forensics --repo <owner/repo> --run <run-id>
+  ```
+
+  The self-hosted fleet runs on spot capacity, so a job can be killed mid-step
+  and report `failure` with every remaining step at `conclusion: null` — which
+  reads exactly like a real defect and sends you diagnosing your own change.
+  This matches the run against the fleet's eviction record and tells you which
+  it was. Of the 22 runner-killed jobs it was validated against, **17 were in
+  satellites** — which is why it ships in the CLI rather than only upstream
+  (#1240).
+
 - **Check whether the branch was already failing before diagnosing your own
   change.** A red deploy has no audience: the author who broke it has moved on,
   and every later merge fails on damage it did not cause. On 2026-08-02 that

package/dist/index.js

@@ -10795,6 +10795,13 @@ It ships with this package via cli/scripts/packaged-root-assets.mjs; if you are
 }
 
 // src/lib/packaged-script-command.ts
+function interpreterFor(script) {
+  return script.endsWith(".mjs") ? "node" : "sh";
+}
+function runPackagedScript(script, args, cwd) {
+  const result = spawnSync(interpreterFor(script), [script, ...args], { stdio: "inherit", cwd });
+  return result.status === null ? 2 : result.status;
+}
 function packagedScriptCommand(spec) {
   const command = new Command26(spec.name).description(spec.description).allowExcessArguments(true).allowUnknownOption(true);
   if (spec.argument) command.argument(`<${spec.argument.name}>`, spec.argument.description);
@@ -10809,8 +10816,7 @@ function packagedScriptCommand(spec) {
     const at = process.argv.indexOf(spec.name);
     const args = at === -1 ? [] : process.argv.slice(at + 1);
     const cwd = process.env["BIFFO_ORIGINAL_CWD"] || process.cwd();
-    const result = spawnSync("sh", [script, ...args], { stdio: "inherit", cwd });
-    process.exit(result.status === null ? 2 : result.status);
+    process.exit(runPackagedScript(script, args, cwd));
   });
 }
 
@@ -10871,6 +10877,13 @@ var waitForChecksCommand = packagedScriptCommand({
   argument: { name: "pr", description: "Pull request number" }
 });
 
+// src/commands/runner-drop-forensics.ts
+var runnerDropForensicsCommand = packagedScriptCommand({
+  name: "runner-drop-forensics",
+  script: "scripts/runner-drop-forensics.mjs",
+  description: "Decide whether a red check was a fleet fault or a real failure (0 explained, 1 real failure, 2 cannot tell)"
+});
+
 // src/index.ts
 var program = new Command27();
 function cliVersion() {
@@ -10890,6 +10903,7 @@ program.addCommand(branchHealthCommand);
 program.addCommand(claimCommand);
 program.addCommand(verifyCommand);
 program.addCommand(gateCoverageCommand);
+program.addCommand(runnerDropForensicsCommand);
 program.addCommand(hookAuditCommand);
 program.addCommand(pgTestDbCommand);
 program.addCommand(rewriteScopeCheckCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.241.1",
+  "version": "0.242.0",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,10 @@
     "scripts/pg-test-db.sh",
     "scripts/rewrite-scope-check.sh",
     "scripts/gate-coverage.sh",
-    "scripts/verify.sh"
+    "scripts/verify.sh",
+    "scripts/runner-drop-forensics.mjs",
+    "scripts/practices-metrics.mjs",
+    "scripts/practices-corpus.mjs"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",

package/scripts/practices-corpus.mjs

@@ -0,0 +1,172 @@
+/**
+ * Shared read/write helpers for the practices evidence corpus (#1132).
+ *
+ * ## Why a directory, not one shared file
+ *
+ * `docs/practices/evidence.jsonl` was a single file every concurrent session
+ * appended to. N writers, one path — conflicts **by construction**, the same
+ * class already fixed twice in this repo (`core.version` #423, the generated
+ * tally block #953). The lever is the same: stop sharing the path. New rows go
+ * into their own file under `docs/practices/evidence/`, one per entry, e.g.
+ *
+ *     docs/practices/evidence/2026-08-03-metric-denominator-blindness.json
+ *
+ * Two sessions writing on the same day still never collide — their filenames
+ * differ.
+ *
+ * ## Migration: read both, split nothing
+ *
+ * Splitting the ~430 existing rows into ~430 files was rejected: it is more
+ * expensive than the alternative for no benefit, and it would re-serialise a
+ * file that must never be re-serialised (whole-file rewrites are the exact
+ * defect being fixed). Instead `evidence.jsonl` is now a **frozen legacy
+ * file** — nothing ever appends to it again — and the read side merges it
+ * with the directory. See `practices-monotonic.mjs` for the guard that keeps
+ * it frozen rather than shrunk.
+ *
+ * ## Ordering
+ *
+ * Filenames carry the date (`YYYY-MM-DD-slug.json`), so the read side sorts
+ * the directory listing by filename rather than relying on directory order,
+ * which the filesystem does not guarantee. Legacy rows keep their existing
+ * file order (untouched) and sort BEFORE every directory row — they predate
+ * all of them by construction.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const LEGACY_EVIDENCE = 'docs/practices/evidence.jsonl'
+export const EVIDENCE_DIR = 'docs/practices/evidence'
+
+/** The per-entry directory that goes with a legacy `.jsonl` path. */
+export function corpusDirFor(legacyFile) {
+  return legacyFile.replace(/\.jsonl$/, '')
+}
+
+/**
+ * Parse the legacy newline-delimited JSON file, leniently: one malformed line
+ * is dropped rather than failing the whole read. Matches the tolerance this
+ * file's readers already had before #1132 (a scan for ranking, not a strict
+ * audit — `readCorpusStrict` below is the strict counterpart).
+ */
+export function readLegacyEvidence(file = LEGACY_EVIDENCE) {
+  if (!existsSync(file)) return []
+  return readFileSync(file, 'utf8')
+    .split('\n')
+    .filter((l) => l.trim() !== '')
+    .map((line) => {
+      try {
+        return JSON.parse(line)
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+}
+
+/** `*.json` filenames directly under the evidence directory, sorted so date-prefixed names order chronologically. */
+export function listEvidenceFiles(dir = EVIDENCE_DIR) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .sort()
+}
+
+/** Every per-entry file, parsed, alongside the filename it came from — needed to rewrite a specific entry (e.g. `--enrich`). */
+export function readEvidenceDirEntries(dir = EVIDENCE_DIR) {
+  return listEvidenceFiles(dir)
+    .map((file) => {
+      try {
+        return { file, row: JSON.parse(readFileSync(join(dir, file), 'utf8')) }
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+}
+
+/** Every per-entry file's row, sorted by filename. Malformed files are dropped, not fatal. */
+export function readEvidenceDir(dir = EVIDENCE_DIR) {
+  return readEvidenceDirEntries(dir).map((e) => e.row)
+}
+
+/**
+ * The full corpus, lenient: legacy rows (their existing order, untouched)
+ * followed by directory rows (sorted by filename). A concatenation, not a
+ * merge — the two never name the same entry, so there is nothing to
+ * reconcile.
+ *
+ * @param {string} legacyFile path to the legacy `.jsonl`; its sibling
+ *   directory is derived from it (`corpusDirFor`)
+ */
+export function readCorpus(legacyFile = LEGACY_EVIDENCE) {
+  return [...readLegacyEvidence(legacyFile), ...readEvidenceDir(corpusDirFor(legacyFile))]
+}
+
+/**
+ * The full corpus, strict: throws on the first line or file that fails to
+ * parse, and throws if neither the legacy file nor the directory has
+ * anything to read. For callers whose whole point is "never report a zero
+ * that could actually be 'could not read this'" (`summariseFailOpenBacklog`)
+ * — a corpus that half-parses must not silently look like a smaller valid
+ * one.
+ *
+ * @param {string} legacyFile
+ */
+export function readCorpusStrict(legacyFile = LEGACY_EVIDENCE) {
+  const dir = corpusDirFor(legacyFile)
+  const legacyExists = existsSync(legacyFile)
+  const dirFiles = listEvidenceFiles(dir)
+  if (!legacyExists && dirFiles.length === 0) {
+    throw new Error(`no corpus at ${legacyFile} or ${dir}`)
+  }
+  const legacyRows = legacyExists
+    ? readFileSync(legacyFile, 'utf8')
+        .split('\n')
+        .filter((l) => l.trim() !== '')
+        .map((l) => JSON.parse(l))
+    : []
+  const dirRows = dirFiles.map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')))
+  return [...legacyRows, ...dirRows]
+}
+
+/** Filename-safe token from a row's summary. */
+export function slugify(text) {
+  return String(text ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60)
+}
+
+/**
+ * Write ONE new evidence entry as its own file. This is the write path every
+ * future session uses — never append to `evidence.jsonl`, which is frozen.
+ *
+ * Refuses to overwrite an existing file: a collision means the slug needs to
+ * be more specific, not that the earlier entry should be silently replaced.
+ *
+ * @param {Record<string, any>} row
+ * @param {{dir?: string, date?: string, slug?: string}} [opts]
+ * @returns {string} the path written, relative to `opts.dir`'s base
+ */
+export function writeEvidenceEntry(row, opts = {}) {
+  const dir = opts.dir ?? EVIDENCE_DIR
+  const date = opts.date ?? row.date ?? new Date().toISOString().slice(0, 10)
+  const slug = opts.slug ?? slugify(row.summary) ?? 'entry'
+  mkdirSync(dir, { recursive: true })
+  const file = `${date}-${slug || 'entry'}.json`
+  const path = join(dir, file)
+  if (existsSync(path)) {
+    throw new Error(`${path} already exists — choose a more specific slug or date`)
+  }
+  writeFileSync(path, `${JSON.stringify({ ...row, date }, null, 2)}\n`)
+  return path
+}
+
+/** Overwrite one already-existing per-entry file in place (e.g. `--enrich` filling in a date). Never touches the legacy file. */
+export function writeEvidenceFile(dir, file, row) {
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, file), `${JSON.stringify(row, null, 2)}\n`)
+}