@naswerks/engineering-loop 0.7.1 → 0.9.0

package/skills/spec-build/SKILL.md

@@ -22,7 +22,8 @@ Invoked as `spec-build {role} {spec-path}`, or told "you are a build session" wi
 apply** (`spec-seat`, Step 0). This list is for a build seat working from a spec.
 
 1. **Your spec** — fully, INCLUDING any Addendum sections. It is self-contained.
-2. **The umbrella** (`01-{topic}.md`) — settled decisions; don't relitigate them.
+2. **The brief** (`00-ignition-brief.md`) — the charter: its sections down to § Platform state bind you,
+   and the owner's rulings in it are settled; don't relitigate them.
 3. **The tracker** — `docs/research/{topic}/project-status.md`. The coordinator's live journal and
    READ-ONLY to you. Prior session rows, deferred findings, and process incidents are your contract: build
    against what ACTUALLY shipped, not the spec's guesses. **If anything in it disagrees with your spec or
@@ -49,6 +50,9 @@ your role's rows from `docs/_meta/doc-index.md` § Role reading lists into your
 Read those the same way. If your prompt carries no `EXTRA DOCS` line, read that section yourself once and
 say in your PLAN TLDR which rows you took.
 
+**Your role is the one your prompt names** — the brief's sequence row carries it in a `Role` cell when the
+author set one — and `mixed` when neither says.
+
 A role is *which docs does this build session read* — nothing else. Jobs are SEAT KINDS, not roles:
 `docs-process` is a session type of its own, and a spec that touches a surface with no role of its own is
 `mixed` with that surface's rows.
@@ -63,9 +67,9 @@ minutes while assuming the work is pending rebuilds what already exists.
 Run `git status`; identify which dirty files are yours-to-be vs NOT yours (coordinator-owned docs appear
 mid-run — never stage them). Answer any STANDING RECON QUESTION your spec or prompt carries.
 
-**Measure your own baseline for any lane you touch, BEFORE you edit.** A same-day coordinator-verified
-baseline is an acceptable substitute when cited, but measuring your own is the norm — and a number you
-cannot reproduce is a finding.
+**The floor is cited, never measured in a pipeline.** The brief's § Baselines was measured at authoring
+and re-measured at the GATE: cite it, lane by lane. **Measure only a lane the brief does not name, and
+measure it before you edit.** A number you cannot reproduce when you do run a lane is a finding.
 
 ## Build
 
@@ -89,6 +93,10 @@ signal that a VERDICT changed, not that the test is stale.
 Run the suite lanes **SERIALLY** — the lanes and their exact invocations are `patterns/testing.md`
 § Running tests; concurrent runs flake.
 
+**A seat that wrote a further repository runs THAT repository's gate too, inside its tree of it** — the
+lanes its own contributing rules name, serially, never beside this repository's — and reports each
+repository's summaries under its own name. This repository's lanes do not run the code you wrote there.
+
 **Capture FULL runner output to a UTF-8 file and search failures by name** — redirect to a file, then
 search `^failed ` / `Failed!`. Piping through a "last N lines" filter destroys failure names.
 

package/skills/spec-coordinator/SKILL.md

@@ -21,8 +21,9 @@ touches the tracker or commits unprompted; you never write feature code — you
 
 **Who carries the messages depends on the mode, and the rest of this skill is written for both:**
 
-- **Hand-cranked** — a human relays every message, clicks plan-approve, and authorizes the push. The
-  ceremony below is the same; the human is the bus.
+- **Hand-cranked** — a human relays every message and approves each plan; an approved seat then runs to
+  done, its commits and branch pushes included (§ The hand-cranked relay). The ceremony below is the same;
+  the human is the bus.
 - **Hosted (including unattended)** — **your own verbs are the relay and the gate.** You spawn each seat's
   session, rule its plan (which is what flips its gate), steer it, receipt its final TLDR and reap it; the
   retro, the commit and the PR are yours. Pushes ride the unattended lane and are receipted, so they do
@@ -34,38 +35,42 @@ hand-testing what shipped. Everything else that a human does hand-cranked, you d
 
 ## Read first
 
-**Step 0 — the same floor every seat reads, all seven, plus every standard doc this repository has.**
-You verify every seat's work, so you start from the context they build in. A coordinator that has not
-read `testing.md` cannot judge a receipt; one that has not read `codegen.md` (when the repo has one)
-cannot spot a hand-written generated file.
+**Step 0 — two reads, and neither is optional.** You verify every seat's work, so you start from the
+context they build in. A coordinator that has not read `testing.md` cannot judge a receipt; one that has
+not read `codegen.md` (when the repo has one) cannot spot a hand-written generated file.
 
-`_meta/doc-index.md` · `_meta/docs-workflow.md` · `_meta/engineering-loop.md` ·
-`patterns/code-organization.md` · `patterns/backend-patterns.md` · `patterns/frontend-patterns.md` ·
-`patterns/testing.md` — then every doc `doc-index.md` § Role reading lists carries a path for.
+1. **The floor every seat reads, all seven:** `_meta/doc-index.md` · `_meta/docs-workflow.md` ·
+   `_meta/engineering-loop.md` · `patterns/code-organization.md` · `patterns/backend-patterns.md` ·
+   `patterns/frontend-patterns.md` · `patterns/testing.md`.
+2. **Then every doc `doc-index.md` § Role reading lists carries a path for.** Open that section and read
+   each one. The floor alone is not Step 0.
 
 **Step 1 — the effort**, in order:
 
 1. `docs/research/{topic}/project-status.md` — the tracker. **You own it.**
