@naswerks/engineering-loop 0.5.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,7 +10,7 @@
10
10
  {
11
11
  "name": "naswerks",
12
12
  "description": "The engineering loop: docs-* knowledge loop, spec-* execution loop, and init for a fresh repository.",
13
- "version": "0.5.1",
13
+ "version": "0.6.0",
14
14
  "source": "./"
15
15
  }
16
16
  ]
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "naswerks",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "The engineering loop: a knowledge loop (docs-*) and an execution loop (spec-*) for repositories driven by hosted agent sessions, plus init to make a repository ready for both.",
5
5
  "author": { "name": "naswerks" },
6
6
  "license": "MIT",
package/CHANGELOG.md CHANGED
@@ -5,6 +5,54 @@ version is the one in `package.json` and `.claude-plugin/plugin.json`, which mus
5
5
 
6
6
  ## [Unreleased]
7
7
 
8
+ ## [0.6.0] - 2026-09-29
9
+
10
+ ### Changed
11
+
12
+ - **Two skills are named for the seat kinds that run them.** `spec-parent` is now `spec-coordinator`, and
13
+ `spec-child` is now `spec-build`. A spec seat's skill is `spec-{kind}` for every kind; `fixit` rides
14
+ `spec-build`, and `docs-process` is its own skill. Invoke them as `/naswerks:spec-coordinator` and
15
+ `/naswerks:spec-build`. A control plane that seeds skills by name seeds the new names, with this version
16
+ as its pack floor.
17
+ - **The coordinator's voice is spelled `COORDINATOR`.** The anchors are `## COORDINATOR RULING`,
18
+ `## COORDINATOR NOTE` and `## COORDINATOR ACCEPT` (beside `## OPERATOR RULING`), the ruling templates open
19
+ `COORDINATOR RESPONSE`, and a seat's own anchors are `## [seat·…] CLOSE-OUT RECEIPT` and
20
+ `## [seat·…] HOLDING`. A board written before this version spells them `## PARENT …` and `[child·…]`:
21
+ every grep the skills run reads both spellings, a parser that reads the anchors should too, and no seat
22
+ rewrites a heading already on its board.
23
+ - The coordinator's close-out audit is filed as `sessions/coordinator-retrospective.md`; a reader takes
24
+ `sessions/parent-retrospective.md` in an effort begun before this version.
25
+ - `spec-coordinator` no longer names a `parallel` spawn argument: a shared worktree holds one live seat at a
26
+ time, and parallel seats need separate worktrees, decided when the pipeline is created.
27
+ - The retired-vocabulary census retires `parent` beside `chain` and `child`.
28
+ - `docs-workflow.md` says the ignition brief is written whole at authoring and verified at ignition. The
29
+ sentence sits in § Templates, which a copy owns: see Upgrading, step 3.
30
+
31
+ ### Added
32
+
33
+ - `pins/names.test.mjs`: every skill name the pack writes is a skill it carries, and every seat kind runs a
34
+ skill named for it. The kinds, their skills and the words shaped like a skill name that name none are one
35
+ list in `skills/init/scripts/owned.mjs`, which the doctor reads too.
36
+ - `init doctor` degrades a brief whose `## The kick` names a skill this pack does not carry, and names the
37
+ coordinator's skill.
38
+
39
+ ### Upgrading from 0.5
40
+
41
+ 1. Take the release (`claude plugin marketplace update engineering-loop`, then
42
+ `claude plugin update naswerks@engineering-loop`) between efforts: a session that invokes `spec-parent`
43
+ or `spec-child` after the update finds no such skill.
44
+ 2. Re-copy the loop text of both references into `docs/_meta/`, keeping your repository-owned sections;
45
+ `init refresh` restamps and never touches loop text.
46
+ 3. Three places are yours, so neither `init refresh` nor a re-copy reaches them. Change each one that still
47
+ carries the old text:
48
+ - § The archive convention (repository-owned): `parent-retrospective.md` is `coordinator-retrospective.md`.
49
+ - § Templates (repository-owned): the ignition brief is "the coordinator seat's standing orders for the
50
+ run — written whole at authoring, verified at ignition" (it read "the parent seat's standing orders
51
+ for the run — two sections completed at ignition").
52
+ - `docs/_meta/doc-index.md`: the build-seat paragraph `init` wrote from its template names `spec-build`
53
+ (it read `spec-child`).
54
+ 4. Run `init doctor`. A brief whose kick still names a retired skill shows a DEGRADE row; change the kick.
55
+
8
56
  ## [0.5.1] - 2026-09-24
9
57
 
10
58
  ### Fixed
package/README.md CHANGED
@@ -69,9 +69,9 @@ and never touches the rest of the text.
69
69
  | `docs-process` | docs | patch living docs from working docs, verified against code, then archive |
70
70
  | `docs-audit-feature` · `docs-audit-full` | docs | audit living docs against code |
71
71
  | `spec-pipeline` | spec | explode an approved plan into numbered specs |
72
- | `spec-parent` | spec | the coordinator seat |
72
+ | `spec-coordinator` | spec | the coordinator seat |
73
73
  | `spec-seat` | spec | the contract every armed seat follows |
74
- | `spec-child` | spec | the build job for one spec |
74
+ | `spec-build` | spec | the build job for one spec |
75
75
  | `spec-review` | spec | the outside look before the retrospective |
76
76
  | `spec-retro` | spec | the coordinator's close-out audit |
77
77
  | `spec-witness` | spec | a read-only verifier |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@naswerks/engineering-loop",
3
- "version": "0.5.1",
3
+ "version": "0.6.0",
4
4
  "description": "The engineering loop as a Claude Code plugin: a knowledge loop (docs-*), an execution loop (spec-*), and init for a fresh repository. The package root is the plugin root.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -1,4 +1,4 @@
1
- <!-- naswerks-loop: version=0.5.1 -->
1
+ <!-- naswerks-loop: version=0.6.0 -->
2
2
  # Docs Workflow
3
3
 
4
4
  > How knowledge flows through `docs/`: the loop, the folder rules, the templates, and the `docs-*` skills.
@@ -204,9 +204,9 @@ one** (via `spec-pipeline`). The trigger for the layout is simply *"does this ef
204
204
  (TWO files — questions ride the PLAN TLDR, and there are no
205
205
  status snapshots, because the tracker is committed live and
206
206
  its git history carries every revision)
207
- code-review.md the review seat's outside look, if
208
- the pipeline had a review row
209
- parent-retrospective.md the parent's inside look
207
+ code-review.md the review seat's outside look, if
208
+ the pipeline had a review row
209
+ coordinator-retrospective.md the coordinator's inside look
210
210
  These are TESTIMONY: an archive pass repairs links elsewhere and
