@naswerks/engineering-loop 0.7.0 → 0.8.0

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
@@ -46,22 +47,24 @@ cannot spot a hand-written generated file.
 **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
@@ -84,15 +87,16 @@ 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` |
-| `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 |
-| `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 |
+| `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` | 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 |
 
-**A QUESTION IS CLOSED BY AN ACT, NOT BY A FILE.** Answer a charge's question with a `callout` carrying
-that post's act id as `answeringActId` — **that act IS the answer**, and it is the only thing that stops
-the re-raise. A `callout` without one steers and closes nothing, and **nothing you write into a file
+**A QUESTION IS CLOSED BY AN ACT, NOT BY A FILE.** Answer a charge's question with a `callout` — or an
+`accept_plan` / `accept` that rules at the same time — carrying that post's act id as `answeringActId`:
+**that act IS the answer**, and it is the only thing that stops the re-raise. An act without one steers or
+rules and closes nothing — a forgotten id costs one re-raise — and **nothing you write into a file
 closes anything**: the latch reads the ledger, so a ruling you never sent is a question still open no
 matter what any blackboard says.
 
@@ -105,6 +109,11 @@ the verb carries your words. **The act still decides** — a section closes noth
 
 **`seat_acts` IS YOUR CENSUS.** Your mint carries `acts:read`: take counts, human touches and receipts from
 the ledger, never from a seat's report about itself, and name the lane any count you publish came from.
+Beside it, read for yourself what the owner used to check for you: `seat_timeline` (a seat's two lanes —
+*the reap ended the process* is the runner's `ended` row, cause `stop_requested`, after your reap act),
+`needs_you` (the owner's Needs-you tab, Active and History), argless `seat_usage` (every seat's spend and
+the pipeline's total), `seat_parks` with a charge's `seatId` or `all: true` (its parks, and the rows that
+ADMITTED a push), and the argless roster's host and `re-raises` per seat.
 
 **WAKES:** you are woken when a charge posts its plan or its tldr, and a one-line pointer rides the wake —
 the revision and the sections it added. Read what is new (`read_blackboard` with `sinceRev`, or the file) and
@@ -114,7 +123,9 @@ answer on first receipt rather than spending a round-trip.
 not a refusal: call it once more, and journal it if it fails again. A refusal has a name; a dropped
 connection does not.
 
-**THE TRACKER IS YOURS ALONE.** Advance it at every seat boundary; never reconstruct it at the close.
+**THE TRACKER IS YOURS ALONE.** Advance it at every seat boundary and **commit it yourself — after each
+reap, before the next spawn — never in a seat's commit call**, so it is never frozen between an acceptance
+and a seat's close-out. Never reconstruct it at the close.
 
 ## The loop (per seat)
 
@@ -126,7 +137,12 @@ connection does not.
    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
@@ -136,7 +152,7 @@ connection does not.
    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.
 
@@ -186,10 +202,10 @@ connection does not.
    **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
+   **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.
 
@@ -204,8 +220,8 @@ connection does not.
    `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
@@ -295,13 +311,15 @@ connection does not.
       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
@@ -323,7 +341,7 @@ connection does not.
 
       **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
@@ -341,11 +359,17 @@ connection does not.
       is not reversible by the seat that does it, and a check the human runs afterwards confirms the damage
       instead of preventing it. **A live-check row is confirmation; this is prevention.** Never hold the
       run waiting for a human to verify this first — you have the list, so you are the gate.
-
-**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.**
+   8. **Hosted, `finish` is your last call** — once every other seat, P included, is reaped. Pass the PR's
+      URL: it records the pipeline done with evidence it reads from the ledger, moves it to `reviewing`,
+      closes your own session and ends your process, and the PR's merge closes the pipeline. **Nothing you
+      send after it is admitted** — commit your tracker and report first. It refuses, recording nothing,
+      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 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
 
@@ -381,7 +405,21 @@ 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.
+- **One pipeline at a time.** A brief's GATE checks only that its predecessor merged; never gate a run on
+  another pipeline's seats, and never run two pipelines over one another.
+- **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.
@@ -391,8 +429,8 @@ so read them as run-time obligations, not close-out ones:
   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
+- 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
@@ -420,6 +458,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
@@ -460,10 +504,11 @@ 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}
+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):
@@ -479,7 +524,7 @@ 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.}
 ```
@@ -502,6 +547,8 @@ 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}
+  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}
@@ -512,7 +559,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}/
@@ -538,7 +586,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
@@ -552,9 +600,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})`
@@ -573,21 +622,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.

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 -->