-2. `00-ignition-brief.md` if there is one — this run's standing orders.
-3. `01-{topic}.md` — the umbrella. Its settled decisions govern; don't relitigate them.
-4. **EVERY numbered spec, before arming the first seat.** You judge plans against them and
-   cut each prompt from the previous session's actual shapes — you cannot do either from the tracker
-   alone. Specs cross-reference: reading them as they come up means ruling on slice 3 without knowing
-   slice 6 depends on its column name.
-
-**Then run the SHAPE COHERENCE CHECK — it takes seconds and it has caught real defects.** The shape
-lives in exactly three places:
-
-> the brief's `## The sequence` · the umbrella's row table · the tracker's `## Session status`
-
-**They must list the same rows, in the same order.** Check it now, and again before you cut the retro. **A
-disagreement is a finding, not a typo** — it means one seat changed the shape and the other two still
-describe the old one, and the seat most likely to act on the stale copy is the one reading only that file.
-Say which is right, fix the others, and journal it.
+2. `00-ignition-brief.md` — **your spec, and the charter every seat reads.** Its sections down to
+   § Platform state bind every seat; the owner's rulings in it are settled — don't relitigate them; the
+   sections after § Platform state are your orders.
+3. **EVERY numbered spec, before arming the first seat.** Every numbered file is one build seat's spec.
+   You judge plans against them and cut each prompt from the previous session's actual shapes — you cannot
+   do either from the tracker alone. Specs cross-reference: reading them as they come up means ruling on
+   slice 3 without knowing slice 6 depends on its column name.
+
+**When no ignition copilot verified the brief — a run by hand — the GATE is yours.** Check that the
+predecessor merged (only that: never a gate on another pipeline's seats), re-verify § Reference against
+HEAD, and re-measure § Baselines, before the first seat is armed. A seat cites those baselines; it measures
+only a lane the brief does not name.
+
+**Then run the SHAPE CHECK — one comparison, seconds, and it has caught real defects.** The sequence is
+written once, in the brief's `## The sequence`; the tracker's `## Session status` carries one status line
+per row, by the brief's ids. **Every row has its status line and every status line has its row.** Check it
+now, and again before you cut the retro. **A disagreement is a finding, not a typo** — it means the shape
+changed in one place and not the other. Say which is right, fix the other, and journal it.
 
 Then produce a **5-line status readback** — shipped / in flight / next action / next prompt you expect to
-cut. Hand-cranked that goes to the human so they can confirm the seat transferred; hosted it is your
-opening journal entry in `project-status.md`, which is how anyone watching the cockpit catches up.
+cut — opening with how many docs each of Step 0's two reads took. Hand-cranked that goes to the human so
+they can confirm the seat transferred; hosted it is your opening journal entry in `project-status.md`,
+which is how anyone watching the cockpit catches up.
 
 **Same-session graduation:** you just ran `spec-pipeline`, so you already hold most of Step 1 — confirm
 the tracker exists and cut Prompt #1. **Step 0 still applies.**
@@ -85,7 +90,7 @@ plus the human relay.
 | Verb | What it does | The part that bites |
 |---|---|---|
 | `seat_spawn` | Opens a DECLARED sibling's session | **It can never CREATE a seat** — the topology is the create door's, decided by a human — and you may only drive seats you `supervises`/`reviews`. With no `hostId` it opens on the host carrying your own session; `model` and `effort` override the seat's own for this session, judged against what the runner offers |
-| `accept_plan` | The verdict act: `accept` · `accept-with-riders` · `blocking-precondition`, **and NOTHING ELSE carries a go** — and it DELIVERS ITSELF: the seat's live session receives a one-line pointer to the ruling, for an accepting verdict and for any verdict that filed a ruling in the seat's file | Write the ruling into the seat's `tldr.md` FIRST (`## COORDINATOR RULING (plan rev N — {verdict})`), then call with a one-line `ruling`: the file is mirrored before your act and the pointer names your section. Pass the workspace HEAD you observed (a backticked sha is fine); an accepting verdict whose seat planned against a different tree is REFUSED, naming both shas. READ THE REPLY'S `delivery:` and `file:` LINES — `NOT DELIVERED` means the seat is idle and only a `callout` reaches it. When the verdict also answers the seat's question, pass `answeringActId` — one act rules and closes it |
+| `accept_plan` | The verdict act: `accept` · `accept-with-riders` · `blocking-precondition`, **and NOTHING ELSE carries a go** — and it DELIVERS ITSELF: the seat's live session receives a one-line pointer to the ruling, for an accepting verdict and for any verdict that filed a ruling in the seat's file | Write the ruling into the seat's `tldr.md` FIRST (`## COORDINATOR RULING (plan rev N — {verdict})`), then call with a one-line `ruling`: the file is mirrored before your act and the pointer names your section. Pass the workspace HEAD you observed as the bare 40-hex sha `git rev-parse HEAD` prints — a backticked or quoted one is refused and records nothing, though a seat's board may fence its own; an accepting verdict whose seat planned against a different tree is REFUSED, naming both shas. READ THE REPLY'S `delivery:` and `file:` LINES — `NOT DELIVERED` means the seat is idle and only a `callout` reaches it. When the verdict also answers the seat's question, pass `answeringActId` — one act rules and closes it |
 | `accept` | The rev-bound FINAL receipt — and it TELLS the seat, so it carries your commit call | Put the next instruction (commit, push, close-out) in `ruling`, or write it under `## COORDINATOR ACCEPT` in the seat's `tldr.md` first — the receipt then binds to that mirrored revision. It binds to the seat's CURRENT tldr revision, so if the seat posts NEW CONTENT again your acceptance no longer covers what it publishes. **Re-accept — it is idempotent and cheap.** This receipt is what the push bar reads; prose is not a receipt. `answeringActId` closes the question it answers, as on `accept_plan` |
 | `complete` | The reap, and it is HONEST | It re-reads the seat and reports ok only after the terminal state is OBSERVED |
 | `callout` | **THE ONLY WAY YOU REACH A CHARGE** (besides the pointers `accept_plan` and `accept` send) | A charge that posted and ended its turn cannot resume any other way — without this verb it waits for a human. Your ruling must carry a DETERMINATE NEXT ACTION it can execute without inference. **Write it into the seat's `tldr.md` first and pass a one-line `ruling`:** the file is mirrored before your act and the seat is pointed at your section. Without a file, KEEP IT TO A LINE: over 600 chars the body is stored as a `ruling` artifact on the board and the seat receives a POINTER — the seat reads the body once, never twice |
@@ -134,7 +139,12 @@ and a seat's close-out. Never reconstruct it at the close.
    opening line and appends nothing of its own to your text, because you are the one who knows the prior
    rows' shapes. **The seed names skills; it never restates ceremony.** A seed that inlines procedure is a
    defect even when it works: there are then two sources for one contract and only one of them gets
-   corrected.
+   corrected. **Hosted, the control plane's opening line already names the skills and the role** — start
+   your text at the spec, and never restate either.
+
+   **Keep each seed as you sent it.** Save the task text verbatim in the effort's record (the tracker's
+   session entry, or a `seed.md` beside the seat's board) at the moment you send it. The review and the
+   retro grade what each seat was told, and a seed reconstructed later from memory is not that.
 
    **Pick the docs:** the floor and the loop's standard docs are settled (`spec-seat`'s Step 0 +
    `spec-build`'s role table). **This repository's own docs are yours to seed, by path, every time:** copy
@@ -144,7 +154,7 @@ and a seat's close-out. Never reconstruct it at the close.
    seat guessing.
 
    **The seed-retirement rule:** each new seed restates ONLY what OVERRIDES a default (every seat
-   re-acquires the defaults from the skill + umbrella from scratch) and DROPS what merely confirms them.
+   re-acquires the defaults from the skill + the brief from scratch) and DROPS what merely confirms them.
    A correction the platform has since absorbed retires from the seed the session after it ships — seeds
    carry deltas, not history. By session 15 an accreted seed is unreadable.
 