211
211
  leaves sessions/** byte-untouched. Older archived sessions may
212
212
  still hold questions.md / status-after-*.md; that is historical
@@ -430,8 +430,8 @@ once the code is fixed. Keep entries one line, dated, and pointing at a `file:li
430
430
  ### Spec doc (a numbered pipeline — `spec-pipeline`)
431
431
 
432
432
  When a research idea graduates into a real plan, `spec-pipeline` explodes it into a numbered pipeline in
433
- `docs/research/{topic}/`: `00-ignition-brief.md` (the parent seat's standing orders for the run — two
434
- sections completed at ignition) · `01-{topic}.md` (the umbrella) · `02..NN-{slice}.md` (**one
433
+ `docs/research/{topic}/`: `00-ignition-brief.md` (the coordinator seat's standing orders for the run —
434
+ written whole at authoring, verified at ignition) · `01-{topic}.md` (the umbrella) · `02..NN-{slice}.md` (**one
435
435
  self-contained spec per planned session**) · `project-status.md` (the tracker, which carries its own
436
436
  section notes) · `live-checks.md` (the human's verification rows).
437
437
  Each per-session spec uses this template (carries `Builds on`/`Source:` so the chain stays navigable):
@@ -472,13 +472,13 @@ come from this copy, so a repository changes them once, here.
472
472
  |-------|------|-------------|
473
473
  | `docs-backlog` | Have an idea | Capture it as a research doc in `research/` |
474
474
  | `spec-pipeline` | A research idea is graduating into a real plan | Explode the plan into a numbered spec pipeline (umbrella + one self-contained spec per session + `project-status`) in `research/{topic}/`; the plan becomes ephemeral |
475
- | `spec-parent` | Right after `spec-pipeline` (same session, context-loaded) or to resume an effort fresh | Assume the coordinator seat: cut seat prompts (one per spec), review/verify TLDRs, give commit calls, own `project-status.md` — the same loop hand-cranked or hosted |
475
+ | `spec-coordinator` | Right after `spec-pipeline` (same session, context-loaded) or to resume an effort fresh | Assume the coordinator seat: cut seat prompts (one per spec), review/verify TLDRs, give commit calls, own `project-status.md` — the same loop hand-cranked or hosted |
476
476
  | `spec-seat` | **Every** seat a coordinator arms — invoked FIRST, before the job skill | The CONTRACT, not a seat: the shared half of every seat's procedure — beliefs, plain-text PLAN TLDR, numbered questions w/ recommendations, six-section FINAL TLDR, commit only on the relayed call |
477
- | `spec-child` | Igniting a build or fixit seat — manually or platform-spawned, after `spec-seat` | The BUILD JOB only: one spec, the role's reading list, the pin taxonomy, the suite protocol; `fixit` variant for no-spec defect sessions. Its ceremony comes from `spec-seat` |
477
+ | `spec-build` | Igniting a build or fixit seat — manually or platform-spawned, after `spec-seat` | The BUILD JOB only: one spec, the role's reading list, the pin taxonomy, the suite protocol; `fixit` variant for no-spec defect sessions. Its ceremony comes from `spec-seat` |
478
478
  | `spec-witness` | A pipeline looks wedged, actors' claims conflict, or you want a substrate-verified state report | The read-only fourth seat: the control plane's read lanes, transcripts, git; zero writes, zero rulings — the seats act, the human judges, the witness testifies |
479
- | `spec-ignite` | Right after `spec-pipeline` when the pipeline runs HOSTED (vs `spec-parent` for hand-cranked) | The ignition copilot: verify the committed brief, derive the stage card (the human clicks Create), "kick it", a hosted coordinator runs the pipeline; two verbal gates, everything announced, every UI gap a named finding |
479
+ | `spec-ignite` | Right after `spec-pipeline` when the pipeline runs HOSTED (vs `spec-coordinator` for hand-cranked) | The ignition copilot: verify the committed brief, derive the stage card (the human clicks Create), "kick it", a hosted coordinator runs the pipeline; two verbal gates, everything announced, every UI gap a named finding |
480
480
  | `spec-review` | A pipeline's builds are done and it has a review row | The outside look, before the retro and before the PR: code + patterns + composition across session seams + the loop's own comms, in two independent passes. Files `sessions/code-review.md` and classifies which findings earn a fixit. **Its value is having none of the pipeline's context** |
481
- | `spec-retro` | The parent's LAST act, after any review and any fixit | The inside look: a substrate-verified grade, the ceremony audit (did the acts the seat believes it performed actually write rows?), the ledger reconciliation, the true economics, the blindnesses, and the ranked fixit backlog |
481
+ | `spec-retro` | The coordinator's LAST act, after any review and any fixit | The inside look: a substrate-verified grade, the ceremony audit (did the acts the seat believes it performed actually write rows?), the ledger reconciliation, the true economics, the blindnesses, and the ranked fixit backlog |
482
482
  | `docs-status` | Session start | Report what's recently archived, what's in `working/`, what's in `research/`; sweep the meta-comments for the condensed status table |
483
483
  | `docs-write` | End of a session | Finalize the working doc; it stays in `working/` (records its `## Archive` target) |
484
484
  | `docs-process` | Start of a session, `working/` has docs | Patch living docs from the working doc's checklist (verified vs code), then file the doc into `archive/` |
@@ -1,11 +1,11 @@
1
- <!-- naswerks-loop: version=0.5.1 -->
1
+ <!-- naswerks-loop: version=0.6.0 -->
2
2
  # The Engineering Loop — flow, seats, skills, and the ceremony
3
3
 
4
4
  > The quick intro to how work gets built with this loop: the two loops (`docs-*` knowledge, `spec-*`
5
5
  > execution), the seats (Human / Coordinator / Seat, plus the read-only Witness), the ceremony per
6
6
  > session, and a bare-bones exchange showing the back-and-forth. Point newcomers at this plus
7
7
  > [doc-index](doc-index.md) + [docs-workflow](docs-workflow.md). Operational templates live in the
8
- > `spec-parent` skill; the seat contract in `spec-seat`.
8
+ > `spec-coordinator` skill; the seat contract in `spec-seat`.
9
9
  <!-- meta: type=guide; status=current; verified={date}; lineage=1 -->
10
10
 
11
11
  ---
@@ -38,7 +38,7 @@ Plan graduates -> spec-pipeline -> docs/research/{topic}/: umbr
38
38
  per session + project-status.md (the plan is
39
39
  now throwaway — the specs carry every crumb)
40
40
  Same session — CHOOSE THE SEAT:
41
- hand-cranked -> spec-parent -> this session becomes the COORDINATOR and cuts
41
+ hand-cranked -> spec-coordinator -> this session becomes the COORDINATOR and cuts
42
42
  Prompt #1 (you relay every message)
43
43
  hosted -> spec-ignite -> this session becomes the IGNITION COPILOT:
44
44
  verify the brief, derive the stage card, YOU
@@ -108,13 +108,13 @@ What a commit and a PR pass here, beyond the loop. These add to the Hard rules b
108
108
  just *plan, build, `docs-write`, `docs-process`* — no pipeline, no coordinator, a flat working
109
109
  doc. This is the default and it never requires a control plane.
110
110
  - **`spec-*` is the execution loop** for work that is more than one session: `spec-pipeline`
111
- graduates the plan, `spec-parent` takes the seat, build seats build one spec each. **Each spec is sized
111
+ graduates the plan, `spec-coordinator` takes the seat, build seats build one spec each. **Each spec is sized
112
112
  for ONE session** — recon, plan, build, suite and FINAL TLDR before the session's context compacts —
113
113
  and the spec count falls out of that: a pipeline of two specs is a pipeline, and so is one of ten. It
114
114
  hands off to the knowledge loop at both ends (research docs in, working docs out).
115
115
  - **Either loop runs by hand or hosted.** The manual version is this document's ceremony with the human
116
116
  relaying; the hosted version is the control plane running the same ceremony, machine-relayed. When they
117
- drift, this doc + the `spec-parent` skill are the requirements; the control plane follows.
117
+ drift, this doc + the `spec-coordinator` skill are the requirements; the control plane follows.
118
118
 
119
119
  ## The seats
120
120
 
@@ -126,7 +126,7 @@ What a commit and a PR pass here, beyond the loop. These add to the Hard rules b
126
126
  | **Witness** *(optional, `spec-witness`)* | a read-only session with substrate access | testifies from rows/transcripts/git when claims conflict or a pipeline looks wedged; answers "whose turn is it" | writes anything; injects anything; rules on anything |
127
127
 
128
128
  The seat, not the chat, is the product: `project-status.md` must stay current enough that a
129
- fresh session can resume as coordinator losslessly (`spec-parent {topic}`).
129
+ fresh session can resume as coordinator losslessly (`spec-coordinator {topic}`).
130
130
 
131
131
  ## The skills
132
132
 
@@ -138,10 +138,10 @@ fresh session can resume as coordinator losslessly (`spec-parent {topic}`).
138
138
  | `docs-process` | docs | effort done, fresh session | patch living docs (verified vs code), archive |
139
139
  | `docs-audit-feature` / `docs-audit-full` | docs | doc suspected stale / monthly | deep-audit docs against code |
140
140
  | `spec-pipeline` | spec | a plan came through and you're committing to it | explode the plan into a numbered spec pipeline — *spare no crumb* |
141
- | `spec-parent` | spec | right after `spec-pipeline` (same session) or fresh with the topic | assume the coordinator seat |
142
- | `spec-seat` | spec | **every** seat the coordinator arms, invoked FIRST | **the CONTRACT, not a seat** — the shared half of every seat's procedure. `spec-parent` does NOT compose it: the coordinator writes rulings rather than receiving them |
143
- | `spec-child` | spec | igniting a build or fixit seat — manual (`spec-child {role} {spec}`) or hosted | **the BUILD JOB only** — one spec, the role's adds, the pin taxonomy, the suite protocol, the fixit variant. Its ceremony comes from `spec-seat` |
144
- | `spec-ignite` | spec | when an authored pipeline runs HOSTED (the `spec-parent` alternative) | the ignition copilot, and it can run COLD: gates, re-verify the brief's baselines + platform state against live HEAD, derive the stage card (human clicks Create), "kick it" with the brief's own kick text as the task; every UI gap a named finding |
141
+ | `spec-coordinator` | spec | right after `spec-pipeline` (same session) or fresh with the topic | assume the coordinator seat |
142
+ | `spec-seat` | spec | **every** seat the coordinator arms, invoked FIRST | **the CONTRACT, not a seat** — the shared half of every seat's procedure. `spec-coordinator` does NOT compose it: the coordinator writes rulings rather than receiving them |
143
+ | `spec-build` | spec | igniting a build or fixit seat — manual (`spec-build {role} {spec}`) or hosted | **the BUILD JOB only** — one spec, the role's adds, the pin taxonomy, the suite protocol, the fixit variant. Its ceremony comes from `spec-seat` |
144
+ | `spec-ignite` | spec | when an authored pipeline runs HOSTED (the `spec-coordinator` alternative) | the ignition copilot, and it can run COLD: gates, re-verify the brief's baselines + platform state against live HEAD, derive the stage card (human clicks Create), "kick it" with the brief's own kick text as the task; every UI gap a named finding |
145
145
  | `spec-review` | spec | a pipeline's builds are done, if it has a review row | the OUTSIDE look, before the retro and before the PR: correctness/security/**composition across session seams** · the patterns, with every departure identified · the loop's own comms. Two independent passes, consolidated. Classifies which findings earn a fixit; **its value is having none of the pipeline's context** |
146
146
  | `spec-retro` | spec | the coordinator's LAST act, after any review and any fixit | the INSIDE look: a substrate-verified grade, the ceremony audit (did the acts write rows?), the ledger reconciliation, the true economics, the blindnesses, the ranked fixit backlog — *a retrospective that cannot indict its own author is marketing* |
147
147
  | `spec-witness` | spec | a pipeline looks wedged, or actors' claims conflict | the read-only fourth seat: substrate access, zero writes, zero rulings |
@@ -155,7 +155,7 @@ The thing that keeps prompts and skills from drifting apart:
155
155
  |---|---|---|
156
156
  | **POLICY** | the policy document § This repository's rails names — and, hosted, the un-skippable system-prompt suffix the control plane supplies at open | cannot be skipped, present on every turn |
157
157
  | **PROCEDURE — shared** | `spec-seat` | the contract for ANY seat the coordinator arms: blackboard, question lane, parked-call discriminator, verdicts, BELIEFS sha, git shapes, six-section FINAL TLDR, close-out order |
158
- | **PROCEDURE — per job** | `spec-child` · `spec-review` · `docs-process` | what THIS seat does. The job skill **refines** the seat contract and never contradicts it; a genuine conflict is a finding, not a fork |
158
+ | **PROCEDURE — per job** | `spec-build` · `spec-review` · `docs-process` | what THIS seat does. The job skill **refines** the seat contract and never contradicts it; a genuine conflict is a finding, not a fork |
159
159
  | **TASK** | the seed prompt + the pipeline's `00-ignition-brief.md` | per-run; dies with the run |
160
160
 
161
161
  A seed's first act is therefore to **invoke its skills** — `spec-seat`, then the job — not to restate them.
@@ -174,7 +174,7 @@ diff.
174
174
  ## The ceremony (one build session)
175
175
 
176
176
  1. **Coordinator cuts the seat prompt** from the PREVIOUS session's actual shipped shapes — never
177
- from the spec's guesses alone. (Template: `spec-parent` skill.)
177
+ from the spec's guesses alone. (Template: `spec-coordinator` skill.)
178
178
  2. **Seat recons, states its beliefs** (HEAD sha, dirty files, versions, baselines), then a
179
179
  **PLAN TLDR as plain text** — before any plan-approval presentation — with **questions as
180
180
  numbered options + an embedded recommendation, then STOP**. Never an interactive question tool.
@@ -208,7 +208,7 @@ COORDINATOR -> Prompt #N: docs preamble, ##PROMPT##, ONE spec + context docs + p
208
208
  + CEREMONY block
209
209
  SEAT -> PLAN TLDR (BELIEFS: head/dirty/versions/baselines · the plan, 5-10 lines ·
210
210
  QUESTIONS 1..n, options + recommendation), STOP
211
- COORDINATOR -> PARENT RESPONSE — PLAN {ACCEPTED / ACCEPTED-WITH-RIDERS / …} · rulings 1..n
211
+ COORDINATOR -> COORDINATOR RESPONSE — PLAN {ACCEPTED / ACCEPTED-WITH-RIDERS / …} · rulings 1..n
212
212
  (DECISION — why) · riders · "Go build."
213
213
  SEAT -> (builds free; mid-run question: numbered text, STOP; COORDINATOR ruling; resume)
214
214
  SEAT -> FINAL TLDR — (a) SHIPPED+VERIFICATION (b) VERBATIM RUNNER SUMMARIES (c) HONEST GAPS
@@ -225,7 +225,7 @@ The exchange above is not just chat — it is a pair of FILES per build session:
225
225
 
226
226
  - **`tldr.md` — the chat.** Append-only, two voices: the seat's PLAN TLDR + numbered
227
227
  questions, the coordinator's ruling appended beneath them, optional mid-build updates +
228
- `## PARENT NOTE`s, then the FINAL TLDR. Read top-to-bottom it IS the session's whole
228
+ `## COORDINATOR NOTE`s, then the FINAL TLDR. Read top-to-bottom it IS the session's whole
229
229
  conversation, greppable by anchor.
230
230
  - **`plan.md` — the document.** The full plan, posted once, corrected on pushback. PULL-only:
231
231
  the coordinator reads it on a `read-full-plan` verdict; it is never force-fed into a wake or chat.
@@ -237,11 +237,11 @@ with the effort:
237
237
 
238
238
  ```
239
239
  docs/research/{topic}/sessions/ <- per-session work in {spec-slug}/, effort-wide at the root
240
- {spec-slug}/plan.md each seat the full plan, posted once, corrected on pushback (PULL-only)
241
- {spec-slug}/tldr.md each seat the two-voice chat — seat turns AND coordinator rulings interleaved
242
- code-review.md the review the outside look, if the pipeline had a review row
243
- parent-retrospective.md the coord. the close-out audit (the inside look)
244
- witness-ledger-*.md a human the witness is zero-writes, so its ledger arrives by hand
240
+ {spec-slug}/plan.md each seat the full plan, posted once, corrected on pushback (PULL-only)
241
+ {spec-slug}/tldr.md each seat the two-voice chat — seat turns AND coordinator rulings interleaved
242
+ code-review.md the review the outside look, if the pipeline had a review row
243
+ coordinator-retrospective.md the coord. the close-out audit (the inside look)
244
+ witness-ledger-*.md a human the witness is zero-writes, so its ledger arrives by hand
245
245
  ```
246
246
 
247
247
  Two files per build session; questions ride the TLDR, and there are no status snapshots because the
@@ -264,39 +264,40 @@ though it can be fed.**
264
264
  **The coordinator's voice is NOT in the seat's file on the hosted plane.** A coordinator answers with
265
265
  `callout` (its sixth drive verb, machine-written, the only downward path), which persists on its own
266
266
  artifact lane and closes the question in the **acts ledger**. So **the file says whether a question was
267
- ASKED; the ledger says whether it was ANSWERED**, and a seat typing a parent-voice heading into its own
268
- TLDR closes nothing. `callout` **refuses when the charge has no live session** — a coordinator must
267
+ ASKED; the ledger says whether it was ANSWERED**, and a seat typing a coordinator-voice heading into its
268
+ own TLDR closes nothing. `callout` **refuses when the charge has no live session** — a coordinator must
269
269
  `seat_spawn` before it can rule — and reports **"RULING RECORDED, NOT DELIVERED"** in those words if the
270
270
  transport drops it.
271
271
 
272
- The parent-voice block (machinery-written hosted; the hand-cranked coordinator writes it — hand-cranked
273
- there is no rev counter, so the heading is `## PARENT RULING (plan — {verdict})`; the stable grep prefix
274
- `## PARENT RULING` is the contract in both modes):
272
+ The coordinator-voice block (machinery-written hosted; the hand-cranked coordinator writes it —
273
+ hand-cranked there is no rev counter, so the heading is `## COORDINATOR RULING (plan — {verdict})`; the
274
+ stable grep prefix `## COORDINATOR RULING` is the contract in both modes, and an older board's
275
+ `## PARENT RULING` is read as the same heading):
275
276
 
276
277
  ```
277
- ## PARENT RULING (plan rev N — {accept | accept-with-riders | blocking-precondition})
278
+ ## COORDINATOR RULING (plan rev N — {accept | accept-with-riders | blocking-precondition})
278
279
 
279
- PARENT RESPONSE — PLAN TLDR {VERDICT}. {one sentence naming the best thing in the plan}
280
+ COORDINATOR RESPONSE — PLAN TLDR {VERDICT}. {one sentence naming the best thing in the plan}
280
281
  Answers:
281
282
  1. {RULING IN CAPS} — {decision first, then the why}.
282
283
  ...
283
284
  Go build. Fold the riders in — no re-approval round-trip.
284
285
  ```
285
286
 
286
- Callouts and nudges append as `## PARENT NOTE` (actor-suffixed when known, e.g. `(operator)`).
287
+ Callouts and nudges append as `## COORDINATOR NOTE` (actor-suffixed when known, e.g. `(operator)`).
287
288
 
288
289
  **The seat's own two anchors:**
289
290
 
290
291
  ```
291
- ## [child·{slug} · run {id}] CLOSE-OUT RECEIPT <- after the push
292
- ## [child·{slug} · run {id}] HOLDING <- "I have pushed and I am waiting"
292
+ ## [seat·{slug} · run {id}] CLOSE-OUT RECEIPT <- after the push
293
+ ## [seat·{slug} · run {id}] HOLDING <- "I have pushed and I am waiting"
293
294
  ```
294
295
 
295
296
  **A question heading, a HOLDING and a close-out receipt are ALL non-staling** — the gates bind an
296
297
  acceptance to the accepted CONTENT, not to the revision number, so appending your own *state* leaves it
297
298
  intact. Only **new content** stales. A seat that has pushed and is waiting is otherwise indistinguishable
298
299
  from a seat that has done nothing, and a coordinator reading a wake led by its own acceptance concludes
299
- there is nothing to rule — the HOLDING anchor is what prevents that. The token is the literal `child·`
300
+ there is nothing to rule — the HOLDING anchor is what prevents that. The token is the literal `seat·`
300
301
  whatever seat you are — it is a protocol anchor, not a description of you.
301
302
 
302
303
  ### Questions ride the same blackboard
@@ -321,4 +322,4 @@ the credential: **a receipt the audited party can mint is not a receipt** — wh
321
322
  door takes the human's own token and never a seat's job ticket.
322
323
 
323
324
  ## Lineage
324
- - **Related** — [docs-workflow](docs-workflow.md) · [doc-index](doc-index.md) · the `spec-parent` and `spec-seat` skills (the operational templates and the seat contract)
325
+ - **Related** — [docs-workflow](docs-workflow.md) · [doc-index](doc-index.md) · the `spec-coordinator` and `spec-seat` skills (the operational templates and the seat contract)
@@ -45,7 +45,8 @@ branch, which is the truth for that PR, and you say so at close.
45
45
  the seat that does it.
46
46
 
47
47
  **If the effort was a spec pipeline, you have a SECOND input: `sessions/code-review.md`** — the review
48
- seat's outside look, filed beside `parent-retrospective.md`. Read both. **Every review finding gets a
48
+ seat's outside look, filed beside the coordinator's retrospective (`coordinator-retrospective.md`, or
49
+ `parent-retrospective.md` in an effort begun before that name). Read both. **Every review finding gets a
49
50
  disposition, and the disposition is TOTAL:** a living-doc patch here · an existing fixit seat · a
50
51
  chartered follow-up · a new spec pipeline · or killed on record with the reason. **A finding with no named
51
52
  home is dropped, not deferred** — and the review's own classification (fixit candidate / deferred /
@@ -250,5 +250,5 @@ write, offer — and ask before doing either — to fill each new absent-line fr
250
250
  - The floor four are always drafted, even in a repository with no frontend — the reading floor must
251
251
  RESOLVE for every seat kind, and "No frontend detected — fill this in" is an honest doc. The standard
252
252
  seven are drafted only on evidence; their absence is recorded, never papered over.
253
- - Counterpart skills: `spec-seat` (reads the floor), `spec-child` (reads the role rows), `spec-pipeline`
253
+ - Counterpart skills: `spec-seat` (reads the floor), `spec-build` (reads the role rows), `spec-pipeline`
254
254
  (writes the brief `doctor` checks), `docs-write` / `docs-process` (the queue `doctor` reads).
@@ -5,7 +5,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
5
5
  import { join, resolve, dirname } from 'node:path';
6
6
  import { fileURLToPath } from 'node:url';
7
7
  import { execFileSync } from 'node:child_process';
8
- import { OWNED, compareVersions, compareMinor, frontmatterListCount, linesOf, bare, h2Index, findSection, railsItems } from './owned.mjs';
8
+ import { OWNED, KINDS, KIND_SKILLS, NOT_SKILLS, skillTokens, compareVersions, compareMinor, frontmatterListCount, linesOf, bare, h2Index, findSection, railsItems } from './owned.mjs';
9
9
 
10
10
  const repo = resolve(process.argv[2] || process.cwd());
11
11
  const packRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
@@ -194,7 +194,9 @@ for (const name of ['CLAUDE.md', 'AGENTS.md']) {
194
194
  }
195
195
 
196
196
  // ── 7. every ignition brief, checked the way the control plane checks it ────────────────────────
197
- const KINDS = new Set(['coordinator', 'build', 'fixit', 'review', 'retro', 'witness', 'docs-process']);
197
+ // The kick is sent verbatim as the coordinator's task, so a skill it names that this pack does not carry
198
+ // (a renamed one, most often) tells the coordinator to invoke nothing.
199
+ const packSkills = new Set(existsSync(join(packRoot, 'skills')) ? readdirSync(join(packRoot, 'skills')) : []);
198
200
  const researchDir = join(repo, 'docs', 'research');
199
201
  if (existsSync(researchDir)) {
200
202
  for (const topic of readdirSync(researchDir)) {
@@ -205,6 +207,7 @@ if (existsSync(researchDir)) {
205
207
  const kick = sectionOf(text, '## The kick');
206
208
  if (kick === null) problems.push('the brief has no `## The kick` section, so the task text could not be read');
207
209
  else if (!kick.split('\n').some((l) => l.trimStart().startsWith('>'))) problems.push('the `## The kick` section carries no blockquote; its whole text stands in for the task');
210
+ const unknown = kick === null || packSkills.size === 0 ? [] : [...new Set(skillTokens(kick))].filter((t) => !packSkills.has(t) && !NOT_SKILLS.includes(t));
208
211
  const seq = sectionOf(text, '## The sequence');
209
212
  if (seq === null) problems.push('the brief has no `## The sequence` section, so no seats could be read');
210
213
  else {
@@ -213,13 +216,14 @@ if (existsSync(researchDir)) {
213
216
  for (const line of tableRows.slice(1)) {
214
217
  const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim().replace(/^`|`$/g, '').trim());
215
218
  if (cells.every((c) => /^[-: ]*$/.test(c))) continue;
216
- if (!cells.some((c) => KINDS.has(c))) { problems.push(`a sequence row names no seat kind and composes nothing: \`${line.trim()}\``); continue; }
219
+ if (!cells.some((c) => KINDS.includes(c))) { problems.push(`a sequence row names no seat kind and composes nothing: \`${line.trim()}\``); continue; }
217
220
  const spec = cells.map((c) => /\b(\d{2}-[A-Za-z0-9._-]*?\.md)\b/.exec(c)).find(Boolean);
218
221
  if (spec && !existsSync(join(researchDir, topic, spec[1]))) problems.push(`the sequence names \`${spec[1]}\` and it is missing from disk`);
219
222
  }
220
223
  }
221
- if (problems.length) for (const pr of problems) row('FAIL', `docs/research/${topic}/00-ignition-brief.md`, pr);
222
- else row('ok', `docs/research/${topic}/00-ignition-brief.md`, 'the kick and the sequence read clean');
224
+ for (const pr of problems) row('FAIL', `docs/research/${topic}/00-ignition-brief.md`, pr);
225
+ for (const t of unknown) row('DEGRADE', `docs/research/${topic}/00-ignition-brief.md`, `the kick names \`${t}\`, a skill this pack does not carry; the coordinator's skill is \`${KIND_SKILLS.coordinator}\``);
226
+ if (!problems.length && !unknown.length) row('ok', `docs/research/${topic}/00-ignition-brief.md`, 'the kick and the sequence read clean');
223
227
  }
224
228
  }
225
229
 
@@ -21,6 +21,32 @@ export const OWNED = [
21
21
 
22
22
  export const STAMP = /^(<!-- naswerks-loop: version=)([0-9]+\.[0-9]+\.[0-9]+[^ ]*)( -->)/;
23
23
 
24
+ // The seat kinds a pipeline row may name, checked the way the control plane checks a brief's sequence.
25
+ export const KINDS = ['coordinator', 'build', 'fixit', 'review', 'retro', 'witness', 'docs-process'];
26
+
27
+ // The skill each kind runs as its job. A spec seat's skill is named for its kind, so a skill's name says
28
+ // which seat runs it: `fixit` is the build job's no-spec variant, and `docs-process` is the knowledge
29
+ // loop's own skill, seated by a pipeline as its last row.
30
+ export const KIND_SKILLS = {
31
+ coordinator: 'spec-coordinator',
32
+ build: 'spec-build',
33
+ fixit: 'spec-build',
34
+ review: 'spec-review',
35
+ retro: 'spec-retro',
36
+ witness: 'spec-witness',
37
+ 'docs-process': 'docs-process',
38
+ };
39
+
40
+ // Words shaped like a skill name that name no skill: the method doc, the placeholders, and the compounds
41
+ // the prose uses. Every other spec-* or docs-* word the pack writes is a skill it carries.
42
+ export const NOT_SKILLS = ['docs-workflow', 'spec-slug', 'spec-path', 'spec-doc', 'spec-driven', 'docs-only'];
43
+
44
+ // Every skill-shaped word in a text. A word followed by `*` or `-*` names a family (docs-*, docs-audit-*),
45
+ // never one skill.
46
+ export function skillTokens(text) {
47
+ return [...text.matchAll(/\b(?:spec|docs)-[a-z]+(?:-[a-z]+)*\b(?![-*])/g)].map((m) => m[0]);
48
+ }
49
+
24
50
  export function compareVersions(a, b) {
25
51
  const pa = a.split(/[.-]/).map((x) => parseInt(x, 10) || 0), pb = b.split(/[.-]/).map((x) => parseInt(x, 10) || 0);
26
52
  for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); }
@@ -1,9 +1,9 @@
1
1
  ---
2
- name: spec-child
3
- description: The BUILD JOB for a pipeline seat — one spec, the role's reading list, the pin taxonomy, the suite protocol, and the fixit variant. Composed AFTER spec-seat, which carries the seat contract (blackboard, question lane, verdicts, FINAL TLDR, close-out). Use when a prompt says you are a build or fixit session, or run spec-child {role} {spec-path}. Roles: backend | frontend | mixed.
2
+ name: spec-build
3
+ description: The BUILD JOB for a pipeline seat — one spec, the role's reading list, the pin taxonomy, the suite protocol, and the fixit variant. Composed AFTER spec-seat, which carries the seat contract (blackboard, question lane, verdicts, FINAL TLDR, close-out). Use when a prompt says you are a build or fixit session, or run spec-build {role} {spec-path}. Roles: backend | frontend | mixed.
4
4
  ---
5
5
 
6
- # spec-child
6
+ # spec-build
7
7
 
8
8
  **Your seat contract is `spec-seat` — invoke it first if you have not.** It carries the blackboard, the
9
9
  question lane, the parked-call discriminator, the verdict vocabulary, the BELIEFS sha, git shapes, the
@@ -14,7 +14,7 @@ You build exactly one spec. The coordinator judges and rules; you recon, plan, b
14
14
  Hand-cranked, a human relays messages; hosted inside a pipeline, your coordinator drives you itself and
15
15
  the relay is machine-carried — **your contract is identical either way.**
16
16
 
17
- Invoked as `spec-child {role} {spec-path}`, or told "you are a build session" with the spec path.
17
+ Invoked as `spec-build {role} {spec-path}`, or told "you are a build session" with the spec path.
18
18
 
19
19
  ## Step 1 — with your role and spec in hand
20
20
 
@@ -130,7 +130,7 @@ build over a tree they had not touched, and they got a **passing receipt that pr
130
130
  false-green genus, embedded in the manual instead of in a test. Name the app you edited and run its
131
131
  commands from its root.
132
132
 
133
- ## Fix-it variant (`spec-child fixit`)
133
+ ## Fix-it variant (`spec-build fixit`)
134
134
 
135
135
  No spec — your contract is the prompt + the coordinator's ledger (READ-ONLY). **STEP 0 — INVESTIGATE,
136
136
  REPORT, STOP:** (1) reproduce/characterize cheaply, (2) find the cheapest reliable RECEIPT for the fixed
@@ -152,6 +152,6 @@ what a truthful partial looks like per named item, **ask for it** before you sta
152
152
  - **The spec's anchors are hypotheses; HEAD is the truth.** The biggest catches — stale trees, false
153
153
  greens, dropped rulings — are all belief-vs-ledger mismatches. Your beliefs block exists so the
154
154
  coordinator can catch them cheaply.
155
- - Counterpart skills: `spec-seat` (your contract) · `spec-parent` (the seat that arms you) ·
155
+ - Counterpart skills: `spec-seat` (your contract) · `spec-coordinator` (the seat that arms you) ·
156
156
  `spec-pipeline` (how your spec came to exist). The hosted version of you runs THIS same pair — the
157
157
  control plane's seed names both skills, in this order.
@@ -1,12 +1,12 @@
1
1
  ---
2
- name: spec-parent
3
- description: Assume the COORDINATOR seat for a spec-pipeline effort — quarterback the build seats (one per spec) via prompts, TLDR reviews, verification, and commit calls. Use immediately after spec-pipeline in the same session (the author is already context-loaded), or in a fresh session with the topic name to resume/take a prepped effort. Run spec-parent {topic}.
2
+ name: spec-coordinator
3
+ description: Assume the COORDINATOR seat for a spec-pipeline effort — quarterback the build seats (one per spec) via prompts, TLDR reviews, verification, and commit calls. Use immediately after spec-pipeline in the same session (the author is already context-loaded), or in a fresh session with the topic name to resume/take a prepped effort. Run spec-coordinator {topic}.
4
4
  ---
5
5
 
6
- # spec-parent
6
+ # spec-coordinator
7
7
 
8
8
  Turn this session into the **coordinator** for a `docs/research/{topic}/` spec pipeline. This is
9
- phase 3 of the backlog model (`docs-backlog`, `spec-pipeline`, **`spec-parent`**, seats build,
9
+ phase 3 of the backlog model (`docs-backlog`, `spec-pipeline`, **`spec-coordinator`**, seats build,
10
10
  `docs-process`).
11
11
 
12
12
  **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.
@@ -117,7 +117,7 @@ read the board and answer on first receipt rather than spending a round-trip.
117
117
  corrected.
118
118
 
119
119
  **Pick the docs:** the floor and the loop's standard docs are settled (`spec-seat`'s Step 0 +
120
- `spec-child`'s role table). **This repository's own docs are yours to seed, by path, every time:** copy
120
+ `spec-build`'s role table). **This repository's own docs are yours to seed, by path, every time:** copy
121
121
  the seat's role rows from `docs/_meta/doc-index.md` § Role reading lists into the prompt's `EXTRA DOCS`
122
122
  line — a seat follows a path in its prompt and does not reliably follow an index. Then add the extras
123
123
  the task itself warrants. When in doubt, seed the doc: a seat reading one extra doc is cheaper than a
@@ -420,10 +420,12 @@ so read them as run-time obligations, not close-out ones:
420
420
  wait or to reshape the command — not to complete a run or curl past the fence. **And a park that sails
421
421
  through anyway is DATA:** record it immediately as an incident, because a fence that failed silently once
422
422
  will fail silently again, and your record is the only trace.
423
- - **`parallel:true` is for specs that share no files — that is its whole purpose.** A refused spawn means
424
- the previous seat is still holding the shared effort worktree and needs reaping; the answer is to reap
425
- it, or to wait if it has not closed out yet. Reaching for `parallel` there is a category error rather
426
- than a shortcut: it does not free the worktree, it just puts two seats in it.
423
+ - **A shared worktree holds one live seat at a time, and nothing but you enforces it.** `seat_spawn`
424
+ refuses a terminal seat, a seat that already has a live session and a runner it cannot reach — it does
425
+ NOT refuse a second seat while another is still live in the shared tree, so spawning early puts two
426
+ seats in one worktree. Reap the previous seat first, or wait if it has not closed out yet. Parallel
427
+ seats need separate worktrees, which is the pipeline's shape, decided at create — and only for specs
428
+ that share no files.
427
429
 
428
430
  ## The steering channel — shape your callouts by SOLICITATION
429
431
 
@@ -442,10 +444,10 @@ send context attached to a ruling instead.
442
444
 
443
445
  ## The seat prompt template
444
446
 
445
- The ceremony rides the **`spec-child` skill** — the prompt is an IGNITER, not a ceremony restatement.
447
+ The ceremony rides the **`spec-build` skill** — the prompt is an IGNITER, not a ceremony restatement.
446
448
 
447
449
  ```
448
- You are a BUILD SEAT in a coordinator-run effort: invoke the spec-child skill with
450
+ You are a BUILD SEAT in a coordinator-run effort: invoke the spec-build skill with
449
451
  role={backend | frontend | mixed} before anything else, and ALWAYS after `spec-seat`: the seat header
450
452
  names `spec-seat` first, the job skill second.
451
453
 
@@ -473,7 +475,7 @@ THE TASK: {compressed spec restatement with the load-bearing specifics inline.}
473
475
 
474
476
  For investigation-first work, add **STEP 0 — INVESTIGATE, REPORT, STOP** before the task, or use
475
477
  `role={...} fixit` for no-spec defect sessions (the skill carries the fix-it ceremony). Fallback: if the
476
- seat can't invoke skills, paste the ceremony from the `spec-child` skill inline.
478
+ seat can't invoke skills, paste the ceremony from the `spec-build` skill inline.
477
479
 
478
480
  ### The bookend rows (R and P) get a MANIFEST instead of prior shapes
479
481
 
@@ -514,7 +516,7 @@ P it is the difference between archiving this effort and sweeping somebody else'
514
516
  ## Ruling template (plan review / question answers)
515
517
 
516
518
  ```
517
- PARENT RESPONSE — PLAN TLDR {ACCEPTED / ACCEPTED WITH RIDERS / BLOCKING-PRECONDITION}.
519
+ COORDINATOR RESPONSE — PLAN TLDR {ACCEPTED / ACCEPTED WITH RIDERS / BLOCKING-PRECONDITION}.
518
520
  {Verdict vocabulary: accept · accept-with-riders (numbered rulings anchored to the SEAT'S OWN item
519
521
  numbers — it folds them in and GOES, no re-approval round-trip; the dominant verdict) ·
520
522
  blocking-precondition ("accept, but step 0 first") · read-full-plan (not a verdict you send — you
@@ -543,14 +545,17 @@ asking for a paste (`read-full-plan` = read `plan.md`, a pull, never force-fed).
543
545
  verbs ARE the appends and the machinery writes them for you.
544
546
 
545
547
  **Anchor grammar (canonical — the witness greps these):** rulings land under
546
- `## PARENT RULING (plan — {verdict})` hand-cranked, `## PARENT RULING (plan rev N — {verdict})` when the
547
- rev ladder exists; notes under `## PARENT NOTE ({context})`. The parent-voice vocabulary is a CLOSED list
548
- of four — `PARENT NOTE` · `PARENT ACCEPT` · `PARENT RULING` · `OPERATOR RULING` — so a fifth anchor you
549
- invent counts as nothing. **Never vary the prefixes**, and **never discuss the anchor grammar inside a
550
- steering note**: the detector matches the STRING, not your intent, and naming an anchor while explaining
551
- it derives a spurious acceptance receipt. Refer to it obliquely ("the acceptance anchor").
552
- **Point, don't paste:** steer with *"read your `tldr.md` under `## PARENT RULING`"*, never by re-pasting a
553
- multi-KB block into a composer.
548
+ `## COORDINATOR RULING (plan — {verdict})` hand-cranked, `## COORDINATOR RULING (plan rev N — {verdict})`
549
+ when the rev ladder exists; notes under `## COORDINATOR NOTE ({context})`. The coordinator-voice
550
+ vocabulary is a CLOSED list of four — `COORDINATOR NOTE` · `COORDINATOR ACCEPT` · `COORDINATOR RULING` ·
551
+ `OPERATOR RULING` — so a fifth anchor you invent counts as nothing. An older board spells the first three
552
+ `PARENT NOTE` · `PARENT ACCEPT` · `PARENT RULING`; every reader of the anchors, each grep in this loop
553
+ included, takes that spelling as the same three, and you write only the new one. **Never vary the prefixes**, and **never
554
+ discuss the anchor grammar inside a steering note**: the detector matches the STRING, not your intent,
555
+ and naming an anchor while explaining it derives a spurious acceptance receipt. Refer to it obliquely
556
+ ("the acceptance anchor").
557
+ **Point, don't paste:** steer with *"read your `tldr.md` under `## COORDINATOR RULING`"*, never by
558
+ re-pasting a multi-KB block into a composer.
554
559
 
555
560
  **When to read (hand-cranked):** the human's nudge is your wake signal, and the human is the ONLY bus — so
556
561
  before cutting each next prompt, sweep `sessions/*/tldr.md` mtimes for appends you were never nudged
@@ -564,7 +569,7 @@ plan-approval click is the human's counterpart of the product's accept-gate —
564
569
  ## Docs-write + commit call template
565
570
 
566
571
  ```
