@naswerks/engineering-loop 0.7.1 → 0.8.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.8.0",
       "source": "./"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "naswerks",
-  "version": "0.7.1",
+  "version": "0.8.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,111 @@ version is the one in `package.json` and `.claude-plugin/plugin.json`, which mus
 
 ## [Unreleased]
 
+## [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);
+}

package/bin/witness-bodycheck.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// A moved or filed file's body, byte-identical to its version at the old path in HEAD, its header aside:
+// the proof that a filing changed where a doc lives and its header, and nothing a reader relies on. The
+// header is a leading frontmatter block and any line matching --header-line (by default the loop's own
+// `<!-- meta: … -->` line). Read-only.
+//
+//   node witness-bodycheck.mjs <worktree> <newRelDir> <oldRelDir> <relPath>... [--header-line <regex>]
+//   node witness-bodycheck.mjs --self-test
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { flag, isMain, positionals, report, scratch } from './witness-lib.mjs';
+
+const DEFAULT_HEADER_LINE = '^<!-- meta: .*-->\\s*$';
+const sha = (text) => createHash('sha256').update(text).digest('hex').slice(0, 16);
+
+// The body of a file: what is left after its leading frontmatter and its header lines.
+export function bodyOf(text, headerLine = DEFAULT_HEADER_LINE) {
+  const fm = text.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+  const rest = fm ? text.slice(fm[0].length) : text;
+  const header = new RegExp(headerLine);
+  const lines = rest.split(/(?<=\n)/);
+  return { header: (fm ? fm[0] : '') + lines.filter((l) => header.test(l)).join(''), body: lines.filter((l) => !header.test(l)).join('') };
+}
+
+export function bodycheck(worktree, newDir, oldDir, files, headerLine = DEFAULT_HEADER_LINE) {
+  const out = [];
+  let bad = 0;
+  for (const f of files) {
+    const now = readFileSync(join(worktree, newDir, f), 'utf8');
+    let head;
+    try { head = execFileSync('git', ['-C', worktree, 'show', `HEAD:${oldDir}/${f}`], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }); }
+    catch { out.push(`?    ${f}: no HEAD version at ${oldDir}/${f}`); bad++; continue; }
+    const n = bodyOf(now, headerLine);
+    const h = bodyOf(head, headerLine);
+    const same = n.body === h.body;
+    if (!same) bad++;
+    out.push(`${same ? 'SAME' : 'DIFF'} ${f}: body ${sha(n.body)} vs HEAD ${sha(h.body)}; header now ${n.header.length} chars, HEAD header ${h.header.length} chars`);
+  }
+  out.push(bad ? `${bad} file(s) NOT proven` : 'all bodies byte-identical to HEAD');
+  return { ok: bad === 0, out };
+}
+
+function selfTest() {
+  const dir = scratch('witness-bodycheck');
+  try {
+    const git = (...args) => execFileSync('git', ['-C', dir, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    git('init', '-q');
+    mkdirSync(join(dir, 'research'), { recursive: true });
+    const body = '# A doc\n\n> what it is\n\nThe body a reader relies on.\n';
+    writeFileSync(join(dir, 'research', 'a.md'), body.replace('\n\n> what', '\n<!-- meta: type=research; status=draft -->\n\n> what'));
+    writeFileSync(join(dir, 'research', 'b.md'), body);
+    git('add', 'research');
+    git('-c', 'user.name=t', '-c', 'user.email=t@local', 'commit', '-q', '-m', 'docs');
+    mkdirSync(join(dir, 'archive'), { recursive: true });
+    writeFileSync(join(dir, 'archive', 'a.md'), body.replace('\n\n> what', '\n<!-- meta: type=research; status=archived -->\n\n> what'));
+    writeFileSync(join(dir, 'archive', 'b.md'), `---\nstatus: deprecated\n---\n${body.replace('relies on', 'once relied on')}`);
+    const { out } = bodycheck(dir, 'archive', 'research', ['a.md', 'b.md']);
+    return report('witness-bodycheck', [
+      { name: 'a filed doc whose header alone changed reads SAME', ok: out.some((l) => l.startsWith('SAME a.md')), detail: out.join(' | ') },
+      { name: 'CONTROL: a filed doc whose body changed reads DIFF, header aside', ok: out.some((l) => l.startsWith('DIFF b.md')), detail: out.join(' | ') },
+    ]);
+  } 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(selfTest());
+  const [worktree, newDir, oldDir, ...files] = positionals(argv, ['--header-line']);
+  if (!worktree || !newDir || !oldDir || files.length === 0) { console.log('usage: witness-bodycheck.mjs <worktree> <newRelDir> <oldRelDir> <relPath>... [--header-line <regex>]'); process.exit(2); }
+  const { ok, out } = bodycheck(worktree, newDir, oldDir, files, flag(argv, '--header-line') ?? DEFAULT_HEADER_LINE);
+  for (const line of out) console.log(line);
+  process.exit(ok ? 0 : 1);
+}

package/bin/witness-edits.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Every edit and write a session made in a time window, the old and new text clipped, and its own words
+// that match a filter: how to tell "fixed the code" from "loosened the test". Read-only.
+//
+//   node witness-edits.mjs <file.jsonl> <fromIso> <toIso> [textFilterRegex] [--worktree-key <folder>]
+//   node witness-edits.mjs --self-test
+
+import { rmSync } from 'node:fs';
+import { assistantText, at, clip, contentOf, entries, flag, isMain, positionals, report, scratch, toolUse, writeTranscript } from './witness-lib.mjs';
+
+export async function edits(file, from, to, filter = null, key = null) {
+  const textFilter = filter ? new RegExp(filter, 'i') : null;
+  const out = [];
+  for await (const { entry } of entries(file)) {
+    const ts = entry.timestamp ?? '';
+    if (ts < from || ts > to) continue;
+    for (const c of contentOf(entry)) {
+      if (c.type === 'tool_use' && /^(Edit|Write|MultiEdit)$/.test(c.name)) {
+        const full = String(c.input?.file_path ?? '');
+        const path = key ? (full.split(new RegExp(`${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[\\\\/]`))[1] ?? full) : full;
+        out.push(`${ts.slice(11, 19)} ${c.name} ${path}`);
+        if (c.name === 'Edit') {
+          out.push(`   - ${clip(c.input.old_string, 240)}`);
+          out.push(`   + ${clip(c.input.new_string, 240)}`);
+        }
+      } else if (c.type === 'text' && textFilter && textFilter.test(c.text ?? '')) {
+        out.push(`${ts.slice(11, 19)} TEXT ${clip(c.text, 420)}`);
+      }
+    }
+  }
+  return out;
+}
+
+async function selfTest() {
+  const dir = scratch('witness-edits');
+  try {
+    const file = writeTranscript(dir, 'seat.jsonl', [
+      toolUse(1, 'a', 'Edit', { file_path: 'C:/work/pipeline-7/src/a.ts', old_string: 'return 1', new_string: 'return 2' }),
+      toolUse(10, 'b', 'Edit', { file_path: 'C:/work/pipeline-7/tests/a.test.ts', old_string: 'assert.equal(x, 2)', new_string: 'assert.ok(x)' }),
+      assistantText(11, 'I loosened the assertion so the test passes'),
+      toolUse(30, 'c', 'Write', { file_path: 'C:/work/pipeline-7/src/b.ts' }),
+    ]);
+    const lines = await edits(file, at(5), at(20), 'loosened', 'pipeline-7');
+    return report('witness-edits', [
+      { name: 'an edit in the window is listed with its old and new text, path inside the worktree', ok: lines.some((l) => l.endsWith('Edit tests/a.test.ts')) && lines.some((l) => l.includes('- assert.equal(x, 2)')), detail: lines.join(' | ') },
+      { name: 'the session\'s own words matching the filter are listed', ok: lines.some((l) => l.includes('TEXT I loosened the assertion')), detail: lines.join(' | ') },
+      { name: 'CONTROL: edits outside the window are not', ok: !lines.some((l) => l.includes('src/a.ts') || l.includes('src/b.ts')), detail: lines.join(' | ') },
+    ]);
+  } 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 [file, from, to, filter] = positionals(argv, ['--worktree-key']);
+  if (!file || !from || !to) { console.log('usage: witness-edits.mjs <file.jsonl> <fromIso> <toIso> [textFilterRegex] [--worktree-key <folder>]'); process.exit(2); }
+  for (const line of await edits(file, from, to, filter ?? null, flag(argv, '--worktree-key') ?? null)) console.log(line);
+}