liteagents 2.22.0 → 2.23.0

package/packages/droid/commands/docs-builder/docs-builder.cjs

@@ -103,6 +103,18 @@ function fenceMask(lines) {
 // prose), sentences()'s own regex strip, and checkCitations/checkLinks doing none at all — so
 // a page documenting the citation/link syntax INSIDE a fence got its own example flagged as
 // a real violation. One mechanism: mask with fenceMask(), drop the masked lines.
+// `text.split('\n')` returns a trailing EMPTY element for any file ending in a newline —
+// which is nearly every file — so `lines.length` is real_lines + 1. That phantom line reached
+// the index row's "N lines", the last H2's range (one line past EOF) and scan()'s outline.json.
+// Use this wherever lines are COUNTED or a range is BOUNDED. The raw `.split('\n')` is still
+// correct where the array is mapped and re-joined back into file text (stripFences,
+// replaceOutsideFences): dropping the element there would strip the file's final newline.
+function splitLines(text) {
+  const lines = text.split('\n');
+  if (lines.length && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
 function stripFences(text) {
   const lines = text.split('\n');
   const mask = fenceMask(lines);
@@ -229,7 +241,7 @@ function scan(files) {
   if (!files.length) die('usage: docs-builder.cjs scan <file.md...>');
   const records = [];
   for (const f of files) {
-    const lines = read(f).split('\n');
+    const lines = splitLines(read(f));
     const mask = fenceMask(lines);
     const { h1, heads } = headings(lines, mask);
     const h2s = heads.filter(h => h.lvl === 2);
@@ -522,8 +534,13 @@ const MIN_PAGE_LINES = 10;
 function pageStatus(file) {
   if (!fs.existsSync(file)) return 'TODO';
   const txt = fs.readFileSync(file, 'utf8');
-  const lines = txt.split('\n');
-  const hasFrontmatter = lines[0].trim() === '---' && lines.slice(1).some(l => l.trim() === '---');
+  const lines = splitLines(txt);
+  // splitLines() returns [] for a 0-byte file — 0 lines is the right COUNT, but it means
+  // lines[0] can be undefined, where the old raw split('\n') always yielded ['']. An empty
+  // page is reachable (a touched placeholder, or page-writing interrupted before it wrote
+  // anything) and must read as PARTIAL, not throw and take `plan` down with it.
+  const hasFrontmatter = lines.length > 0 && lines[0].trim() === '---'
+    && lines.slice(1).some(l => l.trim() === '---');
   return hasFrontmatter && lines.length >= MIN_PAGE_LINES ? 'done' : 'PARTIAL';
 }
 
@@ -732,7 +749,7 @@ const ARCHIVE_WARN_ROWS = 100; // stated default, not measured — see docs-buil
 // section a reader is being routed into, so its row stays H1 + line count + link only.
 function indexRow(rel, dest, includeH2) {
   const text = read(rel);
-  const lines = text.split('\n');
+  const lines = splitLines(text);
   // Same headings()+fenceMask() path scan() uses -- no second parser -- so an H2 inside a
   // ``` fence is masked out here exactly as it is there.
   const mask = fenceMask(lines);
@@ -1398,7 +1415,7 @@ function ledger() {
   const head = git(['rev-parse', 'HEAD'], 'reading HEAD (is this a git repo?)');
   const docs = docFiles().map(f => ({
     path: f,
-    lines: read(f).split('\n').length,
+    lines: splitLines(read(f)).length,
     sha256: sha(path.join(REPO, f)).slice(0, 16)
   }));
   const out = { sha: head, at: new Date().toISOString(),
@@ -1492,7 +1509,7 @@ function lint(files) {
   if (!files.length) die('usage: docs-builder.cjs lint <file.md...>');
   const sections = [];
   for (const f of files) {
-    const lines = read(f).split('\n');
+    const lines = splitLines(read(f));
     const mask = fenceMask(lines);
     let cur = null;
     const close = i => { if (cur) { cur.e = i; cur.body = lines.slice(cur.s, i).join('\n'); } };
@@ -1665,7 +1682,7 @@ function isIncludeStub(lines) {
 // but its size. Oversized is now orthogonal to sorting: a product doc that's too big is
 // still a product doc.
 function classifyDoc(rel, text) {
-  const lines = text.split('\n');
+  const lines = splitLines(text);
   const mask = fenceMask(lines);
   const { h1 } = headings(lines, mask);
   const snip = snippet(lines, mask, 0, lines.length, 200);
@@ -2214,7 +2231,7 @@ function cleanup(files) {
       + `would overwrite that split's still-in-flight outline.json/labels.json. Finish it `
       + `first: write its remaining pages, then re-run \`cleanup-apply ${inFlight} ...\` until `
       + `it archives — THEN run \`cleanup ${file}\`.`);
-  const lines = read(file).split('\n').length;
+  const lines = splitLines(read(file)).length;
   const est = writeCostEstimate(1, lines);
   console.log(`${file}: ${lines} lines`);
   console.log(`est. write cost: $${est.toFixed(2)} (mid tier, floor assuming 1 page — the `

package/packages/droid/commands/refactor.md

@@ -1,12 +1,80 @@
 ---
 name: refactor
 description: Refactor [code]
-usage: /refactor <code-section>
-argument-hint: [file-or-function]
-allowed-tools: Read, Edit, Grep, Glob, Bash(npm test *), Bash(npx jest *), Bash(npx vitest *), Bash(pnpm test *), Bash(yarn test *), Bash(pytest *), Bash(python *), Bash(go test *), Bash(cargo test *), Bash(make test *), Bash(git diff *)
+usage: /refactor <code-section> | /refactor (no args = fix-ledger mode)
+argument-hint: [file-or-function, or empty for the fix ledger]
+allowed-tools: Read, Edit, Grep, Glob, Bash(npm test *), Bash(npx jest *), Bash(npx vitest *), Bash(pnpm test *), Bash(yarn test *), Bash(pytest *), Bash(python *), Bash(go test *), Bash(cargo test *), Bash(make test *), Bash(git diff *), Bash(git grep *), Bash(git status *), Bash(git rev-parse *), Bash(git switch *)
 ---
 Refactor $ARGUMENTS.
 
+## Guardrails
+- **Spawn a worker and explicitly select your tool's mid tier.** State the
+  tier on the spawn — do not omit it and rely on a default. An omitted tier
+  inherits the *parent's* tier, which is not the same thing as the balanced
+  one. Pick the judgment-capable tier that is cheaper and faster than your top
+  reasoning tier. **Not the cheapest/fastest tier**: on judgment work it
+  measurably degrades (misclassification rates several times higher). Choose by
+  tier, not by a vendor model name copied from this file — names drift, and
+  this command ships to several tools. Fall back to running inline if your tool
+  has no subagent mechanism.
+- **Escalate, never assume.** Anything you cannot decide, cannot verify, or
+  that this spec does not cover → **stop and report it to the orchestrator**
+  (the main session). Never improvise, never widen scope, never fix a side
+  issue you noticed along the way.
+- **The worker does the work itself — no delegation.** The fixer must **not**
+  spawn subagents of its own. Every edit it reports, and every test run it
+  cites, has to be one it made or ran with its own tool calls: a relayed "I
+  fixed it and the suite is green" from a sub-worker is hearsay, and this
+  command's whole output is the claim that a change landed and the tests still
+  pass. A fix that delegates its work is a report about a report.
+- **The HITL gates below belong to the orchestrator, not the worker.** A
+  subagent cannot hold a conversation with the user, so it cannot run a gate
+  that ends in *stop and ask*. When one trips — a failing test, a crossed
+  public API boundary, a change bigger than the bullet asked for — the worker
+  **stops there and hands the situation back**, with the options and its
+  reasoning but no choice made. The orchestrator asks. A worker that picks
+  revert / patch / update-test on the user's behalf has answered a question it
+  was never allowed to ask.
+- **Edit only what a surviving bullet names.** Ledger mode's scope is the
+  bullets that survive revalidation, one change per bullet — not the
+  neighbouring code, not the formatting, not a second finding noticed on the
+  way past. Anything else goes back to the orchestrator to become a new
+  bullet.
+- **Prove the blast radius with two checks, because neither sees what the
+  other does.** `git status --porcelain` at exit must list only files a
+  surviving bullet named — that is this command's scope guarantee, and unlike
+  `/branch-review` it is not expected to be empty. It cannot police the
+  memory directory: `.claude/` is normally gitignored, so porcelain stays
+  empty whether you deleted a fixed bullet, wrote nothing, or overwrote
+  `MEMORY.md`. So also take `md5sum .claude/remember/*` before you start and
+  again before you report, and show the comparison: only `fix-ledger.md` may
+  differ. `last-review.md` in particular is `/branch-review`'s to write —
+  a fixer that touches it forges the gate that judges its own work.
+
+## Ledger mode — `$ARGUMENTS` empty
+Work through `.claude/remember/fix-ledger.md`, the non-blocking findings
+`/branch-review` has accumulated. Everything below (goals, constraints,
+verification, HITL gates) still applies; this section only says what to
+refactor and how to close each item.
+
+1. **Tree must be clean and not on `main`.** The orchestrator runs this check
+   before spawning the worker, so a dirty tree costs no worker; the worker
+   then re-runs it as its own first act. `git status --porcelain` non-empty
+   → stop, say what is uncommitted. On `main` → `git switch -c chore/fix-ledger`.
+2. **Ledger missing or has zero bullets** → say so and stop. Nothing to do.
+3. **Revalidate every bullet first, fix nothing yet.** For each: `git grep -F
+   "<snippet>" -- <path>`. **No hit → delete the bullet** and list it as
+   "cleaned by other work". Hit → re-read the surrounding code; if the finding
+   no longer holds, delete the bullet with a one-line reason. What survives is
+   the work list.
+4. **Fix the survivors, one bullet per change**, under the constraints below.
+   Delete each bullet as its fix lands. A fix that turns out to need a
+   behaviour change is not a refactor — leave the bullet, note it in the report.
+5. Run the tests as described below. Then report: **fixed / dropped / left**
+   with the reason per left item, and the remaining bullet count.
+6. Say plainly: **commit, then run `/branch-review`** on this branch — ledger
+   mode is a fixer, not a review, and its diff gets the ordinary gate.
+
 ## Goals
 - Reduce complexity
 - Improve readability

package/packages/droid/commands/release.md

@@ -56,20 +56,48 @@ separate command that must have run first.
 A review must have run on this branch **at the current HEAD SHA**.
 
 **Compare the SHAs yourself; do not settle for an answer.** Run `git rev-parse
-HEAD` and compare it against the SHA the review recorded — `/branch-review`
-ends with `Reviewed at HEAD <sha>`. Asking the orchestrator "did a review run?"
-puts the question to the one party with an incentive to say yes, so its word is
-not evidence: obtain the review's own recorded SHA and match the two strings.
-**No recorded SHA to compare = no review**, never a pass.
+HEAD` and compare it against the `sha:` line in
+`.claude/remember/last-review.md`, which `/branch-review` writes. Asking the
+orchestrator "did a review run?" puts the question to the one party with an
+incentive to say yes, so its word is not evidence — and neither is a SHA
+quoted from a chat message, which is the same claim in another costume and is
+gone after a compaction or a handover. Read the file; match the two strings.
+**No such file, or no `sha:` line in it = no review**, never a pass. A review
+that predates this file's introduction has no record, so it does not count.
 
 - **No review**, or no recorded SHA obtainable → **stop**: "No review at
   `<sha>`. Run `/branch-review medium` (or `/code-review medium`) first."
 - **Stale** — recorded SHA ≠ `git rev-parse HEAD`, i.e. commits landed after
   the review (including fix commits) → **stop** and ask for a re-review. This
   is what makes "all findings fixed" checkable instead of promised.
+  **No exceptions — including the fix ledger.** It is normally gitignored, so
+  appending to it moves nothing and this never comes up. A repo that tracks
+  `.claude/` instead will see a ledger commit land after the review and make
+  it stale. That is the rule working, not a case to carve out: re-review, or
+  leave the ledger uncommitted until after the release.
+- **`coverage:` naming any stage `NOT RUN`** → **stop**. A `ready` from a run
+  that skipped the security stage is not the same fact as one that did not,
+  and this line is the only place the difference is visible to you.
+- **`verdict: blocked` in the record** → **stop**, even when the SHA matches.
+  Read that line as mechanically as the `sha:` one. A matching SHA proves a
+  review ran here; it says nothing about what the review concluded, and
+  leaving the conclusion to the orchestrator's recollection restores exactly
+  the unverified claim this file replaced. Only `verdict: ready` with a
+  matching SHA is a pass.
 - **Reviewed at this SHA with findings outstanding** → **stop**. Findings are
   resolved before a release is cut.
 
+This phase runs **before** `/release` writes anything, so the docs-and-bump
+commit it makes later cannot invalidate the review it just checked. That
+If Phase 2's docs sweep happens to correct a line that a fix-ledger bullet
+also names, that is ordinary sweep work — the doc changed with the feature,
+so it was already yours to update. **Do not delete the bullet.** `/refactor`
+is the only deleter, and its revalidation will drop that bullet on its next
+run when it finds the finding no longer holds. Deleting it here would make
+`/release` a second writer on state that has exactly one owner, and the whole
+value of the ledger's one-append-one-delete split is that it stays readable
+as a log.
+
 Report the comparison you actually ran: recorded `<sha>` vs HEAD `<sha>`,
 match yes/no.
 
@@ -141,15 +169,27 @@ orchestrator can run them on the user's named go:
 > Ready when you are:
 > 1. `git push -u origin <branch>`
 > 2. `gh pr create` into `main`
-> 3. `gh pr merge --admin --squash --delete-branch` (main is PR-protected;
+> 3. `gh pr checks <pr> --watch` — **merge only on green.** Every gate before
+>    this one ran on the same machine; CI is the only differently-configured
+>    instrument in the chain, and this is the first time it sees the branch.
+>    A test that passes locally because of a path, a fixture, or a tool that
+>    exists only on your box fails here and nowhere earlier. Read the exit
+>    code off the bare command. Red → stop, fix, re-review, and start again.
+> 4. `gh pr merge --admin --squash --delete-branch` (main is PR-protected;
 >    owner-authorized admin merge on a solo repo). **Keep `--squash`** — `gh`
 >    requires an explicit merge-method flag (`--squash` / `--merge` /
 >    `--rebase`); drop it and the command will not squash-merge.
-> 4. `git tag vX.Y.Z` on `main` and push the tag
-> 5. Publish **if this project has a publish path** (e.g.
+> 5. `git tag vX.Y.Z` on `main` and push the tag
+> 6. Publish **if this project has a publish path** (e.g.
 >    `gh workflow run publish.yml`) — manual by design
-> 6. Verify it is actually live (`npm view <pkg> version`, and the published
+> 7. Verify it is actually live (`npm view <pkg> version`, and the published
 >    tarball's contents), not the working tree
 
+**Every exit code in this sequence is read off the bare command, including
+the ones you type yourself.** `/ship`'s rule is not just for the worker: a
+pipeline reports its last element's status, so `gh run watch --exit-status |
+tail -2; echo $?` prints `0` for a failed run. That has already turned a red
+CI into a green reading in a real release.
+
 Final line: **Cut ✅ (vX.Y.Z — ready to push)** or **Blocked 🛑** with the
 specific reason.

package/packages/droid/commands/remember/AGENT_RULES.md

@@ -105,11 +105,14 @@ Before adding any external dependency, all of these must be true:
 
 - **Open-source only.** Always use open-source solutions. No vendor lock-in
 - **Lightweight over complex.** If two solutions solve the same problem, use the one with fewer moving parts, fewer dependencies, and less configuration
-- **Every line must have a purpose.** No speculative code, no "might need this later", no abstractions for one use case
+- **Every line earns its place.** If you can't say what breaks when it's deleted, delete it. No speculative code, no "might need this later", no abstractions for one use case. One function, one concern, one owner — small blocks beat spaghetti
 - **Simple > clever.** Readable code that a junior can follow beats elegant code that requires a PhD to debug
+- **One writer per piece of state.** One function assigns each field; everything else calls it. Grep who writes it before you write it. Ownership says *where*, not *when* — if a write can land from a callback, thread, or lifecycle, the reader must tell stale from fresh
+- **Split the decision from the machinery.** A branch whose outcome matters, tangled with a framework, IO, or UI object, moves into a pure function; the framework class applies the result. Extract to pin a branch, not to raise coverage — a one-line delegation in its own file buys a test that cannot fail
+- **Claims in comments must be checkable.** "The only place that writes X" is a claim — run the grep first, and expect the next reader to re-run it. A name search proves an edge exists, never that one doesn't
 - **Containerize only when necessary.** Start with a virtualenv or bare metal. Docker adds value for deployment parity and isolation — not for running a script
 - **Responsive web UI is mandatory in dev projects.** Any web UI must be usable on mobile by default — fluid layouts, viewport meta tag, breakpoints for narrow screens, no horizontal scroll. Test in DevTools device emulation before declaring a UI task done. POCs are exempt (validate the idea first), but the moment a POC graduates to a real project this becomes a hard requirement
-- **Surgical changes only.** Touch what the task requires; nothing else. Don't "improve" adjacent code, comments, or formatting. Match existing style even if you'd do it differently. Only clean up orphans your own change created — leave pre-existing dead code alone unless asked. Every changed line should trace directly to the request
+- **Surgical changes only.** Touch what the task requires; nothing else. Don't "improve" adjacent code, comments, or formatting. Match existing style even if you'd do it differently. Only clean up orphans your own change created. Dead code, nits, bugs you pass on the way: if it's inside or affects the code you're already changing, and the fix changes no behavior, fix it and say so. Otherwise report it — say what it costs to leave it. "It would be nicer" is not a cost. Every changed line traces to the request or to a fix you named
 
 ### Red Flags — Stop and Flag These
 - Over-engineering simple problems
@@ -121,6 +124,8 @@ Before adding any external dependency, all of these must be true:
 - Authoring a fixture/corpus that *guarantees* the result (a test that can't return the negative), or trusting a degenerate-looking number without auditing the harness for confounds — use real uncrafted data; the test must be able to fail
 - Fitting a POC to pass (narrowed input, moved threshold, shrunk scope) instead of reporting the failure; starting module N+1 while module N is unproven
 
+A problem you see and don't fix goes in the report, never in a comment. Comments are where findings go to be forgotten.
+
 ---
 
 ## Testing Standards
@@ -291,7 +296,11 @@ Copy this to any project's AGENTS.md. These are mandatory rules, not suggestions
 
 **Lightweight over complex.** Fewer moving parts, fewer deps, less config. Express over NestJS, Flask over Django, unless the project genuinely needs the framework. Simple > clever. Readable > elegant.
 
-**Open-source only.** No vendor lock-in. Every line of code must have a purpose — no speculative code, no premature abstractions.
+**Open-source only.** No vendor lock-in. Every line of code earns its place — if you can't say what breaks when it's deleted, delete it. No speculative code, no premature abstractions.
+
+**One writer per piece of state.** One function assigns each field; everything else calls it. Grep who writes it before you write it — and if a write can land from a callback, thread, or lifecycle, the reader must tell stale from fresh.
+
+**Surgical changes only.** Touch what the task requires. Dead code, nits, bugs you pass: if it's inside or affects the code you're already changing and the fix changes no behavior, fix it and say so — otherwise report it and say what it costs to leave it. A problem you don't fix goes in the report, never in a comment.
 
 **Responsive web UI is mandatory.** Any web UI must work on mobile by default — fluid layouts, viewport meta, breakpoints, no horizontal scroll. Verify in DevTools device emulation before claiming a UI task is done. POCs exempt; real projects are not.
 

package/packages/droid/commands/remember.md

@@ -133,6 +133,14 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
      Re-processing a stash whose episode is already filed must not create a near-duplicate
      pair. Every older episode is **folded, then deleted**: its lesson becomes a fact (handed
      to the rewrite above); the narrative is removed. No archive — git has the history.
+     **Specify the operation once.** The keep-10 rule is the rule; the set to remove is
+     *derived* from it, never supplied alongside it as a second list. Given both, an agent
+     applies both and removes their union — observed in the field: a run told to keep 10 and
+     handed a 5-entry delete list removed 7, and the 2 extras were never folded, so one
+     lesson left memory with nothing carrying it. **No episode is removed whose lesson has
+     not been folded into a fact first**, and the two sets must match: state the count
+     before, the count after, and name each episode removed. Removed-but-not-folded is a
+     defect to report, not a tidy-up.
    - **Antigens section**: only update from friction output (step 4)
    - Write merged result to `.factory/remember/MEMORY.md` in the format under step 5.
 
@@ -276,7 +284,11 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
        recurrence; a single occurrence has none to track yet. Friction re-scans every
        session log every run, so a later run matches it back to 2+ sessions and seeds it
        then — this does not change matching against an EXISTING entry, which is recurrence
-       regardless of the matching cluster's own session count.
+       regardless of the matching cluster's own session count. **A match is not an
+       increment.** Whether it counts as a new conversation is decided in 4c by
+       `friction.cjs count`, which is a no-op when that session hash is already stored — so
+       several matches against one entry routinely produce zero increments, and that is
+       correct, not a miscount.
      - For `new:<theme>` groups with no ledger match: distinct conversations = distinct
        cluster indices in the group (within one classify batch, no two cluster indices
        share a session hash). `sessions < 2` → writes nothing. `sessions >= 2` → new entry,
@@ -346,18 +358,39 @@ Reads all raw material (`.factory/stash/*.md` + `.factory/remember/friction/anti
      inline duplication is needed
    - If `.factory/remember/AGENT_RULES.md` exists (bootstrapped in step 1), compose a second,
      independent section between `<!-- AGENT_RULES:START -->` and `<!-- AGENT_RULES:END -->`
-     markers. Unlike MEMORY.md above, this is a **plain path pointer, never `@`-referenced**
-     — an `@`-reference hot-loads the whole file into every session, and this is a standards
-     guide to consult when designing/building something new, not hot context:
+     markers. Unlike MEMORY.md above, the file itself is **never `@`-referenced** — an
+     `@`-reference hot-loads all ~300 lines into every session, and it is a standards guide
+     to consult when designing/building something new, not hot context. The section carries
+     a path pointer plus exactly two inline rules: the ones that change what you TYPE, which
+     you cannot look up because you do not know you need them. Everything else stays behind
+     the pointer. Write the section verbatim, rules first:
      ```
      <!-- AGENT_RULES:START -->
+     **One writer per piece of state.** One function assigns each field; everything else
+     calls it. Grep who writes it before you write it — and if a write can land from a
+     callback, thread, or lifecycle, the reader must tell stale from fresh.
+
+     **Surgical changes only.** Touch what the task requires. Dead code, nits, bugs you
+     pass: if it's inside or affects the code you're already changing and the fix changes
+     no behavior, fix it and say so — otherwise report it and say what it costs to leave
+     it. A problem you don't fix goes in the report, never in a comment.
+
      Standards guide (read when designing/building something new, not hot context):
      .factory/remember/AGENT_RULES.md
      <!-- AGENT_RULES:END -->
      ```
-   - Each marker pair is independent: if AGENTS.md already has a given pair, replace the
-     section between them; if not, append it at the end; if no AGENTS.md exists, create one
-     containing whichever section(s) apply
+   - Each marker pair is independent: if AGENTS.md lacks a given pair, append it at the
+     end; if a given pair already exists, replace its content in place; if no AGENTS.md
+     exists, create one containing whichever section(s) apply.
+   - **An existing AGENT_RULES pair is left alone — bootstrap once, never overwrite.** The
+     block above is what to write when creating it, not a template to re-impose every run.
+     Users trim this section deliberately (a pointer-only variant is common), and rewriting
+     it silently re-adds text they removed, on every single run, forever. Observed in the
+     field: a run restored the inline rules into a AGENTS.md whose owner had cut them, and
+     the edit had to be reverted by hand. This matches how `AGENT_RULES.md` itself is
+     handled — bootstrapped once, never overwritten after.
+   - If an existing pair is present but its **path pointer** is missing or wrong, that is
+     load-bearing: **report it and stop**, do not silently rewrite the section around it.
 
    ```markdown
    # Project Memory

package/packages/droid/commands/ship.md

@@ -20,6 +20,22 @@ its exit code**. A check you did not run is a **fail**, never a pass. **N/A
 requires a stated reason** ("no build script in `package.json`") — N/A must
 never stand in for "didn't get to it."
 
+**Capture the exit code of the command itself, never of a pipeline.** Run the
+bare command, then read `$?` on the next line:
+
+```
+node "$f" > /tmp/out 2>&1; e=$?
+```
+
+`$?` after a pipe is the *last element's* status, so the common shape
+`out=$(cmd 2>&1 | tail -1); echo "exit=$?"` reports `tail`'s success — `0` —
+for a suite that exited `2`. Reproduced: a check printing "exit 2:
+prerequisites missing" was recorded as a pass by exactly that loop. Nor does
+`${PIPESTATUS[0]}` rescue it inside a command substitution; it is empty by
+the time you read it. This is the rule the whole gate rests on, and the
+piped form is the natural way to write a multi-suite loop, so it fails
+silently and in the unsafe direction.
+
 ## Checklist
 - [ ] **Tests pass** — run the project's real test command (`npm test`,
       `pytest`, `go test ./...`, `cargo test`, `make test`).