@naswerks/engineering-loop 0.7.1 → 0.9.0

package/bin/witness-writes.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// When a session first wrote into the source folders, set against the plane verbs it called: the
+// plan-before-build tripwire is a seat's first source write against its landed `accept_plan`. Caveats a
+// ledger names with the result: a write made through a shell copy is not seen here (only the edit tools
+// are), and a build's side effect can dirty a source folder with no seat edit at all. Read-only.
+//
+//   node witness-writes.mjs <file.jsonl> <worktree-folder-name> [--source-dirs src,tests] [--plane <server>] [--config <path>]
+//   node witness-writes.mjs --self-test
+
+import { rmSync } from 'node:fs';
+import { contentOf, entries, flag, isMain, loadConfig, planePrefix, positionals, report, scratch, toolUse, writeTranscript } from './witness-lib.mjs';
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+export async function writes(file, key, sourceDirs, prefix) {
+  const realTree = new RegExp(`${escape(key)}[\\\\/]+(${sourceDirs.map(escape).join('|')})[\\\\/]`);
+  let first = null;
+  let last = null;
+  let count = 0;
+  const plane = [];
+  for await (const { line, entry } of entries(file)) {
+    for (const c of contentOf(entry)) {
+      if (c.type !== 'tool_use') continue;
+      if (typeof c.name === 'string' && c.name.startsWith(prefix)) plane.push(`${line} ${entry.timestamp} ${c.name.slice(prefix.length)} ${JSON.stringify(c.input).slice(0, 120)}`);
+      const path = String(c.input?.file_path ?? c.input?.notebook_path ?? '');
+      if (!/^(Write|Edit|MultiEdit|NotebookEdit)$/.test(c.name) || !realTree.test(path)) continue;
+      count++;
+      first ??= `${line} ${entry.timestamp} ${c.name} ${path}`;
+      last = `${line} ${entry.timestamp}`;
+    }
+  }
+  return [`first source write: ${first}`, `source writes: ${count}, last: ${last}`, 'plane calls:', ...plane];
+}
+
+async function selfTest() {
+  const dir = scratch('witness-writes');
+  try {
+    const file = writeTranscript(dir, 'seat.jsonl', [
+      toolUse(1, 'a', 'Write', { file_path: 'C:/work/pipeline-7/docs/notes.md' }),
+      toolUse(2, 'b', 'mcp__plane__post_plan', { path: 'plan.md' }),
+      toolUse(3, 'c', 'Bash', { command: 'cp draft.ts C:/work/pipeline-7/src/a.ts' }),
+      toolUse(4, 'd', 'Edit', { file_path: 'C:\\work\\pipeline-7\\src\\a.ts' }),
+      toolUse(5, 'e', 'Write', { file_path: 'C:/work/pipeline-7/tests/a.test.ts' }),
+    ]);
+    const lines = await writes(file, 'pipeline-7', ['src', 'tests'], 'mcp__plane__');
+    return report('witness-writes', [
+      { name: 'the first source write is the edit into src', ok: lines[0].startsWith('first source write: 4 ') && lines[0].includes('Edit'), detail: lines[0] },
+      { name: 'both source writes are counted, and the plane call is listed', ok: lines[1].startsWith('source writes: 2') && lines.some((l) => l.includes('post_plan')), detail: lines.join(' | ') },
+      { name: 'CONTROL: a docs write and a shell copy are not source writes', ok: !lines[0].includes('notes.md') && !lines[0].includes('cp '), detail: lines[0] },
+    ]);
+  } 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 config = loadConfig(argv);
+  const [file, key] = positionals(argv, ['--plane', '--config', '--source-dirs']);
+  if (!file || !key) { console.log('usage: witness-writes.mjs <file.jsonl> <worktree-folder-name> [--source-dirs src,tests] [--plane <server>]'); process.exit(2); }
+  const sourceDirs = (flag(argv, '--source-dirs') ?? config.sourceDirs.join(',')).split(',').filter(Boolean);
+  for (const line of await writes(file, key, sourceDirs, planePrefix(argv, config))) console.log(line);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naswerks/engineering-loop",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "The engineering loop as a Claude Code plugin: a knowledge loop (docs-*), an execution loop (spec-*), and init for a fresh repository. The package root is the plugin root.",
   "license": "MIT",
   "type": "module",

package/references/docs-workflow.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.7.1 -->
+<!-- naswerks-loop: version=0.9.0 -->
 # Docs Workflow
 
 > How knowledge flows through `docs/`: the loop, the folder rules, the templates, and the `docs-*` skills.
@@ -41,7 +41,7 @@ narrative. That's also why it's a separate session, not the tail of the implemen
 | Folder | What it holds | Lifecycle |
 |--------|---------------|-----------|
 | `_meta/` | This system — `doc-index` (the menu) + `docs-workflow` (this file) + `engineering-loop` (the seats and the ceremony) | Maintained as the system evolves; the sections marked **(repository-owned)** are rewritten by each repository to its own conventions |
-| `research/` | The running tab of ideas to do, not yet built. The folder is the queue. | Created by `docs-backlog`; stays through the build, then **archived with its working doc(s)** by `docs-process` |
+| `research/` | The running tab of ideas to do, not yet built. The folder is the queue. | Created by `docs-backlog`; stays through the build, then **archived with its working doc(s)** by `docs-process` — or, when the platform moves past it unbuilt, **retired** to `archive/retired/` |
 | `working/` | Active + finished-but-unprocessed session docs (one effort may chain several). The folder is the queue. | **Leaves via `docs-process`** — research + the whole chain archived together once the living docs are patched |
 | `archive/` | Completed/abandoned session docs, grouped into **topic** folders (or the home "The archive convention" below names for them) | Write-once. Frozen history — never edit archived docs |
 | `guides/` | How to ADD a new thing — step-by-step walkthroughs | Living — patched by `docs-process` |
@@ -83,7 +83,7 @@ that replaces the section rewrites alongside it):
 
 | Section | What the skills read from it | Also echoed in |
 |---------|------------------------------|----------------|
