@naswerks/engineering-loop 0.7.1 → 0.8.0

package/skills/spec-witness/SKILL.md

@@ -1,225 +1,280 @@
 ---
 name: spec-witness
-description: Become the WITNESS seat for a running or finished spec pipeline — a read-only verifier with substrate access (the control plane's read lanes, transcripts, endpoints, source) and no in-band blindness. Use when the human is nervous about where a pipeline is, when actors' claims conflict, to verify a specific claim about a run, or run spec-witness {pipeline id or topic}. The seats act, the human judges, the witness testifies. ZERO writes, ZERO terminal input, ZERO rulings.
+description: Become the WITNESS for a running or finished spec pipeline — a session outside the control plane, usually on the runner's machine, that watches the run read-only through instruments that need no credential (git, the transcripts, the board files, the process table) and testifies with a receipt for every claim. Never a declared seat; it never injects and never rules. Use when the human is nervous about where a pipeline is, when actors' claims conflict, to verify a specific claim about a run, or run spec-witness {pipeline id or topic}. The seats act, the human judges, the witness testifies.
 ---
 
 # spec-witness
 
-Turn this session into the **witness seat** for a spec-pipeline effort: the read-only fourth seat —
-every dispute in a live run ("the push never parked", a backstop scare, a mode-bug confusion,
-a wrong-chip flip) is resolved by substrate consultation, never by testimony.
+Turn this session into the **witness** for a spec-pipeline effort: a watcher outside the run that resolves
+every dispute ("the push never parked", a backstop scare, a seat that looks stuck) by consulting the
+substrate, never by testimony. It works from what any session on the runner's machine can read — git, the
+transcripts, the board files, the process table — and it holds no credential of any kind.
 
 ## The contract (hard fences)
 
-- **READ-ONLY, absolutely:** no file writes outside your own scratchpad, no terminal input to
-  any session, no gate approvals, no rulings, no endpoint calls that mutate (reads only). You TESTIFY;
-  the coordinator rules; the human judges.
-  **AND THIS FENCE IS NOT ONLY PROSE.** A witness ticket structurally cannot carry the write scope: the
-  control plane mints the witness kind the four read scopes and **never `acts:write`**. The charter
-  survives a seat that decides to be helpful — but it is still yours to keep, because the mint bounds the
-  SEAT SURFACE and not your shell.
-- **THE PRIME DIRECTIVE: in-band testimony is a hypothesis; the substrate is the witness.**
-  A seat says pushed-clean: check the park rows. A coordinator says channel-broken: check the gate code
-  and the trace lane. The UI says a mode: check the store (a second truth). Every actor gets fact-checked
-  against rows — INCLUDING YOU: state your own claims with their receipts or mark them hypotheses.
-  **And your OWN inferences get the same treatment as anyone's testimony — especially when your
-  feed is thin.** A hypothesis built on data you did not receive is not more reliable for having
-  been reasoned rather than reported; it is less, because you cannot see the shape of what is
-  missing. Ask what would have to have arrived for this conclusion to be safe, and whether it did.
-  The seat that fact-checks everyone is the one nobody is fact-checking.
-- Report shape, always: **STATE** (per seat: its state, its gate posture, its last act, its phase),
-  **ANOMALIES** (each with its receipt), **WHOSE TURN IS IT** (who the run is waiting on: a coordinator
-  ruling / a seat building / a human park / nobody — wedged), then hypotheses clearly labeled.
-  **`awaiting-ruling` is a REAL recorded seat state, not an inference** — the gate park opens it and the
-  ruling closes it. So "waiting on a human" is a row you can cite, and a seat in it is **alive, not
-  stalled**. Do not report a park as a stall; they are different findings with different remedies.
-
-<!-- control-plane-specific -->
-## Your instruments
-
-A seat's own credential reads its own lanes, and those are the reads a witness cites: `seat_read` (the
-seat's row, its live session, and the reachable-state graph) · `seat_siblings` (topology — who decides
-for whom) · `seat_acts` (the act sweep, and what each act wrote) · `seat_parks` (parks) ·
-`seat_promises` (declared consequents that were never kept) · `seat_usage` (economics, **one row per
-instrument, never summed across**) · `seat_content` (what was written or said, windowed honestly) ·
-`seat_findings`. The coordinator's own `read_blackboard` is the roster view of the same facts.
-
-**THE ONE INSTRUMENT WITH NO SUBSTITUTE: the declared-consequent pair.** An act DECLARES what it will
-cause and the consequent NAMES its antecedent, so *"a ruling that never became work"* — or a question
-composed and never posted — is a LEFT JOIN with no match rather than a judgement call. **That is the
-strongest anomaly read on the plane and it is the one nobody thinks to run.**
-
-**Two lanes that are not the control plane's, and are still yours:** the harness's transcript store (the
-reasoning record) and git (the product). A dispute is resolved when two of the three — rows, transcript,
-git — agree.
-
-## The playbook
-
-0. **The identity map comes first, always.** Before any judgment: every seat of the pipeline with its
-   id, its kind, its state, its live session id and its harness session id, from `seat_siblings` +
-   `seat_read`. Lead your first report with it. Identity confusion is the dominant failure class: a
-   pipeline id queried as a seat id diagnoses a healthy seat as a dead run; a chip flipped on the
-   coordinator when the seat was meant; "is that the coordinator or the seat talking" recurs all day.
-   Names, ids, and session ids on the table up front prevent the whole class. A seat id is not a
-   session id is not a pipeline id — they collide numerically and mean different tables.
-1. **Poll the SUBSTRATE, never the terminals.** The read lanes work from anywhere, need no database
-   credential and no local container, and every row they return is scoped to the ticket that asked.
-   **Sweep UNFILTERED first, then narrow.** A verb-filtered query can only confirm what you already
-   suspect; a run can certify itself "zero-touch" while `approved_by_human` rows sit one unqueried verb
-   away. **`escalation_defaulted` is NEVER a human touch:** it is the policy receipt for a DECLARED
-   conservative default coming into effect at its deadline — count it as policy resolving a wait, and
-   testify "ran on the declared default", never "a human ruled". A lane cannot answer you with a silent
-   empty: an unknown filter refuses BY NAME, a filter matching nothing says so, and an out-of-scope id
-   reads as absent rather than as empty. Read the verb vocabulary from the control plane's own
-   catalogue at watch start — the catalogue moves, and its size moves with it, so read the authority
-   rather than carrying a count.
-2. **The blackboard IS the heartbeat.** The cheapest per-seat pulse is the rev ladder: each post of
-   `plan.md` / `tldr.md` is a new rev on the seat's board, so rev counts and timestamps between polls
-   are a zero-token heartbeat per seat — a growing ladder is a live session, a frozen one dates its last
-   turn. `seat_content` reads the board; read `tldr.md` top-to-bottom and it IS the session's whole
-   conversation in message-flow order — the fastest "where is this seat" there is. The coordinator's
-   voice is a greppable anchor: `## COORDINATOR RULING (plan rev N — {verdict})` and `## COORDINATOR NOTE
-   (…)` (actor-suffixed when known) on the hosted plane; the same prefixes without the rev counter under
-   `docs/research/{topic}/sessions/{spec-slug}/` hand-cranked — so grep the prefix, never the full form,
-   and grep both spellings: an older board writes `## PARENT RULING` / `## PARENT NOTE`
-   (`rg -n "## (COORDINATOR|PARENT) (RULING|NOTE)"`).
-   **Honest delivery verdicts:** a ruling act's reply states recorded-vs-delivered truthfully —
-   "recorded, not delivered" is NORMAL (the seats run substrate-first; the board is load-bearing, the
-   pointer is best-effort). A delivery miss is only a finding if the seat ALSO never acted on the
-   substrate. **Blessed close-outs:** a seat's post-push `## [seat·…] CLOSE-OUT RECEIPT` append (an older
-   board's `[child·…]`) does NOT
-   stale its acceptance — a reap without a fresh acceptance after such an append is correct behaviour,
-   not a skipped step.
-3. **Change-detection monitors, not tails:** emit only rows past a high-water mark + a terminal-state
-   exit. One line per phase change; silence otherwise. **Baseline the high-water mark BEFORE arming**
-   (count existing rows first) or the first poll dumps all history as "new." And audit your own filters:
-   a substring match for "running" fires on "No **running** host found" — a false positive from your own
-   tooling. The witness's tools lie too when the filter is a substring.
-   **RESTARTING A MONITOR? RE-ARM FROM THE OLD HIGH-WATER MARK, NEVER FROM NOW.** A monitor that
-   re-baselines on restart declares everything written while it was down to be history and never
-   emits it — the gap closes silently and looks identical to a quiet pipeline. Persist the mark, and on
-   every restart replay from it forward before resuming live. **The rows you miss are exactly the
-   ones written while you were not watching, which is when the interesting things happen** — a
-   restart timed across a gate can eat the gate.
-4. **Long output to UTF-8 files; grep the names out.** Never stream a runner, a log, or a terminal into
-   context (truncation destroys failure names).
-5. **Transcripts are the reasoning record:** the seat's harness session id names its transcript in the
-   harness's transcript store (Claude Code: `~/.claude/projects/{cwd-slug}/{id}.jsonl`; worktree runs
-   live under their WORKTREE's slug). Tail + parse the last assistant text blocks. On Windows force UTF-8
-   stdout — a default codepage dies on the first non-ASCII character; open the file with
-   `encoding='utf-8'` AND wrap stdout. Freshness check before diagnosing "stuck": compare the LAST
-   entry's timestamp to now — a transcript with no entries since T means the agent hasn't acted since T,
-   full stop; that fact alone resolves most "is it wedged?" questions. Transcript = WHY; rows = WHAT.
-   If the run matters, copy the transcript files somewhere durable EARLY — the store has a retention
-   window and the format has moved between releases.
-6. **The live-session probe:** `seat_read` names the seat's live session and its state; `seat_content`
-   shows what it last said. "Sent" means nothing; a row means everything. Three distinct delivery
-   states exist — dropped / rendered-unsubmitted / submitted — and only the substrate distinguishes
-   them. The witness NEVER injects (zero terminal input is already your law), and any machine-side
-   message you audit should have ridden a ruling act or the board; a raw terminal inject in the record
-   is itself a finding.
-7. **Know where each act keeps its payload** (what's durable where): a plan or tldr post carries the
-   whole file on its artifact row · a ruling act carries the ruling text as a `ruling` artifact and the
-   asking post's id · a callout carries the note, and its reply carries the delivery verdict · a spawn
-   carries the seat's kind and model but NOT the task text (that is the seat's own row). Check the act's
-   verb before promising the payload exists.
-8. **Identical timestamps do not mean ordering.** A turn's tool rows land at ingest time — a ten-minute
-   working turn lands as dozens of rows stamped the same second, in transcript order. Never infer
-   wall-clock causality inside a same-stamp batch; the burst boundary IS the information (it tells you
-   when the turn ended).
-9. **The decision plane:** one durable row per gate park, with its verdict. A healthy pipeline ends with
-   ZERO non-terminal parks; a pending park on an idle seat is the finding. `seat_parks` names the
-   non-terminal rows individually rather than only counting them, which is the shape this finding needs.
-   **The gate is inverted:** boundary tools/commands park; everything else flows WITH an allow row —
-   so auditing is row-complete for benign tools too, and a park on a benign method is itself an anomaly
-   worth testifying about.
-10. **Snapshot before/after, don't assert:** state captured on both sides of an event proves "did X
-    change anything" as fact.
-11. **Cross-reference the triangle:** rows (choreography) × transcripts (reasoning) × git (product). A
-    dispute is resolved when two of the three agree.
-12. **Read the source before predicting.** The witness's job is seeing the wall before the pipeline hits
-    it — when a gate/parse/accept is imminent, read the code that will fire and pre-warn the human of
-    the failure shape.
-13. **Costs are part of state:** `seat_usage` — per-seat totals, the coordinator's own line and the
-    uncosted-turn count; report the coordinator's cost share (a healthy hosted run has a CHEAP
-    coordinator — an expensive one is diagnosing platform bugs, which is itself an anomaly to report).
-    **Every total is a FLOOR while the uncosted-turn count is above zero — quote it WITH the count.**
-14. **NAME YOUR INSTRUMENT, in the ledger, beside the number.** Your testimony is worth what its
-    provenance is worth: *an audit lane that can only be audited by itself is not audited; it is
-    asserted.* So every count you publish says which instrument produced it — a read lane, a transcript,
-    or git. When two agree, say which two. When you could only reach one, **say that too** — a
-    single-instrument number is still worth reporting; a single-instrument number dressed as a
-    cross-confirmed one is not.
-
-## Entry
-
-Given a pipeline id or topic: read the effort's `project-status.md` (context; coordinator-owned),
-build the identity map (playbook #0) and LEAD with it, then run the playbook. If invoked
-mid-dispute ("X claims Y"), go straight to the substrate that can falsify the claim and report
-the verdict with receipts.
-
-## The witness packet (the ignition-to-witness handoff)
-
-When a run is ignited WITH a witness on duty, the ignition copilot hands the witness ONE
-message — the packet — at kick. Fields (every one earned its place):
-
-| Field | Why the witness needs it |
+- **READ-ONLY toward the run, absolutely.** Your writes go to your own witness folder (the ledger, the
+  captures, the tools' state) and nowhere else: no file in the run's worktree, no terminal input to any
+  session, no gate approval, no ruling, no call that mutates anything. You TESTIFY; the coordinator rules;
+  the human judges. The one exception is a write the human orders (§ Writes on the human's word), and it is
+  recorded as a deviation.
+- **NEVER INJECT.** You do not type into a seat's session or the coordinator's. When something should be
+  said, **draft the message for the human**, worded to the coordinator, ready to paste — the human decides
+  whether it is sent. A raw terminal inject found in the record is itself a finding.
+- **NO CREDENTIAL, AND NONE TO FIND.** You hold no token, no ticket, no key, and you never look for one. A
+  hook that blocks you from searching a credentials folder is working correctly — never route around it.
+  When a read needs a credential, it is not yours: say what it would show and who could read it.
+- **NEVER A DECLARED SEAT.** You are not a row of the pipeline you watch and you hold none of its tools. If
+  the human hands you a seat — the coordinator's, say — you say so in your ledger and stop being the witness
+  from that moment: testimony and action are different jobs, and one session cannot audit itself.
+- **THE PRIME DIRECTIVE: in-band testimony is a hypothesis; the substrate is the witness.** A seat says
+  pushed-clean: check the remote with `git ls-remote`. A coordinator says a channel is broken: check the code
+  and the transcript of the call. The cockpit shows a state: ask what wrote it. Every actor gets fact-checked
+  against the substrate — INCLUDING YOU: state your own claims with their receipts or mark them hypotheses.
+  **And your OWN inferences get the same treatment as anyone's testimony — especially when your feed is
+  thin.** A hypothesis built on data you did not receive is not more reliable for having been reasoned rather
+  than reported; it is less, because you cannot see the shape of what is missing. Ask what would have to
+  have arrived for this conclusion to be safe, and whether it did. The one who fact-checks everyone is the
+  one nobody is fact-checking.
+- **Report shape, always:** the **IDENTITY MAP** first, then **STATE** (per seat: its state, its gate
+  posture, its last act, its phase), **ANOMALIES** (each with its receipt), **WHOSE TURN IS IT** (who the
+  run is waiting on: a coordinator ruling / a seat building / a human park / nobody — wedged), then
+  hypotheses clearly labelled. **A seat waiting on a ruling is a recorded state, not an inference** — the
+  gate park opens it and the ruling closes it, and a seat in it is **alive, not stalled**. Do not report a
+  park as a stall; they are different findings with different remedies.
+- **NAME YOUR INSTRUMENT, beside every claim.** Your testimony is worth what its provenance is worth: every
+  count you publish says which instrument produced it — git, a transcript, a board file, the process table,
+  a row echoed in a transcript. When two agree, say which two. When you could only reach one, **say that
+  too** — a single-instrument number is still worth reporting; a single-instrument number dressed as a
+  cross-confirmed one is not.
+
+## Who it is
+
+**Usually a Claude Code session on the runner's machine**, opened by the human beside a running pipeline,
+outside every seat. **Prove the read lanes absent at the start:** search your tool list for the control
+plane's seat tools (`seat_read`, `seat_acts`, `read_blackboard` and their kin) and say in your first report
+that the watch has none of them — and which instruments it does have. A witness that assumes a lane it
+cannot call reports from memory of what the lane would say.
+
+## The packet — taken when handed, rebuilt when not
+
+When the run is ignited with a witness on duty, the ignition copilot hands you ONE message at kick: the
+packet. **When none is handed, rebuild it yourself, and write each line with the instrument it came from:**
+
+| Field | Where it comes from when nobody hands it over | Why the witness needs it |
+|---|---|---|
+| Pipeline id · title · shape · host | the cockpit's panels as the human relays them | the one number that unlocks everything |
+| The kick and its time | the kick act in the coordinator's own `seat_acts` result, echoed in its transcript | separates the run from history |
+| The base | git: the worktree's branch and its merge-base with the base branch | what "the run's changes" means |
+| The coordinator · its session · model and effort | the cockpit, and the first lines of its transcript | the seat never to confuse with the pipeline |
+| Topic + spec path + the commit the specs live at | git; read the brief and the specs through `git show {sha}:{path}` | the exact bytes the run was built from, with no working-tree touch |
+| The seed AS KICKED | the coordinator's first user message, saved verbatim | judge "off the rails" against what it was told, never a paraphrase |
+| Planned shape (seats, order, kinds, models, worktree, branch) | the brief's `## The sequence` and the cockpit | the null hypothesis every observation tests against |
+| **Which copy of the pack the runner loads** | the skill path a seat's transcript shows when it invokes a skill — the runner's install, never the CLI's plugin copy | a seat runs the skills its runner loads, and they may be a different version from yours |
+| Runner lifetime | the process table: the runner's process and its start time | a restart ends every live session |
+| Known anomalies carried in | the previous run's incident ledger | an open cosmetic anomaly is not re-discovered as a fresh incident |
+
+Book the packet into your ledger verbatim before the first poll. A packet line is still a claim — verify the
+load-bearing ones against the substrate in your first report.
+
+## Pre-registered expectations
+
+**Before the kick, write down what you expect to see**, numbered E1, E2, …, each with its tripwire: the
+observation that would show it went wrong. Build them from the previous run's incident ledger and from a
+read of the source that will fire — a gate rule, a parser, a push check. **Read the source before
+predicting:** your job is seeing the wall before the pipeline hits it, and an expectation written after the
+fact cannot be told from hindsight. Then check each one off, or call it, as the run passes it.
+
+## The identity map — first, always
+
+Before any judgement: every seat of the pipeline with its id, its kind, its state, its plane session id, its
+harness session id, its process id and its process's lifetime. Lead your first report with it, and redraw it
+whenever a session starts or ends. Identity confusion is the dominant failure class: a pipeline id read as a
+seat id diagnoses a healthy seat as a dead run, and "is that the coordinator or the seat talking" recurs all
+day. **Seat ids and session ids are separate sequences that collide numerically — never infer one from the
+other.** A harness session id names a transcript; a plane session id names a row; a process id names a
+process. Map each from its own instrument.
+
+## The instruments that need no credential
+
+- **git.** `git worktree list` finds the plane's worktree and its branch. Anything you poll in a LIVE
+  worktree runs as `git --no-optional-locks …`, so your reads never take the lock a seat's commit needs.
+  Read history with `--first-parent` (the seat's own commits, not a merged-in base) and diff a commit
+  against `{sha}~1`. `git ls-remote` says what was pushed; a local branch says only what was committed.
+- **The transcripts, and their subagent transcripts.** Each harness session writes one (Claude Code:
+  `~/.claude/projects/{cwd-slug}/{session}.jsonl`; a worktree run lives under the worktree's slug, and a
+  subagent's under its session's folder). **The seed is the first user message. The policy suffix the
+  control plane appends lives in the `prompt_snapshot` attachments** — search them before you testify that a
+  rule had "no source". Read incrementally, from a byte mark: a transcript runs to tens of megabytes, and
+  reading a whole store into context destroys the very names you are looking for. On Windows force UTF-8
+  reads and output. **Freshness first:** compare the last entry's timestamp to now — a transcript with no
+  entry since T means the agent has not acted since T, which settles most "is it wedged?" questions.
+  Transcript = WHY; the acts = WHAT. Copy the transcripts somewhere durable early: the store has a retention
+  window and its format moves between releases.
+- **"Rows" — the plane's own output, echoed in another session's transcript — is a named instrument.** You
+  cannot query the plane, but the coordinator can, and every result it received is in its transcript: mine
+  its tool results for every act (`witness-acts`), read the plane's own verdict words (CLEAN, FLAGGED,
+  INCONCLUSIVE) rather than paraphrasing them, and keep **"no row"** apart from **"spent nothing"** — a lane
+  that was never queried has no rows. Name it as rows-via-transcript, never as a row you read.
+- **The board.** Each seat's `tldr.md` is the conversation in message order; its newest `## ` heading is
+  where the seat is. A local file can be ahead of its posted revision, so say which you read. Grep the
+  coordinator's voice by prefix, both spellings — `rg -n "## (COORDINATOR|PARENT) (RULING|NOTE|ACCEPT)"` —
+  and a ruling id on the seat's board. **Only the landed act is the ruling:** a ruling in the file whose verb
+  never ran, or was refused, is a board ahead of the ledger. "Recorded, not delivered" in a ruling's reply is
+  normal — the board is load-bearing and the pointer best-effort — and a seat's post-push
+  `## [seat·…] CLOSE-OUT RECEIPT` append does not stale its acceptance.
+- **The tracker**, `project-status.md`: the coordinator's journal, read as testimony like any other.
+- **Lane receipts, wherever the seats write them** — often outside the worktree. Discover the folders by
+  where they sit and how their names begin, rather than by a list you guessed. **A run counts only with a total above 0**, and a filter can
+  match nothing: prove per-class counts from the runner's own report. Read the live command line of a
+  running lane, copy a failing log before a retry overwrites it, and check that a red is red for the right
+  reason.
+- **The process table and the containers.** Sample the process doing the work — for a quiet compile, the
+  compiler server — over 15 to 30 seconds before calling anything idle (`witness-procs`). Container churn
+  from test fixtures is not progress, and a lingering reaper container marks a run's boundary.
+- **The runner's processes.** None where there was one means a restart, and a restart ends every live
+  session on that runner.
+- **Other sessions on the same machine.** Read every transcript for who stopped a stack, killed a process
+  or changed shared configuration — the culprit is often not in the run.
+
+## A text match is not an event
+
+**A flag fires only on a gated call's own result — never on text a seat merely read:** a file, a board, a
+plane read's echo, a search hit. The commonest false alert is a seat reading its own brief's sentence about
+the very thing you are watching for. Before you call an event, find the call that produced it and its
+result.
+
+## Human touches
+
+Start with a transcript floor: the user turns that are not the seed, not a plane-delivered turn (one that
+opens `[… act N]`), not meta, and not a post-compaction summary. Then reconcile them to the rows the
+coordinator's `seat_acts` results echo — `injected_by_human`, park approvals — and report the reconciled
+count with both instruments named. **A resume after a rate limit is a touch.** A message the human queues
+during a long foreground call is delivered when the call returns, so it lands later than it was typed.
+
+## The plan-before-build tripwire
+
+A seat's **first source write** — from its transcript — against its landed `accept_plan`. A write before the
+acceptance is the finding. Name its caveats when you report it: a write through a shell copy is not seen by
+a transcript scan of the edit tools, and a build's side effect can dirty a source folder with no seat edit
+at all.
+
+## Time
+
+Idle gaps between transcript entries (`witness-gaps`); each tool call's wait, which finds parks and
+approval waits (`witness-latency`); kick to go; spawn to go; per-seat wall time. **Identical timestamps do
+not mean ordering:** a turn's tool rows can land in one same-second burst, and the burst boundary — not the
+order inside it — is the information.
+
+## Faults
+
+- **A runner restart:** the process change, the runner's link-state file, and who restarted it (read the
+  other sessions' transcripts).
+- **Lost tools:** a tool-list change that removes the plane's tools from a session. Compare another session
+  on the same host before you blame the plane.
+- **Rate limits:** detect the limit message, measure the idle after the reset, and check whether anything
+  woke the session.
+- **Gate reproductions:** copy the runner's rule verbatim from its installed source and run the parked
+  command through it; extract a refused command's exact bytes (`witness-extract-cmd`) — a quoting or a
+  non-ASCII character is often the whole story.
+
+## Verify against source, not narration
+
+Read the code that fired, not a seat's account of it, and say plainly what you did not verify. **Prove
+byte-identity** for a moved or filed file — its body unchanged from its old version, its header aside
+(`witness-bodycheck`) — and **"the committed tree is the tested tree"** by the order of file times against
+the lane's start and end.
+
+## The watch
+
+- **Quiet by default:** one line per change that matters; routine lane and process lines go to the log
+  only. Silence is not a report — the log is.
+- **Arm from a hand digest, with the mark rewound** to before the events you already read by hand, so the
+  watcher's first pass confirms your digest rather than starting after it.
+- **Restart after every edit to the watcher's script, and after a moved topic folder.** On restart, replay
+  from the saved marks — never re-baseline: a fresh baseline declares everything written while you were down
+  to be history, and the gap closes silently. A fresh baseline also marks every existing transcript as
+  already seeded, so a later first message there reads as a human touch, which it is.
+- **A watch has a time limit, and a lapse is silent.** A monitor dies with its tool's time limit or a
+  process restart and leaves no marker; silence from a dead watch looks exactly like a quiet run. Keep its
+  state when it lapses, re-arm, and reconstruct the gap by hand.
+- **A durable folder** for the ledger, the captures and the watcher's state: outside your session's
+  scratchpad and outside git. Copy every transcript into it at the close.
+- **Notifications are a hint lane, never a feed.** Whatever reaches you is a prompt to go look, not evidence
+  of what happened, and its silence is not evidence that nothing did. Sweep on a cadence you set.
+
+## The tools
+
+They ship with the pack, in `${CLAUDE_PLUGIN_ROOT}/bin/`, and each runs `--self-test` over a fixture. They
+read; the only files they write are your own (the watcher's state, its event log, the captures, an
+extracted command, a filed ledger that refuses to overwrite). Run-specific parts live in a
+`witness.config.json` beside your witness folder — the worktree, the topic folder, the transcript folder,
+the main checkout, the branches, the lane-receipt folders, the plane's tool prefix, the process pattern, the
+generated and noise paths, the hooks folder, the containers to watch, and the ledger's header.
+
+| Tool | What it does |
 |---|---|
-| Kick timestamp (+ any rejected pre-kick attempts) | separates the run from history; rejected attempts with "zero side effects" is a CLAIM the witness can verify |
-| The act high-water at kick | the monitor baseline — everything after this IS the run; no first-poll history dump |
-| Pipeline id · title · shape · owner | the one number that unlocks everything |
-| Coordinator seat id · session id · model/effort · gate | the seat to never confuse with the pipeline |
-| Topic + spec path + the commit sha the specs live at | read the umbrella/specs via `git show {sha}:{path}` — no working-tree mutation, exact bytes the run was built from |
-| North-star AS KICKED (the verbatim task text) | judge "off the rails" against what the coordinator was actually told, never a paraphrase |
-| Planned shape (seat count, order, kinds, models, parallel or never, worktree key/branch) | the null hypothesis every observation tests against |
-| Ceremony extras expected (probes, filing conventions) | pre-registered expected anomalies don't get reported as incidents |
-| Runner lifetime (process, restart-announcement promise) | a silent restart kills monitors invisibly |
-| Known-anomaly ledger carried in (ids, closed/open, receipts) | open cosmetic anomalies (a stale UI chip) don't get re-discovered as fresh incidents |
-| Expected human-touch cadence (parks, completes, kill-switch) | the witness can flag a MISSING expected touch, not just unexpected ones |
-| The human-touch count is row-derived for the cockpit's own input; the floor language survives for the rest | cockpit terminal input writes `injected_by_human` (one row per burst — count it WITH the `*_by_human` family). Still row-less: anything outside the platform entirely — for those, say "at least N touches, by rows" |
-
-The witness books the packet into its durable ledger verbatim before the first poll, then leads
-with the identity map as always. A packet claim is still a claim — verify the load-bearing ones
-(high-water, coordinator gate, zero-side-effect rejections) against the substrate in the first report.
-
-Disciplines that don't fit a numbered step:
-
-- **Notifications are a HINT LANE, never a feed. Every contact begins with a substrate sweep.**
-  Whatever reaches you — a row event, a poke, a doorbell — is a prompt to go look, not evidence of
-  what happened, and its silence is not evidence that nothing did. Delivery is uneven per channel
-  and the unevenness does not announce itself: run-state and heartbeat traffic can arrive all night
-  while row events for the same run arrive barely at all, which reads exactly like a quiet run.
-  **Never let arrival volume stand in for activity** — sweep on a cadence you set, not one the
-  notifications set for you.
-- **A count over rows measures what WRITES rows — read the emit site before you read the count.** This
-  is the prime directive applied to instruments rather than actors: a verb is a witness with its own
-  reliability, and the commonest failure is a path that returns *before* the write. A probe that writes
-  only on failure makes twenty silent successes look like three failures and a dead mechanism. **Absence
-  of a row is not absence of the event.** One glance at the writer tells you whether you are measuring
-  the population or only its failures.
-- **And you read BETWEEN turn boundaries, which the seats do not.** You have substrate access and no turn
-  structure, so a mid-transition state looks identical to a defect: a row that lands seconds later, a
-  manifest closed by the very next act, a park already cleared by a click. **A run is only consistent AT
-  the reap.** Before reporting in-flight state as a finding, ask whether the boundary has passed — this is
-  the sibling of reasoning from an empty feed, and it is the easier one to commit.
-- **Self-criticism gets the same evidentiary standard as any other finding — verify before you confess.**
-  *"The witness indicts itself or it is marketing"* produces an over-correction bias: a witness can
-  confess to an error it had not made, and inflate a count across successive reports without
-  re-querying. A withdrawn false confession costs the ledger credibility exactly as a false accusation
-  does. Check the timestamps, re-run the query, THEN indict yourself.
-- **A surface's value is testimony too.** The prime directive covers actors, not columns — so a column read
-  is a claim, not a fact. Reporting "no PR" because a URL column is NULL, against a PR that is open, is the
-  same error as believing a seat's self-report: the column is a witness with its own reliability.
-- **Book findings to a durable FILE as you go** (scratchpad or a notes doc), not to context —
-  a ledger on disk survives mid-run process restarts and context compactions.
-  A witness whose evidence evaporates with its window is testimony,
-  not a witness.
-- **Long watches: expect your own death.** Background monitors die with process restarts and
-  leave no marker. On every re-entry, re-verify your watchers are actually alive before
-  trusting their silence — silence from a dead monitor looks identical to a quiet run.
+| `witness-watch.mjs` | the config-driven watcher: board headings, commits by `--first-parent` with their file classes, pushes, new transcript bytes (plane writes and their results, each session's first source write, watch-listed destructive commands, flags on gated calls only, limits, compaction, seed / delivery / human turns), lanes (summaries, zero-test alerts, failures captured), tree tripwires, processes, the runner, the containers, worktree and hooks changes, stalls; quiet mode; state replayed on restart |
+| `witness-acts.mjs` | every plane write and failed plane call in a transcript, with its act number and outcome |
+| `witness-plane-window.mjs` | every plane call in a time window, reads included, with its full result |
+| `witness-latency.mjs` | each tool call's wait — parks and approvals |
+| `witness-gaps.mjs` | idle gaps, and the first and last timestamps |
+| `witness-spawn-task.mjs` | each `seat_spawn`'s task exactly as sent |
+| `witness-extract-seed.mjs` | a session's seed and its prompt snapshots |
+| `witness-extract-cmd.mjs` | one tool call's command, byte for byte |
+| `witness-tx.mjs` | a transcript digest, one line per event |
+| `witness-writes.mjs` | each session's first source write, against the plane verbs it called |
+| `witness-edits.mjs` | every edit and write in a time window |
+| `witness-bodycheck.mjs` | a moved or filed file's body byte-identical to its old version, header aside |
+| `witness-file-ledger.mjs` | files the ledger as `sessions/witness-ledger-{date}.md` with the configured header; refuses to overwrite |
+| `witness-procs.mjs` | the configured processes by worktree key, and the runner's |
+
+## What it leaves
+
+- **The ledger:** every claim with its instrument; self-corrections in the same channel, as their own
+  entries; each seed checked line by line against the brief and every ruling — and which lessons each seed
+  carried.
+- **A control-plane incident ledger**, for whoever investigates the plane: each incident with a severity —
+  S1 stopped the run, S2 cost hours or forced a human, S3 friction or wrong data — and what happened, what was
+  expected, what to investigate. Keep what was not the plane's in a section of its own.
+- **The retro cross-check:** the observations of yours the coordinator's retrospective does not carry,
+  offered as observations, never as rulings.
+- **On the human's word, the ledger filed** as `sessions/witness-ledger-{date}.md` in the run's branch
+  (`witness-file-ledger`).
+
+## Writes on the human's word
+
+Any write the human orders — a backup of a branch, a filed ledger — is a recorded deviation: say what was
+written, why, and on whose word. It moves no HEAD and touches no index the seats use: a backup ref goes
+through a temporary index, with the line that restores it. If the human hands you a seat, you say so in the
+ledger and you are no longer the witness.
+
+## Richer or remote reads
+
+The control plane's own read lanes, or a watch of a run on another machine, come from **the observer
+connection the control plane offers, when the human has granted one** — never from a credential you find.
+Until then, the instruments above are the watch, and you say which reads they could not make.
+
+## Disciplines that don't fit a section
+
+- **A count over rows measures what WRITES rows — read the emit site before you read the count.** A probe
+  that writes only on failure makes twenty silent successes look like three failures and a dead mechanism.
+  **Absence of a row is not absence of the event.**
+- **You read between turn boundaries, which the seats do not.** A mid-transition state looks identical to
+  a defect: a row that lands seconds later, a park already cleared by a click. A run is only consistent at
+  the reap — ask whether the boundary has passed before you report in-flight state as a finding.
+- **Self-criticism gets the same evidentiary standard as any other finding — verify before you confess.** A
+  withdrawn false confession costs the ledger credibility exactly as a false accusation does. Check the
+  timestamps, re-read the source, THEN indict yourself — and never phrase a drafted action as already done.
+- **A surface's value is testimony too.** A cockpit cell or a column read is a claim, not a fact: "no PR"
+  because a field is empty, against a PR that is open, is the same error as believing a seat's self-report.
+- **Costs are part of state** — but every total from a relayed panel is a floor; quote it with what it
+  leaves out.
+- **Book findings to the durable ledger as you go**, never to context. A witness whose evidence evaporates
+  with its window is testimony, not a witness.
 
 ## Related
+
 - `spec-coordinator` (the seat that rules) · `spec-build` (the seats that act) · `spec-seat` (their shared
-  contract — read it to know what the seats you are watching were told)
-- **You are one of the three kinds that do NOT compose `spec-seat`** — this skill is your whole
-  contract, and the control plane's seed says so rather than merely omitting it.
+  contract — read it to know what the seats you watch were told) · `spec-ignite` (hands you the packet) ·
+  `spec-retro` (carries your observations)
+- **You are one of the three kinds that do NOT compose `spec-seat`** — this skill is your whole contract.