@biffo/cli 0.315.5 → 0.315.7

package/_skeletons/plugin-template/.githooks/pre-push

@@ -93,10 +93,13 @@ fi
 # BIFFO_SKIP_CLAIM_GUARD -- narrow, claim-only escape hatch (#1327). Before
 # this, the only documented way past a false positive here was
 # BIFFO_SKIP_VERIFY at the top of this file, which does not target the claim
-# guard: it skips the WHOLE gate -- ruff, pyright, bandit, gitleaks,
-# rewrite-scope, this guard, everything. An agent reading "skip the claim
-# guard" reasonably reaches for the only hatch documented and gets "skip
-# everything" instead; one did, in the session #1327 was filed from. This
+# guard: it skips the WHOLE gate -- ruff, pyright, bandit, rewrite-scope,
+# this guard, everything. gitleaks is deliberately not named here: verify.sh
+# only runs it when the binary is installed locally and reports "APPLICABLE
+# BUT NOT RUN" otherwise, so it is not a member of the gate this variable
+# reliably skips (#2038). An agent reading "skip the claim guard" reasonably
+# reaches for the only hatch documented and gets "skip everything" instead;
+# one did, in the session #1327 was filed from. This
 # variable bypasses exactly the `claim --guard` call below and nothing else --
 # rewrite-scope-check, the pg-test block gate and `verify` all still run.
 branch=$(git symbolic-ref --quiet --short HEAD) || branch=""

package/_skeletons/sibling-template/.githooks/pre-push

@@ -93,10 +93,13 @@ fi
 # BIFFO_SKIP_CLAIM_GUARD -- narrow, claim-only escape hatch (#1327). Before
 # this, the only documented way past a false positive here was
 # BIFFO_SKIP_VERIFY at the top of this file, which does not target the claim
-# guard: it skips the WHOLE gate -- ruff, pyright, bandit, gitleaks,
-# rewrite-scope, this guard, everything. An agent reading "skip the claim
-# guard" reasonably reaches for the only hatch documented and gets "skip
-# everything" instead; one did, in the session #1327 was filed from. This
+# guard: it skips the WHOLE gate -- ruff, pyright, bandit, rewrite-scope,
+# this guard, everything. gitleaks is deliberately not named here: verify.sh
+# only runs it when the binary is installed locally and reports "APPLICABLE
+# BUT NOT RUN" otherwise, so it is not a member of the gate this variable
+# reliably skips (#2038). An agent reading "skip the claim guard" reasonably
+# reaches for the only hatch documented and gets "skip everything" instead;
+# one did, in the session #1327 was filed from. This
 # variable bypasses exactly the `claim --guard` call below and nothing else --
 # rewrite-scope-check, the pg-test block gate and `verify` all still run.
 branch=$(git symbolic-ref --quiet --short HEAD) || branch=""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@biffo/cli",
-  "version": "0.315.5",
+  "version": "0.315.7",
   "description": "Biffo project scaffolding CLI",
   "license": "MIT",
   "type": "module",
@@ -33,9 +33,7 @@
     "scripts/pgtest-diff-check.sh",
     "scripts/gate-coverage.sh",
     "scripts/verify.sh",
-    "scripts/runner-drop-forensics.mjs",
-    "scripts/practices-metrics.mjs",
-    "scripts/practices-corpus.mjs"
+    "scripts/runner-drop-forensics.mjs"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean --external typescript",

package/scripts/runner-drop-forensics.mjs

@@ -14,10 +14,9 @@
  * reading of a red branch and the lazy one are indistinguishable, and #982
  * showed the estate had been counting these as broken code for months.
  *
- * `isRunnerKill` (in `practices-metrics.mjs`, imported below rather than
- * re-implemented) already answers *"did a runner die?"* from the run's own step
- * conclusions. It cannot answer *"why?"* — and "why" is what decides whether
- * anyone should be looking at the code at all.
+ * `isRunnerKill` below already answers *"did a runner die?"* from the run's own
+ * step conclusions. It cannot answer *"why?"* — and "why" is what decides
+ * whether anyone should be looking at the code at all.
  *
  * ## The join nobody had written
  *