-| **The archive convention** (this file) | the archive home for each kind of effort (hand-cranked, spec pipeline, follow-on round) and for audit reports · the shape inside it · what a working doc's `## Archive` line says, and whether an umbrella carries an `Archive:` line · the links a move repairs · what is frozen once filed | The Loop (the diagram and its prose) · Folders (`research/`, `working/`, `archive/`) · "Living docs vs session docs" · the skills table (`docs-process`) · Conventions (incident receipts, archived docs) · `engineering-loop.md` "The loop at a glance" |
+| **The archive convention** (this file) | the archive home for each kind of effort (hand-cranked, spec pipeline, follow-on round) and for audit reports · the shape inside it · what a working doc's `## Archive` line says, and whether a pipeline's ignition brief carries an `Archive:` line · the links a move repairs · what is frozen once filed | The Loop (the diagram and its prose) · Folders (`research/`, `working/`, `archive/`) · "Living docs vs session docs" · the skills table (`docs-process`) · Conventions (incident receipts, archived docs) · `engineering-loop.md` "The loop at a glance" |
 | **Doc metadata** (this file) | the header — its form and its place · the sweep: one command, one line per doc · the word for each loop state (below) · where the verified date lives, and the rule that moves it · whether `## Lineage` stays · the gates a doc passes, and the folders they exempt | the skills table (`docs-status`) · Conventions (the machine layer; dates in the header) · `engineering-loop.md`'s own header line and its `## Lineage` |
 | **Templates** (this file) | each template's header lines, at the state its writer names | — |
 | **This repository's rails** (`engineering-loop.md`) | the policy document, and how a seat reaches it · the gates a commit passes · the suite before a PR · the base branch, the PR target, the branch names and how a PR is opened · the staging rule · the repository's own skills a seat meets | the POLICY row of "Where a rule lives" · the Hard rules, which the rails add to and never subtract from |
@@ -142,7 +142,7 @@ Keep what the skills need to find, change the words to yours:
   re-sorted, every file keeps its name and its place, `sessions/` rides along untouched, and the effort's
   working docs join the package under `implementation/`, with the tracker still the "read me first" at its
   root. When where a pipeline files depends on something only its authoring session knows, say so —
-  `spec-pipeline` then records the resolved path in the umbrella's blockquote as an `Archive:` line.
+  `spec-pipeline` then records the resolved path in the brief's `## Where it came from` as an `Archive:` line.
 - **Your rails.** Fill each item of `engineering-loop.md` § This repository's rails from what the
   repository already wrote down — a policy document, hooks, CI, a pull-request template.
 - **Your menu.** A repository that already indexes its docs declares its menu curated and names that index:
@@ -196,17 +196,20 @@ one** (via `spec-pipeline`). The trigger for the layout is simply *"does this ef
   ```
   archive/{topic}/
     project-status.md        <- the tracker/index — root, "read me first" (spans both halves)
-    live-checks.md           <- the human's verification rows, accumulated as the pipeline ran
-    specs/                   <- the spec pipeline: 00-ignition-brief · 01 umbrella · 02..NN slices
+    live-checks.md           <- the rows the owner dictated, if any
+    specs/                   <- the spec pipeline: 00-ignition-brief · 01..NN slices
     implementation/          <- the per-session working docs that built it
     sessions/                <- THE PIPELINE'S CONVERSATION, archived intact:
                                  {spec-slug}/plan.md  + {spec-slug}/tldr.md  per build session
                                    (TWO files — questions ride the PLAN TLDR, and there are no
                                     status snapshots, because the tracker is committed live and
                                     its git history carries every revision)
+                                 docs-process/plan.md + tldr.md  the docs-process row's board
+                                 {step-slug}/receipt.md        a human step's receipt
                                  code-review.md                the review seat's outside look, if
                                                                the pipeline had a review row
                                  coordinator-retrospective.md  the coordinator's inside look
+                                 witness-ledger-{date}.md      a witness ledger, filed on the human's word
                                These are TESTIMONY: an archive pass repairs links elsewhere and
                                leaves sessions/** byte-untouched. Older archived sessions may
                                still hold questions.md / status-after-*.md; that is historical
@@ -218,7 +221,7 @@ already-archived effort gets its **own sibling topic folder**, never filed insid
 Rules: (a) name the new topic `{family-prefix}-{subtopic}` so the family groups
 alphabetically; (b) each folder keeps the full split shape (own `project-status.md` at root); (c) the
 **family index is the living feature doc's `## Lineage`** — it accumulates Idea/Spec/Built rows from
