@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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +48 -0
- package/README.md +2 -2
- package/package.json +1 -1
- package/references/docs-workflow.md +10 -10
- package/references/engineering-loop.md +32 -31
- package/skills/docs-process/SKILL.md +2 -1
- package/skills/init/SKILL.md +1 -1
- package/skills/init/scripts/doctor.mjs +9 -5
- package/skills/init/scripts/owned.mjs +26 -0
- package/skills/{spec-child → spec-build}/SKILL.md +6 -6
- package/skills/{spec-parent → spec-coordinator}/SKILL.md +32 -27
- package/skills/spec-ignite/SKILL.md +5 -5
- package/skills/spec-pipeline/SKILL.md +7 -7
- package/skills/spec-retro/SKILL.md +18 -15
- package/skills/spec-review/SKILL.md +7 -6
- package/skills/spec-seat/SKILL.md +39 -34
- package/skills/spec-witness/SKILL.md +8 -5
- package/templates/docs/_meta/doc-index.md +1 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "naswerks",
|
|
3
|
-
"version": "0.
|
|
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-
|
|
72
|
+
| `spec-coordinator` | spec | the coordinator seat |
|
|
73
73
|
| `spec-seat` | spec | the contract every armed seat follows |
|
|
74
|
-
| `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.
|
|
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.
|
|
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
|
|
208
|
-
|
|
209
|
-
|
|
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
|
|
434
|
-
|
|
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-
|
|
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-
|
|
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-
|
|
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
|
|
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.
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
143
|
-
| `spec-
|
|
144
|
-
| `spec-ignite` | spec | when an authored pipeline runs HOSTED (the `spec-
|
|
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-
|
|
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-
|
|
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 ->
|
|
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
|
-
`##
|
|
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
|
|
241
|
-
{spec-slug}/tldr.md
|
|
242
|
-
code-review.md
|
|
243
|
-
|
|
244
|
-
witness-ledger-*.md
|
|
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
|
|
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
|
|
273
|
-
there is no rev counter, so the heading is `##
|
|
274
|
-
`##
|
|
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
|
-
##
|
|
278
|
+
## COORDINATOR RULING (plan rev N — {accept | accept-with-riders | blocking-precondition})
|
|
278
279
|
|
|
279
|
-
|
|
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 `##
|
|
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
|
-
## [
|
|
292
|
-
## [
|
|
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 `
|
|
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-
|
|
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 `
|
|
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 /
|
package/skills/init/SKILL.md
CHANGED
|
@@ -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-
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
222
|
-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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
|
-
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
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-
|
|
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-
|
|
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-
|
|
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
|
-
|
|
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
|
-
`##
|
|
547
|
-
rev ladder exists; notes under `##
|
|
548
|
-
of four — `
|
|
549
|
-
invent counts as nothing.
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
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
|
-
|
|
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 `##
|
|
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 `## [
|
|
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 `##
|
|
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 `##
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
275
|
-
coordinator's procedure, and the HAND-CRANKED alternative) · `spec-seat` + `spec-
|
|
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
|
-
|
|
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,
|
|
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 `##
|
|
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-
|
|
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-
|
|
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-
|
|
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 `##
|
|
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/
|
|
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-
|
|
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 `##
|
|
152
|
-
anchor in each seat's `tldr.md`, and the receipt DERIVES from it.
|
|
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
|
|
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
|
|
181
|
-
in the same file
|
|
182
|
-
tolerant as the code it
|
|
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`
|
|
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/
|
|
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-
|
|
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
|
|
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
|
|
198
|
-
|
|
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** — `
|
|
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 `
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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 `##
|
|
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 `##
|
|
122
|
-
prefixes are the contract: one grep for `## PARENT RULING` across every session's
|
|
123
|
-
ruling in the effort.
|
|
124
|
-
|
|
125
|
-
**THE HEADING VOCABULARY IS CLOSED, AND THAT IS THE HAZARD AS WELL AS THE CONTRACT.** The
|
|
126
|
-
list is exactly four — `
|
|
127
|
-
by the control plane on a word boundary, so `##
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
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
|
-
**`##
|
|
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
|
-
|
|
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
|
|
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 `##
|
|
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
|
-
|
|
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 `##
|
|
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
|
-
`##
|
|
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
|
-
## [
|
|
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
|
-
## [
|
|
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 `
|
|
441
|
-
on `[
|
|
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.
|
|
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
|
-
`##
|
|
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-
|
|
523
|
-
`docs-process` (compile the living docs). Counterpart: `spec-
|
|
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: `##
|
|
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 `## [
|
|
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-
|
|
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-
|
|
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;
|