@@ -163,6 +173,8 @@ and a seat's close-out. Never reconstruct it at the close.
    call out / hand the human both sides when the call is genuinely theirs.
    **The accepting verdict carries the workspace HEAD you observed, and a seat that planned against a
    different tree is REFUSED with both shas named.** So read the BELIEFS sha before you rule, not after.
+   **A seat whose row names a further repository states that tree too,** on an `ALSO WRITING` line beneath
+   its BELIEFS: diff its commit and branch against that repository's branch, with your own `git` read of it.
    **AND GRADE THE `CONTROLS` LINE — it is a required PLAN TLDR field and you are its only reader.** For
    every probe or pin the seat plans, it must name the positive control and what would make it FAIL. A
    missing or hand-wavy `CONTROLS` line is a rider, not a nit: a control that cannot fail is a green light
@@ -180,6 +192,8 @@ and a seat's close-out. Never reconstruct it at the close.
    But spot-check the riskiest claim yourself (never trust self-reported "N green"), and **verify your own
    rulings were APPLIED** — a ruling can silently drop, and a seat can rebuild the exact problem
    the ruling solved. Diff the shipped behavior against your ruling list before accepting.
+   **A seat that wrote two repositories returns two of everything:** a staging list and its receipt per
+   repository, and each repository's gate under its own name. A green in one says nothing about the other.
    **VERIFY THE CLAIM WHOSE FAILURE WOULD BE SILENT; MACHINE-COMPARE THE REST.** That is the rule that
    keeps your own share of the spend honest — a seat producing receipts that reconcile arithmetically has
    already done the work you would be repeating.
@@ -194,10 +208,14 @@ and a seat's close-out. Never reconstruct it at the close.
    **Advance the tracker AT EVERY CHECKPOINT.** Plan accepted: the row says so; final TLDR accepted: the
    row says so; push confirmed: SHIPPED with the hash. A stale tracker is your omission.
 
-   **REAPING A HUMAN ROW: TAKE THE RECEIPT, DO NOT WRITE IT.** A human row has no seat to post a TLDR,
-   so the temptation is to transcribe the sitting into your tracker and call the row recorded. **That
-   leaves the row with ONE voice — yours — and it is the only row in the effort with one.** Ask the human
-   for `sessions/{slug}/receipt.md` in the row's own commit: each check id, what was run, the literal
+   **WHEN A BRANCH A SEAT PUSHES HAS A PULL REQUEST OPEN, READ ITS CHECKS AT EVERY SEAT REPORT,** in
+   whichever repository it is, with your own read and not the seat's sentence about it: a check read at
+   the first commit says nothing about the tenth.
+
+   **CLOSING A HUMAN STEP: TAKE THE RECEIPT, DO NOT WRITE IT.** A `step` row has no seat to post a TLDR,
+   so the temptation is to transcribe the sitting into your tracker and call the step recorded. **That
+   leaves it with ONE voice — yours — and it is the only row in the effort with one.** Ask the human
+   for `sessions/{step-slug}/receipt.md` in the step's own commit: each check id, what was run, the literal
    result, who observed it. Your tracker entry then reads *against* it, the way you read every other row's
    tldr.
 
@@ -212,8 +230,8 @@ and a seat's close-out. Never reconstruct it at the close.
    `plan.md` + `tldr.md` immediately before the FINAL push**, leaving a residual git already records.
 
    **AND TRANSCRIBE THE SEAT'S RECEIPT SWEEP.** A seat's close-out reports which receipts its