-every round; (d) the new pipeline's umbrella/tracker back-link to the prior round's archive (allowed —
+every round; (d) the new pipeline's brief/tracker back-link to the prior round's archive (allowed —
 cross-effort links into archives are historical record). Never reopen a frozen topic folder to add
 a round.
 
@@ -227,12 +230,29 @@ a round.
 working docs' `Source:` to the spec's new path (`../specs/NN-*.md`), the spec / `project-status` links, the
 index's links into `specs/`, and the feature doc's `## Lineage` rows (`Spec` to `specs/…`,
 `Built` to `implementation/…`). **Pre-existing cross-effort links** in archived docs (to *other* topic
-folders / research chains) are **left as historical record** — don't chase those.
-
-**`archive/audit/` is the one exception to topic-folder grouping.** Audit reports mirror the *living-doc
-groups* instead — `archive/audit/{guides,patterns,infrastructure,features}/{doc}-audit.md` — so each
-report sits beside the docs it audits. The cross-cutting `health-report-{date}.md` (from
-`docs-audit-full`) stays at the `audit/` root.
+folders / research chains) are **left as historical record** — don't chase those. The one exception is
+provenance: when a doc moves, every link to it from another archived doc's header blockquote (`Source:`,
+`Builds on`) or `## Lineage` footer, or from a line marked `Idea` / `Spec` / `Built` / `Source:`, is repointed,
+`sessions/**` excepted, because that is how a reader replays an effort.
+
+**Two homes are the exceptions to topic-folder grouping.**
+
+- **`archive/audit/`** — audit reports mirror the *living-doc groups* instead —
+  `archive/audit/{guides,patterns,infrastructure,features}/{doc}-audit.md` — so each report sits beside the
+  docs it audits. The cross-cutting `health-report-{date}.md` (from `docs-audit-full`) stays at the `audit/`
+  root.
+- **`archive/retired/`** — research the platform moves past without building it (superseded by a different
+  design, its product retired, or the idea dropped), laid out exactly as it stood in `research/`: a folder
+  stays a folder, a loose doc stays loose, names and headers unchanged, and no link inside it is repaired.
+  Before it moves, its still-good ideas go one line each into `research/misc/idea-scratchpad.md`, its
+  code-verified open defects become `## Open Issues` rows in the living doc that owns the code, and a row in
+  `archive/retired/README.md` says why it was retired and where its live parts went. Links into it from
+  living docs and kept research are repaired. Research that shipped is filed with the effort that delivered
+  it; when that effort is already filed, the doc goes into the effort's home (a split effort's `research/`),
+  which completes the effort's own filing and is not a new round. Research that fed several efforts rather
+  than one goes on its theme's shelf (`archive/infrastructure/`, say). A running tab, or a research doc that
+  spanned several efforts, whose shipped parts are already filed with their own efforts retires with its unbuilt remainder; those efforts'
+  provenance links then point at it on the shelf.
 
 ---
 
