@naswerks/engineering-loop 0.2.1 → 0.5.0

package/skills/spec-retro/SKILL.md

@@ -10,6 +10,8 @@ today that perspective evaporates the moment the run closes. This skill turns it
 
 **It is not a summary. It is an audit — of the pipeline, and of the seat that ran it.**
 
+**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.
+
 Run it as the **last act of the coordinator seat**, after the final session's close-out commit — before or
 after the PR is cut, either works. Output: `docs/research/{topic}/sessions/parent-retrospective.md`. It is
 a scoped write on the pipeline's branch, so it rides the PR to the base branch either way.
@@ -381,8 +383,9 @@ is the look of a record with none of a record's properties.
 4. **Do not fix anything.** Findings become proposed fixits. The retro is a read.
 5. **Then** commit the retro (explicit path) and push it (`git push origin <the effort's branch>`), and
    write `BUILD COMPLETE` into `docs/research/{topic}/project-status.md` (the tracker's close marker). **If no
-   PR exists yet, create it yourself** — `gh pr create` on the effort's branch; one branch, one PR from any
-   seat. **If one is already open, the push is enough.** These three git commands are your own close-out
+   PR exists yet, create it yourself** — on the effort's branch, where and how `docs/_meta/engineering-loop.md`
+   § This repository's rails (repository-owned) says (when it names no route, ask the human once and suggest
+   recording the answer there); one branch, one PR from any seat. **If one is already open, the push is enough.** These three git commands are your own close-out
    lane and they are gated and receipted like any other publish. **The push command must be the ENTIRE
    command** — a leading `cd` disqualifies it — and keep git-verb words out of any echo label you write
    around it; the deny layer matches TEXT, not parsed verbs.

package/skills/spec-review/SKILL.md

@@ -12,6 +12,8 @@ run **before the coordinator's retro and before the PR exists.**
 each; the coordinator judged them all and formed beliefs doing it. You arrive with none of that, which is
 why you can see the seams between sessions that no session's own verification structurally covers.
 
+**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.
+
 Two documents come out of a pipeline's close and they are deliberately different: **the retro looks
 inward, and you look in from outside.** They are independent grades, and reconciling them is somebody
 else's job.
@@ -33,7 +35,9 @@ else's job.
 Your seed carries **no beliefs about the pipeline, and that is deliberate** — but it should carry an
 **inventory**, because you cannot review what you cannot find:
 
-- the **topic**, the **branch**, and the **diff range** (`main...<branch>`);
+- the **topic**, the **branch**, and the **diff range** (`{base}...<branch>` — `{base}` is the base branch
+  `docs/_meta/engineering-loop.md` § This repository's rails (repository-owned) names, or the remote's
+  default when it names none);
 - **every numbered spec path** — you read them as claims, not facts;
 - the **`sessions/`** folder, holding each build seat's `plan.md` + `tldr.md`;
 - the **working docs for this effort, named explicitly** — `docs/working/` is a shared queue and you must
@@ -54,7 +58,7 @@ That is testimony; record it and treat it as a claim.
 3. **The working docs** in `docs/working/` — the narrative: what was tried, what failed, what changed.
 4. **The tracker** — `project-status.md`, the coordinator's journal: rulings and their reasoning, recon
    corrections, incidents.
-5. **THEN the diff** — `git diff main...<pipeline-branch>`, plus `git log --oneline main..<pipeline-branch>`.
+5. **THEN the diff** — `git diff {base}...<pipeline-branch>`, plus `git log --oneline {base}..<pipeline-branch>`.
 
 **Read the artifacts before the code, and the code before you conclude.** Reading the diff first makes
 you review a patch; reading the claims first makes you review whether the pipeline did what it said.
@@ -144,7 +148,7 @@ finding seen twice.
 - **A receipt is false** — a TLDR, spec, or doc asserts something proven that the code does not do. This
   matters as much as a bug, because the next pipeline builds on it.
 
-**(b) Leaving it costs more than a session costs** — it reaches main, propagates to the next pipeline, or a
+**(b) Leaving it costs more than a session costs** — it reaches the base branch, propagates to the next pipeline, or a
 human discovers it live.
 
 Everything else is a finding with a home, and you name the home:
