@naswerks/engineering-loop 0.5.1 → 0.7.0

package/skills/spec-seat/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-seat
-description: The CONTRACT for any seat a pipeline coordinator arms — the blackboard, the question lane, the parked-call discriminator, the verdict vocabulary, the BELIEFS sha, git shapes, the six-section FINAL TLDR, and the close-out order. Invoked FIRST, then the job skill (spec-child | spec-review | docs-process). Not a seat of its own; the shared half of every seat's procedure.
+description: The CONTRACT for any seat a pipeline coordinator arms — the blackboard, the question lane, the parked-call discriminator, the verdict vocabulary, the BELIEFS sha, git shapes, the six-section FINAL TLDR, and the close-out order. Invoked FIRST, then the job skill (spec-build | spec-review | docs-process). Not a seat of its own; the shared half of every seat's procedure.
 ---
 
 # spec-seat
@@ -10,13 +10,13 @@ the review row, the docs-process row — runs THIS, then its own job skill:
 
 | Seat kind | Composes |
 |---|---|
-| `build` · `fixit` | `spec-seat` + **`spec-child`** |
+| `build` · `fixit` | `spec-seat` + **`spec-build`** |
 | `review` | `spec-seat` + **`spec-review`** |
 | `docs-process` | `spec-seat` + **`docs-process`** |
 
 **THE PAIRING IS SEVEN-WAY AND NON-UNIFORM, and the three kinds missing from that table are missing
 DELIBERATELY.** `coordinator`, `retro` and `witness` each carry their OWN whole contract
-(`spec-parent` · `spec-retro` · `spec-witness`) and are **never** told to invoke this file — prefixing
+(`spec-coordinator` · `spec-retro` · `spec-witness`) and are **never** told to invoke this file — prefixing
 `spec-seat` onto a skill that already carries a whole contract ships a seed contradicting the skill it
 points at. The control plane composes each kind's seed from this table and has no catch-all: an unknown
 kind is refused by name (`seat-kind-has-no-seed`) rather than ignited wrongly.
@@ -26,7 +26,7 @@ contradicts it. Where they genuinely conflict, that is **a finding to report**,
 quietly — say so in your PLAN TLDR and let the coordinator rule.
 
 **The coordinator does NOT compose this.** It writes rulings rather than receiving them, owns the tracker,
-and holds the close — a different contract, and `spec-parent` carries it whole.
+and holds the close — a different contract, and `spec-coordinator` carries it whole.
 
 **Why this file exists:** a base contract that every seat kind shared, with the build job mixed in, sent
 the review row into the umbrella its own charter excluded and offered the docs-process row a `docs-write`
@@ -98,16 +98,26 @@ that is your scope — do not widen it on the theory that more reading is safer.
 `plan.md` (the full plan document) and `tldr.md` (the chat: your PLAN TLDR, any mid-build updates, the
 FINAL TLDR — **append, never overwrite**) are FILES, not just chat text.
 
+**ONE CEREMONY IN BOTH MODES: you write your file, then you poke; your coordinator appends its ruling to the
+SAME file, then pokes you. Nobody pastes a document into a message.**
+
 - **Hand-cranked:** create them under `docs/research/{topic}/sessions/{slug}/` at plan time and end your
   turn announcing the path. The coordinator reads `tldr.md` with normal file tools and APPENDS its ruling