@@ -301,7 +321,7 @@ links become the `Related` row:
 - **Real lineage only.** Wire a row only where the idea/implementation origin is *genuine* — never on
   coincidental topic overlap (junk links would pollute the graph's communities).
 - Most `patterns/`/`guides/` docs carry only `Related` (maybe `Built`); `features/` carry the full chain.
-- **`Spec` mirrors `Built`; the vision goes to `Idea`.** For a spec-driven effort: put the umbrella +
+- **`Spec` mirrors `Built`; the vision goes to `Idea`.** For a spec-driven effort: put the ignition brief +
   any `00-operating-frame` (the *why/what*) in `Idea`, and list in `Spec` **every per-slice spec that a
   listed `Built` session implemented** — the two rows stay symmetric. A session in `Built` whose spec is
   missing from `Spec` (or vice-versa) is the smell. Don't silently drop chain members because they feel
@@ -430,17 +450,17 @@ once the code is fixed. Keep entries one line, dated, and pointing at a `file:li
 ### Spec doc (a numbered pipeline — `spec-pipeline`)
 
 When a research idea graduates into a real plan, `spec-pipeline` explodes it into a numbered pipeline in
-`docs/research/{topic}/`: `00-ignition-brief.md` (the coordinator seat's standing orders for the run —
-written whole at authoring, verified at ignition) · `01-{topic}.md` (the umbrella) · `02..NN-{slice}.md` (**one
-self-contained spec per planned session**) · `project-status.md` (the tracker, which carries its own
-section notes) · `live-checks.md` (the human's verification rows).
-Each per-session spec uses this template (carries `Builds on`/`Source:` so the chain stays navigable):
+`docs/research/{topic}/`: `00-ignition-brief.md` (the coordinator seat's spec and the charter every seat
+reads — written whole at authoring, verified at ignition) · `01..NN-{slice}.md` (**one self-contained spec
+per build seat** — every numbered file is one seat's spec) · `project-status.md` (the tracker, which carries
+its own section notes) · `live-checks.md` (created empty; the rows the owner dictates).
+Each per-seat spec uses this template (carries `Builds on`/`Source:` so the chain stays navigable):
 
 ```markdown
 # Spec NN — {Slice title}
 
 > {what this slice builds} — {why / the gap it closes}. {what it builds on / supersedes / defers}.
-> Builds on [{prior}]({prior}.md). Source: [{umbrella / research}](...). Written {date}.
+> Builds on [{prior}]({prior}.md). Source: [{brief / research}](...). Written {date}.
 <!-- meta: type=spec; status=draft; verified={date}; lineage=N -->
 
 ## The Problem / The Target
@@ -452,7 +472,7 @@ Each per-session spec uses this template (carries `Builds on`/`Source:` so the c
 ```
 
 Specs stay physically in `research/{topic}/` through the build; when the effort ships, `docs-process` archives
-the umbrella + specs + working docs together into `archive/{topic}/` — a spec-driven effort splits into
+the brief + specs + working docs together into `archive/{topic}/` — a spec-driven effort splits into
 `specs/` + `implementation/` with `project-status.md` at the root (see "Two topic-folder shapes" above). The
 spec set *is* the design history.
 
@@ -471,11 +491,11 @@ come from this copy, so a repository changes them once, here.
 | Skill | When | What it does |
 |-------|------|-------------|
 | `docs-backlog` | Have an idea | Capture it as a research doc in `research/` |
-| `spec-pipeline` | A research idea is graduating into a real plan | Explode the plan into a numbered spec pipeline (umbrella + one self-contained spec per session + `project-status`) in `research/{topic}/`; the plan becomes ephemeral |
+| `spec-pipeline` | A research idea is graduating into a real plan | Explode the plan into a numbered spec pipeline (the ignition brief + one self-contained spec per build seat + `project-status`) in `research/{topic}/`; the plan becomes ephemeral |
 | `spec-coordinator` | Right after `spec-pipeline` (same session, context-loaded) or to resume an effort fresh | Assume the coordinator seat: cut seat prompts (one per spec), review/verify TLDRs, give commit calls, own `project-status.md` — the same loop hand-cranked or hosted |
-| `spec-seat` | **Every** seat a coordinator arms — invoked FIRST, before the job skill | The CONTRACT, not a seat: the shared half of every seat's procedure — beliefs, plain-text PLAN TLDR, numbered questions w/ recommendations, six-section FINAL TLDR, commit only on the relayed call |
+| `spec-seat` | **Every** seat a coordinator arms — invoked FIRST, before the job skill | The CONTRACT, not a seat: the shared half of every seat's procedure — beliefs, plain-text PLAN TLDR, numbered questions w/ recommendations, the hand-cranked relay, six-section FINAL TLDR, commits once the plan is approved |
 | `spec-build` | Igniting a build or fixit seat — manually or platform-spawned, after `spec-seat` | The BUILD JOB only: one spec, the role's reading list, the pin taxonomy, the suite protocol; `fixit` variant for no-spec defect sessions. Its ceremony comes from `spec-seat` |
-| `spec-witness` | A pipeline looks wedged, actors' claims conflict, or you want a substrate-verified state report | The read-only fourth seat: the control plane's read lanes, transcripts, git; zero writes, zero rulings — the seats act, the human judges, the witness testifies |
+| `spec-witness` | A pipeline looks wedged, actors' claims conflict, or you want a substrate-verified state report | The outside watcher — a session outside the plane, never a declared seat, no credential: git, transcripts, board files, the process table; zero writes into the run, zero rulings — the seats act, the human judges, the witness testifies |
 | `spec-ignite` | Right after `spec-pipeline` when the pipeline runs HOSTED (vs `spec-coordinator` for hand-cranked) | The ignition copilot: verify the committed brief, derive the stage card (the human clicks Create), "kick it", a hosted coordinator runs the pipeline; two verbal gates, everything announced, every UI gap a named finding |
 | `spec-review` | A pipeline's builds are done and it has a review row | The outside look, before the retro and before the PR: code + patterns + composition across session seams + the loop's own comms, in two independent passes. Files `sessions/code-review.md` and classifies which findings earn a fixit. **Its value is having none of the pipeline's context** |
 | `spec-retro` | The coordinator's LAST act, after any review and any fixit | The inside look: a substrate-verified grade, the ceremony audit (did the acts the seat believes it performed actually write rows?), the ledger reconciliation, the true economics, the blindnesses, and the ranked fixit backlog |

package/references/engineering-loop.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.7.1 -->
+<!-- naswerks-loop: version=0.9.0 -->
 # The Engineering Loop — flow, seats, skills, and the ceremony
 
 > The quick intro to how work gets built with this loop: the two loops (`docs-*` knowledge, `spec-*`
@@ -34,9 +34,11 @@ out-of-pipeline buys a clean PR diff and no contingency. Nothing else about the
 ```
 Idea                    -> docs-backlog          -> research doc in docs/research/
 Research matures        -> a plan (a plan-approval mode, if the harness has one)
-Plan graduates          -> spec-pipeline         -> docs/research/{topic}/: umbrella + one spec
-                                                    per session + project-status.md (the plan is
-                                                    now throwaway — the specs carry every crumb)
+Plan graduates          -> spec-pipeline         -> docs/research/{topic}/: the ignition brief (the
+                                                    coordinator's spec and the charter every seat
+                                                    reads) + one spec per build seat +
+                                                    project-status.md (the plan is now throwaway —
+                                                    the specs carry every crumb)
 Same session — CHOOSE THE SEAT:
   hand-cranked          -> spec-coordinator      -> this session becomes the COORDINATOR and cuts
                                                     Prompt #1 (you relay every message)
@@ -45,8 +47,9 @@ Same session — CHOOSE THE SEAT:
                                                     click Create, "kick it", a hosted coordinator
                                                     runs the whole pipeline; you own parks +
                                                     completes + the kill-switch
-Per spec (new session)  -> BUILD SEAT            -> recon, PLAN TLDR, rulings, build,
-                                                    FINAL TLDR, docs-write, commit (on call)
+Per spec (new session)  -> BUILD SEAT            -> recon, PLAN TLDR, rulings, build, docs-write,
+                                                    commit + branch push (by hand: on the plan's
+                                                    approval; hosted: on the call), FINAL TLDR
 Builds done, if chosen  -> spec-review           -> the OUTSIDE look, before the retro and before the
   (a pipeline row)                                  PR: code + patterns + composition across seams +
                                                     the loop's own comms; sessions/code-review.md.
@@ -59,21 +62,27 @@ Close (coordinator)     -> spec-retro            -> the INSIDE look: the ceremon
 Effort done             -> docs-process          -> living docs patched (consuming the working docs
   (fresh session, or a                              AND code-review.md); specs + working docs
    pipeline row if chosen)                          archived together to docs/archive/{topic}/
-Then, and ONLY these    -> the human MERGES the PR, and runs the live-checks rows <- THE TWO HUMAN GATES
+Then, and ONLY these    -> the human MERGES the PR, and takes the quick pass   <- THE TWO HUMAN GATES
 Anytime / periodic      -> docs-status, docs-audit-feature, docs-audit-full  <- NEVER a pipeline row
-Alongside, optional     -> spec-witness — a session OUTSIDE the worktree, read-only, zero writes: a
+Alongside, optional     -> spec-witness — a session OUTSIDE the plane, read-only, no credential: a
                            window into a running pipeline so the human can take its pulse without the UI
 ```
 
 **Two things are the human's, permanently and by design:** the **merge** (a person in the merge path is
-the point, not a gap) and the **live-checks** rows (a machine cannot hand-test a UI). Everything between
-`idea` and `archived` a pipeline can do for itself.
+the point, not a gap) and the **live checks** (a machine cannot hand-test a UI). Live checks are the
+owner's — never a seat's job and never a doc's row: the coordinator offers a short, ordered quick pass in
+the chat, and `live-checks.md` holds only the rows the owner dictates. Everything between `idea` and
+`archived` a pipeline can do for itself.
+
+**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.
 
 **`docs-audit-*` is never a pipeline row.** It runs off-hours and scheduled, over the whole doc tree — not
 inside an effort, and not at an effort's close. A stale living doc is not something a pipeline must stop for.
 
 **The pipeline's SHAPE is decided at authoring, not by a runtime flag.** `spec-pipeline` asks whether the
-effort wants a review row and a docs-process row, and writes them into the row table — so the coordinator
+effort wants a review row and a docs-process row, and writes them into the brief's sequence — so the coordinator
 learns the shape by reading its own sequence, and nothing needs a toggle. A pipeline can be plain,
 `+review`, `+review +process`, or `+process`.
 
@@ -120,10 +129,10 @@ What a commit and a PR pass here, beyond the loop. These add to the Hard rules b
 
 | Seat | Who | Holds | Never does |
 |---|---|---|---|
-| **Human** | you | final approvals (plan-approve click, hard questions, push/publish, hand-testing), the relay in manual mode | writes feature code mid-pipeline |
+| **Human** | you | final approvals (plan-approve click, hard questions, publish, the merge, hand-testing), the relay in manual mode | writes feature code mid-pipeline |
 | **Coordinator** | one long-lived session per effort | the north star + full pipeline context; cuts each seat prompt from the previous session's *actual* results; judges PLAN/FINAL TLDRs; rules with rationale; verifies load-bearing claims itself; owns `project-status.md` | writes feature code; trusts self-reported "N green" |
-| **Seat** | one fresh session per spec | exactly ONE spec; recons the real code first; builds; reports honestly | touches the tracker or memory; commits without the relayed call; runs `docs-write` unprompted |
-| **Witness** *(optional, `spec-witness`)* | a read-only session with substrate access | testifies from rows/transcripts/git when claims conflict or a pipeline looks wedged; answers "whose turn is it" | writes anything; injects anything; rules on anything |
+| **Seat** | one fresh session per spec | exactly ONE spec; recons the real code first; builds; reports honestly | touches the tracker, `live-checks.md` or memory; commits before its plan is approved; pushes to the base branch; runs `docs-write` unprompted |
+| **Witness** *(optional, `spec-witness`)* | a session outside the plane, usually on the runner's machine — never a declared seat, no credential | testifies from git, transcripts, board files and the process table when claims conflict or a pipeline looks wedged; answers "whose turn is it"; drafts messages for the human | writes into the run; injects anything; rules on anything |
 
 The seat, not the chat, is the product: `project-status.md` must stay current enough that a
 fresh session can resume as coordinator losslessly (`spec-coordinator {topic}`).
@@ -144,7 +153,7 @@ fresh session can resume as coordinator losslessly (`spec-coordinator {topic}`).
 | `spec-ignite` | spec | when an authored pipeline runs HOSTED (the `spec-coordinator` alternative) | the ignition copilot, and it can run COLD: gates, re-verify the brief's baselines + platform state against live HEAD, derive the stage card (human clicks Create), "kick it" with the brief's own kick text as the task; every UI gap a named finding |
 | `spec-review` | spec | a pipeline's builds are done, if it has a review row | the OUTSIDE look, before the retro and before the PR: correctness/security/**composition across session seams** · the patterns, with every departure identified · the loop's own comms. Two independent passes, consolidated. Classifies which findings earn a fixit; **its value is having none of the pipeline's context** |
 | `spec-retro` | spec | the coordinator's LAST act, after any review and any fixit | the INSIDE look: a substrate-verified grade, the ceremony audit (did the acts write rows?), the ledger reconciliation, the true economics, the blindnesses, the ranked fixit backlog — *a retrospective that cannot indict its own author is marketing* |
-| `spec-witness` | spec | a pipeline looks wedged, or actors' claims conflict | the read-only fourth seat: substrate access, zero writes, zero rulings |
+| `spec-witness` | spec | a pipeline looks wedged, or actors' claims conflict | the outside watcher: read-only, no credential, never a declared seat; its tools ship in `bin/` |
 | `init` | — | a repository that has none of this yet | create the `docs/` shape, the method docs, first drafts of every doc the skills read; `init doctor` says what is missing |
 
 ### Where a rule lives — policy, procedure, task
@@ -163,7 +172,7 @@ One copy per rule: where a prompt and a skill would say the same thing, the prom
 holds it.
 
 **Why the split exists.** A single base contract every seat kind shared, with the build job mixed in,
-sends the REVIEW row into the umbrella its own charter excludes and offers the DOCS-PROCESS row a
+sends the REVIEW row into the coordinator's settled framing its own charter excludes and offers the DOCS-PROCESS row a
 `docs-write` from a build skill's close-out — the row that has just *emptied* `docs/working/`. One base
 class, three wrong instructions, and none of it visible until the loop runs end to end.
 
@@ -182,19 +191,26 @@ diff.
    `blocking-precondition` / `read-full-plan`), one CAPS ruling per question, decision first
    then the WHY. The coordinator diffs the seat's beliefs against the ledger before ruling.
 4. **Plan-approve = the freedom moment** (manual: approve + bypass-permissions; hosted: the gate
-   flips). The seat builds uninterrupted; mid-run questions repeat the relay loop.
+   flips). The seat builds uninterrupted; mid-run questions repeat the relay loop. **By hand, the seat
+   then runs to done without a stop** — build, suites, `docs-write`, commits with `verify-staged`, its
+   branch pushes (never the base branch) — its notes from the coordinator transcribed verbatim into its
+   `tldr.md` first. Its only stops: a destructive act outside the effort's branches, a credential
+   exposure, a host restart, a `verify-staged` failure.
 5. **Seat ends with the six-section FINAL TLDR** — shipped+verification, verbatim runner
-   summaries (with invocation commands), honest gaps, deferred findings, live checklist
-   entries, staging list + commit HELD + session cost.
+   summaries (with invocation commands), honest gaps, deferred findings, what the owner could try
+   (in the chat, never a file), staging list + its receipt (hosted: commit HELD) + session cost.
 6. **Coordinator verifies one load-bearing claim itself** (receipts compared first; rerun only in
-   doubt), then the **close-out call**: optional fix/rerun, `docs-write` with an itemized
-   carry, COMMIT CALL with the seat's own staging list, push (human approves the push).
+   doubt). By hand it reviews the FINAL against the tree and writes `## COORDINATOR ACCEPT (final —
+   {slice})` into the seat's `tldr.md`; hosted it sends the **close-out call**: optional fix/rerun,
+   `docs-write` with an itemized carry, COMMIT CALL with the seat's own staging list, then the push.
 7. **Coordinator flips the tracker row** to SHIPPED + hash and transcribes deferred findings — the
    seat never writes the tracker. **The coordinator also commits the closing seat's post-push
    close-out append, byte-untouched, as part of closing the row** — the append lands after the
    seat's own commit, so left alone it hands the NEXT seat a dirty tree. Goto 1.
 
-**Hard rules:** no commit/push without the relayed call; explicit staging, never `git add -A`, verified
+**Hard rules:** no commit or push before the plan is approved, and never a push to the base branch —
+approved work includes its commit, its push and the coordinator's PR, and nobody asks for them again;
+explicit staging, never `git add -A`, verified
 with `verify-staged`; codegen only through the command `patterns/codegen.md` names (when the repo has
 one); component files as
 `patterns/frontend-patterns.md` states; additive-only, never amend pushed commits; parallel sessions only
@@ -212,7 +228,7 @@ COORDINATOR -> COORDINATOR RESPONSE — PLAN {ACCEPTED / ACCEPTED-WITH-RIDERS /
                (DECISION — why) · riders · "Go build."
 SEAT        -> (builds free; mid-run question: numbered text, STOP; COORDINATOR ruling; resume)
 SEAT        -> FINAL TLDR — (a) SHIPPED+VERIFICATION (b) VERBATIM RUNNER SUMMARIES (c) HONEST GAPS
-               (d) DEFERRED FINDINGS (e) LIVE CHECKLIST (f) STAGING + commit HELD + cost
+               (d) DEFERRED FINDINGS (e) WHAT THE OWNER COULD TRY (f) STAGING + receipt + cost
 COORDINATOR -> FINAL TLDR ACCEPTED (+ what the coordinator verified itself) · 1. docs-write, carry: …
                · 2. COMMIT CALL — message: … · then push, report hash
 SEAT        -> books the working doc, commits, pushes, reports hash + post-push status
@@ -239,9 +255,11 @@ with the effort:
 docs/research/{topic}/sessions/         <- per-session work in {spec-slug}/, effort-wide at the root
   {spec-slug}/plan.md           each seat   the full plan, posted once, corrected on pushback (PULL-only)
   {spec-slug}/tldr.md           each seat   the two-voice chat — seat turns AND coordinator rulings interleaved
+  docs-process/plan.md + tldr.md  the P row  its board, here from the start — never a gitignored folder
+  {step-slug}/receipt.md        a human     a `step` row's receipt, in the step's own commit
   code-review.md                the review  the outside look, if the pipeline had a review row
   coordinator-retrospective.md  the coord.  the close-out audit (the inside look)
-  witness-ledger-*.md           a human     the witness is zero-writes, so its ledger arrives by hand
+  witness-ledger-*.md           a human     the witness writes nothing into the run; its ledger is filed on the human's word
 ```
 
 Two files per build session; questions ride the TLDR, and there are no status snapshots because the

package/skills/docs-audit-full/SKILL.md

@@ -27,7 +27,8 @@ what to audit next.
    `docs/patterns/` docs; note drift.
 
 4. **Research scan** — scan `docs/research/`; flag ideas that look already-implemented (so they can be
-   graduated/removed) and ideas worth surfacing.
+   filed with their effort, or retired as § The archive convention (repository-owned) says) and ideas worth
+   surfacing.
 
 5. **Working/archive sanity** — note any docs lingering in `docs/working/` that look done (should be
    filed via `docs-process`), and confirm the filed efforts are intact where § The archive convention