@@ -61,7 +60,80 @@
 
 // @ts-check
 import { execFileSync } from 'node:child_process'
-import { isRunnerKill } from './practices-metrics.mjs'
+
+/**
+ * Step conclusions that mean the step **stopped without a verdict**.
+ *
+ * A dying runner produces two different signatures and #982 caught only the
+ * first, so `biffo-platform` kept two failures it had not earned:
+ *
+ * - `null` — the step was still executing when the lights went out. A deploy
+ *   frozen on "Package and deploy Lambda", six steps left `pending`.
+ * - `cancelled` — the step was stopped, and every later step reads `skipped`.
+ *   Two `biffo-platform` CI runs died 64 seconds in this way, on "Type check"
+ *   and "Lint".
+ *
+ * ## Why `cancelled` here is not an ordinary cancellation
+ *
+ * The obvious objection is that this launders someone hitting cancel, or a
+ * `cancel-in-progress` supersession. It does not, and the reason is structural:
+ * **those conclude the run `cancelled`**, which `isRunnerKill` is only ever
+ * reached for a run that concluded `failure`. A run that concluded `failure`
+ * while no step ever returned a verdict was therefore stopped by something
+ * that is not a cancellation.
+ *
+ * A step that hits `timeout-minutes` (20 since #980) is expected to be marked
+ * `failure` and so stays a real failure.
+ */
+const STOPPED_SHORT = new Set([null, undefined, 'cancelled'])
+
+/**
+ * Did this run fail because a **runner died**, rather than because a gate
+ * rejected the change? (#982)
+ *
+ * ## The hole this closes
+ *
+ * A killed or superseded run naturally concludes `cancelled`, which is not a
+ * defect. That reasoning is right and its coverage is only partial: **a runner
+ * killed mid-job reports `cancelled` only sometimes.** The rest of the time
+ * GitHub concludes the run `failure` with *no failing step* — the same
+ * physical event, a different label, and the second label was counted as if
+ * code had broken.
+ *
+ * Measured on `tabsii-com/tabsii-platform`, 2026-07-31: **all six** `dev`
+ * failures inspected had zero failing steps and 3–21 steps left incomplete. One
+ * deploy succeeded through thirteen steps and froze on "Package and deploy
+ * Lambda". Not one gate rejected a change.
+ *
+ * ## The rule, and why it errs the way it does
+ *
+ * A failed run is a runner kill when **no job reports a failing step** and **at
+ * least one failed job has a step that stopped without a verdict** — see
+ * {@link STOPPED_SHORT} for the two signatures that means, and why `cancelled`
+ * among them is not an ordinary cancellation. Both halves matter: the first
+ * says nothing rejected the change, the second says work was still outstanding
+ * when the lights went out.
+ *
+ * A failed run with no steps recorded at all is deliberately **not** classified
+ * as a kill. It stays a failure. That is the conservative direction for a
+ * counter-metric — it can still refute an experiment the author would prefer to
+ * confirm — and this module's whole purpose is to make that the default.
+ *
+ * A job that hits its `timeout-minutes` (20 since #980) marks the offending step
+ * `failure`, so a genuine hang stays a genuine failure and is not laundered
+ * through here.
+ *
+ * @param {Array<Record<string, any>>} jobs the `jobs` array of one run
+ * @returns {boolean}
+ */
+export function isRunnerKill(jobs) {
+  const failed = (jobs ?? []).filter((job) => job.conclusion === 'failure')
+  if (failed.length === 0) return false
+  const steps = failed.flatMap((job) => job.steps ?? [])
+  if (steps.length === 0) return false
+  if (steps.some((step) => step.conclusion === 'failure')) return false
+  return steps.some((step) => STOPPED_SHORT.has(step.conclusion))
+}
 
 /**
  * How far outside a job's own start/finish window an eviction may fall and

package/scripts/verify.sh

@@ -460,9 +460,11 @@ fi
 # and NO_CI must not fire just because a repo has not adopted the split (a
 # sibling never will; an instance not yet upgraded past #1319 has not yet).
 # But if it EXISTS and cannot be READ, that is the identical #1218 shape as
-# ci.yml itself, and ci_has() must search it too or "practices-monotonic"
-# (moved into it) would silently stop being locally mirrored the moment it
-# left ci.yml -- covered less than verify.sh claims, with nothing saying so.
+# ci.yml itself, and ci_has() must search it too -- a check that lives ONLY
+# in release-guards.yml (any of the ones this repo's own header explains
+# moved here to avoid re-running the whole ci.yml matrix on a PR edit) would
+# otherwise silently stop being locally mirrored, covered less than verify.sh
+# claims, with nothing saying so.
 RELEASE_GUARDS_YML_UNREADABLE=""
 if [ -f .github/workflows/release-guards.yml ] && [ ! -r .github/workflows/release-guards.yml ]; then
   RELEASE_GUARDS_YML_UNREADABLE=1
@@ -1544,15 +1546,6 @@ fi
 [ -f scripts/check-orphan-ratchet-instance.test.sh ] &&
   run_check orphan-ratchet-instance-selftest sh scripts/check-orphan-ratchet-instance.test.sh
 
-# The append-only corpus guard (#778). CI runs it in Release Guards, and it was
-# invisible to the parity test until #897 widened the harvester -- it is neither
-# `pnpm`, `uv`, `terraform` nor `sh scripts/`, so the guard whose property is
-# "every CI check is in the gate or explicitly excluded" could not see it at all.
-# Measured 0.06s here, which is cheaper than every other check in this file.
-if [ -f scripts/practices-monotonic.mjs ]; then
-  ci_has "practices-monotonic" && run_check corpus-append-only node scripts/practices-monotonic.mjs
-fi
-
 # Terraform plan artefacts, refused by CONTENT (biffo-runners#1).
 #
 # A saved plan is a zip. `strings`/`grep` over it is a false-negative machine —

package/scripts/practices-corpus.mjs

@@ -1,202 +0,0 @@
-/**
- * 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.
- *
- * The refusal is an atomic `wx` create, not an `existsSync` check followed by
- * a write (#1222). This corpus has concurrent writers BY DESIGN — several
- * agent sessions run against this estate at once — so the window between a
- * check and a write is not theoretical here: two sessions writing the same
- * `date-slug` is the exact case the guard exists for, and the check-then-write
- * form lost the earlier entry rather than refusing. `EEXIST` is translated
- * back into the same message, so nothing else changes.
- *
- * @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
-  // `undefined` means "nobody said"; `null` means "known to be unknown". Both
-  // must reach the stored field as null rather than today's date.
-  //
-  // This used to read `opts.date ?? row.date ?? new Date()…` and write that
-  // single value to BOTH the filename and the row. The module docstring says
-  // the opposite in as many words — "Rows citing nothing keep `date: null` —
-  // never a guess, because a fabricated date would corrupt exactly the ranking
-  // this exists to enable" — and `--extract` even passes `date: row.date ??
-  // null` to say so explicitly. `null ?? today` discarded that.
-  //
-  // It was invisible while rows were extracted the day they were written, and
-  // surfaced on 2026-08-09 when extracting five rows also swept up eighteen
-  // older ones and stamped every one with that day. `--enrich` recovers real
-  // dates from the cited issues afterwards, and it can only do that for rows
-  // whose date is *absent*; a fabricated one looks recovered and is skipped.
-  const date = opts.date ?? row.date ?? null
-  const slug = opts.slug ?? slugify(row.summary) ?? 'entry'
-  mkdirSync(dir, { recursive: true })
-  // The filename is used only for sorting and uniqueness — every reader parses
-  // the JSON body — so an undated row says so here too, rather than carrying a
-  // date prefix that the data it contains denies.
-  const file = `${date ?? 'undated'}-${slug || 'entry'}.json`
-  const path = join(dir, file)
-  try {
-    writeFileSync(path, `${JSON.stringify({ ...row, date }, null, 2)}\n`, { flag: 'wx' })
-  } catch (err) {
-    if (err && err.code === 'EEXIST') {
-      throw new Error(`${path} already exists — choose a more specific slug or date`)
-    }
-    throw err
-  }
-  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`)
-}