567
- PARENT RESPONSE — FINAL TLDR ACCEPTED {(+ what I verified myself)}.
572
+ COORDINATOR RESPONSE — FINAL TLDR ACCEPTED {(+ what I verified myself)}.
568
573
  1. Run docs-write. Carry: {departures, honest gaps, deferred findings verbatim, gotchas}.
569
574
  2. COMMIT CALL — approved. Stage explicitly (never git add -A): YOUR diff + working doc,
570
575
  PLUS docs/research/{topic}/project-status.md — my ledger rides your commit,
@@ -583,7 +588,7 @@ PARENT RESPONSE — FINAL TLDR ACCEPTED {(+ what I verified myself)}.
583
588
  ```
584
589
 
585
590
  **THE ACCEPTANCE IS A RECEIPT VERB, AND PROSE IS NOT A RECEIPT.** Send the acceptance act carrying your
586
- text; it lands in the seat's `tldr.md` under `## PARENT ACCEPT (final — {slice})` and the rev-bound
591
+ text; it lands in the seat's `tldr.md` under `## COORDINATOR ACCEPT (final — {slice})` and the rev-bound
587
592
  receipt derives from it. **An acceptance delivered as a steering note records zero rows** — and the push
588
593
  bar reads the row, not the paragraph.
589
594
 
