@naswerks/engineering-loop 0.7.1 → 0.9.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "naswerks",
       "description": "The engineering loop: docs-* knowledge loop, spec-* execution loop, and init for a fresh repository.",
-      "version": "0.7.1",
+      "version": "0.9.0",
       "source": "./"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "naswerks",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "The engineering loop: a knowledge loop (docs-*) and an execution loop (spec-*) for repositories driven by hosted agent sessions, plus init to make a repository ready for both.",
   "author": { "name": "naswerks" },
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,205 @@ version is the one in `package.json` and `.claude-plugin/plugin.json`, which mus
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-11-14
+
+A minor: the skills act differently, the doctor can newly fail a brief, and a repository's copy of the loop text
+takes one paragraph (§ Upgrading from 0.8). A pipeline that writes one repository runs as it did.
+
+### Added
+
+- **A seat may also write a second repository: the `Repository` column.** A sequence row names the repositories its
+  seat also writes in, in an optional `Repository` column: one or more names, as the runner serves them. The column
+  never moves a seat: its home is the pipeline's own repository, where its spec, its board and the tracker are, and
+  one pull request still closes the pipeline. `spec-pipeline` states the column. `init doctor` reads it the way a
+  launcher does, and fails a cell holding a kind word, `step`, a name that is not one path segment of at most 200
+  characters, a ninth name, or a name twice. **A pipeline that writes one repository has no such column and is
+  unchanged.**
+- **What a seat does in a second repository** (`spec-seat` § Git shapes, `spec-build`). Its home stays this
+  repository and nothing of the pipeline's record is written in the other one. Its code goes in its own tree of
+  that repository, never the owner's checkout: hosted, at the path the variable its seed names holds; by hand, at
+  the path its prompt names. Then a staging list, a `verify-staged` receipt, a commit and a push per repository;
+  that repository's whole gate, run in its tree; its own rules for commit and pull-request text; a draft pull
+  request where it checks them, its checks read after every push; no merge, tag or publish. Its commit there goes
+  on an `ALSO WRITING` line beneath BELIEFS, and its FINAL gives a list and a receipt per repository. A pin holds
+  every clause, because a launcher that knows this version says only where the tree is.
+- **The push in a second repository has its own form:** `cd` into the tree, then the push, and nothing else on the
+  line. `spec-seat` said a leading `cd` disqualifies every push; that is the rule for the home repository, and it
+  now says so.
+- **The coordinator's and the review's side of a second repository.** `spec-coordinator` tells such a seat where
+  its tree is and nothing else (by hand; hosted, the seed says where), diffs its `ALSO WRITING` line, checks two
+  receipts at the FINAL, reads a pull request's checks at every seat report in whichever repository the branch is,
+  and hands the review one diff range per repository (by release tags when the run released it mid-run).
+  `spec-review` reads each range and the seam between them. A pin holds every template line for a further
+  repository under a line saying when it applies.
+- **A conditional fixit that must write a further repository is listed as a row, directly after the review row**
+  (`spec-pipeline`). Listed anywhere else, a launcher reads a second fixit beside the one the review implies, and
+  the doctor names it.
+- **The model and the effort a run starts on are named in the brief and read back.** `spec-pipeline`'s `## Birth`
+  names both, each in backticks, because the launcher reads them from that section; a brief that names neither
+  leaves both to the launcher's default. A seat's BELIEFS line states the model and effort its session is running
+  on, as it can read them, and `spec-coordinator` settles a seat on a pair the brief does not name before it rules
+  that seat's plan.
+
+### Changed
+
+- **Pipelines never intertwine** replaces "one pipeline at a time", in `spec-coordinator`'s hard rules and in
+  `references/engineering-loop.md`. A brief's GATE still checks only that its predecessor merged, and no seat waits
+  on another pipeline; independent pipelines may run at the same time, each on its own branch. The coordinator takes
+  a moved base branch in between seats, by a merge. A repository's `docs/_meta/` copy takes the paragraph by hand.
+- **A review's diff range reads the remote's copy of the base branch** (`origin/{base}...{branch}`), in
+  `spec-coordinator`'s REVIEW manifest, `spec-review` and `spec-pipeline`: a local base branch can sit behind it and
+  pull another effort's commits into the range.
+- **`spec-coordinator`'s Step 0 is two numbered reads:** the seven floor docs, then every doc the repository's role
+  reading lists carry a path for. The second read was a trailing clause, and coordinators read the floor and stopped.
+  The status readback opens with how many docs each read took.
+- **The coordinator edits its tracker and a seat's board with file tools, never a shell heredoc or an interpreter
+  one-liner** (`spec-coordinator`): one collapses backslashes, and one whose text quotes a publish is held.
+
+### Fixed
+
+- `spec-coordinator` said a backticked sha is fine for the plan verdict's workspace HEAD. The verb takes only the
+  bare 40-hex sha and refuses a backticked or quoted one, recording nothing, so a coordinator that followed the skill
+  spent a refused call on every plan ruling. It now says the bare sha; a seat's board may still fence its own.
+- `spec-coordinator` wrote an amount as a dollar sign before a digit, which a harness that substitutes a skill's
+  arguments by position rewrote at load: the line about uncosted turns read with the invocation's first argument in
+  the amount's place. The amount is spelled out, and a pin holds every skill's text free of a dollar sign before a
+  digit and of the arguments token.
+- `spec-seat`, `spec-coordinator` and `spec-retro` said the gate matches text and told a seat to keep git words out
+  of echo labels, section headers and searches. The gate reads the command the shell would run: what parks is the
+  operation, at any depth, and an echo label, a branch listing and a quoted search are data unless something on the
+  line could run them. Six passages say so now, in fewer lines, and a pin keeps the old rule out.
+- `spec-seat` said the HEAD check takes the first `HEAD <sha>` it meets. It reads the newest line that carries
+  `BELIEFS`, so a seat whose HEAD moved appends a new BELIEFS line and never edits the old one.
+
+### Upgrading from 0.8
+
+In this order:
+
+1. **Take the release where every session loads it:** `claude plugin marketplace update engineering-loop`, then
+   `claude plugin update naswerks@engineering-loop --scope <scope>` for each scope that runs sessions, and a new
+   session. A runner takes `@naswerks/engineering-loop@0.9.0` in the folder its plugin directories name, and is
+   restarted by its owner with no seat live.
+2. **Replace one paragraph of loop text.** In `docs/_meta/engineering-loop.md`, the paragraph that opens
+   **One pipeline at a time.** becomes:
+
+   > **Pipelines never intertwine.** A pipeline's GATE is that its predecessor merged — never a seat of another
+   > pipeline — and no seat waits on another pipeline. Independent pipelines may run at the same time, each on
+   > its own branch, merged one after the other.
+
+   It is the only loop text that changed. `docs/_meta/docs-workflow.md` takes nothing but its stamp, and the four
+   repository-owned sections are yours and are not touched.
+3. **Restamp and check:** `init refresh` (with `--write`) restamps both copies and leaves every other line as it
+   is; then `init doctor`. A repository that read clean on 0.8.0 reads clean, unless a brief lists a `fixit` row
+   away from its `review` row or holds a `Repository` cell that is not a list of names.
+
+No pipeline folder changes shape, and a sequence with no `Repository` column reads as it always has.
+
+## [0.8.0] - 2026-10-21
+
+A minor: the skills act differently, and a repository must act — its method docs take new text, and every
+pipeline folder in the old shape is carried over before it runs on this version (§ Upgrading from 0.7).
+
+### Changed
+
+- **One brief per pipeline.** A pipeline folder is `00-ignition-brief.md` — the coordinator seat's spec and
+  the charter every seat reads, never a session — and `01..NN-{slice}.md`, each one build seat's spec. The
+  umbrella `01-{topic}.md` is gone: its vision, settled decisions, hard constraints and sources live in the
+  brief's `## Why`, `## The owner's rulings`, `## Law`, `## What this effort does NOT do` and
+  `## Where it came from`. The brief's sections down to § Platform state bind every seat; its beliefs,
+  close-out and kick are the coordinator's. Its H1 is the pipeline's title. The sequence is written once, in
+  the brief; the tracker's status lines name its rows by id and copy nothing, and its `## Settled decisions`
+  is `## Rulings made during the run`. `spec-pipeline`'s template, the coordinator's reading order and its
+  one-comparison shape check, `spec-ignite`'s stage card, the build seat's reading list, the review's
+  inventory (the brief down to § Platform state, read as claims), `docs-process` and `docs-write` (the
+  brief's `Archive:` line) all say so. No skill carries a fallback for the old shape.
+- **`step` rows and a role cell.** A sequence row that is not a seat — a publish, a merge, a human sitting
+  — says `step` in its `Kind` cell, and is shown on the stage card and never staged. A misspelled kind is
+  still refused by name, because no misspelling can equal `step`. A seat row may carry `backend`,
+  `frontend` or `mixed` in a `Role` column. A human step files `sessions/{step-slug}/receipt.md`.
+- **The hand-cranked relay.** A seat posts its PLAN TLDR and questions in the chat; the coordinator
+  answers in one message of notes; on the human's approval the seat writes `plan.md` and `tldr.md` with
+  the notes transcribed verbatim and runs to done without a stop — build, suites, `docs-write`, commits with
+  `verify-staged`, its branch pushes — then posts its FINAL TLDR. The coordinator writes its acceptance into
+  the seat's `tldr.md` after the push. The hosted ceremony is unchanged.
+- **Live checks are the owner's.** `live-checks.md` is created with no rows and holds only the rows the
+  owner dictates; the coordinator writes a row only on the owner's word and never aggregates seats' checks
+  into it; a seat's FINAL TLDR section (e) is "what the owner could try", in the chat; the close offers the
+  owner a short, ordered quick pass; `docs-process` adds no live check to a living doc.
+- **The owner's standing rules:** one pipeline at a time (a GATE checks only that the predecessor merged);
+  approved work includes its commit, its push and the coordinator's PR, and nobody asks for them again; the
+  floor is cited from the brief's `## Baselines` and measured only for a lane the brief does not name.
+- **What three watched runs taught the ceremony.** `spec-coordinator`: a ruling that binds a running seat
+  goes onto its board in the same act as the tracker entry; a ruling counts only when its act lands;
+  append at the end of a seat's file; stop instead of sleep-polling when the plane's calls fail; never advise
+  a runner restart while a seat is live; an escalation is an act; keep each seed as sent; the hosted seed
+  stops restating the skills and the role; the commit call no longer stages the tracker. `spec-seat`: write
+  the board with the file tools, never a heredoc; the BELIEFS line near the top of both files; never route
+  around a refusal by disguising a path. `spec-review`: its inventory wins over a narrower brief, and the
+  report says whether it was cold or warm. `docs-process`: its board lives in `sessions/docs-process/`, and
+  every input arrives as a list. `spec-retro`: a witness ledger is an input.
+- **`spec-witness` is the outside watcher's playbook:** a session outside the control plane, usually on
+  the runner's machine, never a declared seat, holding no credential — the packet, pre-registered
+  expectations, the identity map, the instruments that need no credential (git, the transcripts, the board
+  files, the process table, the plane's rows as another session's transcript shows them), what is and is
+  not an event, human touches, the watch, the ledger and the control-plane incident ledger.
+- `references/docs-workflow.md` takes the retire path for research the platform moved past
+  (`archive/retired/`) and the provenance exception to the archive's frozen links.
+
+### Added
+
+- `bin/witness-*.mjs`, the witness's tools: a config-driven watcher (`witness-watch`) and the transcript,
+  git and process probes `spec-witness` names, each with a `--self-test` that `npm test` runs. A run's own
+  facts — its worktree, its folders, the plane's tool prefix, the process pattern, the noise paths — live in
+  a `witness.config.json` beside the witness's folder.
+- `init doctor` reads `step` rows and the role cell, and a pipeline folder whose `01-` file no sequence row
+  names reads DEGRADE: "old shape — fold `01-{topic}.md` into the brief (CHANGELOG 0.8.0 § Upgrading)".
+- Pins: `pins/shape.test.mjs` (a `step` row and its misspelled-kind control, the role cell, the old-shape
+  row and its control, one `## The sequence` in the template, no umbrella in any skill) and
+  `pins/witness-tools.test.mjs`; the content census reads `bin/` too.
+
+### Fixed
+
+- `verify-staged` on a large repository: every listing is read for the expected paths only, and an output
+  past the buffer is an ERROR by name. A full listing over Node's default 1 MiB buffer made
+  `--against head` print "HEAD is unreadable" and call a committed file never-added, and made the index
+  mode fail the same way.
+
+### Upgrading from 0.7
+
+In this order:
+
+1. **Take the release where every session loads it:** `claude plugin marketplace update engineering-loop`,
+   then `claude plugin update naswerks@engineering-loop --scope <scope>`, and a new session. A runner that
+   loads the pack from an npm install takes `@naswerks/engineering-loop@0.8.0` there (its pinned
+   `package.json`, or a global install) and is restarted by its owner with no seat live — a runner left on
+   0.7 serves the 0.7 skills, which read the old shape.
+2. **Re-copy the loop text** of both references into `docs/_meta/`. The four repository-owned sections are
+   yours, so neither the re-copy nor `init refresh` touches them; three carry changed text, offered as
+   replacements you take or fit to your own patterns: § The archive convention (the `research/` retire
+   path, the provenance exception and the `archive/retired/` home, the `specs/` line
+   `00-ignition-brief · 01..NN slices`, the sessions map, the brief in a follow-on's back-link),
+   § Doc metadata (the ignition brief goes in `Idea`), § Templates (the spec-doc preamble and its
+   `Source: [brief / research]`). Then `init refresh` restamps both copies, and `init doctor` lists the
+   folders to carry.
+3. **Carry every old-shape folder over before it runs on 0.8.0** — each one the doctor marks "old shape". A
+   pipeline that is mid-run finishes on its old pack first; never carry a live one. Per folder:
+   - **Fold the umbrella into the brief, section by section, losing nothing:** its vision into `## Why`,
+     its settled decisions into `## The owner's rulings`, its hard constraints into `## Law` and
+     `## What this effort does NOT do`, its research sources into `## Where it came from` (with its
+     `Archive:` line), and anything else into the section that fits or a `## Reference`. The brief's H1
+     becomes the pipeline's title — the umbrella's H1 — and its blockquote says every seat reads it.
+   - **One sequence:** reconcile the brief's `## The sequence` with the umbrella's row table and the
+     tracker, keep it in the brief alone, and write each prose step (a publish, a merge, a human sitting) as
+     a `step` row in its place.
+   - **The tracker stops copying:** its status lines name the brief's rows by id, and
+     `## Settled decisions` becomes `## Rulings made during the run`, holding only what the run ruled.
+   - **Delete the umbrella**, and repair every link to it outside `docs/archive/` and `sessions/**` to point
+     at the brief. Archives and testimony are never edited.
+   - **Keep the specs' numbers.** A spec that was `02-` stays `02-`; the gap at `01` is the umbrella's.
+   - **Check it:** every heading of the old umbrella is found in the brief or named where it merged, and
+     `init doctor` reads the folder with no "old shape" row and no FAIL.
+
 ## [0.7.1] - 2026-10-04
 
 ### Changed

package/README.md

@@ -74,7 +74,7 @@ and never touches the rest of the text.
 | `spec-build` | spec | the build job for one spec |
 | `spec-review` | spec | the outside look before the retrospective |
 | `spec-retro` | spec | the coordinator's close-out audit |
-| `spec-witness` | spec | a read-only verifier |
+| `spec-witness` | spec | the outside watcher: read-only, no credential, never a declared seat |
 | `spec-ignite` | spec | the ignition copilot for a hosted run |
 | `init` | — | make a repository ready for both loops; `init doctor` checks one, `init refresh` takes a newer pack's repository-owned sections |
 
@@ -82,7 +82,9 @@ and never touches the rest of the text.
 rewrites where they say (repository-owned);
 `bin/verify-staged` is the staging receipt the seats run between `git add` and `git commit`. A
 marketplace install puts nothing on PATH: `npm i -g @naswerks/engineering-loop` does, and the skills
-carry the fallback `node <pack root>/bin/verify-staged.mjs`.
+carry the fallback `node <pack root>/bin/verify-staged.mjs`. `bin/witness-*.mjs` are the witness's tools —
+a config-driven watcher and the transcript, git and process probes `spec-witness` names — run by path,
+each with a `--self-test`; a run's own facts live in a `witness.config.json` beside the witness's folder.
 
 Running a skill through a child `claude -p` from inside another Claude Code session: scrub the
 `CLAUDE_CODE_*` variables from the child's environment and name the repository root in the prompt,
@@ -92,11 +94,14 @@ or the child may resolve `docs/` paths against the parent session's workspace.
 
 `npm test` runs the pins: one version across the package, the plugin manifest, the marketplace entry and
 both method documents' stamps; every skill directory carries a `SKILL.md` named for its folder; no
-byte-order marks; the vocabulary and content censuses; no skill states a format a repository owns, and
-every skill that needs one carries the same find-format line; exactly four repository-owned sections, found
-by the one grep; the loop's own preferences stay stated in the method documents; the menu's two shapes; `init refresh` leaves
-every line outside those sections byte for byte. `node bin/verify-staged.mjs --self-test` drives the
-receipt against a throwaway repository and reports each case.
+byte-order marks; the vocabulary and content censuses, `bin/` included; no skill states a format a
+repository owns, and every skill that needs one carries the same find-format line; exactly four
+repository-owned sections, found by the one grep; the loop's own preferences stay stated in the method
+documents; the menu's two shapes; `init refresh` leaves every line outside those sections byte for byte;
+the pipeline folder's shape (a `step` row reads ok and a misspelled kind still fails, a role cell, the
+old-shape row, one sequence, no umbrella); and every witness tool's self-test.
+`node bin/verify-staged.mjs --self-test` drives the receipt against throwaway repositories, one of them
+past Node's default 1 MiB listing buffer, and reports each case.
 
 ## Releasing
 

package/bin/verify-staged.mjs

@@ -16,6 +16,10 @@
 // Deliberately not a fix for .gitignore: widening or anchoring a repository's ignore rules is a
 // repository decision, and force-adding against one is a ruling, not a default.
 //
+// Every listing is read for the expected paths only, never for the whole tree: a large repository's
+// full listing is megabytes, and a listing cut short by a buffer reads as files that were never added.
+// An output that still overflows is an ERROR by name, never a partial listing.
+//
 // Paths with embedded newlines are not supported (line-delimited git output, core.quotepath=false).
 
 import { execFileSync } from 'node:child_process';
@@ -24,20 +28,49 @@ import { tmpdir } from 'node:os';
 import { isAbsolute, join, sep } from 'node:path';
 
 const DIR_EXPANSION_CAP = 2000;
+const MAX_BUFFER = 256 * 1024 * 1024;
+// Paths per git call, so one call stays well under the Windows command-line limit.
+const PATHSPEC_BATCH = 100;
 
-function git(root, args) {
+function git(root, args, maxBuffer = MAX_BUFFER) {
   try {
     const out = execFileSync('git', ['-C', root, '-c', 'core.quotepath=false', ...args], {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
+      maxBuffer,
     });
-    return { ok: true, exit: 0, lines: out.split(/\r?\n/).filter((l) => l.length > 0) };
+    return { ok: true, exit: 0, overflow: false, lines: out.split(/\r?\n/).filter((l) => l.length > 0) };
   } catch (e) {
     const out = typeof e.stdout === 'string' ? e.stdout : '';
-    return { ok: false, exit: typeof e.status === 'number' ? e.status : 1, lines: out.split(/\r?\n/).filter((l) => l.length > 0) };
+    return {
+      ok: false,
+      exit: typeof e.status === 'number' ? e.status : 1,
+      overflow: e.code === 'ENOBUFS',
+      lines: out.split(/\r?\n/).filter((l) => l.length > 0),
+    };
   }
 }
 
+// One listing, read for the given paths only, in batches. Each path is a literal pathspec (case-insensitive
+// when the repository is), so a path holding `*` or `?` names itself and nothing else.
+function gitFor(root, args, paths, caseInsensitive, maxBuffer) {
+  const lines = [];
+  const magic = caseInsensitive ? ':(literal,icase)' : ':(literal)';
+  for (let i = 0; i < paths.length; i += PATHSPEC_BATCH) {
+    const batch = paths.slice(i, i + PATHSPEC_BATCH).map((p) => magic + p);
+    const r = git(root, [...args, '--', ...batch], maxBuffer);
+    if (!r.ok) return { ...r, lines: [...lines, ...r.lines] };
+    lines.push(...r.lines);
+  }
+  return { ok: true, exit: 0, overflow: false, lines };
+}
+
+const overflowFinding = (what) => ({
+  file: what,
+  state: 'ERROR',
+  detail: 'git output exceeded the buffer, so this listing is incomplete and nothing is judged against it',
+});
+
 function toRepoRelative(root, input) {
   let p = input.trim().replace(/\\/g, '/').replace(/\/+$/, '');
   if (isAbsolute(p) || /^[A-Za-z]:\//.test(p)) {
@@ -48,33 +81,21 @@ function toRepoRelative(root, input) {
   return p.length === 0 ? null : p;
 }
 
-export function testStagedList(root, paths, mode = 'index') {
+export function testStagedList(root, paths, mode = 'index', options = {}) {
+  const maxBuffer = options.maxBuffer ?? MAX_BUFFER;
   const findings = [];
   const notes = [];
-  const top = git(root, ['rev-parse', '--show-toplevel']);
+  const top = git(root, ['rev-parse', '--show-toplevel'], maxBuffer);
   if (!top.ok || top.lines.length === 0) {
     findings.push({ file: root, state: 'ERROR', detail: 'not inside a git repository (rev-parse --show-toplevel failed)' });
     return { ok: false, findings, notes, expected: 0, green: 0 };
   }
   const repoTop = top.lines[0];
-  const igc = git(root, ['config', 'core.ignorecase']);
+  const igc = git(root, ['config', 'core.ignorecase'], maxBuffer);
   const caseInsensitive = igc.ok && igc.lines[0]?.trim() === 'true';
   const key = (s) => (caseInsensitive ? s.toLowerCase() : s);
   const setOf = (lines) => new Set(lines.map(key));
 
-  const tracked = setOf(git(root, ['ls-files', '--cached']).lines);
-  let head = null;
-  let staged = null;
-  let dirty = null;
-  if (mode === 'head') {
-    const lsTree = git(root, ['ls-tree', '-r', '--name-only', 'HEAD']);
-    head = setOf(lsTree.lines);
-    if (!lsTree.ok) notes.push('HEAD is unreadable (empty repository?) - every expected file will read as missing from HEAD');
-  } else {
-    staged = setOf(git(root, ['diff', '--cached', '--no-renames', '--name-only']).lines);
-    dirty = setOf(git(root, ['diff', '--name-only']).lines);
-  }
-
   const expected = [];
   const seen = new Set();
   for (const raw of paths) {
@@ -87,12 +108,19 @@ export function testStagedList(root, paths, mode = 'index') {
     const onDisk = join(repoTop, rel.split('/').join(sep));
     if (existsSync(onDisk) && statSync(onDisk).isDirectory()) {
       const inDir = [];
+      let overflowed = false;
       for (const spec of [
         ['ls-files', '--cached', '--', rel],
         ['ls-files', '--others', '--exclude-standard', '--', rel],
         ['ls-files', '--others', '--ignored', '--exclude-standard', '--', rel],
       ]) {
-        inDir.push(...git(root, spec).lines);
+        const r = git(root, spec, maxBuffer);
+        if (r.overflow) overflowed = true;
+        inDir.push(...r.lines);
+      }
+      if (overflowed) {
+        findings.push(overflowFinding(rel));
+        continue;
       }
       if (inDir.length > DIR_EXPANSION_CAP) {
         findings.push({ file: rel, state: 'TOO-BROAD', detail: `directory expands to ${inDir.length} files (cap ${DIR_EXPANSION_CAP}) - name explicit paths` });
@@ -109,6 +137,35 @@ export function testStagedList(root, paths, mode = 'index') {
     }
   }
 
+  // The listings, for the expected paths only.
+  const read = (args) => gitFor(root, args, expected, caseInsensitive, maxBuffer);
+  const lsFiles = read(['ls-files', '--cached']);
+  const listings = [lsFiles];
+  let head = null;
+  let staged = null;
+  let dirty = null;
+  if (mode === 'head') {
+    // `ls-tree` takes no `icase` magic, so on a case-insensitive repository each expected path is read in
+    // the case the index spells it (after the commit, the index and HEAD agree on every committed path).
+    const spelled = new Map(lsFiles.lines.map((l) => [key(l), l]));
+    const asCommitted = expected.map((p) => spelled.get(key(p)) ?? p);
+    const lsTree = gitFor(root, ['ls-tree', '-r', '--name-only', 'HEAD'], asCommitted, false, maxBuffer);
+    listings.push(lsTree);
+    head = setOf(lsTree.lines);
+    if (!lsTree.ok && !lsTree.overflow) notes.push('HEAD is unreadable (empty repository?) - every expected file will read as missing from HEAD');
+  } else {
+    const cached = read(['diff', '--cached', '--no-renames', '--name-only']);
+    const worktree = read(['diff', '--name-only']);
+    listings.push(cached, worktree);
+    staged = setOf(cached.lines);
+    dirty = setOf(worktree.lines);
+  }
+  if (listings.some((l) => l.overflow)) {
+    findings.push(overflowFinding(`${expected.length} expected file(s)`));
+    return { ok: false, findings, notes, expected: expected.length, green: 0 };
+  }
+  const tracked = setOf(lsFiles.lines);
+
   let green = 0;
   for (const f of expected) {
     const onDisk = join(repoTop, f.split('/').join(sep));
@@ -157,6 +214,16 @@ function report(result, mode, pathCount) {
   console.log('  git add -f is a ruling, not a default, and .gitignore is never edited from a seat.');
 }
 
+// A throwaway tree's removal. Windows can still hold files git just wrote, so the removal retries; one that
+// still fails is a warning naming the folder, never a failed self-test — the verdict is the cases'.
+function cleanUp(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+  } catch (e) {
+    console.log(`  warning: could not remove the self-test folder ${dir} (${e.code ?? e.message}); remove it by hand`);
+  }
+}
+
 function selfTest() {
   const tmp = mkdtempSync(join(tmpdir(), 'verify-staged-selftest-'));
   const cases = [];
@@ -179,11 +246,14 @@ function selfTest() {
     git(tmp, ['-c', 'user.name=selftest', '-c', 'user.email=selftest@local', 'commit', '-q', '-m', 'selftest']);
     cases.push({ name: 'positive control: committed-clean is a note, not a red', shouldFail: false, result: testStagedList(tmp, ['docs/session/a.md']) });
     cases.push({ name: 'head mode: the eaten receipt is absent from the commit', shouldFail: true, result: testStagedList(tmp, ['docs/session'], 'head'), expect: 'IGNORED', detail: '' });
+    cases.push(...largeTreeCases());
 
     let failed = 0;
     for (const c of cases) {
       let verdict;
-      if (c.shouldFail) {
+      if (c.verdict !== undefined) {
+        verdict = c.verdict;
+      } else if (c.shouldFail) {
         const hit = c.result.findings.filter((f) => f.state === c.expect);
         if (c.result.ok) verdict = 'DID NOT FIRE - the detector is broken';
         else if (hit.length === 0) verdict = `fired with the WRONG state (wanted ${c.expect})`;
@@ -196,13 +266,56 @@ function selfTest() {
       console.log(`  [${verdict.startsWith('PASS') ? 'PASS' : 'FAIL'}] ${c.name}: ${verdict}`);
     }
     if (failed === 0) {
-      console.log('SELF-TEST PASSED: the detector fires on both ignore sightings, discriminates never-added from ignored, and stays silent on good input.');
+      console.log('SELF-TEST PASSED: the detector fires on both ignore sightings, discriminates never-added from ignored, stays silent on good input, and reads a repository whose listing is over 1 MiB.');
       return 0;
     }
     console.log(`SELF-TEST FAILED: ${failed} case(s) - do not trust this detector until it fires correctly.`);
     return 1;
   } finally {
-    rmSync(tmp, { recursive: true, force: true });
+    cleanUp(tmp);
+  }
+}
+
+// A repository whose full listing is over 1 MiB: twelve thousand paths written to the index alone (no files
+// on disk) and committed, plus one real file that sorts after all of them, so a listing cut short at the
+// buffer is exactly the listing that loses it. The CONTROL reads the full listing at Node's default buffer
+// and must overflow; if it does not, the fixture is too small to prove anything about a large repository.
+function largeTreeCases() {
+  const tmp = mkdtempSync(join(tmpdir(), 'verify-staged-large-'));
+  try {
+    git(tmp, ['init', '-q']);
+    writeFileSync(join(tmp, 'zz-kept.md'), 'committed\n');
+    git(tmp, ['add', 'zz-kept.md']);
+    const blob = execFileSync('git', ['-C', tmp, 'hash-object', '-w', '--stdin'], { input: 'padding\n', encoding: 'utf8' }).trim();
+    const folder = `padding/${'p'.repeat(80)}`;
+    const entries = [];
+    for (let i = 0; i < 12000; i++) entries.push(`100644 ${blob}\t${folder}/${String(i).padStart(5, '0')}.txt`);
+    execFileSync('git', ['-C', tmp, 'update-index', '--index-info'], { input: `${entries.join('\n')}\n` });
+    git(tmp, ['-c', 'user.name=selftest', '-c', 'user.email=selftest@local', 'commit', '-q', '-m', 'large']);
+
+    let overflowed = false;
+    try {
+      execFileSync('git', ['-C', tmp, 'ls-tree', '-r', '--name-only', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    } catch (e) {
+      overflowed = e.code === 'ENOBUFS';
+    }
+    return [
+      {
+        name: 'CONTROL: the large fixture\'s full listing overflows the default buffer',
+        verdict: overflowed ? 'PASS - the fixture is over 1 MiB' : 'the full listing fit the default buffer - the fixture proves nothing',
+      },
+      { name: 'large repository, head mode: a committed file reads IN-HEAD', shouldFail: false, result: testStagedList(tmp, ['zz-kept.md'], 'head') },
+      { name: 'large repository, index mode: thousands of index-only paths do not hide a clean file', shouldFail: false, result: testStagedList(tmp, ['zz-kept.md']) },
+      {
+        name: 'an overflowing listing is an ERROR by name, never a partial listing',
+        shouldFail: true,
+        result: testStagedList(tmp, ['padding'], 'index', { maxBuffer: 64 * 1024 }),
+        expect: 'ERROR',
+        detail: 'exceeded the buffer',
+      },
+    ];
+  } finally {
+    cleanUp(tmp);
   }
 }
 

package/bin/witness-acts.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Every control-plane write in a transcript, and every plane call that failed, with its act number and
+// outcome: the plane's rows as one session's tool results show them. Name them "rows via transcript" in a
+// ledger, never a row you read. Read-only.
+//
+//   node witness-acts.mjs <label> <file.jsonl> [--plane <server>] [--config <path>]
+//   -> TSV: time, label, verb, seat, act, ok|ERROR, detail
+//   node witness-acts.mjs --self-test
+
+import { rmSync } from 'node:fs';
+import { PLANE_READS, clip, contentOf, entries, isMain, loadConfig, planePrefix, positionals, report, resultText, scratch, toolResult, toolUse, writeTranscript } from './witness-lib.mjs';
+
+export async function acts(file, prefix, label) {
+  const uses = new Map();
+  const out = [];
+  for await (const { entry } of entries(file)) {
+    for (const c of contentOf(entry)) {
+      if (c.type === 'tool_use' && typeof c.name === 'string' && c.name.startsWith(prefix)) {
+        uses.set(c.id, { ts: entry.timestamp ?? '', verb: c.name.slice(prefix.length), input: c.input ?? {} });
+      } else if (c.type === 'tool_result' && uses.has(c.tool_use_id)) {
+        const use = uses.get(c.tool_use_id);
+        uses.delete(c.tool_use_id);
+        if (PLANE_READS.test(use.verb) && !c.is_error) continue;
+        const body = resultText(c);
+        const act = body.match(/"spawnedActId":(\d+)/)?.[1] ?? body.match(/\bact (\d{3,})/)?.[1] ?? '';
+        const detail = c.is_error ? body : (use.input.verdict ?? use.input.ruling ?? use.input.basis ?? use.input.path ?? '');
+        out.push([`${String(use.ts).slice(0, 19)}Z`, label, use.verb, use.input.seatId ?? '', act, c.is_error ? 'ERROR' : 'ok', clip(detail, 170)].join('\t'));
+      }
+    }
+  }
+  return out;
+}
+
+async function selfTest() {
+  const dir = scratch('witness-acts');
+  try {
+    const file = writeTranscript(dir, 'coordinator.jsonl', [
+      toolUse(1, 'a', 'mcp__plane__accept_plan', { seatId: 7, verdict: 'accept-with-riders' }),
+      toolResult(2, 'a', 'Accepted. Recorded as act 1234; delivery: delivered'),
+      toolUse(3, 'b', 'mcp__plane__seat_read', { seatId: 7 }),
+      toolResult(3, 'b', 'seat 7 is building'),
+      toolUse(4, 'c', 'mcp__plane__seat_acts', { seatId: 7 }),
+      toolResult(4, 'c', 'HTTP 404 from the plane', true),
+      toolUse(5, 'd', 'Read', { file_path: 'tldr.md' }),
+      toolResult(5, 'd', 'the board says act 9999 landed'),
+    ]);
+    const lines = await acts(file, 'mcp__plane__', 'coord');
+    return report('witness-acts', [
+      { name: 'a plane write is a line, with its act number', ok: lines.some((l) => l.includes('\taccept_plan\t7\t1234\tok\taccept-with-riders')), detail: lines.join(' | ') },
+      { name: 'a failed plane read is a line', ok: lines.some((l) => l.includes('\tseat_acts\t7\t\tERROR\tHTTP 404')), detail: lines.join(' | ') },
+      { name: 'CONTROL: a read that answered, and a Read of a file that mentions an act, are not', ok: lines.length === 2, detail: `${lines.length} lines` },
+    ]);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+if (isMain(import.meta.url)) {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--self-test')) process.exit(await selfTest());
+  const [label, file] = positionals(argv, ['--plane', '--config']);
+  if (!label || !file) { console.log('usage: witness-acts.mjs <label> <file.jsonl> [--plane <server>]'); process.exit(2); }
+  for (const line of await acts(file, planePrefix(argv, loadConfig(argv)), label)) console.log(line);
+}