package/skills/docs-process/SKILL.md

@@ -18,9 +18,13 @@ Most of the time a human runs this cold, after a merge, and this section does no
 you have not. It carries the blackboard, the question lane, the PLAN TLDR, the verdict vocabulary, the
 six-section FINAL TLDR, and the close-out order. Two things are yours specifically:
 
-- **You are handed a MANIFEST of this effort's working docs BY NAME. `docs/working/` is a SHARED QUEUE
-  — never infer membership from the folder.** A seat that archives a neighbouring effort's docs cannot
-  undo it. If your prompt did not name them, ask before you move anything.
+- **You are handed a MANIFEST of this effort's working docs BY NAME — every input arrives as a LIST,
+  never a folder. `docs/working/` is a SHARED QUEUE — never infer membership from the folder.** A seat that
+  archives a neighbouring effort's docs cannot undo it. If your prompt did not name them, ask before you move
+  anything.
+- **Your board is `docs/research/{topic}/sessions/docs-process/`** (`plan.md` + `tldr.md`) from the start —
+  never a gitignored folder you copy from later. The folder moves with the effort when you file it, so the
+  board you commit is the board you wrote, close-out receipt included.
 - **Do NOT run `/docs-write`.** You are that skill's CONSUMER, never its caller — a working doc from you
   would be an orphan in the queue you just emptied, for an effort you just archived. Your artifacts are
   the patched living docs and the archive; go straight to the commit call.