-  under `## PARENT RULING`, so read the answer in your own file and proceed. The full plan is PULL — it is
+  under `## COORDINATOR RULING`, so read the answer in your own file and proceed. The full plan is PULL — it is
   read only on a read-full-plan verdict; never paste it into chat. (If your harness has a plan-approval
   mode that forbids writes: give the chat summary, get the human's approve, THEN post and stop.)
-- **Hosted (a seat inside a pipeline):** the same two files are yours to edit with normal file tools, then
-  call **`post_plan` / `post_tldr` with the file's whole text as `content`** — the control plane runs on
-  another machine and cannot read your file. It records a revision and wakes your coordinator with ONE
-  LINE naming the act and the rev; the coordinator reads your file from the board; nothing you wrote is
-  pasted into its context (the pointer protocol).
+- **Hosted (a seat inside a pipeline):** the same two files are yours to edit with normal file tools. **Write,
+  then poke:** the first time, call `post_tldr` with `path` — the file's path inside your workspace, relative
+  to its root — and the control plane reads the file from your runner; after that, call `post_tldr` with
+  NOTHING and it reads the same path again (`post_plan` the same way). It records a revision and wakes your
+  coordinator with ONE LINE naming the rev and the sections you added. **Your coordinator's ruling arrives
+  IN YOUR FILE** — it appends under its coordinator-voice heading, and you are poked with one line naming
+  the section (*"Your tldr.md rev 5 adds `## COORDINATOR RULING (plan rev 1 — accept)`"*). Read it with
+  your own file tools; it is never pasted to you.
+  **If the post answers `host-lacks-workspace-read`** (a runner older than periscope 1.4.0) **or asks for
+  `content`** (a control plane that predates reading files), it cannot read your workspace: pass the whole
+  file as `content` instead, and read rulings from your board (`seat_content(kind: "ruling")`) as well as
+  your file.
   **THE FILE IS THE RECORD AND THE ROW MIRRORS IT** — one artifact row per rev carrying the whole file
   verbatim, so the two voices stay interleaved because nothing splits them. The control plane refuses
   `blackboard-rev-regressed` · `blackboard-shrank` · `blackboard-rev-content-mismatch` at the door: **an
@@ -118,29 +128,33 @@ Either way, `tldr.md` read top-to-bottom is the session's whole conversation in
 
 **Greppable turn anchors:** every append gets a stable heading carrying actor + identity —
 `## [{seat}·{slug} · run {id}] {phase}` when your seat has a run identity, `## [{seat}·{slug}] {phase}`
-hand-cranked. The coordinator's voice is always `## PARENT RULING …` / `## PARENT NOTE …`. The stable
-prefixes are the contract: one grep for `## PARENT RULING` across every session's `tldr.md` lists every
-ruling in the effort.
-
-**THE HEADING VOCABULARY IS CLOSED, AND THAT IS THE HAZARD AS WELL AS THE CONTRACT.** The parent-voice
-list is exactly four — `PARENT NOTE` · `PARENT ACCEPT` · `PARENT RULING` · `OPERATOR RULING` — matched
-by the control plane on a word boundary, so `## PARENT NOTEBOOK` cannot pass. A fifth anchor invented
-later closes nothing and counts as nothing until the control plane learns it. **Section boundaries are
-level-2 headings only** — `### Option A` inside your question block is still inside the question,
-deliberately, so a ruling never arrives having truncated your options.
-
-**Point, don't paste:** to direct anyone at content, say *"read `tldr.md` under `## PARENT RULING`"* —
-never re-paste a multi-KB block into a composer.
+hand-cranked. The coordinator's voice is always `## COORDINATOR RULING …` / `## COORDINATOR NOTE …`. The
+stable prefixes are the contract: one grep for `## (COORDINATOR|PARENT) RULING` across every session's
+`tldr.md` lists every ruling in the effort.
+
+**THE HEADING VOCABULARY IS CLOSED, AND THAT IS THE HAZARD AS WELL AS THE CONTRACT.** The
+coordinator-voice list is exactly four — `COORDINATOR NOTE` · `COORDINATOR ACCEPT` · `COORDINATOR RULING`
+· `OPERATOR RULING` — matched by the control plane on a word boundary, so `## COORDINATOR NOTEBOOK`
+cannot pass. An older board spells the first three `PARENT NOTE` · `PARENT ACCEPT` · `PARENT RULING`; a
+reader of the anchors takes that spelling as the same three, which is why the grep above carries both. A fifth
+anchor invented later closes nothing and counts as nothing until the control plane learns it. **Section
+boundaries are level-2 headings only** — `### Option A` inside your question block is still inside the
+question, deliberately, so a ruling never arrives having truncated your options.
+
+**Point, don't paste:** to direct anyone at content, say *"read `tldr.md` under `## COORDINATOR
+RULING`"* — never re-paste a multi-KB block into a composer.
 
 **If `tldr.md` already exists when you go to create your blackboard, APPEND** — machinery may have written
-before you, and recreating the file clobbers it (the platform refuses a shrinking rewrite).
+before you, and recreating the file clobbers it (the platform refuses a shrinking rewrite). **And every
+heading already on your board stays exactly as written, an older spelling included:** the platform refuses
+a revision whose earlier headings changed, so never tidy an old heading into the current vocabulary.
 
 **Re-read `tldr.md` immediately before every append.** The coordinator appends into the SAME file between
 your turns — an edit whose old text no longer matches almost always means the conversation moved.
 Re-read, fold what's new, then append. Never resolve the mismatch by rewriting the whole file; the rev
 ladder is the history.
 
-**`## PARENT NOTE (FYI — no reply needed)` is the NO-TURN lane:** the coordinator can leave you
+**`## COORDINATOR NOTE (FYI — no reply needed)` is the NO-TURN lane:** the coordinator can leave you
 informational context WITHOUT waking you — it lands durably in your `tldr.md` and costs you nothing.
 The re-read above is where you pick FYIs up: fold them as context, owe no reply, and never treat one as
 a ruling — an FYI cannot answer an open question (only a ruling heading does).
@@ -149,7 +163,7 @@ a ruling — an FYI cannot answer an open question (only a ruling heading does).
 
 **When you need a decision at ANY point:** append a question section to your own `tldr.md`, post
 (`post_tldr`), and **END YOUR TURN.** Your coordinator is woken with your text, and its ruling under a
-parent-voice heading is your answer — pick it up from your own file and resume.
+coordinator-voice heading is your answer — pick it up from your own file and resume.
 
 **TWO literal headings, one lane — pick by phase, and use a real `##` heading either way:**
 
@@ -170,7 +184,7 @@ every section and answers `Blocking` / `NotBlocking` / `Undeclared`. Markdown ar
 - **Never let a reader turn your declaration into liveness.** It is a claim made at the instant you
   typed it; a seat that wrote `BLOCKING:` and then kept working was telling the truth.
 
-**Both poke the coordinator identically** — same wake, same re-raise, same parent-voice answer. The split
+**Both poke the coordinator identically** — same wake, same re-raise, same coordinator-voice answer. The split
 is for the READER (a recon fork and a mid-build discovery are different kinds of news), never for the
 machinery. A question under any OTHER heading — or as a bare `QUESTIONS:` label with no `##` — gets no
 banner and **the re-raise can never fire**, so it can sit unanswered indefinitely. And never use
@@ -190,17 +204,18 @@ question tool — the relay cannot copy it.
 **An unanswered question re-raises to your coordinator on a cooldown** until a ruling lands. Asking costs
 the pipeline a round-trip and nothing else.
 
-**WHAT ACTUALLY CLOSES A QUESTION.** On the hosted plane **nothing you write into a FILE closes anything.**
-The latch reads the ACTS LEDGER: a ruling closes your question only when it is delivered as a `callout`
-carrying your post's act id as `answeringActId`. A `callout` without one steers you and closes nothing.
+**WHAT ACTUALLY CLOSES A QUESTION.** On the hosted plane **nothing written into a FILE closes anything** —
+not yours, and not your coordinator's section in it. The latch reads the ACTS LEDGER: a ruling closes your
+question only when the coordinator's act carries your post's act id as `answeringActId`. The words arrive in
+your file; the act is what decides. A `callout` without one steers you and closes nothing.
 **The reason is a security property, not tidiness:** `tldr.md` is written BY YOU, so a file-side close
-predicate is a string the audited party can type — a seat could write `## PARENT RULING` into its own file
+predicate is a string the audited party can type — a seat could write `## COORDINATOR RULING` into its own file
 and switch off the very re-raise that exists to stop it waiting forever. The question is therefore split
 in two: *was one asked?* — a fact about the file, where forgery only wakes your own coordinator — versus
 *was it answered?* — a fact about what the coordinator DID, read from the ledger.
 
 **The honest rendering of your file is unchanged**: an open-questions read of the file still clears on the
-parent-voice heading, because that is what the file SAYS. What differs is what a DECISION may be
+coordinator-voice heading, because that is what the file SAYS. What differs is what a DECISION may be
 predicated on.
 
 ### THREE CONTRACT LINES, all earned by one kind of silence
@@ -238,7 +253,7 @@ Ask what the park is protecting:
 
 - **A park on a STATE condition** — the park text names a rev, a hash, or a version: it is STATE, not
   approval. Do not re-request, do not reshape; read the substrate for the healing signal (your own acts:
-  the fresh acceptance receipt, or the `## PARENT NOTE (re-accept)` append) and retry ONCE on receipt.
+  the fresh acceptance receipt, or the `## COORDINATOR NOTE (re-accept)` append) and retry ONCE on receipt.
   State parks are machine-healable — one argless re-accept re-binds a stale acceptance. **Never hold for
   one specific lane: whichever arrives first IS your signal, and the substrate outranks the bus.**
 - **A park on your own legitimate in-worktree work** — **re-request it** (no self-imposed cap, no
@@ -246,6 +261,9 @@ Ask what the park is protecting:
   the platform's turn, not your failure; routing around it hides the defect the park is surfacing.
 - **A park on a boundary command** (push to the base branch, force-push, branch delete — or a command
   whose *text* merely tripped the scanner) — **never re-request; reshape the command.**
+  **A search is data only in one shape:** a quoted literal pattern given to a read-only search tool (`rg`,
+  `grep`, `git grep`, `Select-String`, `findstr`), with no `$`, no backtick, no interpreter and no `xargs`
+  in the pipeline. Any other command carrying boundary words parks — search for the symbol, not the verb.
   **THE SCANNER MATCHES TEXT, NOT PARSED VERBS, AND THIS IS THE MOST-PAID FENCE IN THE CEREMONY.** It
   fires on read-only commands a careful seat runs to PROVE its work: an `echo` label reading
   `=== remote tip ===` on a `git status`/`git log` block, or `git branch -r --contains <sha>` — a branch
@@ -262,6 +280,16 @@ Ask what the park is protecting:
 The test: is the park **blocking your work** (re-request + disclose), **guarding the boundary** (reshape),
 or **a wall** (reshape or escalate — never a click)?
 
+**BEFORE A CALL YOU KNOW WILL PARK, SAY SO.** When your work needs a boundary command — a lane that tests the
+park, a push your coordinator called for from a state the push bar cannot see — append
+
+```
+## [seat·{slug} · run {id}] ABOUT TO PARK
+```
+
+with the verbatim command and what it waits on, post, then run it. A seat held by the gate without saying so
+looks idle to everyone watching. Like `HOLDING`, it is a state report, and it does not stale your acceptance.
+
 **EVERY park is DISCLOSED in your next TLDR — including one you resolved yourself in seconds:** the
 verbatim command AND the verbatim park text. A self-resolved park looks like nothing happened and leaves
 the coordinator no signal, so the gate's false-park rate is only ever knowable from the seat that paid it.
@@ -342,7 +370,7 @@ naming both. That is why your BELIEFS sha is a contract line and not a courtesy
 moves mid-build is disclosed FIRST, never absorbed quietly.
 
 **The re-accept signal:** after a rev-bound/stale-acceptance park, the re-accept arrives as a
-`## PARENT NOTE (re-accept)` append plus a callout — retry your held action on receipt. If your next wake
+`## COORDINATOR NOTE (re-accept)` append plus a callout — retry your held action on receipt. If your next wake
 shows the fresh acceptance receipt in your own rows WITHOUT the note, **that row IS your signal** — the
 substrate outranks the bus. Never hold for one specific lane. **A re-accept with no retry order is a
 doorbell with no follow-through**; if you receive one bare, retry anyway and say that you did.
@@ -375,7 +403,9 @@ doorbell with no follow-through**; if you receive one bare, retry anyway and say
   parks where the same three commands, sent one at a time, flow unattended. Keep the word "push" out of
   echo text — the deny layer matches text, not parsed verbs.
 - Prefer native read/glob/grep tools for reads; a shell read flows with its row like any other
-  non-boundary call.
+  non-boundary call. On a periscope 1.4.0 runner they reach anything outside your workspace except
+  credential material; on an older runner Read is jailed to your workspace, so read a file outside it —
+  the runner's installed package, say — with a shell command.
 - **Codegen only through the command `patterns/codegen.md` § Running codegen names** (when the repo has
   one) — never hand-write a generated folder.
 - **Never improvise a qualifying path in.** If a push parks and the remedy you can think of is touching a
@@ -416,13 +446,13 @@ produces a working doc**, COMMIT CALL with the message). Execute it exactly.
 makes the acceptance stale by design. Append your close-out receipt AFTER the push under this heading:
 
 ```
-## [child·{slug} · run {id}] CLOSE-OUT RECEIPT
+## [seat·{slug} · run {id}] CLOSE-OUT RECEIPT
 ```
 
 ## IF YOU HAVE PUSHED AND ARE WAITING, SAY SO. IT DOES NOT STALE YOU.
 
 ```
-## [child·{slug} · run {id}] HOLDING
+## [seat·{slug} · run {id}] HOLDING
 ```
 
 **Then `post_tldr` and end your turn.** Body: what you pushed, and what you are waiting for