@@ -591,10 +596,10 @@ bar reads the row, not the paragraph.
591
596
  (the receipt binds pre-commit), then the seat commits and pushes. **The receipt is rev-bound:** it covers
592
597
  the tldr rev + HEAD it was written against — if the seat re-posts its TLDR CONTENT after your acceptance,
593
598
  the unattended push parks naming both revs, and one **argless re-accept** is the cheap repair, **sent with
594
- the retry order in the same act**. A seat's post-push `## [child·…] CLOSE-OUT RECEIPT` append does NOT
599
+ the retry order in the same act**. A seat's post-push `## [seat·…] CLOSE-OUT RECEIPT` append does NOT
595
600
  stale your acceptance — reap without a re-accept after it.
596
601
 
597
- **Hand-cranked:** append the same `## PARENT ACCEPT (final — {slice})` heading to the seat's
602
+ **Hand-cranked:** append the same `## COORDINATOR ACCEPT (final — {slice})` heading to the seat's
598
603
  `sessions/{slug}/tldr.md` yourself — there is no machinery and no derivation; the anchor + your tracker
599
604
  row ARE the receipts.
600
605
 
@@ -617,7 +622,7 @@ post-merge.
617
622
  corrections, what you verified yourself, mid-build directives, and anything you don't want to forget —