@@ -197,8 +201,8 @@ not a chat transcript, and it archives with the effort.
 # Code + session review — {topic}, pipeline {id}
 
 > The outside look, written before the retro and before the PR. Two independent passes, consolidated.
-> Reviewed `main..{sha}` across N sessions. **This seat did not read the coordinator's retrospective.**
-<!-- meta: type=session; status=final; verified={date}; lineage=N -->
+> Reviewed `{base}..{sha}` across N sessions. **This seat did not read the coordinator's retrospective.**
+{the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for `shipped`}
 
 ## The verdict, first
 {The one thing a reader must not miss. If the pipeline ships something untrue, say it here in bold.}
@@ -238,7 +242,7 @@ that does not exist yet (an unauthored row, an unwritten charter) is NOT homed:
 ## What I could not verify
 {Stated, not omitted.}
 
-## Lineage
+## Lineage   _(where § Doc metadata (repository-owned) keeps the footer)_
 - **Pipeline** — the tracker · the umbrella · sessions 02..NN
 - **Counterpart** — `parent-retrospective.md` (the inside look; written after this)
 ```

package/skills/spec-seat/SKILL.md

@@ -33,6 +33,8 @@ the review row into the umbrella its own charter excluded and offered the docs-p
 it must never run. One base class, three wrong instructions. The contract and the job are therefore two
 files.
 
+**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.
+
 ## What you hold (and what you never touch)
 
 - **Yours:** your one assignment; the recon; the plan; the work; your artifacts; your own explicit-path
@@ -51,9 +53,9 @@ Do this immediately, whatever your assignment turns out to be. It needs no role
 
 | Doc | What it gives you |
 |---|---|
-| `docs/_meta/doc-index.md` | the menu — which living doc answers which question |
-| `docs/_meta/docs-workflow.md` | the folders, the templates, the two loops |
-| `docs/_meta/engineering-loop.md` | the seats, the ceremony, and **the comms protocol you follow** |
+| `docs/_meta/doc-index.md` | the menu — which living doc answers which question: every living doc, or on a curated menu the ones meant for seats (its shape line says which) |
+| `docs/_meta/docs-workflow.md` | the folders, the templates, the two loops — and, in its sections marked (repository-owned), this repository's doc header and where an effort is filed |
+| `docs/_meta/engineering-loop.md` | the seats, the ceremony, **the comms protocol you follow** — and this repository's rails (repository-owned) |
 
 Then recon the tree: `git rev-parse HEAD`, `git status --porcelain`, `git branch --show-current`.
 
@@ -79,9 +81,9 @@ prompt's `EXTRA DOCS` line names this repository's own.** Read every one that ex
 is absent was not detected by `init` — `docs/_meta/doc-index.md` § Role reading lists carries a row
 saying so — and is not a missing-file finding.
 
-A doc marked `status=draft` in its meta line was scanned by `init`, not decided by the repo's owners —
-read it as the starting point it is, and treat a rule it states without a cited source as a question for
-your PLAN TLDR, not a law.
+A doc whose header carries the word for `draft` (§ Doc metadata (repository-owned)) was scanned by `init`,
+not decided by the repo's owners — read it as the starting point it is, and treat a rule it states without
+a cited source as a question for your PLAN TLDR, not a law.
 
 Then report your orientation and beliefs, and ask ONE question: **your assignment.** Stop.
 
@@ -347,6 +349,9 @@ doorbell with no follow-through**; if you receive one bare, retry anyway and say
 
 ## Git shapes
 
+- **This repository's rails add to these shapes.** `docs/_meta/engineering-loop.md` § This repository's
+  rails (repository-owned) names the gates a commit passes, the suite before a PR, the PR route and any
+  stricter staging — follow them beside these, never instead of them.
 - **Explicit staging only, never `git add -A`.** Additive-only; never amend pushed commits.
 - **VERIFY EVERY STAGE BEFORE THE COMMIT — `git add` skips gitignored paths under a directory with
   exit 0 and NO output, and `git status` cannot show the loss** (an ignored file is neither staged nor

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

@@ -2,6 +2,12 @@
 
 > The menu. Read this at session start, pick the 2-3 docs that match your task, read those for context.
 > This is the curated short list — the compiled layer you read *before* diving into source.
+<!-- naswerks-loop: menu=all -->
+<!-- init: the shape line above stays in the output. It says menu=all unless the scan found an index the
+     repository already keeps of every doc (a docs/INDEX.md or docs/index.md that lists them, a
+     docs/SUMMARY.md, a mkdocs.yml nav, a docusaurus or vitepress sidebar); then it says
+     menu=curated; index={that path}, and the tables below list only the docs init drafted plus the Meta
+     rows. The owner adds each further doc that meets the loop's standard. -->
 
 ---
 
@@ -43,7 +49,7 @@
 
 | Doc | When to read |
 |-----|-------------|
-| [docs-workflow](docs-workflow.md) | The loop, folder rules, templates (the `<!-- meta -->` header + `## Lineage` footer convention and the spec-doc template), the `docs-*` knowledge-loop + `spec-*` execution-loop skills — read before running `docs-write` / `docs-process` / `spec-pipeline` |
+| [docs-workflow](docs-workflow.md) | The loop, folder rules, templates (the doc header + `## Lineage` footer convention, the sections marked repository-owned, and the spec-doc template), the `docs-*` knowledge-loop + `spec-*` execution-loop skills — read before running `docs-write` / `docs-process` / `spec-pipeline` |
 | [engineering-loop](engineering-loop.md) | The quick intro to how work gets built: the two loops (`docs-*` knowledge / `spec-*` execution, both hand-crankable), the seats, the ceremony, the blackboard + the question lane, and where a rule lives (policy / procedure / task) |
 
 ## Role reading lists