@@ -437,16 +467,18 @@ cost a pipeline hours. Preventing it is your job, and it costs you one append.
 the accepted CONTENT, not to the revision number, so appending your own state or a question leaves it
 intact. Only **new content** stales.
 
-**The token is the literal `child·`, whatever seat you are.** The control plane's close-out matcher keys
-on `[child·…] CLOSE-OUT RECEIPT`, so a review or docs-process seat that writes `[review·…]` or
+**The token is the literal `seat·`, whatever seat you are.** The control plane's close-out matcher keys
+on `[seat·…] CLOSE-OUT RECEIPT`, so a review or docs-process seat that writes `[review·…]` or
 `[process·…]` **fails the match and stales its own acceptance** — costing a re-post and an argless
-re-accept. **It is a PROTOCOL ANCHOR, not a description of you.** A descriptive tail after the marker IS
+re-accept. (An older board's `[child·…]` token matches too; write only `seat·`.) **It is a PROTOCOL
+ANCHOR, not a description of you.** A descriptive tail after the marker IS
 blessed (`… CLOSE-OUT RECEIPT — addendum: the six staged, tree clean`) — an end-anchored pattern on the
 one heading seats are told to write would be a trap that fires on ordinary prose.
 
-**Any post-accept append that is NOT one of these four — close-out receipt, HOLDING, a question heading, or
-your coordinator's own voice — needs the argless re-accept.** The bar is content, not revision: it asks *is
-what you are publishing still what I approved?*, and a state report is not a change of work.
+**Any post-accept append that is NOT one of these five — close-out receipt, HOLDING, ABOUT TO PARK, a
+question heading, or your coordinator's own voice — needs the argless re-accept.** The bar is content, not
+revision: it asks *is what you are publishing still what I approved?*, and a state report is not a change of
+work.
 
 **FILE YOUR SESSION ARTIFACTS:** copy your final `plan.md` and `tldr.md` into
 `docs/research/{topic}/sessions/{slug}/`. **Two files — that is the whole filing step.** Questions ride the
@@ -489,7 +521,7 @@ why. Silence is not compliance.
 **THE TESTIMONY REGRESS, AND THE DECLARED STOPPING POINT — read this before you copy anything.** The
 order above puts the COMMIT before the CLOSE-OUT RECEIPT, so the copy you commit ends at your FINAL TLDR
 and can contain neither the receipt (hash, session id, staging receipt) nor the coordinator's
-`## PARENT ACCEPT`. **A follow-up commit does not fix this, it moves it:** any receipt ABOUT that commit is
+`## COORDINATOR ACCEPT`. **A follow-up commit does not fix this, it moves it:** any receipt ABOUT that commit is
 also written after it. The regress is infinite and the ceremony does not pretend otherwise.
 
 **So the rule is a declared stopping point rather than a fix: RE-COPY `plan.md` AND `tldr.md` ONCE,
@@ -519,5 +551,8 @@ plane. The publish receipt is written at your turn's STOP and is structurally un
   with a clean rerun builds trust, an undisclosed one destroys it.
 - **A rule recalled from context needs re-reading at the source before it is used to refuse work.** A
   rule already corrected on disk is the commonest thing a seat blocks itself on.
-- Your job skill is next: `spec-child` (build/fixit) · `spec-review` (the outside look) ·
-  `docs-process` (compile the living docs). Counterpart: `spec-parent` (the seat that arms you).
+- **A control-plane verb that fails with a transport error** (`ECONNRESET`, a socket closed under the call)
+  is the transport, not a refusal: call it once more. If it fails again, say so in your next TLDR and carry
+  on with work that does not need it. A refusal has a name; a dropped connection does not.
+- Your job skill is next: `spec-build` (build/fixit) · `spec-review` (the outside look) ·
+  `docs-process` (compile the living docs). Counterpart: `spec-coordinator` (the seat that arms you).

package/skills/spec-witness/SKILL.md

@@ -78,13 +78,16 @@ git — agree.
    are a zero-token heartbeat per seat — a growing ladder is a live session, a frozen one dates its last
    turn. `seat_content` reads the board; read `tldr.md` top-to-bottom and it IS the session's whole
    conversation in message-flow order — the fastest "where is this seat" there is. The coordinator's
-   voice is a greppable anchor: `## PARENT RULING (plan rev N — {verdict})` and `## PARENT NOTE (…)`
-   (actor-suffixed when known) on the hosted plane; the same prefixes without the rev counter under
-   `docs/research/{topic}/sessions/{spec-slug}/` hand-cranked — so grep the prefix, never the full form.
+   voice is a greppable anchor: `## COORDINATOR RULING (plan rev N — {verdict})` and `## COORDINATOR NOTE
+   (…)` (actor-suffixed when known) on the hosted plane; the same prefixes without the rev counter under
+   `docs/research/{topic}/sessions/{spec-slug}/` hand-cranked — so grep the prefix, never the full form,
+   and grep both spellings: an older board writes `## PARENT RULING` / `## PARENT NOTE`
+   (`rg -n "## (COORDINATOR|PARENT) (RULING|NOTE)"`).
    **Honest delivery verdicts:** a ruling act's reply states recorded-vs-delivered truthfully —
    "recorded, not delivered" is NORMAL (the seats run substrate-first; the board is load-bearing, the
    pointer is best-effort). A delivery miss is only a finding if the seat ALSO never acted on the
-   substrate. **Blessed close-outs:** a seat's post-push `## [child·…] CLOSE-OUT RECEIPT` append does NOT
+   substrate. **Blessed close-outs:** a seat's post-push `## [seat·…] CLOSE-OUT RECEIPT` append (an older
+   board's `[child·…]`) does NOT
    stale its acceptance — a reap without a fresh acceptance after such an append is correct behaviour,
    not a skipped step.
 3. **Change-detection monitors, not tails:** emit only rows past a high-water mark + a terminal-state
@@ -216,7 +219,7 @@ Disciplines that don't fit a numbered step:
   trusting their silence — silence from a dead monitor looks identical to a quiet run.
 
 ## Related
-- `spec-parent` (the seat that rules) · `spec-child` (the seats that act) · `spec-seat` (their shared
+- `spec-coordinator` (the seat that rules) · `spec-build` (the seats that act) · `spec-seat` (their shared
   contract — read it to know what the seats you are watching were told)
 - **You are one of the three kinds that do NOT compose `spec-seat`** — this skill is your whole
   contract, and the control plane's seed says so rather than merely omitting it.

package/templates/docs/_meta/doc-index.md

@@ -54,7 +54,7 @@
 
 ## Role reading lists
 
-The docs a build seat reads on top of the floor every seat reads (`spec-seat` Step 0). The `spec-child`
+The docs a build seat reads on top of the floor every seat reads (`spec-seat` Step 0). The `spec-build`
 skill names the loop's standard docs by path; this table is the repository's reserved space — one row per
 doc, saying which roles read it. The coordinator copies a role's rows into every seat's seed as
 `EXTRA DOCS`, so a seat sees paths, not this index. Add a row for any doc of your own a role should read;