-   change made false. It can correct `live-checks.md` itself; it may **not** write `project-status.md` or
-   `sessions/**`, so **those corrections arrive as a list in its FINAL TLDR and they are yours to apply.**
+   change made false. It may **not** write `project-status.md`, `sessions/**` or a row of `live-checks.md`
+   (the owner's), so **those corrections arrive as a list in its FINAL TLDR and they are yours to apply.**
    Do not hand a seat "just fix the false receipts" without checking who owns them — a coordinator that
    does finds the receipts are its own or immutable, and has handed the seat a dead end. Likewise
    **check off every BINDING instruction you gave**: if you said "report the count either way" and no
@@ -303,13 +321,15 @@ and a seat's close-out. Never reconstruct it at the close.
       nothing in that column is the pass's first finding. Then read your own session entries: **if any of
       them needs superseding, stop and record that as a finding** — it means the ledger was not kept, and
       the retro must say so rather than quietly correcting it.
-   2. **Aggregate the effort's `live-checks.md` — YOURSELF, with ordinary edits.** The effort home's
-      `.md` files (`live-checks.md`, the numbered specs, the umbrella) are inside your scoped write path —
-      same gate, same receipt as your ledger. **This also means a line you have PROVEN false in a spec or
-      a live-check row is yours to strike at the source.** Research stage only — after docs-process
-      files the folder, only the ledger remains writable.
-      Every session's TLDR section (e) row belongs there, plus any status only you observed. Unaggregated
-      rows are the most common thing to fall through, and the human's sitting is what they are for.
+   2. **Offer the owner a short, ordered quick pass — in the chat.** Live checks are the owner's, never
+      a seat's job and never a row you aggregate. From the seats' section (e) ("what the owner could try")
+      pick the few that matter most and write them as a numbered pass the owner can follow cold: what to
+      open, what to do, what passing looks like. A long list nobody can follow is the failure this
+      replaces. `live-checks.md` holds only the rows the owner dictates; write a row there only when the
+      owner dictates it. The effort home's `.md` files (`live-checks.md`, the numbered specs, the brief)
+      are inside your scoped write path — same gate, same receipt as your ledger — so **a line you have
+      PROVEN false in a spec, or a dictated row a seat reported false, is yours to strike at the source.**
+      Research stage only — after docs-process files the folder, only the ledger remains writable.
    3. **Run `spec-retro`.** It is written FROM the tracker, which is why step 1 comes first — a retro
       assembled from a stale ledger invents. It is a READ: findings become proposed fixits, and it fixes
       nothing. **If the effort had a review, your retro may cite `sessions/code-review.md` — and the two
@@ -320,9 +340,7 @@ and a seat's close-out. Never reconstruct it at the close.
       `docs/_meta/engineering-loop.md` § This repository's rails (repository-owned) says (when it names no
       route, ask the human once and suggest recording the answer there); if one is already open the push is
       enough. These are your own git — gated and receipted like any other publish. **The
-      push command must be the ENTIRE command** (a leading `cd` disqualifies it), and keep git-verb words
-      out of any echo label around it — the deny layer matches TEXT, not parsed verbs, and a decorative
-      `=== remote tip ===` header over a read-only block will park.
+      push command must be the ENTIRE command** (a leading `cd` disqualifies it).
    6. **Report the close:** commits, receipts, total cost with its uncosted-turn count, the findings ledger,
       and the explicit list of what the human still owns. **The merge is theirs, never yours.**
    7. **If the effort has a DOCS-PROCESS row, it runs last** — after the PR exists, as its own session,
@@ -331,7 +349,7 @@ and a seat's close-out. Never reconstruct it at the close.
 
       **P MOVES THE EFFORT HOME OUT OF YOUR REACH — the tracker pass in step 1 is your LAST chance at
       the specs and live-checks.** P `git mv`s `docs/research/{topic}/` to the archive home