@@ -77,7 +81,7 @@ branch, which is the truth for that PR, and you say so at close.
        spec pipeline (the `Spec` row), and the working-doc sequence / `## Archive` target (the `Built` row);
        derive `Related` from existing peer links. Compute any field the header derives from those links the
        way the section says. **Keep `Spec` and `Built` symmetric** — list **every per-slice spec that a
-       `Built` session implemented** (the umbrella + `00-operating-frame` go in `Idea`, not `Spec`); a `Built`
+       `Built` session implemented** (the ignition brief + any `00-operating-frame` go in `Idea`, not `Spec`); a `Built`
        session whose spec is missing from `Spec` is the smell (the `## Lineage` rules § Doc metadata
        (repository-owned) gives).
      - *Patching an existing doc*: update the status if it changed and recompute any field the header
@@ -92,6 +96,8 @@ branch, which is the truth for that PR, and you say so at close.
      section (create the section if absent). Only what you actually saw in the code this pass — never
      speculation. A sizable design idea goes to `docs-backlog` (research/) instead. `docs-status`
      surfaces these so they aren't lost.
+   - **Never add a live check to a living doc.** Live checks are the owner's: a working doc's "the owner
+     could try" lines are not a checklist item, and no living doc grows a row of checks to run.
 
 3. **A new living doc?** If the work added a feature, ensure it has a doc in `docs/features/` (one doc per
    feature). Then register every living doc this run created where the menu's shape line says
