@naswerks/engineering-loop 0.7.1 → 0.9.0

package/skills/spec-pipeline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-pipeline
-description: Graduate a plan into a numbered spec pipeline in docs/research/{topic}/ — an umbrella plus one self-contained spec per planned seat. Use when a research idea is "really getting into it" and a plan has come through (a plan-approval mode, if your harness has one) and you want to commit it as specs instead of executing it directly, or run spec-pipeline.
+description: Graduate a plan into a numbered spec pipeline in docs/research/{topic}/ — one ignition brief (the coordinator's spec and the charter every seat reads) plus one self-contained spec per build seat. Use when a research idea is "really getting into it" and a plan has come through (a plan-approval mode, if your harness has one) and you want to commit it as specs instead of executing it directly, or run spec-pipeline.
 ---
 
 # spec-pipeline
@@ -8,7 +8,7 @@ description: Graduate a plan into a numbered spec pipeline in docs/research/{top
 Turn a *plan* into a durable, numbered **spec pipeline** in `docs/research/{topic}/`. This is phase 2 of
 the two-phase backlog model: `docs-backlog` parks an idea; `spec-pipeline` graduates the plan behind it
 into specs. **The plan is throwaway — the specs carry every crumb.** A future session reads ONE spec + the
-umbrella and can build without the plan or the original conversation.
+brief and can build without the plan or the original conversation.
 
 **Find the format first.** This repository writes its formats (the doc header and status words, where an effort is filed, its rails) in the sections `rg -n '^#+ .*\(repository-owned\)' docs/_meta/` lists; read the one a step names before that step writes. This skill names the section, never the format.
 
@@ -24,23 +24,29 @@ umbrella and can build without the plan or the original conversation.
 ## What a pipeline folder contains
 
 > **THIS FOLDER IS THE CREATE PAYLOAD.** Ignition does not compose a pipeline from memory or from a
-> conversation — it DERIVES one from these files: the folder name is the topic, the umbrella's H1 is the
-> title, `## The sequence` is the seat list, and the numbered specs are the seats. Author them knowing
-> they will be read mechanically, and the ignition step becomes a verification rather than a
-> transcription. The mapping is the table in `spec-ignite` § *the stage card is derived*; keep the two
-> in step if either moves.
+> conversation — it DERIVES one from these files: the folder name is the topic, the brief's H1 is the
+> title, its `## The sequence` is the seat list (a `step` row is shown, never a seat), and the numbered
+> specs are the build seats. Author them knowing they will be read mechanically, and the ignition step
+> becomes a verification rather than a transcription. The mapping is the table in `spec-ignite` § *the
+> stage card is derived*; keep the two in step if either moves.
 
 ```
 docs/research/{topic}/
-  00-ignition-brief.md   the coordinator's standing orders for THIS run (template below)
-  01-{topic}.md          the umbrella: vision, the row table, settled decisions, hard constraints
-  02..NN-{slice}.md      one self-contained spec per planned seat, in build order
+  00-ignition-brief.md   the coordinator's spec AND the charter every seat reads (template below);
+                         never a session
+  01..NN-{slice}.md      one self-contained spec per build seat, in build order: every numbered
+                         file is one seat's spec
   project-status.md      the living tracker — the coordinator's journal (template below)
-  live-checks.md         the human's verification rows, accumulated as the run proceeds
+  live-checks.md         created with NO rows: it holds only the rows the owner dictates
   sessions/              the CONVERSATION — see below. NOT authored here: the FIRST seat
                          brings it into existence when it files, so a fresh folder has none
 ```
 
+**Every numbered file is one seat's spec, and the brief is the coordinator's.** The brief carries what
+binds the whole run — why it exists, the sequence, the owner's rulings, the law, the reference facts, what
+it does not do, the baselines, the platform state — so a seat reads its own spec and the brief, and nothing
+else is a charter. The sequence is written once, in the brief.
+
 ### `sessions/` — the conversation, and its durable record
 
 **Nobody creates this folder as an act.** The FIRST seat brings it into existence by committing its two
@@ -58,11 +64,13 @@ sessions/                        WHO PUTS IT THERE
   {spec-slug}/tldr.md            each build seat, same commit — the two-voice CHAT: its TLDRs and
                                  questions with the coordinator's rulings appended beneath them. Read
                                  top-to-bottom it IS the session's whole conversation, in message order
+  docs-process/plan.md + tldr.md the docs-process row's board, same shape; it lives here from the start,
+                                 never in a gitignored folder, so it moves with the effort when P files it
+  {step-slug}/receipt.md         a human `step` row, in its own commit — see "A HUMAN STEP OWES A RECEIPT"
   code-review.md                 the review seat, in its own commit, if the run has a review row
   coordinator-retrospective.md   the coordinator, at the close
-  witness-ledger-*.md            a human commit — the witness is zero-writes by contract (its ticket
-                                 cannot even carry the write scope), so its testimony reaches the repo
-                                 by someone else's hand
+  witness-ledger-*.md            a human commit — the witness writes nothing into the run, so its
+                                 testimony reaches the repo by someone else's hand, on the human's word
 ```
 
 - **Per-seat artifacts go in a `{spec-slug}/` subfolder; effort-wide artifacts sit at the `sessions/`
@@ -102,7 +110,7 @@ sessions/                        WHO PUTS IT THERE
    slice: recon + plan + build + suite + FINAL TLDR fits in one session with room for two rulings.
 
 2b. **Decide the pipeline's SHAPE — ask the human both questions, with your recommendation.** The bookends
-   are rows in the row table like any other seat, which is why the decision belongs here: nothing
+   are rows in the brief's sequence like any other seat, which is why the decision belongs here: nothing
    downstream needs a flag, and the coordinator learns the shape by reading its own sequence.
 
    **"Do you want a REVIEW row?"** Recommend YES when the run ships a lot of code, touches security or
@@ -123,31 +131,55 @@ sessions/                        WHO PUTS IT THERE
    verbs its credential admits, and a kind nobody has heard of composes NOTHING rather than something
    plausible. Name rows in those words.
 
-   Then write the rows into the row table and the brief's sequence, in this order:
+   **What is not a seat is a `step` row** — a human act in its place in the order (a publish, a merge, a
+   sitting). Its `Kind` cell says `step`, and nothing is staged or seeded for it. `step` is the one
+   non-seat word on purpose: no misspelled seat kind can equal it, so a row whose kind is misspelled is
+   still refused by name rather than read as a step. A PR the coordinator opens at its close is its own
+   close-out, not a row.
+
+   **A seat row may carry a role** — `backend` · `frontend` · `mixed` — in a `Role` column, when the
+   reading list of a build seat should not be left to the default. Leave the column out when no row needs
+   it.
+
+   **A seat row may name the repositories it ALSO writes in** — in a `Repository` column, when the seat
+   builds something that lives in another repository: a package this repository consumes, say. The cell
+   holds one or more names, as the runner that carries the seat serves them, separated by ` · ` or `,`;
+   an empty cell, `-` or `—` means none. **The column never moves a seat:** its home is always the
+   pipeline's own repository, where the specs, the boards and the tracker are. The pipeline still closes
+   on ONE pull request, its own repository's; a release of the other repository is a `step` row. Leave
+   the column out when no row needs it — most pipelines write one repository, and nothing about them
+   changes.
+
+   Then write the rows into the brief's sequence, in this order:
 
    ```
-   02..NN   the build seats
-   {R}      REVIEW      — spec-review, if chosen. Runs on `git diff {base}...<branch>` (the rails' base branch); no PR yet
+   0        the coordinator, with the brief as its spec
+   01..NN   the build seats, with any `step` rows in their places
+   {R}      REVIEW      — spec-review, if chosen. Runs on `git diff origin/{base}...<branch>` (the rails' base branch); no PR yet
    {F}      FIXIT       — MAY materialise, one maximum, only if the review classifies an (a)+(b)
                           finding AND the coordinator rules it in. Not authored up front; the
-                          coordinator charters it from the review's named list
+                          coordinator charters it from the review's named list. Listed as a row
+                          only when it must write a further repository: then directly after the
+                          review row, with its `Repository` cell — anywhere else a launcher reads
+                          a second fixit beside the one the review implies
    —        the coordinator's retro + PR (its own close-out, not a row)
    {P}      DOCS-PROCESS — if chosen
    ```
 
    **The REVIEW row's seed carries NO coordinator beliefs** — no provenance list, no prior-shapes
    bullets, no framing about what is already settled. Every other seat's prompt deliberately carries those;
-   this one must not, because the seat's whole value is the absence of the run's context. **Write that
-   instruction into the brief**, or it will be seeded helpfully and destroy what it is buying.
+   this one must not, because the seat's whole value is the absence of the run's context. It reads the
+   brief's sections down to § Platform state and every numbered spec **as claims**, and never the
+   coordinator's sections after it. **Write that instruction into the brief**, or it will be seeded
+   helpfully and destroy what it is buying.
 
-   **The sequence you just decided lands in THREE documents, and they must agree**: the brief's
-   `## The sequence`, the umbrella's row table, and the tracker's `## Session status`. Write all three
-   in one pass, listing the same rows in the same order. **The coordinator re-checks this at ignition** —
-   an effort whose three documents disagree has one seat acting on a shape the others have stopped
-   describing.
+   **The sequence is written ONCE, in the brief.** The tracker's `## Session status` carries one status
+   line per row, by the brief's ids, and copies nothing else: no second table, no settled-decisions list.
+   **The coordinator compares the two at ignition and before its retro** — a status line with no row, or a
+   row with no status line, is a finding.
 
 3. **Write the specs**, using the spec-doc template in `docs/_meta/docs-workflow.md`. Each per-seat
-   spec opens with the spec-doc blockquote (`Builds on [prior]` + `Source: [umbrella / research]`) and the
+   spec opens with the spec-doc blockquote (`Builds on [prior]` + `Source: [brief / research]`) and the
    machine header `docs/_meta/docs-workflow.md` § Doc metadata (repository-owned) prescribes, at the word for
    `draft`, so the set stays navigable.
 
@@ -201,20 +233,20 @@ sessions/                        WHO PUTS IT THERE
    exists has a blind spot. **A count pinned in a doc needs a named owning session**, or it rots: say
    which spec moves it, and have the others leave it alone.
 
-4. **Name the RESEARCH the effort came from, in the umbrella, by path.** The idea that fed this work
-   archives *with* it — that is how its archive home ends up holding the whole arc from "thing we'd like to
-   do" to "done." When the research doc already lives at `research/{topic}/`, it travels for free. **When
-   it does not** — a standalone `research/{something}.md`, or several — the umbrella's `Source:` / Lineage
-   is the only record that it belongs to this effort.
+4. **Name the RESEARCH the effort came from, in the brief, by path** — its `## Where it came from`. The
+   idea that fed this work archives *with* it — that is how its archive home ends up holding the whole arc
+   from "thing we'd like to do" to "done." When the research doc already lives at `research/{topic}/`, it
+   travels for free. **When it does not** — a standalone `research/{something}.md`, or several — the
+   brief's `## Where it came from` and its Lineage are the only record that it belongs to this effort.
 
    **Say it plainly, because a later seat has to act on it:** whoever archives this gets handed that
    list, and a research doc nobody named is one that stays behind in the running tab after its effort has
-   shipped. Two lines in the umbrella now saves a hunt through a shared folder later.
+   shipped. Two lines in the brief now saves a hunt through a shared folder later.
 
 5. **Name the archive destination when only you can.** Read `docs/_meta/docs-workflow.md` § The archive
    convention (repository-owned). If where a pipeline files depends on something only this session knows
-   (which living feature the effort belongs to, say), resolve it now and write the path into the
-   umbrella's blockquote as an `Archive:` line; `spec-coordinator` hands it to the docs-process row and
+   (which living feature the effort belongs to, say), resolve it now and write the path into the brief's
+   `## Where it came from` as an `Archive:` line; `spec-coordinator` hands it to the docs-process row and
    `docs-process` files there. A convention that needs nothing from you needs no line.
 
 6. **Stop.** The specs stay in `research/{topic}/`. Do NOT implement, do NOT touch living docs, do NOT
@@ -222,8 +254,10 @@ sessions/                        WHO PUTS IT THERE
 
 ## The `00-ignition-brief.md` template
 
-The coordinator's standing orders for this run, and **you write all of it here — every section, nothing
-left blank.**
+The coordinator seat's spec and the charter every seat reads, and **you write all of it here — every
+section, nothing left blank.** The sections down to § Platform state bind every seat; the three after it
+are the coordinator's orders, and a seat whose charter excludes them (the review row) stops at § Platform
+state.
 
 **Why here and not at ignition:** this is the hot session. You just placed the specs, counted the
 populations, and read the code they cite, so you are the only seat that can state the baselines and the
@@ -236,53 +270,83 @@ That includes the **kick text**: write the coordinator's task string here, ready
 requires no authoring at all.
 
 ```markdown
-# {Topic} — Ignition Brief (the coordinator's standing orders)
+# {The pipeline's title}
 
-> You are the COORDINATOR of the {topic} pipeline. Read this, then the umbrella (01-*.md), then the
-> tracker (project-status.md — yours), then EVERY numbered spec before arming the first seat.
+> **Every seat reads this file.** It is the coordinator seat's spec and the charter this pipeline stands on,
+> and it is never a session. The sections down to § Platform state bind every seat; the sections after it
+> are the coordinator's orders. The numbered files `01`–`{NN}` are the build seats' specs.
 {the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for `draft`}
 
 **Last verified against:** {date}, `{sha}`. Ignition re-verifies this brief against live HEAD and
 corrects drift; it does not re-author it.
 
+## Why
+What is wrong today and what the effort makes true — the vision a seat builds toward.
+
 ## Birth
-Topic · spec path · receipt prefix · attended/unattended · branch `{the effort's branch}`.
+Topic · spec path · receipt prefix · mode (hosted, or by hand) · shape · the effort's branch · **the model
+and the effort every seat starts on** · the rows chosen at authoring (review? docs-process?) and why ·
+**the GATE**: only that the predecessor merged, then re-verify this brief's § Reference and re-measure
+§ Baselines.
+
+**Name the model and the effort, each in backticks** — the word model then the id, the word effort then the
+level (*every seat starts on model `{id}` at effort `{level}`*) — because the launcher reads both from this
+section. Write the id as the runner's catalog offers it. A brief that names neither leaves both to the
+launcher's default; hand-cranked, the same line tells the human which model to open each seat's session on.
 
 ## The sequence
 | Seat | Spec | Kind | Why it sits here |
 
 **THE `Kind` COLUMN IS THE VOCABULARY WORD, VERBATIM** — `build` · `fixit` · `review` ·
-`docs-process` · `coordinator` · `retro` · `witness` — **not a prose role.** This table is READ, not
-just read by people: ignition derives the create payload from it (`spec-ignite` § the stage card is
-derived), and the create door validates the kind against a closed set and refuses an unknown by name.
-A cell saying "the one that reviews" composes nothing.
+`docs-process` · `coordinator` · `retro` · `witness`, or `step` for a row that is not a seat — **not a
+prose role.** This table is READ, not just read by people: ignition derives the create payload from it
+(`spec-ignite` § the stage card is derived), the create door validates the kind against a closed set and
+refuses an unknown by name, and the doctor fails a row whose kind is none of these. A cell saying "the one
+that reviews" composes nothing. An optional `Role` column carries `backend` · `frontend` · `mixed` for a
+seat whose reading list should not be left to the default. An optional `Repository` column names the
+repositories a seat also writes in, by the runner's names; a seat's home is always this repository. Neither
+column's cell may hold a kind word or `step`: the table is read by kind value, and a kind word anywhere in
+a row is read as that row's kind.
+
+**This is the only copy of the sequence.** The tracker's status lines name these rows by id and copy
+nothing else.
 
 **AND THE COORDINATOR IS A ROW.** It is a seat on the create payload like any other, it is not one
 of the numbered specs, and a pipeline without exactly one is refused at start
-(`pipeline-has-no-coordinator` / `-has-many-coordinators`). List it first, at stage 0, with the brief
+(`pipeline-has-no-coordinator` / `-has-many-coordinators`). List it first, at stage 0, with this brief
 as its spec.
 
 Include the REVIEW and DOCS-PROCESS rows if the pipeline has them, and say which it does NOT have —
 the coordinator needs to know whether a review precedes its retro. If there is a review row, add:
-**its seed carries no coordinator beliefs, no provenance, no already-settled framing** · a FIXIT row
-may follow it (one maximum, coordinator-ruled from the review's named candidates) · **the retro comes
-after the review and after any fixit**, never before. If docs-process is a row, note that its
-living-doc patches are contingent on the merge.
+**its seed carries no coordinator beliefs, no provenance, no already-settled framing, and it reads this
+brief down to § Platform state as claims** · a FIXIT row may follow it (one maximum, coordinator-ruled
+from the review's named candidates) · **the retro comes after the review and after any fixit**, never
+before. If docs-process is a row, note that its living-doc patches are contingent on the merge.
 
-## The coordinator's beliefs, with provenance
-Each load-bearing claim and which pipeline, row, or commit established it. A seat that finds a mismatch
-has produced something worth more than a build hour. **Never head this section with a claim that
-questioning it counts against the session** — that framing gets pointed at exactly the claims that
-turn out to be wrong.
+## The owner's rulings — settled, don't relitigate
+Each decision the owner made while the plan came through, and its consequence for the run. A seat that
+needs one overturned asks; it never rebuilds an argument the owner already ruled on.
+
+## Law — what binds every seat beyond the skills
+Only what OVERRIDES a default, in one section: the relay or the hosted ceremony this run uses, the suite
+and coverage lanes, spend fences, ordering constraints that are not obvious from the specs, the stack
+rules, what is frozen. Never a restatement of a skill.
+
+## Reference — the facts the specs stand on
+The symbols, files and states every spec cites, each read against the tree on a stated date. The specs
+point here instead of each re-deriving them.
 
-## Pipeline-specific law (beyond the prompt and the skills)
-Only what OVERRIDES a default: the suite/coverage lane, spend fences, ordering constraints that are not
-obvious from the specs, per-spec riders already ruled.
+## Where it came from
+The research that fed this effort, by path — it archives with the effort — and an `Archive:` line when
+only this session can name the archive home (step 5).
+
+## What this effort does NOT do
+The out-of-scope list, each item with where it lives instead. A seat never touches what is named here.
 
 ## Baselines
-MEASURE these — run the suites and quote the real numbers. Ignition re-verifies; it cannot invent them.
-Per lane: the result, **the exact invocation**, and **the environment it was measured in**. Three things
-that each cost a live run:
+MEASURE these — run the suites and quote the real numbers. The GATE re-measures them; every seat cites
+them and measures only a lane this section does not name. Per lane: the result, **the exact invocation**,
+**the environment it was measured in**, and **its duration**. Three things that each cost a live run:
 - **A number without its invocation is not a receipt** — it invites the next reader to widen its scope.
   Say which projects ran, not just a total.
 - **State the environment.** A baseline measured with the stack down is a different number from one
@@ -307,17 +371,22 @@ If this pipeline CHANGES the machinery it runs on — the ledger, the wake diges
 sentinel, the gate — say so here, and tell the coordinator to expect to meet that defect while fixing it.
 Meeting it is a first-hand receipt worth more than the spec's analysis: journal it and cite it in the fix.
 
+## The coordinator's beliefs, with provenance
+Each load-bearing claim and which pipeline, row, or commit established it. A seat that finds a mismatch
+has produced something worth more than a build hour. **Never head this section with a claim that
+questioning it counts against the session** — that framing gets pointed at exactly the claims that
+turn out to be wrong.
+
 ## Close-out
-Per-seat artifact filing · live-checks aggregation · what the PR must say · the receipt this pipeline
-owes about itself.
+Per-seat artifact filing · what the PR must say · the owner's quick pass (short and ordered, offered in
+the chat) · the receipt this pipeline owes about itself.
 
-**A HUMAN ROW OWES A RECEIPT, NOT A NARRATION.** If the pipeline has a human row, carry this rule
-into the brief verbatim: the row is exempt from `plan.md` (there is no build to plan) and is **NOT**
-exempt from an independent record. It files `sessions/{slug}/receipt.md` in the row's own commit —
-each check id, what was run, the literal result, and who observed it. Every other row has TWO
-voices, the seat's tldr and the coordinator's tracker, and the retro's ceremony audit is built on
-cross-reading them; a human row recorded only by the coordinator has ONE, and the one voice is the
-one whose errors nobody else catches.
+**A HUMAN STEP OWES A RECEIPT, NOT A NARRATION.** If the sequence has a human `step` row, carry this rule
+into the brief verbatim: the step is exempt from `plan.md` (there is no build to plan) and is **NOT**
+exempt from an independent record. It files `sessions/{step-slug}/receipt.md` in its own commit — each
+check id, what was run, the literal result, and who observed it. Every seat has TWO voices, the seat's
+tldr and the coordinator's tracker, and the retro's ceremony audit is built on cross-reading them; a step
+recorded only by the coordinator has ONE, and the one voice is the one whose errors nobody else catches.
 
 ## The kick — paste this verbatim as the coordinator's task
 > You are the COORDINATOR of the {topic} pipeline. Invoke the `spec-coordinator` skill, then read
@@ -354,10 +423,11 @@ viewer because they are instructions to the coordinator, not content for the hum
 {one paragraph}
 
 ## Session status
-<!-- ready -> building -> SHIPPED {sha} / PARKED {sha}. One line each, no prose. -->
+<!-- ready -> building -> SHIPPED {sha} / PARKED {sha}. One line per row, by the brief's ids; the sequence
+     itself lives in the brief and is never copied here. -->
 
-## Settled decisions
-<!-- The don't-relitigate list, carried from the umbrella; append rulings that become standing. -->
+## Rulings made during the run
+<!-- Append-only. What was settled at authoring is the brief's; this section holds only what the run rules. -->
 
 ## What's verified (trust basis)
 <!-- What a build session may take on faith, and what it must re-check itself. -->
@@ -415,10 +485,10 @@ viewer because they are instructions to the coordinator, not content for the hum
 
 ## `live-checks.md`
 
-One file at the effort's root, created with the specs. Every parked demo and human-verification row lands
-here — a seat's FINAL TLDR section (e) rows get transcribed into it **at close-out, in the same commit as
-the work**. Rows scattered across five sessions' TLDRs and never aggregated is the most common thing to
-fall through: name the file at authoring time so nobody invents a new one.
+One file at the effort's root, **created with no rows**. **Live checks are the owner's**: the file holds
+only the rows the owner dictates, the coordinator writes a row only when the owner dictates it, and nothing
+is aggregated into it — a seat's FINAL TLDR section (e) is what the owner could try, said in the chat, and
+never a row. Create the file at authoring time so nobody invents a second one.
 
 **The status vocabulary carries a PARTIAL, not just pass/fail:**
 `owed` · `passed` · `failed` (a failure is a finding, not a retry) · `not exercised` (with the reason — an
@@ -430,10 +500,9 @@ single passed/failed cell over a check whose seed half was clean and whose platf
 to invent a status to record the truth. **If you can name two owners while writing the row, write two
 rows.**
 
-**TWO WRITERS ON THIS FILE IS A DIVERGENCE WAITING TO HAPPEN — and it is the file the review grades
-from.** The coordinator dictates rows into a seat's close-out call and the SEAT stages them; a seat never
-writes it unprompted. Author the file knowing that, and do not write instructions telling the coordinator
-to edit it directly.
+**ONE WRITER, ON ONE PERSON'S WORD.** A seat never authors or edits a row. A seat whose change makes a
+dictated row false says so in its FINAL TLDR, quoting the row, and the coordinator corrects it. Author no
+instruction that sends a seat's checks into this file.
 
 ## Notes
 
@@ -444,7 +513,7 @@ to edit it directly.
   folder), the chat transcript, and any subagent reports vanish. Inline their load-bearing content; never
   point at ephemeral state as the source of truth. Cross-links to *other durable docs* are fine.
 - **Lifecycle.** Specs live in `research/{topic}/` through the build. When the effort ships, `docs-process`
-  archives the umbrella + every spec + the working docs together into the home `docs-workflow.md` § The
+  archives the brief + every spec + the working docs together into the home `docs-workflow.md` § The
   archive convention (repository-owned) names, in its shape — the spec set *is* the design history.
 - **Anti-fabrication.** A spec's header verified date is the date it was *authored against the code it
   cites*, not a promise the code stays unchanged. Only write facts you actually checked this run.

package/skills/spec-retro/SKILL.md

@@ -73,9 +73,10 @@ population or only its failures.
   silently-empty result is usually a broken query, not an empty table.
 - **A search that times out is not a search that found nothing.** If a sweep backs an ABSENCE claim,
   re-run it on the tool that completes before you report the absence.
-- **A gate scanner matches TEXT.** A query or command whose text contains `git` and `push`, or
-  `git` + `branch` + a `-d` flag, parks by design. **Reshape the command — never re-request it.** (The
-  boundary half of `spec-seat`'s discriminator.)
+- **The gate reads the command the shell would run, not its words.** A quoted search pattern naming a
+  boundary operation is data; the same words handed to an interpreter, or carrying a substitution, are read
+  as something that could run, and park. **Reshape the command — never re-request it.** (The boundary half
+  of `spec-seat`'s discriminator.)
 
 **READS ONLY. Never write to the platform's store.**
 
@@ -319,8 +320,10 @@ effort). The pipeline exists to widen the seat's autonomy — **so every wall it
 ### 9. WHAT FELL THROUGH THE CRACKS
 
 Named explicitly, because the alternative is that it stays fallen. Include the open questions the run
-could not settle, and say plainly that they are open. **Check the effort's `live-checks.md`** — unaggregated
-verification rows are the most common thing to fall through.
+could not settle, and say plainly that they are open. **Check that the owner was offered a quick pass** —
+the seats' "what the owner could try" lines that never reached the owner are the most common thing to fall
+through. `live-checks.md` holds only the rows the owner dictated; an unrun dictated row is the owner's open
+item, said so here.
 
 ### 10. THE FINDINGS DISPOSITION PASS — *the drain, and it is the section that decides whether the effort's findings survive it*
 
@@ -341,7 +344,7 @@ not on this list, the honest answer is CLOSED with a reason:
 | Destination | Why a later effort reaches it |
 |---|---|
 | A working doc's **Living-Docs checklist** | `docs-process` patches a living doc; living docs get read |
-| A **`live-checks.md` row** | The owed-checks authority is read at every sitting |
+| A **`live-checks.md` row the owner dictates** | The owner's own checks, read at every sitting — offered to the owner, never written without their word |
 | A named input in the **NEXT pipeline's brief** | The only legal forward-carry — no standing ledgers |
 | An **in-code revisit note at the symbol** | Grep-findable by whoever next opens that file |
 | A **chartered fixit**, with its discharge record | Someone is building it, and the record closes |
@@ -372,7 +375,10 @@ is the look of a record with none of a record's properties.
 ## Ceremony
 
 1. **Read** your own ledger — `docs/research/{topic}/project-status.md`, the one ledger of §4 — every
-   session's `tldr.md`, and the working docs.
+   session's `tldr.md`, the working docs, and **a witness ledger when one exists**
+   (`sessions/witness-ledger-*.md`, or the copy the human hands you). The witness watched from outside the
+   plane with instruments you do not have: carry every observation of it your retro does not already hold,
+   in a section of its own, attributed to the witness — never folded silently into your own findings.
 2. **Query** the substrate for §§2-5. Verify each query FIRES on a known-positive row before trusting a
    clean result.
 3. **Write** `docs/research/{topic}/sessions/coordinator-retrospective.md` — NATIVELY, in the tree you were born
@@ -388,8 +394,7 @@ is the look of a record with none of a record's properties.
    § This repository's rails (repository-owned) says (when it names no route, ask the human once and suggest
    recording the answer there); one branch, one PR from any seat. **If one is already open, the push is enough.** These three git commands are your own close-out
    lane and they are 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 you write
-   around it; the deny layer matches TEXT, not parsed verbs.
+   command** — a leading `cd` disqualifies it.
 6. **Sweep for stale beliefs BY MEANING, NEVER BY PHRASE — and sweep the SIBLINGS that restate a rule, not
    just the rule's own home.** A sweep keyed on wording only finds the wording it thought of. Ask what each
    instruction *depends on being true* — which file it names, which lane it assumes exists, who it thinks

package/skills/spec-review/SKILL.md

@@ -35,9 +35,14 @@ else's job.
 Your seed carries **no beliefs about the pipeline, and that is deliberate** — but it should carry an
 **inventory**, because you cannot review what you cannot find:
 
-- the **topic**, the **branch**, and the **diff range** (`{base}...<branch>` — `{base}` is the base branch
-  `docs/_meta/engineering-loop.md` § This repository's rails (repository-owned) names, or the remote's
-  default when it names none);
+- the **topic**, the **branch**, and the **diff range** (`origin/{base}...<branch>` — `{base}` is the base
+  branch `docs/_meta/engineering-loop.md` § This repository's rails (repository-owned) names, or the
+  remote's default when it names none; it is read from the remote's copy, because a local base branch can
+  sit behind it and pull another effort's commits into the range);
+- **one more range per further repository the run wrote**, with that repository's path — by its release
+  tags when the run released it mid-run, since its branch is merged by then;
+- **the brief** (`00-ignition-brief.md`) — its sections down to § Platform state, read as claims like the
+  specs, and **never the coordinator's sections after it** (its beliefs, its close-out, its kick);
 - **every numbered spec path** — you read them as claims, not facts;
 - the **`sessions/`** folder, holding each build seat's `plan.md` + `tldr.md`;
 - the **working docs for this effort, named explicitly** — `docs/working/` is a shared queue and you must
@@ -45,20 +50,30 @@ Your seed carries **no beliefs about the pipeline, and that is deliberate** —
 - the **tracker** (`project-status.md`), which is the process record lens 3 grades from.
 
 **If any of that is missing, ask for it** — a numbered question in your `tldr.md`, same lane as any seat.
-Do not hunt, and do not guess a scope. **What you must NOT be given, and must not accept as fact if it
-arrives anyway:** prior-shapes bullets, a provenance list, or any framing about what is already settled.
-That is testimony; record it and treat it as a claim.
+Do not hunt, and do not guess a scope. **This inventory wins over a narrower instruction:** a brief or a seed
+that tells you to read less (only the diff and your skill, say) does not shrink it — ask for what is missing,
+and say in your report that the instruction was narrower. **What you must NOT be given, and must not accept
+as fact if it arrives anyway:** prior-shapes bullets, a provenance list, or any framing about what is
+already settled. That is testimony; record it and treat it as a claim.
+
+**Say whether this review is COLD or WARM, in your report's first paragraph.** Cold: you were seeded with
+the inventory and nothing else. Warm: you were handed the run's context — a tracker reading before your own
+passes, a coordinator's framing, the owner's briefing. A warm review can be worth having; it is a different
+instrument, and a reader who takes it for a cold one over-trusts its independence.
 
 ## Reading order (it matters)
 
-1. **The specs** — what the pipeline said it would do, per slice, including each escape hatch and the
-   declared out-of-scope.
+1. **The brief, down to § Platform state, and the specs** — what the pipeline said it would do, as a
+   whole and per slice, including each escape hatch, the owner's rulings and the declared out-of-scope.
 2. **The session docs** — every seat's `tldr.md` in `sessions/`. What each seat claims it shipped,
    its honest gaps, its deferred findings, its receipts.
 3. **The working docs** in `docs/working/` — the narrative: what was tried, what failed, what changed.
 4. **The tracker** — `project-status.md`, the coordinator's journal: rulings and their reasoning, recon
    corrections, incidents.
-5. **THEN the diff** — `git diff {base}...<pipeline-branch>`, plus `git log --oneline {base}..<pipeline-branch>`.
+5. **THEN the diff** — `git diff origin/{base}...<pipeline-branch>`, plus `git log --oneline
+   origin/{base}..<pipeline-branch>`; and the same pair for each further range your seed names, run inside
+   that repository. Read the two sides of a seam together: what one repository ships and what the other
+   consumes are one claim.
 
 **Read the artifacts before the code, and the code before you conclude.** Reading the diff first makes
 you review a patch; reading the claims first makes you review whether the pipeline did what it said.
@@ -203,6 +218,7 @@ a pipeline artifact, not a chat transcript, and it archives with the effort.
 
 > The outside look, written before the retro and before the PR. Two independent passes, consolidated.
 > Reviewed `{base}..{sha}` across N sessions. **This seat did not read the coordinator's retrospective.**
+> **{COLD | WARM}:** {what this seat was seeded with — the inventory alone, or the run's context, and which}.
 {the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for `shipped`}
 
 ## The verdict, first
@@ -232,8 +248,9 @@ the smallest fix that makes the claim true. If none: say NONE, plainly.}
 ## Deferred findings — with their DESTINATIONS
 | R-n | Finding | Found by | Destination |
 {Report-local ids — the coordinator allocates the effort id at the ruling. A DESTINATION is a place that
-exists and that someone reads: a working doc's Living-Docs checklist · a `live-checks.md` row · a
-named input in the NEXT pipeline's brief · an in-code revisit note at the symbol · a chartered fixit ·
+exists and that someone reads: a working doc's Living-Docs checklist · an item for the owner's quick pass
+(offered in the chat; a `live-checks.md` row only when the owner dictates one) · a named input in the NEXT
+pipeline's brief · an in-code revisit note at the symbol · a chartered fixit ·
 or CLOSED with its reason. **"deferred log" is not a destination** — it is the holding pen the
 finding sits in until the retro's disposition pass drains it. A row whose destination is a document
 that does not exist yet (an unauthored row, an unwritten charter) is NOT homed: say so here.}
@@ -244,7 +261,7 @@ that does not exist yet (an unauthored row, an unwritten charter) is NOT homed:
 {Stated, not omitted.}
 
 ## Lineage   _(where § Doc metadata (repository-owned) keeps the footer)_
-- **Pipeline** — the tracker · the umbrella · sessions 02..NN
+- **Pipeline** — the tracker · the brief · sessions 01..NN
 - **Counterpart** — `coordinator-retrospective.md` (the inside look; written after this)
 ```
 
@@ -252,8 +269,9 @@ that does not exist yet (an unauthored row, an unwritten charter) is NOT homed:
 
 **Your contract is `spec-seat`** — invoke it first if you have not. It carries recon, the plain-text PLAN
 TLDR with beliefs and numbered questions, the question lane, the parked-call discriminator, the verdict
-vocabulary, the six-section FINAL TLDR, and the close-out order. You commit `sessions/code-review.md` on
-your coordinator's call like any seat.
+vocabulary, the six-section FINAL TLDR, and the close-out order. You commit `sessions/code-review.md` as
+any seat commits its work: hand-cranked on your plan's approval (the relay), hosted on your coordinator's
+call.
 
 **The close-out receipt's heading token is the literal `seat·` for you too** — it is a protocol anchor,
 not a description of your seat, and writing `[review·…]` stales your own acceptance. `spec-seat` carries