-      `docs/_meta/docs-workflow.md` § The archive convention (repository-owned) names, or to the umbrella's
+      `docs/_meta/docs-workflow.md` § The archive convention (repository-owned) names, or to the brief's
       `Archive:` line when it carries one. The ledger survives the
       rename (its write predicate admits `docs/{research|archive}/*/project-status.md`; a home elsewhere
       is outside it, so there P's write to the tracker is the last one), but the effort-home lane
@@ -356,10 +374,10 @@ and a seat's close-out. Never reconstruct it at the close.
       while any seat is still live or when none shipped. Hand-cranked there is no `finish`; the human closes
       the effort.
 
-**The human hand-tests.** Live verification is the human's role, not a seat's claim — when a slice
-ships something clickable, tell the human concretely what to drive (the 2-3 highest-value clicks), and
-make sure user-run smokes accumulate in the effort's `live-checks.md` rather than piling up in chat —
-**written by you with ordinary edits, gated and receipted like your ledger.**
+**The human hand-tests.** Live verification is the owner's, not a seat's claim and not a seat's job —
+when a slice ships something clickable, tell the owner concretely what to drive (the 2-3 highest-value
+clicks), in the chat. A check becomes a row of `live-checks.md` only when the owner dictates it, and then
+you write it, with ordinary edits, gated and receipted like your ledger.
 
 ## What you will have to prove at close — make it runnable NOW
 
@@ -387,7 +405,7 @@ so read them as run-time obligations, not close-out ones:
 - **Verify a query FIRES on a known-positive before you trust a clean result.** A silently-empty result
   is usually a broken query, not an empty table — and a false all-clear on an audit query is worse than
   no query.
-- **Costs: uncosted turns count $0**, so any total is a FLOOR while the uncosted-turn count is above zero.
+- **Costs: an uncosted turn counts as nothing**, so any total is a FLOOR while the uncosted-turn count is above zero.
   Report it with the count. **Never sum across instruments** — session footers ride the seats' wakes and
   omit your own spend.
 
@@ -395,18 +413,34 @@ so read them as run-time obligations, not close-out ones:
 
 - Plan TLDR as **plain text BEFORE any plan-approval mode**; questions as **plain numbered text, then
   STOP** — never an interactive question tool (the human can't copy from it).
-- **No commit/push without your relayed call.** Explicit staging only — never `git add -A`.
+- **Approved work includes its commit, its push and the PR — you do not ask for them.** Hand-cranked, an
+  approved seat commits and pushes its branch itself (the relay, below); hosted, the commit call rides your
+  acceptance. The PR is yours at the close. The merge is the human's, always. Explicit staging only —
+  never `git add -A` — and never a push to the base branch.
+- **Pipelines never intertwine.** A brief's GATE checks only that its predecessor merged; never gate a run
+  on another pipeline's seats, and never make a seat wait on one. Independent pipelines may run at the same
+  time, each on its own branch; never two over the same files or on one branch. When the base branch moves
+  under your run, take it in between seats, by a merge, never under a live seat and never as a rebase.
+- **Never advise or run a runner restart while a seat is live.** A restart ends every live session on that
+  runner, and the plane may not notice. "Restarting it is fine" said to the human in that state is how a
+  run loses every seat at once; say instead which seats are live and that the restart waits.
+- **When your plane calls fail, stop — never sleep-poll.** Journal the failure, report it, and end your
+  turn. A timer that wakes you to retry a plane that is not answering spends a whole context on every wake
+  and produces nothing; the human resumes you when the plane is back.
+- **An escalation is an act, never chat text alone.** Write it where it is read — the seat's board under a
+  coordinator-voice heading, and the tracker — and carry it with a verb the owner's queue shows. Text in
+  your own terminal reaches the owner only if they happen to read that terminal.
 - **This repository's rails add to these rules.** `docs/_meta/engineering-loop.md` § This repository's rails
   (repository-owned) names the policy, the gates a commit passes, the suite before a PR, the PR route and
   any stricter staging — bake every rail in beside these, and never let one subtract from them.
 - **The unattended git form, and it binds YOU as much as the seats: one git command per call, no shell
   metacharacters.** The FORM check reads the whole command string, so chaining, redirects or substitution
   disqualify it — `git add … && git commit … && git push …` parks, while the same three sent separately
-  flow. Pushes always name the refspec; a push without one parks by design. Keep git-verb words out of
-  echo text and section labels — **including `branch`**, which parks a read-only branch LISTING on the
-  branch-deletion backstop. The fence fires on the commands a careful seat runs to PROVE its work.
-- Seats never edit `project-status.md` or memory files; never run `docs-write` unprompted; respect the
-  umbrella's out-of-scope list; codegen only through the command `patterns/codegen.md` § Running codegen
+  flow. Pushes always name the refspec; a push without one parks by design. The gate reads the command
+  the shell would run, not its words: an echo label or a quoted search naming a git verb is data, unless
+  a shell or an interpreter is on the same line.
+- Seats never edit `project-status.md`, `live-checks.md` or memory files; never run `docs-write` unprompted;
+  respect the brief's § What this effort does NOT do; codegen only through the command `patterns/codegen.md` § Running codegen
   names (when the repo has one); component files laid out as `patterns/frontend-patterns.md` § Component files states. Run the
   suite lanes SERIALLY.
 - Cross-slice changes (touching a shipped spec's files) need your explicit approval and get recorded as
@@ -414,9 +448,11 @@ so read them as run-time obligations, not close-out ones:
 - **Cite symbols, not bare `file:line`.** In a seed, a ruling, or the tracker, name the symbol and use the
   line as a hint — a line number is a comment, not an address, and the seat documenting why a line matters
   is what moves it.
-- Model policy: seats run **the effort's declared default model** (allowlist-exact, set at creation);
-  investigation-heavy sessions may warrant a reasoning-heavier one. Parallel sessions only when
-  the specs share no files — and sequence the *commits* regardless.
+- Model policy: seats run **the effort's declared default model and effort** — the pair the brief's
+  `## Birth` names (allowlist-exact, set at creation); investigation-heavy sessions may warrant a
+  reasoning-heavier one. **A seat's BELIEFS line states the pair it started on, and one the brief does not
+  name is settled before you rule its plan:** re-open the seat on the named pair, or rule the difference in
+  by name. Parallel sessions only when the specs share no files — and sequence the *commits* regardless.
 - **The gate is inverted (means are free, protocol is law):** benign tools/methods flow with audit rows;
   only the ceremony's boundaries park — in EVERY tier, recon included. Reads, execs, suites, pipes,
   redirects and in-worktree writes all flow pre-accept. **Do not seed tool-avoidance rules the platform
@@ -434,6 +470,12 @@ so read them as run-time obligations, not close-out ones:
   catch. Cite, and your beliefs become checkable too.
 - **No message of yours carries a build order except the plan ruling itself.** Answers, callouts, and
   status requests are steering or information; the go IS the `accept`/`accept-with-riders` verdict.
+- **A ruling that binds a running seat goes onto that seat's board in the same act as your tracker entry.**
+  Recorded is not delivered: a ruling that lives only in your tracker never reaches the seat it binds.
+  Hosted, write it into the seat's file and call the verb (a `callout` when no verdict carries it).
+- **A ruling counts only when its act lands.** Write it into the file, call the verb, and say "landed" only
+  from the verb's reply. A ruling written ahead of its act — a claim about a build that has not finished, a
+  verdict the verb then refuses — is a board ahead of the ledger, and the seat may act on the board.
 - **If the next action is yours and nothing gates it, TAKE it — do not describe it.** Any turn of
   yours that ends with a plan instead of an act is a defect, and not a close-out quirk: a coordinator
   that rules a fixit IN, writes the brief, and ends the turn sits idle with nothing gating it. The human
@@ -474,10 +516,14 @@ The ceremony rides the **`spec-build` skill** — the prompt is an IGNITER, not
 ```
 You are a BUILD SEAT in a coordinator-run effort: invoke the spec-build skill with
 role={backend | frontend | mixed} before anything else, and ALWAYS after `spec-seat`: the seat header
-names `spec-seat` first, the job skill second.
+names `spec-seat` first, the job skill second.        <- hand-cranked only; hosted, start at the spec
 
 Your spec: {absolute path to the spec}
-Pipeline context: {umbrella path} (settled decisions — don't relitigate) + {project-status.md path}
+{only when the seat's row names a further repository, one line each; hand-cranked only — hosted, the
+ seed says where:}
+You also write: {repository} — your tree of it is {absolute path}, on branch {branch}. Never its owner's checkout.
+Pipeline context: {brief path} — the charter: its sections down to § Platform state bind you, and the owner's
+rulings in it are settled (don't relitigate) + {project-status.md path}
 (READ-ONLY, coordinator-owned — prior rows, deferred findings, and process incidents are your contract).
 
 EXTRA DOCS for this task (beyond your role's floor — read them):
@@ -493,11 +539,15 @@ MY BELIEFS, WITH PROVENANCE (a mismatch is worth more than a build hour — repo
 
 STANDING RECON QUESTION (answer in your PLAN TLDR): {if any}
 Known coordinator-owned dirty files (never stage): {list}
-Baselines: {per lane, as patterns/testing.md names them: N (+known pre-existing reds)}
+Baselines (cite, don't re-measure): {per lane, from the brief's § Baselines: N (+known pre-existing reds)}
 
 THE TASK: {compressed spec restatement with the load-bearing specifics inline.}
 ```
 
+**A seat that also writes a further repository is told WHERE, and nothing else about it:** what it does
+there is `spec-seat` § Git shapes, and a prompt that restates it is a second copy of the contract. A seat
+whose row names none gets no such line, and a prompt exactly as it would have been.
+
 For investigation-first work, add **STEP 0 — INVESTIGATE, REPORT, STOP** before the task, or use
 `role={...} fixit` for no-spec defect sessions (the skill carries the fix-it ceremony). Fallback: if the
 seat can't invoke skills, paste the ceremony from the `spec-build` skill inline.
@@ -515,7 +565,12 @@ second** — this is the whole point of the row.
 ```
 REVIEW row (R):
   You are the REVIEW SEAT: invoke the spec-review skill before anything else.
-  Topic: {topic} · branch: {branch} · diff range: {base}...{branch}
+  Topic: {topic} · branch: {branch} · diff range: origin/{base}...{branch}
+  {when the run wrote a further repository, one more line each:}
+  Also: {repository}, at {its path} · diff range: origin/{its base}...{its branch}, or by its release
+    tags ({the release before}...{this run's release}) when the run released it mid-run
+  The brief, down to § Platform state and never past it (read as claims, not facts):
+    docs/research/{topic}/00-ignition-brief.md
   Specs (read as claims, not facts): {every numbered spec path}
   Session artifacts: docs/research/{topic}/sessions/  (each seat's plan.md + tldr.md)
   Working docs for THIS effort: {explicit list of docs/working/*.md}
@@ -526,7 +581,8 @@ REVIEW row (R):
 DOCS-PROCESS row (P):
   You are the DOCS-PROCESS seat: invoke the docs-process skill before anything else.
   Effort: {topic} · archive target: {per docs/_meta/docs-workflow.md § The archive convention
-    (repository-owned), or the umbrella's Archive: line when it carries one} · shape: {as that section says}
+    (repository-owned), or the brief's Archive: line when it carries one} · shape: {as that section says}
+  Your board: docs/research/{topic}/sessions/docs-process/  (plan.md + tldr.md; never a gitignored folder)
   Working docs for THIS effort, and ONLY these: {explicit list — docs/working/ is a shared
     queue and may hold other efforts' docs; do not infer membership from the folder}
   Research/spec docs to archive: docs/research/{topic}/
@@ -552,7 +608,7 @@ Answers:
    mandatory: seats generalize from the WHY to the next hundred micro-decisions.}
 2. ...
 {Optional call-outs that don't block.}
-Go build. Ending ceremony as before; no commit without the relayed call.
+{Hand-cranked: the run-to-done order (the relay, below). Hosted: Go build; the ending ceremony as before.}
 ```
 
 Rules: one numbered ruling per question, decision-first then rationale, never leave a question
@@ -566,9 +622,10 @@ still open, however good the prose; the seat is still holding and the re-raise i
 **The blackboard append.** Hand-cranked, the seat's `plan.md` and `tldr.md` are live FILES at
 `docs/research/{topic}/sessions/{spec-slug}/` — read the TLDR there with normal file tools instead of
 asking for a paste (`read-full-plan` = read `plan.md`, a pull, never force-fed). Deliver every ruling by
-**APPENDING it verbatim to the seat's `tldr.md`**, right under the questions it answers. Hosted, the same
-append, then the verb: the control plane mirrors the file before your act and points the seat at the
-section (§ Your hands, the coordinator's append).
+**APPENDING it verbatim at the END of the seat's `tldr.md`** — never between its sections, not even under
+the question it answers: the file is the conversation read top to bottom, in message order, and an insert
+above a later post rewrites that order. Hosted, the same append, then the verb: the control plane mirrors
+the file before your act and points the seat at the section (§ Your hands, the coordinator's append).
 
 **Anchor grammar (canonical — the witness greps these):** rulings land under
 `## COORDINATOR RULING (plan — {verdict})` hand-cranked, `## COORDINATOR RULING (plan rev N — {verdict})`
@@ -587,21 +644,31 @@ re-pasting a multi-KB block into a composer.
 before cutting each next prompt, sweep `sessions/*/tldr.md` mtimes for appends you were never nudged
 about. A missed nudge must cost one `ls`, not a wedged run.
 
-**Human relay mechanic:** when pasting a ruling into the seat's session, the human prepends *"Here
-is the response from the coordinator, take account for the notes and pop up the plan i will approve it."*
-— so the seat applies the rulings, then presents its plan for the human's explicit approve. This
-plan-approval click is the human's counterpart of the product's accept-gate — keep it.
+**The hand-cranked relay.** A seat posts its PLAN TLDR and numbered questions **in the chat**, before any
+plan-approval presentation. The human relays them, and you answer in **ONE message of notes**: the
+verdict, the answers, the riders, and the standing run-to-done order. The seat folds them in and the human
+approves its plan — that approval is the human's counterpart of the product's accept-gate. The seat then
+writes `plan.md` and `tldr.md`, your notes transcribed verbatim under `## COORDINATOR RULING (plan —
+{verdict})`, and **runs to done without a stop**: build, suites, `docs-write`, commits with
+`verify-staged`, its branch pushes (never the base branch), and its FINAL TLDR in the chat. Its only stops
+are a destructive act outside the effort's branches, a credential exposure, a host restart and a
+`verify-staged` failure; a red it cannot fix takes its escape hatch, and it still closes out. A mid-build
+question gets your ruling appended to its `tldr.md`. After its last push you review the FINAL against the
+tree and write `## COORDINATOR ACCEPT (final — {slice})` into its `tldr.md` yourself. The hosted ceremony —
+the acceptance that carries the commit call, the receipted push bar — is unchanged.
 
 ## Docs-write + commit call template
 
+The hosted close-out call. Hand-cranked, the relay's run-to-done order carries the same content and the
+seat closes out without waiting for it.
+
 ```
 COORDINATOR RESPONSE — FINAL TLDR ACCEPTED {(+ what I verified myself)}.
 1. Run docs-write. Carry: {departures, honest gaps, deferred findings verbatim, gotchas}.
-2. COMMIT CALL — approved. Stage explicitly (never git add -A): YOUR diff + working doc,
-   PLUS docs/research/{topic}/project-status.md — my ledger rides your commit,
-   which is its only route to durability. You stage it; you never edit it. Other research
-   notes stay untouched. Re-copy plan.md + tldr.md into sessions/{slug}/ ONCE, immediately
-   before the final push.
+2. COMMIT CALL — approved. Stage explicitly (never git add -A): YOUR diff + working doc +
+   sessions/{slug}/. Never stage docs/research/{topic}/project-status.md — I commit my ledger
+   myself. Other research notes stay untouched. Re-copy plan.md + tldr.md into sessions/{slug}/
+   ONCE, immediately before the final push.
    VERIFY before committing: verify-staged {same list} — commit only on exit 0. Non-zero means
    git add silently dropped files (usually a .gitignore rule); STOP, report the output verbatim,
    and wait — do not force-add, do not widen .gitignore.
@@ -642,7 +709,9 @@ post-merge.
 - **The tracker is the seat — ONE ledger, and you write it live.** `project-status.md` is your journal: you
   own it, you advance it at every boundary, and the human never edits it. That file, not the chat, is the
   product of this skill. **The mechanism is ordinary file tools** — edit it exactly as a seat edits
-  `tldr.md`/`plan.md`; the gate permits the path. Git commits are the receipt: timestamped, attributed,
+  `tldr.md`/`plan.md`; the gate permits the path. **Never a shell heredoc or an interpreter one-liner,
+  for the tracker or for a seat's board:** one collapses backslashes in what it writes, and one whose
+  text quotes a publish is held as if it ran it. Git commits are the receipt: timestamped, attributed,
   carrying the diff.
 - **The session entry is a JOURNAL entry, not a status cell.** The ruling *and its reasoning*, recon
   corrections, what you verified yourself, mid-build directives, and anything you don't want to forget —

package/skills/spec-ignite/SKILL.md

@@ -30,9 +30,10 @@ the named-finding discipline are UNCHANGED either way — **only the mouse hand
 1. Confirm the specs are **committed to the base branch** — seats read specs from their checkouts, so
    uncommitted specs reach no worktree. If they are not committed, that commit is the coordinator's call
    first.
-2. Enumerate the **ignition gates** explicitly and check each: dependency efforts landed AND merged (name
-   the PRs); known-blocker fixits landed (name them); the control plane up and a runner connected; the
-   human's words per stage. Report any gate not yet green — you WAIT, never work around.
+2. Enumerate the **ignition gates** explicitly and check each: the predecessor merged (name the PR) — one
+   pipeline runs at a time, so that is the only gate on another pipeline, never one of its seats; known-blocker
+   fixits landed (name them); the control plane up and a runner connected; the human's words per stage.
+   Report any gate not yet green — you WAIT, never work around.
 3. **VERIFY the ignition brief — you do not author it.** `spec-pipeline` wrote `00-ignition-brief.md`
    complete, from the hot session that placed the specs. **You may be a cold session, and that is fine,
    because your job is the check:** re-run the **Baselines** and confirm the quoted numbers; re-verify each
@@ -53,32 +54,33 @@ the named-finding discipline are UNCHANGED either way — **only the mouse hand
    | Payload field | Derived from | Note |
    |---|---|---|
    | `topic` | the folder name (`docs/research/{topic}/`) | kebab-case, as authored |
-   | `title` | the umbrella `01-*.md` H1 | |
+   | `title` | the brief's H1 (the pipeline's title) | |
    | `specPath` | `docs/research/{topic}/` | **the folder, trailing slash** — a seat's own spec is a different field |
    | `shape` | the brief's `## Birth` | closed set; the create door refuses an unknown by name |
    | `defaultModel` | the brief's `## Birth` | **allowlist-exact** — a near-miss is refused, not coerced |
    | `defaultEffort` | the brief's `## Birth` | |
    | `seats[0]` | **THE COORDINATOR — it is a SEAT, and it is not one of the numbered specs** | omit it and the start door answers `pipeline-has-no-coordinator`; two answer `pipeline-has-many-coordinators` |
-   | `seats[1..]` | the brief's `## The sequence`, in order | one row per numbered spec, plus the review / docs-process rows if the pipeline has them |
+   | `seats[1..]` | the brief's `## The sequence`, in order | one row per numbered spec, plus the review / docs-process rows if the pipeline has them. **A `step` row is shown on the card and never staged** — it is a human act, not a seat |
    | `seats[].kind` | the sequence row's kind, **verbatim from the closed vocabulary** | `build · fixit · review · docs-process · coordinator · retro · witness`. A kind nobody has heard of composes NOTHING; `unknown-seat-kind` names it |
+   | `seats[].role` | the row's `Role` cell, when the sequence has the column | `backend · frontend · mixed`; omitted when absent, and the seat's default applies |
    | `seats[].title` | the spec's H1, or the sequence row's label | |
    | `seats[].specPath` | `docs/research/{topic}/NN-{slug}.md` | **the FILE.** Confirm each exists — a spec named in the sequence and missing from disk reaches no worktree |
    | `seats[].stageOrdinal` / `ordinal` | position in the sequence | sequential unless the brief declares stages |
    | `edges[]` | the shape + the sequence | `fromSeatIndex`/`toSeatIndex` are **indices into your own `seats` array**, not seat ids — the ids do not exist until the create answers. `unknown-seat-relation` names a bad relation |
 
-   **A FIXIT ROW IS NEVER IN THE CREATE PAYLOAD.** `spec-pipeline` authors at most one and only as a
-   possibility — *"MAY materialise… not authored up front; the coordinator charters it from the review's
-   named list."* Staging a seat for it invents a seat the run may never want, and the coordinator cannot
-   un-charter it.
+   **A CONDITIONAL FIXIT IS A PLANNED SEAT, NEVER A SPEC.** `spec-pipeline` authors at most one and only
+   as a possibility — *"MAY materialise… not authored up front; the coordinator charters it from the
+   review's named list."* When the card carries it, the control plane creates it as a planned seat the
+   coordinator supervises, shown as "if needed": it opens only when the coordinator charters it, and
+   `finish` closes it as not chartered when it never opened. Never give it a spec file, and never stage a
+   second one.
 
-   **DERIVING THE CARD *IS* THE THREE-DOCUMENT CHECK, AND THAT IS WHY THIS SEAT DERIVES IT.**
-   `spec-pipeline` requires the sequence to appear in THREE places and agree: the brief's
-   `## The sequence`, the umbrella's row table, and the tracker's `## Session status`. Build the seat
-   list from the brief, then read the other two and confirm they list the same rows in the same order.
-   **A disagreement is a finding, reported to the authoring seat — never something you reconcile
-   silently by picking one.** An effort whose three documents disagree has a seat acting on a shape the
-   others have stopped describing, and the create you are about to stage would make one of them true by
-   force.
+   **DERIVING THE CARD *IS* THE SHAPE CHECK, AND THAT IS WHY THIS SEAT DERIVES IT.** The sequence is
+   written once, in the brief's `## The sequence`; the tracker's `## Session status` carries one status
+   line per row by the brief's ids. Build the seat list from the brief, then confirm every row has its
+   status line and every status line its row. **A disagreement is a finding, reported to the authoring
+   seat — never something you reconcile silently by picking one** — the create you are about to stage
+   would make one of them true by force.
 
    **The card names only controls that exist.** A card that promises a budget cap or an artifact prefix
    the launcher cannot take hands over values the form refuses and omits the ones it needs. **If you want
@@ -105,7 +107,8 @@ the named-finding discipline are UNCHANGED either way — **only the mouse hand
    if a retry is needed, re-announce and say the failed attempts had zero side effects.
 9. Verify ignition receipts — the coordinator's opening ledger write, its first `seat_spawn`, any scripted
    probe's refusal — and **narrate each beat as it lands**, plain language. A loud row at ignite is
-   information, not a failure.
+   information, not a failure. **When a witness is on duty, hand it the packet** (`spec-witness` § The
+   packet) before you go hands-off: it watches from outside the plane and cannot read the kick for itself.
 10. **HANDS OFF.** Heartbeats only (one line per phase change; long output to files, never into context).
     The human owns the parks, the reaps, and the kill-switch from the first second. If the run wedges:
     report state + STOP — the kill-switch is theirs.
@@ -130,9 +133,10 @@ reviewed the way a committed file can, so anything longer than a pointer is law
 place — and accumulated prompt-law breaks the coordinator it was meant to steer.
 
 **Your job is to READ it and confirm the brief behind it holds up** — the coordinator reviews the text
-before kick. Before you hand it over, check the brief actually covers: the sequence and roles · the
-coordinator's beliefs with provenance · effort-specific law and per-spec riders · verified baselines ·
-platform state · close-out (artifact filing, live-checks aggregation, what the PR must say). **A gap you
+before kick. Before you hand it over, check the brief actually covers: why the effort exists · the
+sequence and roles · the owner's rulings · the law and per-spec riders · the reference facts · what the
+effort does not do · verified baselines · platform state · the coordinator's beliefs with provenance ·
+close-out (artifact filing, what the PR must say, the owner's quick pass). **A gap you
 find is a finding to report, not a section for you to write** — send it back to the authoring seat.
 
 <!-- control-plane-specific -->