@@ -110,11 +116,11 @@ branch, which is the truth for that PR, and you say so at close.
    patched and verified, file the whole effort where `docs/_meta/docs-workflow.md` § The archive convention
    (repository-owned) says, in the shape it gives for this kind of effort (a small effort, a spec pipeline,
    a follow-on round). That section holds the destination, the shape and the links a move repairs; this
-   step holds the procedure, which is the same everywhere. A pipeline whose umbrella carries an `Archive:`
-   line files there.
+   step holds the procedure, which is the same everywhere. A pipeline whose ignition brief carries an
+   `Archive:` line files there.
 
    **FIRST, RECONCILE THE DESTINATIONS — `rg -A1 '^## Archive' <every working doc in the effort>`, plus
-   the umbrella's `Archive:` line when there is a pipeline.**
+   the brief's `Archive:` line when there is a pipeline.**
    This step says *"one archive home"* and *"use the `## Archive` line"* — a singular read over a PLURAL
    source, so the set is checked before any move. **If the docs disagree, STOP and ask.** Do not pick the
    majority, do not pick the first, and do not pick the one you happen to be reading. The failure is not

package/skills/docs-write/SKILL.md

@@ -31,7 +31,7 @@ keeps the doc editable until its living-doc obligations are discharged.
    - **Watch-Outs** — edge cases, gotchas
    - **Living Docs to Update** — the bridge to `docs-process`. For each stale living doc, name it and say what changed and in what form. Be specific ("references `OldEntity`, should be `NewEntity`"), not vague.
 
-3. **Record the archive target — don't move the file.** Add an `## Archive` line to the doc, in the form the session template gives it (`docs/_meta/docs-workflow.md` § Templates (repository-owned)), naming where § The archive convention (repository-owned) files this effort — reuse what that section says to reuse, and name it the way that section names things. When the effort has a spec pipeline whose umbrella carries an `Archive:` line, that path is the target. `docs-process` files it there later. The doc itself **stays in `docs/working/`**.
+3. **Record the archive target — don't move the file.** Add an `## Archive` line to the doc, in the form the session template gives it (`docs/_meta/docs-workflow.md` § Templates (repository-owned)), naming where § The archive convention (repository-owned) files this effort — reuse what that section says to reuse, and name it the way that section names things. When the effort has a spec pipeline whose ignition brief carries an `Archive:` line, that path is the target. `docs-process` files it there later. The doc itself **stays in `docs/working/`**.
 
 4. **Stop.** The finished doc sits in `docs/working/` as the queue. Do NOT patch living docs, do NOT grep for stale references, do NOT file it — all of that is `docs-process`.
 

package/skills/init/scripts/doctor.mjs

@@ -5,7 +5,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
-import { OWNED, KINDS, KIND_SKILLS, NOT_SKILLS, skillTokens, compareVersions, compareMinor, frontmatterListCount, linesOf, bare, h2Index, findSection, railsItems } from './owned.mjs';
+import { OWNED, KINDS, STEP, ROLES, SPEC_FILE, KIND_SKILLS, NOT_SKILLS, skillTokens, compareVersions, compareMinor, frontmatterListCount, linesOf, bare, h2Index, findSection, railsItems } from './owned.mjs';
 
 const repo = resolve(process.argv[2] || process.cwd());
 const packRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