618
623
  written when it happens, never reconstructed at close. **The tracker's own section notes say what each
619
624
  section holds**; follow them rather than inventing structure. Do **not** add a `## Checkpoint ledger` or
620
- a `## Parent decisions` section — the session entry *is* the decision record, and a parallel section
625
+ a `## Coordinator decisions` section — the session entry *is* the decision record, and a parallel section
621
626
  splits one narrative across two places.
622
627
  - **If a retro has to supersede your session rows, the ledger was not kept.** A retro confirms the rows
623
628
  and adds the audit and economics; it never corrects facts that should already be written.
@@ -644,7 +649,7 @@ post-merge.
644
649
  a sequence, and do not treat a stale living doc as something this effort must fix.
645
650
  - Periodically remind the human to sweep your doc edits into a small `docs` commit.
646
651
  - Counterpart skills: `spec-seat` (the contract of every seat you arm — read it to know what they were
647
- told) · `spec-child` (the builders' job skill) · `spec-pipeline` (how the specs came to exist) ·
652
+ told) · `spec-build` (the builders' job skill) · `spec-pipeline` (how the specs came to exist) ·
648
653
  `spec-review` (the outside look, before your retro) · `spec-retro` (your close-out audit) ·
649
654
  `spec-witness` (the read-only verifier) · `spec-ignite` (the ignition copilot that puts an authored
650
655
  effort onto the plane).
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-ignite
3
- description: Become the IGNITION COPILOT for a spec pipeline — verify the committed ignition brief against live state, verify every step by receipt, and kick on the human's word. Authoring belongs to spec-pipeline; this seat VERIFIES, so it can run cold. Use right after spec-pipeline when the pipeline will run hosted (the manual alternative is spec-parent), or fresh with a topic whose specs are already authored. Two verbal gates: nothing moves before "stage it"; nothing spawns before "kick it".
3
+ description: Become the IGNITION COPILOT for a spec pipeline — verify the committed ignition brief against live state, verify every step by receipt, and kick on the human's word. Authoring belongs to spec-pipeline; this seat VERIFIES, so it can run cold. Use right after spec-pipeline when the pipeline will run hosted (the manual alternative is spec-coordinator), or fresh with a topic whose specs are already authored. Two verbal gates: nothing moves before "stage it"; nothing spawns before "kick it".
4
4
  ---
5
5
 
6
6
  # spec-ignite
@@ -119,10 +119,10 @@ injects** — the human keyboard and the hardened ladders are the only submit pa
119
119
 
120
120
  The coordinator's task is the brief's own **`## The kick`** section, copied verbatim. Roughly:
121
121
 
122
- > You are the COORDINATOR of the {topic} pipeline. Invoke the `spec-parent` skill, then read
122
+ > You are the COORDINATOR of the {topic} pipeline. Invoke the `spec-coordinator` skill, then read
123
123
  > `docs/research/{topic}/00-ignition-brief.md` and follow it. Your branch is `{the effort's branch}`.
124
124
 
125
- **Do not draft a constitution here.** The seat's PROCEDURE is the `spec-parent` skill; its POLICY rides the
125
+ **Do not draft a constitution here.** The seat's PROCEDURE is the `spec-coordinator` skill; its POLICY rides the
126
126
  un-skippable policy suffix the control plane supplies at open (you do not paste it, and you cannot
127
127
  override it); its HANDS are the coordinator charter the control plane attaches to a `coordinator` seed
128
128
  and to no other kind. This RUN's choreography is the committed brief. A task string cannot be diffed or
@@ -271,7 +271,7 @@ you found rather than working around it.
271
271
  anomalies that may change it — surprises are findings, not adjustments.
272
272
 
273
273
  ## Related
274
- - `spec-pipeline` (authors what you ignite, including the brief you verify) · `spec-parent` (the
275
- coordinator's procedure, and the HAND-CRANKED alternative) · `spec-seat` + `spec-child` (what the
274
+ - `spec-pipeline` (authors what you ignite, including the brief you verify) · `spec-coordinator` (the
275
+ coordinator's procedure, and the HAND-CRANKED alternative) · `spec-seat` + `spec-build` (what the
276
276
  control plane seeds into every build seat) · `spec-retro` (the close-out audit) · `spec-witness`
277
277
  (point one at the run you just ignited)
@@ -59,14 +59,14 @@ sessions/ WHO PUTS IT THERE
59
59
  questions with the coordinator's rulings appended beneath them. Read
60
60
  top-to-bottom it IS the session's whole conversation, in message order
61
61
  code-review.md the review seat, in its own commit, if the run has a review row
62
- parent-retrospective.md the coordinator, at the close
62
+ coordinator-retrospective.md the coordinator, at the close
63
63
  witness-ledger-*.md a human commit — the witness is zero-writes by contract (its ticket
64
64
  cannot even carry the write scope), so its testimony reaches the repo
65
65
  by someone else's hand
66
66
  ```
67
67
 
68
68
  - **Per-seat artifacts go in a `{spec-slug}/` subfolder; effort-wide artifacts sit at the `sessions/`
69
- root.** The first seat creates its subfolder and, incidentally, the parent folder; everything after
69
+ root.** The first seat creates its subfolder and, incidentally, `sessions/` itself; everything after
70
70
  writes into what exists.
71
71
  - **RE-COPY BOTH FILES ONCE, IMMEDIATELY BEFORE THE FINAL PUSH.** A seat's close-out receipt is written
72
72
  AFTER the commit that carries its testimony, so a single copy always lands truncated — and a follow-up
@@ -78,7 +78,7 @@ sessions/ WHO PUTS IT THERE
78
78
  separate questions file, and there are no status snapshots: the tracker is committed live, so its git
79
79
  history already carries the progression a snapshot would fake.
80
80
  - **Append-only.** `tldr.md` grows; nobody rewrites it. The rev ladder is the history.
81
- - **Who READS it:** the coordinator reads each TLDR and appends its rulings under `## PARENT RULING` · the
81
+ - **Who READS it:** the coordinator reads each TLDR and appends its rulings under `## COORDINATOR RULING` · the
82
82
  review seat reads every session's TLDR as testimony **and reads nothing else** · the retro greps it for
83
83
  acceptance anchors and unanswered questions · the witness uses rev counts and mtimes as a zero-cost
84
84
  heartbeat.
@@ -214,7 +214,7 @@ sessions/ WHO PUTS IT THERE
214
214
  5. **Name the archive destination when only you can.** Read `docs/_meta/docs-workflow.md` § The archive
215
215
  convention (repository-owned). If where a pipeline files depends on something only this session knows
216
216
  (which living feature the effort belongs to, say), resolve it now and write the path into the
217
- umbrella's blockquote as an `Archive:` line; `spec-parent` hands it to the docs-process row and
217
+ umbrella's blockquote as an `Archive:` line; `spec-coordinator` hands it to the docs-process row and
218
218
  `docs-process` files there. A convention that needs nothing from you needs no line.
219
219
 
220
220
  6. **Stop.** The specs stay in `research/{topic}/`. Do NOT implement, do NOT touch living docs, do NOT
@@ -320,7 +320,7 @@ cross-reading them; a human row recorded only by the coordinator has ONE, and th
320
320
  one whose errors nobody else catches.
321
321
 
322
322
  ## The kick — paste this verbatim as the coordinator's task
323
- > You are the COORDINATOR of the {topic} pipeline. Invoke the `spec-parent` skill, then read
323
+ > You are the COORDINATOR of the {topic} pipeline. Invoke the `spec-coordinator` skill, then read
324
324
  > `docs/research/{topic}/00-ignition-brief.md` and follow it. Your branch is `{the effort's branch}`.
325
325
 
326
326
  Deltas true of THIS kick only (a concurrent pipeline, a model override, a one-off probe) go here as a
@@ -328,7 +328,7 @@ short list. Everything else is already in this brief — the task string is a PO
328
328
  stays short because a task buried in a run row cannot be diffed or reviewed the way this file can.
329
329
  ```
330
330
 
331
- **Do not restate the ceremony here.** The coordinator's procedure lives in `spec-parent` and its policy
331
+ **Do not restate the ceremony here.** The coordinator's procedure lives in `spec-coordinator` and its policy
332
332
  is the one § This repository's rails (repository-owned) names, which a hosted run also carries in the
333
333
  un-skippable policy suffix the control plane supplies; a brief that re-teaches them accretes
334
334
  into prompt-law that breaks the coordinator it was meant to steer. The brief carries THIS RUN's
@@ -410,7 +410,7 @@ viewer because they are instructions to the coordinator, not content for the hum
410
410
  |---|---|---|---|
411
411
  ```
412
412
 
413
- **Never generate a `## Checkpoint ledger` or a `## Parent decisions` section.** The session section
413
+ **Never generate a `## Checkpoint ledger` or a `## Coordinator decisions` section.** The session section
414
414
  *is* the decision record; a parallel section splits one narrative across two places.
415
415
 
416
416
  ## `live-checks.md`
@@ -13,8 +13,8 @@ today that perspective evaporates the moment the run closes. This skill turns it
13
13
  **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.
14
14
 
15
15
  Run it as the **last act of the coordinator seat**, after the final session's close-out commit — before or
16
- after the PR is cut, either works. Output: `docs/research/{topic}/sessions/parent-retrospective.md`. It is
17
- a scoped write on the pipeline's branch, so it rides the PR to the base branch either way.
16
+ after the PR is cut, either works. Output: `docs/research/{topic}/sessions/coordinator-retrospective.md`.
17
+ It is a scoped write on the pipeline's branch, so it rides the PR to the base branch either way.
18
18
 
19
19
  **You are one of the three kinds that do NOT compose `spec-seat`** — this skill is your whole contract,
20
20
  and the control plane's seed says so rather than merely omitting it.
@@ -54,7 +54,7 @@ document** — a number whose lane you cannot name is testimony, not an audit.
54
54
 
55
55
  **If the argless sweep is not runnable at your run's scale, that is a day-one escalation, not a
56
56
  close-out discovery.** A few thousand rows can exceed the lane's page budget; you cannot retroactively
57
- obtain the audit your own doctrine mandates. `spec-parent` carries this as a run-time obligation.
57
+ obtain the audit your own doctrine mandates. `spec-coordinator` carries this as a run-time obligation.
58
58
 
59
59
  **Two instruments that share no code are the only way a ceremony audit means anything** — on one
60
60
  instrument you are grading your own homework with your own pencil. Where the control plane offers a
@@ -148,11 +148,13 @@ could not tell. And do not flatten predicates that were measured apart: a conten
148
148
  stales a PUSH; a close-out-receipt append does not stale a REAP. Report what you observe; never
149
149
  generalise one park into a law.
150
150
 
151
- **The derived-row path:** the acceptance's durable record is the `## PARENT ACCEPT (final — {slice})`
152
- anchor in each seat's `tldr.md`, and the receipt DERIVES from it. Reconcile file against substrate:
151
+ **The derived-row path:** the acceptance's durable record is the `## COORDINATOR ACCEPT (final —
152
+ {slice})` anchor in each seat's `tldr.md`, and the receipt DERIVES from it. A board written before this
153
+ vocabulary spells it `## PARENT ACCEPT`; a reader of the anchors takes both spellings, so the grep does too. Reconcile
154
+ file against substrate:
153
155
 
154
156
  ```bash
155
- rg -n "## PARENT ACCEPT" docs/research/{topic}/sessions/*/tldr.md
157
+ rg -n "## (COORDINATOR|PARENT) ACCEPT" docs/research/{topic}/sessions/*/tldr.md
156
158
  ```
157
159
 
158
160
  **AUDIT THE QUESTION LANE THE SAME WAY — it is a heading grep, not a row query.** A seat asks by appending
@@ -163,8 +165,8 @@ run whose seats asked repeatedly and changed a ruling by it.
163
165
  **AND ON THE HOSTED PLANE THE FILE IS NOT THE CLOSE PREDICATE — audit BOTH halves, because they answer
164
166
  different questions.** *Was one asked?* is a fact about the file (the heading grep below, mirroring the
165
167
  control plane's grammar). *Was it answered?* is a fact about the LEDGER — the ruling act carrying the
166
- asking post's id — and it is deliberately not read from the file, because a seat can type a parent-voice
167
- heading into its own blackboard. **A retro that audits only the file can be shown a question that
168
+ asking post's id — and it is deliberately not read from the file, because a seat can type a
169
+ coordinator-voice heading into its own blackboard. **A retro that audits only the file can be shown a question that
168
170
  answered itself.** Reconcile the grep's hits against the ruling acts, and report any hit with no act as an
169
171
  unanswered question whatever the file says.
170
172
 
@@ -177,11 +179,12 @@ prefixed and plural headings, and the lane has TWO headings: `## QUESTIONS` (rec
177
179
  rg -niE '^##[[:space:]]*(\[[^]]*\][[:space:]]*)?(MID-BUILD[[:space:]]+)?QUESTIONS?\b' docs/research/{topic}/sessions/*/tldr.md | rg -viE 'QUESTIONS?[[:space:]]+ANSWERED'
178
180
  ```
179
181
 
180
- Reconcile each hit against the parent-voice append that answered it (`## PARENT RULING` / `## PARENT NOTE`
181
- in the same file) — an unanswered question is the finding. **Your audit instrument must be at least as
182
- tolerant as the code it audits.**
182
+ Reconcile each hit against the coordinator-voice append that answered it (`## COORDINATOR RULING` /
183
+ `## COORDINATOR NOTE` in the same file, or `## PARENT RULING` / `## PARENT NOTE` on an older board) — an
184
+ unanswered question is the finding. **Your audit instrument must be at least as tolerant as the code it
185
+ audits.**
183
186
 
184
- - **Hosted:** N `## PARENT ACCEPT` anchors imply N acceptance acts (rev-bound: the act carries the tldr
187
+ - **Hosted:** N acceptance anchors (`## (COORDINATOR|PARENT) ACCEPT`) imply N acceptance acts (rev-bound: the act carries the tldr
185
188
  rev, the HEAD and a content hash). An anchor with no act means the derivation failed (LOUD in the
186
189
  logs — find it); an act with no anchor is a cockpit accept (legitimate; the act says so).
187
190
  Acceptance-shaped PROSE without the anchor writes nothing by design — flag it as a ceremony miss.
@@ -374,7 +377,7 @@ is the look of a record with none of a record's properties.
374
377
  session's `tldr.md`, and the working docs.
375
378
  2. **Query** the substrate for §§2-5. Verify each query FIRES on a known-positive row before trusting a
376
379
  clean result.
377
- 3. **Write** `docs/research/{topic}/sessions/parent-retrospective.md` — NATIVELY, in the tree you were born
380
+ 3. **Write** `docs/research/{topic}/sessions/coordinator-retrospective.md` — NATIVELY, in the tree you were born
378
381
  in: the coordinator lives in the effort's worktree, so the scoped write (the effort home's own `.md`
379
382
  files, `sessions/`, the tracker, `live-checks.md` and the specs) lands on the effort's branch and rides
380
383
  its PR. Every write earns its loud audit row. **If the write REFUSES, that is a PLATFORM DEFECT:**
@@ -396,6 +399,6 @@ is the look of a record with none of a record's properties.
396
399
  leaves an identical belief standing in a sibling that words it differently has to be made twice.
397
400
 
398
401
  ## Related
399
- - `spec-parent` (the seat, and the run-time half of this skill's close-out demands) · `spec-child` (the
400
- builders) · `spec-seat` (their shared contract) · `spec-witness` (the read-only verifier) ·
402
+ - `spec-coordinator` (the seat, and the run-time half of this skill's close-out demands) · `spec-build`
403
+ (the builders) · `spec-seat` (their shared contract) · `spec-witness` (the read-only verifier) ·
401
404
  `spec-pipeline` (which authored the specs you are grading)
@@ -24,7 +24,7 @@ else's job.
24
24
  Reading it anchors you on that grade and the pipeline pays for two opinions to get one.
25
25
  - **You do not fix anything.** Findings get classified and filed. A reviewer that repairs its own findings
26
26
  cannot be trusted to count them.
27
- - **You do not decide whether a fixit runs — you classify.** The parent rules on it. A reviewer that can
27
+ - **You do not decide whether a fixit runs — you classify.** The coordinator rules on it. A reviewer that can
28
28
  trigger work is grading its own necessity.
29
29
  - **Every TLDR, spec, and doc claim is TESTIMONY to verify, never a fact to build on.** That includes
30
30
  anything your coordinator tells you: if a ruling arrives in your `tldr.md`, record it and treat it as a
@@ -194,8 +194,9 @@ testimony.
194
194
 
195
195
  ## The report — `sessions/code-review.md`
196
196
 
197
- Files beside `parent-retrospective.md` in the pipeline's `sessions/` folder. It is a pipeline artifact,
198
- not a chat transcript, and it archives with the effort.
197
+ Files beside the coordinator's retrospective in the pipeline's `sessions/` folder
198
+ (`coordinator-retrospective.md`, or `parent-retrospective.md` in an effort begun before that name). It is
199
+ a pipeline artifact, not a chat transcript, and it archives with the effort.
199
200
 
200
201
  ```markdown
201
202
  # Code + session review — {topic}, pipeline {id}
@@ -244,7 +245,7 @@ that does not exist yet (an unauthored row, an unwritten charter) is NOT homed:
244
245
 
245
246
  ## Lineage _(where § Doc metadata (repository-owned) keeps the footer)_
246
247
  - **Pipeline** — the tracker · the umbrella · sessions 02..NN
247
- - **Counterpart** — `parent-retrospective.md` (the inside look; written after this)
248
+ - **Counterpart** — `coordinator-retrospective.md` (the inside look; written after this)
248
249
  ```
249
250
 
250
251
  ## Ceremony
@@ -254,7 +255,7 @@ TLDR with beliefs and numbered questions, the question lane, the parked-call dis
254
255
  vocabulary, the six-section FINAL TLDR, and the close-out order. You commit `sessions/code-review.md` on
255
256
  your coordinator's call like any seat.
256
257
 
257
- **The close-out receipt's heading token is the literal `child·` for you too** — it is a protocol anchor,
258
+ **The close-out receipt's heading token is the literal `seat·` for you too** — it is a protocol anchor,
258
259
  not a description of your seat, and writing `[review·…]` stales your own acceptance. `spec-seat` carries
259
260
  the detail.
260
261
 
@@ -267,7 +268,7 @@ Your baselines are reads, not builds: you run the suites to confirm the pipeline
267
268
  number you cannot reproduce is a finding.
268
269
 
269
270
  ## Related
270
- - `spec-parent` (rules on your fixit candidates; writes the retro after you) · `spec-child` (the seats you
271
+ - `spec-coordinator` (rules on your fixit candidates; writes the retro after you) · `spec-build` (the seats you
271
272
  are reviewing) · `spec-retro` (the inside look) · `spec-witness` (the live read-only seat; its ledger, if
272
273
  one exists, is evidence like any other artifact) · `docs-process` (consumes this report and gives every
273
274
  finding a disposition)
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-seat
3
- 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.
3
+ 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.
4
4
  ---
5
5
 
6
6
  # spec-seat
@@ -10,13 +10,13 @@ the review row, the docs-process row — runs THIS, then its own job skill:
10
10
 
11
11
  | Seat kind | Composes |
12
12
  |---|---|
13
- | `build` · `fixit` | `spec-seat` + **`spec-child`** |
13
+ | `build` · `fixit` | `spec-seat` + **`spec-build`** |
14
14
  | `review` | `spec-seat` + **`spec-review`** |
15
15
  | `docs-process` | `spec-seat` + **`docs-process`** |
16
16
 
17
17
  **THE PAIRING IS SEVEN-WAY AND NON-UNIFORM, and the three kinds missing from that table are missing
18
18
  DELIBERATELY.** `coordinator`, `retro` and `witness` each carry their OWN whole contract
19
- (`spec-parent` · `spec-retro` · `spec-witness`) and are **never** told to invoke this file — prefixing
19
+ (`spec-coordinator` · `spec-retro` · `spec-witness`) and are **never** told to invoke this file — prefixing
20
20
  `spec-seat` onto a skill that already carries a whole contract ships a seed contradicting the skill it
21
21
  points at. The control plane composes each kind's seed from this table and has no catch-all: an unknown
22
22
  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**,
26
26
  quietly — say so in your PLAN TLDR and let the coordinator rule.
27
27
 
28
28
  **The coordinator does NOT compose this.** It writes rulings rather than receiving them, owns the tracker,
29
- and holds the close — a different contract, and `spec-parent` carries it whole.
29
+ and holds the close — a different contract, and `spec-coordinator` carries it whole.
30
30
 
31
31
  **Why this file exists:** a base contract that every seat kind shared, with the build job mixed in, sent
32
32
  the review row into the umbrella its own charter excluded and offered the docs-process row a `docs-write`
@@ -100,7 +100,7 @@ FINAL TLDR — **append, never overwrite**) are FILES, not just chat text.
100
100
 
101
101
  - **Hand-cranked:** create them under `docs/research/{topic}/sessions/{slug}/` at plan time and end your
102
102
  turn announcing the path. The coordinator reads `tldr.md` with normal file tools and APPENDS its ruling
103
- under `## PARENT RULING`, so read the answer in your own file and proceed. The full plan is PULL — it is
103
+ under `## COORDINATOR RULING`, so read the answer in your own file and proceed. The full plan is PULL — it is
104
104
  read only on a read-full-plan verdict; never paste it into chat. (If your harness has a plan-approval
105
105
  mode that forbids writes: give the chat summary, get the human's approve, THEN post and stop.)
106
106
  - **Hosted (a seat inside a pipeline):** the same two files are yours to edit with normal file tools, then
@@ -118,29 +118,33 @@ Either way, `tldr.md` read top-to-bottom is the session's whole conversation in
118
118
 
119
119
  **Greppable turn anchors:** every append gets a stable heading carrying actor + identity —
120
120
  `## [{seat}·{slug} · run {id}] {phase}` when your seat has a run identity, `## [{seat}·{slug}] {phase}`
121
- hand-cranked. The coordinator's voice is always `## PARENT RULING …` / `## PARENT NOTE …`. The stable
122
- prefixes are the contract: one grep for `## PARENT RULING` across every session's `tldr.md` lists every
123
- ruling in the effort.
124
-
125
- **THE HEADING VOCABULARY IS CLOSED, AND THAT IS THE HAZARD AS WELL AS THE CONTRACT.** The parent-voice
126
- list is exactly four — `PARENT NOTE` · `PARENT ACCEPT` · `PARENT RULING` · `OPERATOR RULING` — matched
127
- by the control plane on a word boundary, so `## PARENT NOTEBOOK` cannot pass. A fifth anchor invented
128
- later closes nothing and counts as nothing until the control plane learns it. **Section boundaries are
129
- level-2 headings only** — `### Option A` inside your question block is still inside the question,
130
- deliberately, so a ruling never arrives having truncated your options.
131
-
132
- **Point, don't paste:** to direct anyone at content, say *"read `tldr.md` under `## PARENT RULING`"* —
133
- never re-paste a multi-KB block into a composer.
121
+ hand-cranked. The coordinator's voice is always `## COORDINATOR RULING …` / `## COORDINATOR NOTE …`. The
122
+ stable prefixes are the contract: one grep for `## (COORDINATOR|PARENT) RULING` across every session's
123
+ `tldr.md` lists every ruling in the effort.
124
+
125
+ **THE HEADING VOCABULARY IS CLOSED, AND THAT IS THE HAZARD AS WELL AS THE CONTRACT.** The
126
+ coordinator-voice list is exactly four — `COORDINATOR NOTE` · `COORDINATOR ACCEPT` · `COORDINATOR RULING`
127
+ · `OPERATOR RULING` — matched by the control plane on a word boundary, so `## COORDINATOR NOTEBOOK`
128
+ cannot pass. An older board spells the first three `PARENT NOTE` · `PARENT ACCEPT` · `PARENT RULING`; a
129
+ reader of the anchors takes that spelling as the same three, which is why the grep above carries both. A fifth
130
+ anchor invented later closes nothing and counts as nothing until the control plane learns it. **Section
131
+ boundaries are level-2 headings only** — `### Option A` inside your question block is still inside the
132
+ question, deliberately, so a ruling never arrives having truncated your options.
133
+
134
+ **Point, don't paste:** to direct anyone at content, say *"read `tldr.md` under `## COORDINATOR
135
+ RULING`"* — never re-paste a multi-KB block into a composer.
134
136
 
135
137
  **If `tldr.md` already exists when you go to create your blackboard, APPEND** — machinery may have written
136
- before you, and recreating the file clobbers it (the platform refuses a shrinking rewrite).
138
+ before you, and recreating the file clobbers it (the platform refuses a shrinking rewrite). **And every
139
+ heading already on your board stays exactly as written, an older spelling included:** the platform refuses
140
+ a revision whose earlier headings changed, so never tidy an old heading into the current vocabulary.
137
141
 
138
142
  **Re-read `tldr.md` immediately before every append.** The coordinator appends into the SAME file between
139
143
  your turns — an edit whose old text no longer matches almost always means the conversation moved.
140
144
  Re-read, fold what's new, then append. Never resolve the mismatch by rewriting the whole file; the rev
141
145
  ladder is the history.
142
146
 
143
- **`## PARENT NOTE (FYI — no reply needed)` is the NO-TURN lane:** the coordinator can leave you
147
+ **`## COORDINATOR NOTE (FYI — no reply needed)` is the NO-TURN lane:** the coordinator can leave you
144
148
  informational context WITHOUT waking you — it lands durably in your `tldr.md` and costs you nothing.
145
149
  The re-read above is where you pick FYIs up: fold them as context, owe no reply, and never treat one as
146
150
  a ruling — an FYI cannot answer an open question (only a ruling heading does).
@@ -149,7 +153,7 @@ a ruling — an FYI cannot answer an open question (only a ruling heading does).
149
153
 
150
154
  **When you need a decision at ANY point:** append a question section to your own `tldr.md`, post
151
155
  (`post_tldr`), and **END YOUR TURN.** Your coordinator is woken with your text, and its ruling under a
152
- parent-voice heading is your answer — pick it up from your own file and resume.
156
+ coordinator-voice heading is your answer — pick it up from your own file and resume.
153
157
 
154
158
  **TWO literal headings, one lane — pick by phase, and use a real `##` heading either way:**
155
159
 
@@ -170,7 +174,7 @@ every section and answers `Blocking` / `NotBlocking` / `Undeclared`. Markdown ar
170
174
  - **Never let a reader turn your declaration into liveness.** It is a claim made at the instant you
171
175
  typed it; a seat that wrote `BLOCKING:` and then kept working was telling the truth.
172
176
 
173
- **Both poke the coordinator identically** — same wake, same re-raise, same parent-voice answer. The split
177
+ **Both poke the coordinator identically** — same wake, same re-raise, same coordinator-voice answer. The split
174
178
  is for the READER (a recon fork and a mid-build discovery are different kinds of news), never for the
175
179
  machinery. A question under any OTHER heading — or as a bare `QUESTIONS:` label with no `##` — gets no
176
180
  banner and **the re-raise can never fire**, so it can sit unanswered indefinitely. And never use
@@ -194,13 +198,13 @@ the pipeline a round-trip and nothing else.
194
198
  The latch reads the ACTS LEDGER: a ruling closes your question only when it is delivered as a `callout`
195
199
  carrying your post's act id as `answeringActId`. A `callout` without one steers you and closes nothing.
196
200
  **The reason is a security property, not tidiness:** `tldr.md` is written BY YOU, so a file-side close
197
- predicate is a string the audited party can type — a seat could write `## PARENT RULING` into its own file
201
+ predicate is a string the audited party can type — a seat could write `## COORDINATOR RULING` into its own file
198
202
  and switch off the very re-raise that exists to stop it waiting forever. The question is therefore split
199
203
  in two: *was one asked?* — a fact about the file, where forgery only wakes your own coordinator — versus
200
204
  *was it answered?* — a fact about what the coordinator DID, read from the ledger.
201
205
 
202
206
  **The honest rendering of your file is unchanged**: an open-questions read of the file still clears on the
203
- parent-voice heading, because that is what the file SAYS. What differs is what a DECISION may be
207
+ coordinator-voice heading, because that is what the file SAYS. What differs is what a DECISION may be
204
208
  predicated on.
205
209
 
206
210
  ### THREE CONTRACT LINES, all earned by one kind of silence
@@ -238,7 +242,7 @@ Ask what the park is protecting:
238
242
 
239
243
  - **A park on a STATE condition** — the park text names a rev, a hash, or a version: it is STATE, not
240
244
  approval. Do not re-request, do not reshape; read the substrate for the healing signal (your own acts:
241
- the fresh acceptance receipt, or the `## PARENT NOTE (re-accept)` append) and retry ONCE on receipt.
245
+ the fresh acceptance receipt, or the `## COORDINATOR NOTE (re-accept)` append) and retry ONCE on receipt.
242
246
  State parks are machine-healable — one argless re-accept re-binds a stale acceptance. **Never hold for
243
247
  one specific lane: whichever arrives first IS your signal, and the substrate outranks the bus.**
244
248
  - **A park on your own legitimate in-worktree work** — **re-request it** (no self-imposed cap, no
@@ -342,7 +346,7 @@ naming both. That is why your BELIEFS sha is a contract line and not a courtesy
342
346
  moves mid-build is disclosed FIRST, never absorbed quietly.
343
347
 
344
348
  **The re-accept signal:** after a rev-bound/stale-acceptance park, the re-accept arrives as a
345
- `## PARENT NOTE (re-accept)` append plus a callout — retry your held action on receipt. If your next wake
349
+ `## COORDINATOR NOTE (re-accept)` append plus a callout — retry your held action on receipt. If your next wake
346
350
  shows the fresh acceptance receipt in your own rows WITHOUT the note, **that row IS your signal** — the
347
351
  substrate outranks the bus. Never hold for one specific lane. **A re-accept with no retry order is a
348
352
  doorbell with no follow-through**; if you receive one bare, retry anyway and say that you did.
@@ -416,13 +420,13 @@ produces a working doc**, COMMIT CALL with the message). Execute it exactly.
416
420
  makes the acceptance stale by design. Append your close-out receipt AFTER the push under this heading:
417
421
 
418
422
  ```
419
- ## [child·{slug} · run {id}] CLOSE-OUT RECEIPT
423
+ ## [seat·{slug} · run {id}] CLOSE-OUT RECEIPT
420
424
  ```
421
425
 
422
426
  ## IF YOU HAVE PUSHED AND ARE WAITING, SAY SO. IT DOES NOT STALE YOU.
423
427
 
424
428
  ```
425
- ## [child·{slug} · run {id}] HOLDING
429
+ ## [seat·{slug} · run {id}] HOLDING
426
430
  ```
427
431
 
428
432
  **Then `post_tldr` and end your turn.** Body: what you pushed, and what you are waiting for
@@ -437,10 +441,11 @@ cost a pipeline hours. Preventing it is your job, and it costs you one append.
437
441
  the accepted CONTENT, not to the revision number, so appending your own state or a question leaves it
438
442
  intact. Only **new content** stales.
439
443
 
440
- **The token is the literal `child·`, whatever seat you are.** The control plane's close-out matcher keys
441
- on `[child·…] CLOSE-OUT RECEIPT`, so a review or docs-process seat that writes `[review·…]` or
444
+ **The token is the literal `seat·`, whatever seat you are.** The control plane's close-out matcher keys
445
+ on `[seat·…] CLOSE-OUT RECEIPT`, so a review or docs-process seat that writes `[review·…]` or
442
446
  `[process·…]` **fails the match and stales its own acceptance** — costing a re-post and an argless
443
- re-accept. **It is a PROTOCOL ANCHOR, not a description of you.** A descriptive tail after the marker IS
447
+ re-accept. (An older board's `[child·…]` token matches too; write only `seat·`.) **It is a PROTOCOL
448
+ ANCHOR, not a description of you.** A descriptive tail after the marker IS
444
449
  blessed (`… CLOSE-OUT RECEIPT — addendum: the six staged, tree clean`) — an end-anchored pattern on the
445
450
  one heading seats are told to write would be a trap that fires on ordinary prose.
446
451
 
@@ -489,7 +494,7 @@ why. Silence is not compliance.
489
494
  **THE TESTIMONY REGRESS, AND THE DECLARED STOPPING POINT — read this before you copy anything.** The
490
495
  order above puts the COMMIT before the CLOSE-OUT RECEIPT, so the copy you commit ends at your FINAL TLDR
491
496
  and can contain neither the receipt (hash, session id, staging receipt) nor the coordinator's
492
- `## PARENT ACCEPT`. **A follow-up commit does not fix this, it moves it:** any receipt ABOUT that commit is
497
+ `## COORDINATOR ACCEPT`. **A follow-up commit does not fix this, it moves it:** any receipt ABOUT that commit is
493
498
  also written after it. The regress is infinite and the ceremony does not pretend otherwise.
494
499
 
495
500
  **So the rule is a declared stopping point rather than a fix: RE-COPY `plan.md` AND `tldr.md` ONCE,
@@ -519,5 +524,5 @@ plane. The publish receipt is written at your turn's STOP and is structurally un
519
524
  with a clean rerun builds trust, an undisclosed one destroys it.
520
525
  - **A rule recalled from context needs re-reading at the source before it is used to refuse work.** A
521
526
  rule already corrected on disk is the commonest thing a seat blocks itself on.
522
- - Your job skill is next: `spec-child` (build/fixit) · `spec-review` (the outside look) ·
523
- `docs-process` (compile the living docs). Counterpart: `spec-parent` (the seat that arms you).
527
+ - Your job skill is next: `spec-build` (build/fixit) · `spec-review` (the outside look) ·
528
+ `docs-process` (compile the living docs). Counterpart: `spec-coordinator` (the seat that arms you).
@@ -78,13 +78,16 @@ git — agree.
78
78
  are a zero-token heartbeat per seat — a growing ladder is a live session, a frozen one dates its last
79
79
  turn. `seat_content` reads the board; read `tldr.md` top-to-bottom and it IS the session's whole
80
80
  conversation in message-flow order — the fastest "where is this seat" there is. The coordinator's
81
- voice is a greppable anchor: `## PARENT RULING (plan rev N — {verdict})` and `## PARENT NOTE (…)`
82
- (actor-suffixed when known) on the hosted plane; the same prefixes without the rev counter under
83
- `docs/research/{topic}/sessions/{spec-slug}/` hand-cranked — so grep the prefix, never the full form.
81
+ voice is a greppable anchor: `## COORDINATOR RULING (plan rev N — {verdict})` and `## COORDINATOR NOTE
82
+ (…)` (actor-suffixed when known) on the hosted plane; the same prefixes without the rev counter under
83
+ `docs/research/{topic}/sessions/{spec-slug}/` hand-cranked — so grep the prefix, never the full form,
84
+ and grep both spellings: an older board writes `## PARENT RULING` / `## PARENT NOTE`
85
+ (`rg -n "## (COORDINATOR|PARENT) (RULING|NOTE)"`).
84
86
  **Honest delivery verdicts:** a ruling act's reply states recorded-vs-delivered truthfully —
85
87
  "recorded, not delivered" is NORMAL (the seats run substrate-first; the board is load-bearing, the
86
88
  pointer is best-effort). A delivery miss is only a finding if the seat ALSO never acted on the
87
- substrate. **Blessed close-outs:** a seat's post-push `## [child·…] CLOSE-OUT RECEIPT` append does NOT
89
+ substrate. **Blessed close-outs:** a seat's post-push `## [seat·…] CLOSE-OUT RECEIPT` append (an older
90
+ board's `[child·…]`) does NOT
88
91
  stale its acceptance — a reap without a fresh acceptance after such an append is correct behaviour,
89
92
  not a skipped step.
90
93
  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:
216
219
  trusting their silence — silence from a dead monitor looks identical to a quiet run.
217
220
 
218
221
  ## Related
219
- - `spec-parent` (the seat that rules) · `spec-child` (the seats that act) · `spec-seat` (their shared
222
+ - `spec-coordinator` (the seat that rules) · `spec-build` (the seats that act) · `spec-seat` (their shared
220
223
  contract — read it to know what the seats you are watching were told)
221
224
  - **You are one of the three kinds that do NOT compose `spec-seat`** — this skill is your whole
222
225
  contract, and the control plane's seed says so rather than merely omitting it.
@@ -54,7 +54,7 @@
54
54
 
55
55
  ## Role reading lists
56
56
 
57
- The docs a build seat reads on top of the floor every seat reads (`spec-seat` Step 0). The `spec-child`
57
+ The docs a build seat reads on top of the floor every seat reads (`spec-seat` Step 0). The `spec-build`
58
58
  skill names the loop's standard docs by path; this table is the repository's reserved space — one row per
59
59
  doc, saying which roles read it. The coordinator copies a role's rows into every seat's seed as
60
60
  `EXTRA DOCS`, so a seat sees paths, not this index. Add a row for any doc of your own a role should read;