package/templates/docs/infrastructure/background-work.md

@@ -2,7 +2,7 @@
 
 > What runs outside a request in this repository — workers, queues, schedulers — and how long-running,
 > multi-stage work is orchestrated. Last verified {today}.
-<!-- meta: type=infrastructure; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=infrastructure; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/infrastructure/realtime-events.md

@@ -2,7 +2,7 @@
 
 > How server-side events reach the client in this repository, and the poke/refetch pattern that keeps
 > the two consistent. Last verified {today}.
-<!-- meta: type=infrastructure; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=infrastructure; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/backend-patterns.md

@@ -1,7 +1,7 @@
 # Backend Patterns
 
 > Rules and conventions for the server side of this repository. Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/code-organization.md

@@ -2,7 +2,7 @@
 
 > Where the code lives and where a new piece goes — the folder shape this repository actually uses, per
 > stack, and the checklist for adding a feature to it. Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/codegen.md

@@ -2,7 +2,7 @@
 
 > What is generated in this repository, from what, by which command — and the one rule: never hand-write
 > a generated file. Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/design-tokens.md

@@ -3,7 +3,7 @@
 > The token authority: which colour, spacing and typography tokens exist, what each means, and how
 > component CSS consumes them. Component usage (which class for which job) lives in
 > [ui-style-guide](ui-style-guide.md). Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/frontend-patterns.md

@@ -1,7 +1,7 @@
 # Frontend Patterns
 
 > Rules and conventions for the client side of this repository. Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/long-running-workflows.md

@@ -3,7 +3,7 @@
 > How multi-stage work is orchestrated in this repository: the stages, per-item progress, exactly-once
 > transitions, and how progress reaches the client. The transport it runs on is
 > [background-work](../infrastructure/background-work.md). Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/state-management.md

@@ -2,7 +2,7 @@
 
 > The store convention for the client side of this repository: the files per store, how a store is
 > registered, how a component consumes it. Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/testing.md

@@ -1,7 +1,7 @@
 # Testing Patterns
 
 > How to write and run tests in this repository — every lane. Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---

package/templates/docs/patterns/ui-style-guide.md

@@ -2,7 +2,7 @@
 
 > Which class or component to reach for, for which job, and the composition rules that keep screens
 > consistent. The tokens themselves are the authority of [design-tokens](design-tokens.md). Last verified {today}.
-<!-- meta: type=pattern; status=draft; verified={today}; lineage=0 -->
+<!-- init: write here the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for draft; where that section keeps no date in the blockquote, drop the `Last verified {today}.` above. The loop's own header is the one-line meta comment: type=pattern; status=draft; verified={today}; lineage=0 -->
 <!-- naswerks-loop: draft; scanned={files} -->
 
 ---