@@ -197,6 +197,11 @@ for (const name of ['CLAUDE.md', 'AGENTS.md']) {
 // The kick is sent verbatim as the coordinator's task, so a skill it names that this pack does not carry
 // (a renamed one, most often) tells the coordinator to invoke nothing.
 const packSkills = new Set(existsSync(join(packRoot, 'skills')) ? readdirSync(join(packRoot, 'skills')) : []);
+// A repository's name as a sequence row may write it: one path segment, no separators, no spaces, of at most
+// MAX_REPOSITORY_NAME characters; a row names at most MAX_REPOSITORIES, none twice.
+const REPOSITORY_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const MAX_REPOSITORY_NAME = 200;
+const MAX_REPOSITORIES = 8;
 const researchDir = join(repo, 'docs', 'research');
 if (existsSync(researchDir)) {
   for (const topic of readdirSync(researchDir)) {
@@ -209,21 +214,54 @@ if (existsSync(researchDir)) {
     else if (!kick.split('\n').some((l) => l.trimStart().startsWith('>'))) problems.push('the `## The kick` section carries no blockquote; its whole text stands in for the task');
     const unknown = kick === null || packSkills.size === 0 ? [] : [...new Set(skillTokens(kick))].filter((t) => !packSkills.has(t) && !NOT_SKILLS.includes(t));
     const seq = sectionOf(text, '## The sequence');
+    const named = new Set();
     if (seq === null) problems.push('the brief has no `## The sequence` section, so no seats could be read');
     else {
       const tableRows = seq.split('\n').filter((l) => l.trim().startsWith('|'));
       if (tableRows.length === 0) problems.push('the `## The sequence` section holds no table, so no seats could be read');
+      const cellsOf = (line) => line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim().replace(/^`|`$/g, '').trim());
+      // The optional Role column, found by its header; a row's cell there is a role or empty.
+      const roleAt = tableRows.length ? cellsOf(tableRows[0]).findIndex((c) => c.toLowerCase() === 'role') : -1;
+      // The optional Repository column, found by its header; a row's cell there names the repositories the
+      // seat also writes in, or is empty. The table is read by kind value, so a kind word or `step` in that
+      // cell would be read as the row's kind: it fails by name, before either is looked for.
+      const repositoryAt = tableRows.length ? cellsOf(tableRows[0]).findIndex((c) => c.toLowerCase() === 'repository') : -1;
+      // The seat rows' kinds, in order: where a listed fixit sits is read from them.
+      const seatKinds = [];
       for (const line of tableRows.slice(1)) {
-        const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim().replace(/^`|`$/g, '').trim());
+        const cells = cellsOf(line);
         if (cells.every((c) => /^[-: ]*$/.test(c))) continue;
-        if (!cells.some((c) => KINDS.includes(c))) { problems.push(`a sequence row names no seat kind and composes nothing: \`${line.trim()}\``); continue; }
-        const spec = cells.map((c) => /\b(\d{2}-[A-Za-z0-9._-]*?\.md)\b/.exec(c)).find(Boolean);
+        const spec = cells.map((c) => SPEC_FILE.exec(c)).find(Boolean);
+        if (spec) named.add(spec[1]);
+        const repositories = repositoryAt >= 0 ? (cells[repositoryAt] ?? '') : '';
+        const names = !repositories || /^[-—]$/.test(repositories) ? [] : repositories.split(/\s*[·,]\s*/).map((n) => n.replace(/`/g, '').trim()).filter((n) => n !== '');
+        const notNames = names.filter((n) => KINDS.includes(n) || n === STEP || !REPOSITORY_NAME.test(n) || n.length > MAX_REPOSITORY_NAME);
+        if (notNames.length) {
+          for (const n of notNames) problems.push(`a sequence row's repository \`${n.length > 60 ? `${n.slice(0, 60)}…` : n}\` is not a repository's name (one path segment of at most ${MAX_REPOSITORY_NAME} characters; a kind word or \`${STEP}\` there is read as the row's kind): \`${line.trim().slice(0, 200)}\``);
+          continue;
+        }
+        if (names.length > MAX_REPOSITORIES) problems.push(`a sequence row names ${names.length} repositories and a seat writes at most ${MAX_REPOSITORIES}: \`${line.trim()}\``);
+        for (const n of new Set(names.filter((name, i) => names.indexOf(name) !== i))) problems.push(`a sequence row names the repository \`${n}\` twice: \`${line.trim()}\``);
+        if (cells.includes(STEP)) continue;
+        if (!cells.some((c) => KINDS.includes(c))) { problems.push(`a sequence row names no seat kind and composes nothing (a row that is not a seat says \`${STEP}\`): \`${line.trim()}\``); continue; }
+        seatKinds.push(cells.find((c) => KINDS.includes(c)));
+        const role = roleAt >= 0 ? (cells[roleAt] ?? '') : '';
+        if (role && !/^[-—]$/.test(role) && !ROLES.includes(role)) problems.push(`a sequence row's role \`${role}\` is not one of ${ROLES.map((r) => `\`${r}\``).join(' · ')}: \`${line.trim()}\``);
         if (spec && !existsSync(join(researchDir, topic, spec[1]))) problems.push(`the sequence names \`${spec[1]}\` and it is missing from disk`);
       }
+      // A listed fixit is the one its review implies only when it is the next seat row after that review. Listed
+      // anywhere else, a launcher reads a second fixit beside the implied one, and that one names no repository.
+      const reviewAt = seatKinds.indexOf('review');
+      const fixitAt = seatKinds.indexOf('fixit');
+      if (reviewAt >= 0 && fixitAt >= 0 && fixitAt !== reviewAt + 1) problems.push('the sequence lists a `fixit` row that is not the next seat row after its `review` row, so a launcher reads two fixits and the extra one names no repository: move the row directly after the review');
     }
+    // An old-shape folder carries an umbrella: a `01-` file no sequence row names. It still runs on an older
+    // pack; carry it over before it runs on this one.
+    const umbrellas = seq === null ? [] : readdirSync(join(researchDir, topic)).filter((f) => /^01-.+\.md$/.test(f) && !named.has(f));
     for (const pr of problems) row('FAIL', `docs/research/${topic}/00-ignition-brief.md`, pr);
     for (const t of unknown) row('DEGRADE', `docs/research/${topic}/00-ignition-brief.md`, `the kick names \`${t}\`, a skill this pack does not carry; the coordinator's skill is \`${KIND_SKILLS.coordinator}\``);
-    if (!problems.length && !unknown.length) row('ok', `docs/research/${topic}/00-ignition-brief.md`, 'the kick and the sequence read clean');
+    for (const u of umbrellas) row('DEGRADE', `docs/research/${topic}/00-ignition-brief.md`, `old shape — fold \`${u}\` into the brief (CHANGELOG 0.8.0 § Upgrading)`);
+    if (!problems.length && !unknown.length && !umbrellas.length) row('ok', `docs/research/${topic}/00-ignition-brief.md`, 'the kick and the sequence read clean');
   }
 }
 

package/skills/init/scripts/owned.mjs

@@ -24,6 +24,16 @@ export const STAMP = /^(<!-- naswerks-loop: version=)([0-9]+\.[0-9]+\.[0-9]+[^ ]
 // The seat kinds a pipeline row may name, checked the way the control plane checks a brief's sequence.
 export const KINDS = ['coordinator', 'build', 'fixit', 'review', 'retro', 'witness', 'docs-process'];
 
+// The one word for a sequence row that is not a seat (a publish, a merge, a human sitting). No misspelled
+// seat kind can equal it, so a row whose kind is misspelled still fails by name instead of reading as a step.
+export const STEP = 'step';
+
+// The roles a sequence row's optional `Role` cell may carry: which reading list a build seat takes.
+export const ROLES = ['backend', 'frontend', 'mixed'];
+
+// A numbered file a sequence row names: a seat's spec, or the brief itself on the coordinator's row.
+export const SPEC_FILE = /\b(\d{2}-[A-Za-z0-9._-]*?\.md)\b/;
+
 // The skill each kind runs as its job. A spec seat's skill is named for its kind, so a skill's name says
 // which seat runs it: `fixit` is the build job's no-spec variant, and `docs-process` is the knowledge
 // loop's own skill, seated by a pipeline as its last row.