@naswerks/engineering-loop 0.2.1 → 0.4.0

package/skills/init/scripts/owned.mjs

@@ -0,0 +1,96 @@
+// The repository-owned sections: the four spaces in the two method docs where a repository writes its own
+// formats in place of the loop's. One list, read by the doctor, by refresh and by the pins, so the three can
+// never disagree about what a space is. Everything else a space means (what the skills read from it, where
+// the method docs echo it, the rails items) is read from the pack's own references/, never restated here.
+
+// The one grep that lists every space, and nothing else, with its line number.
+export const GREP = "rg -n '^#+ .*\\(repository-owned\\)' docs/_meta/";
+export const MARKED = /^#+ .*\(repository-owned\)/;
+
+// The line every skill that needs a format carries, verbatim, near its top.
+export const FIND_FORMAT = "**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.";
+
+// Each space by its heading, in the order the pack writes them, with the spellings a copy taken before the
+// sections were marked still carries. `earlier` is the only fact here that the references cannot supply.
+export const OWNED = [
+  { file: 'docs-workflow.md', heading: '## The archive convention (repository-owned)', title: 'The archive convention', earlier: ['## The archive convention'] },
+  { file: 'docs-workflow.md', heading: '## Doc metadata (repository-owned)', title: 'Doc metadata', earlier: ['## Doc metadata (header + lineage)', '## Doc metadata'] },
+  { file: 'docs-workflow.md', heading: '## Templates (repository-owned)', title: 'Templates', earlier: ['## Templates'] },
+  { file: 'engineering-loop.md', heading: "## This repository's rails (repository-owned)", title: "This repository's rails", earlier: [] },
+];
+
+export const STAMP = /^(<!-- naswerks-loop: version=)([0-9]+\.[0-9]+\.[0-9]+[^ ]*)( -->)/;
+
+export function compareVersions(a, b) {
+  const pa = a.split(/[.-]/).map((x) => parseInt(x, 10) || 0), pb = b.split(/[.-]/).map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); }
+  return 0;
+}
+
+// A file as lines that keep their own terminators, so an untouched line is written back byte for byte.
+export function linesOf(text) {
+  return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+export const bare = (line) => line.replace(/\r?\n$/, '').replace(/^/, '');
+export const eolOf = (text) => (text.includes('\r\n') ? '\r\n' : '\n');
+
+// The index of every H2 heading outside a fenced block. The Templates space holds fenced examples whose
+// own `## ` lines are template text, not sections.
+export function h2Index(lines) {
+  const out = [];
+  let fence = null;
+  lines.forEach((raw, i) => {
+    const line = bare(raw);
+    const f = /^\s*(```|~~~)/.exec(line);
+    if (f) { fence = fence === null ? f[1] : (fence === f[1] ? null : fence); return; }
+    if (fence === null && /^## /.test(line)) out.push({ i, heading: line.trimEnd() });
+  });
+  return out;
+}
+
+// A section by heading: the heading line's index and the index of the next H2 (or the end of the file).
+export function findSection(lines, heading) {
+  const hs = h2Index(lines);
+  const k = hs.findIndex((h) => h.heading === heading);
+  if (k < 0) return null;
+  return { start: hs[k].i, end: k + 1 < hs.length ? hs[k + 1].i : lines.length };
+}
+
+// The rails items a section carries, by the bold lead-in of each top-level bullet: `- **Policy.** ...`.
+export function railsItems(sectionLines) {
+  const items = [];
+  for (let i = 0; i < sectionLines.length; i++) {
+    const m = /^- \*\*(.+?)\.?\*\*/.exec(bare(sectionLines[i]));
+    if (!m) continue;
+    let j = i + 1;
+    while (j < sectionLines.length && /^\s+\S/.test(bare(sectionLines[j]))) j++;
+    items.push({ name: m[1].replace(/\.$/, ''), text: sectionLines.slice(i, j).join(''), first: i, last: j - 1 });
+  }
+  return items;
+}
+
+// The stamp line: line 1, or the first non-blank line after a leading frontmatter block.
+export function stampIndex(lines) {
+  let i = 0;
+  if (bare(lines[0] ?? '') === '---') {
+    i = 1;
+    while (i < lines.length && bare(lines[i]) !== '---') i++;
+    i++;
+    while (i < lines.length && bare(lines[i]).trim() === '') i++;
+  }
+  return i < lines.length && STAMP.test(bare(lines[i])) ? i : -1;
+}
+
+// The map's rows in the pack's docs-workflow.md: what the skills read from each space, and where the method
+// docs echo it. Keyed by the space's title.
+export function mapOf(workflowText) {
+  const lines = linesOf(workflowText.replace(/\r\n/g, '\n'));
+  const sec = findSection(lines, '## The repository-owned sections');
+  const out = {};
+  if (!sec) return out;
+  for (const raw of lines.slice(sec.start, sec.end)) {
+    const m = /^\|\s*\*\*(.+?)\*\*[^|]*\|([^|]*)\|([^|]*)\|/.exec(bare(raw));
+    if (m) out[m[1].trim()] = { reads: m[2].trim(), echoed: m[3].trim() };
+  }
+  return out;
+}

package/skills/init/scripts/refresh.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// refresh — bring a repository's copies of the two method docs up to this pack version by writing ONLY their
+// repository-owned sections and the stamp. Every other line is left exactly as it is: the loop text in a
+// copy is the repository's, whatever it has done to it. Dry run by default; --write applies the rows it
+// printed. Node >= 22, no dependencies. Usage: node refresh.mjs [repo-root] [--write]
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { OWNED, STAMP, compareVersions, linesOf, bare, eolOf, h2Index, findSection, railsItems, stampIndex, mapOf } from './owned.mjs';
+
+const args = process.argv.slice(2);
+const write = args.includes('--write');
+const repo = resolve(args.find((a) => !a.startsWith('--')) || process.cwd());
+const packRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const packVersion = JSON.parse(readFileSync(join(packRoot, '.claude-plugin', 'plugin.json'), 'utf8')).version;
+const packText = (file) => readFileSync(join(packRoot, 'references', file), 'utf8').replace(/\r\n/g, '\n');
+
+const rows = [];
+const row = (file, subject, action) => rows.push({ file, subject, action });
+let changedFiles = 0;
+
+console.log(`init refresh — ${repo} — pack ${packVersion}`);
+console.log('writes only the repository-owned sections and the stamp; every other line is left as it is.\n');
+
+for (const file of ['docs-workflow.md', 'engineering-loop.md']) {
+  const path = join(repo, 'docs', '_meta', file);
+  const shown = `docs/_meta/${file}`;
+  if (!existsSync(path)) { row(shown, '(file)', 'missing — `init` writes it; refresh only updates a copy that exists'); continue; }
+  const original = readFileSync(path, 'utf8');
+  const eol = eolOf(original);
+  let lines = linesOf(original);
+  const sIdx = stampIndex(lines);
+  if (sIdx < 0) { row(shown, '(file)', 'no naswerks-loop stamp on its first line — not recognised as a copy of the method doc; nothing written'); continue; }
+
+  const packLines = linesOf(packText(file));
+  const withEol = (text) => text.replace(/\r?\n/g, eol);
+  let changed = false;
+
+  for (const space of OWNED.filter((o) => o.file === file)) {
+    const hs = h2Index(lines);
+    const present = hs.find((h) => h.heading === space.heading);
+    if (present) {
+      row(shown, space.heading, 'kept — yours, byte for byte');
+    } else {
+      const was = hs.find((h) => space.earlier.includes(h.heading));
+      if (was) {
+        const raw = lines[was.i];
+        lines[was.i] = space.heading + raw.slice(bare(raw).length);
+        row(shown, space.heading, `heading marked — was "${was.heading}"; only that line changes`);
+        changed = true;
+      } else {
+        // Insert the pack's own section before the first pack heading after it that this copy also has.
+        const pack = findSection(packLines, space.heading);
+        const packHs = h2Index(packLines);
+        const after = packHs.filter((h) => h.i > pack.start).map((h) => h.heading);
+        const anchor = after.map((h) => hs.find((c) => c.heading === h)).find(Boolean);
+        const chunk = linesOf(withEol(packLines.slice(pack.start, pack.end).join('')));
+        if (anchor) {
+          lines.splice(anchor.i, 0, ...chunk);
+          row(shown, space.heading, `added — the pack's default, before "${anchor.heading}"`);
+        } else {
+          if (lines.length && !/\n$/.test(lines[lines.length - 1])) lines[lines.length - 1] += eol;
+          lines.push(eol, ...chunk);
+          row(shown, space.heading, 'added — the pack\'s default, at the end of the file');
+        }
+        changed = true;
+      }
+    }
+
+    // The rails: a bullet this version names that the copy's section lacks is appended as its absent-line.
+    if (space.heading.includes('rails')) {
+      const packSec = findSection(packLines, space.heading);
+      const packItems = railsItems(packLines.slice(packSec.start, packSec.end));
+      const sec = findSection(lines, space.heading);
+      const have = railsItems(lines.slice(sec.start, sec.end)).map((it) => it.name.toLowerCase());
+      const missing = packItems.filter((it) => !have.includes(it.name.toLowerCase()));
+      if (missing.length) {
+        let at = sec.end;
+        while (at > sec.start + 1 && bare(lines[at - 1]).trim() === '') at--;
+        if (!/\n$/.test(lines[at - 1])) lines[at - 1] += eol;
+        const add = [];
+        if (!have.length) add.push(eol);
+        for (const it of missing) add.push(...linesOf(withEol(it.text)));
+        lines.splice(at, 0, ...add);
+        for (const it of missing) row(shown, `rails item: ${it.name}`, 'item added — its absent-line, at the end of the section');
+        changed = true;
+      }
+    }
+  }
+
+  // The stamp names the pack version whose repository-owned sections this copy carries.
+  const stampAt = stampIndex(lines);
+  const current = STAMP.exec(bare(lines[stampAt]))[2];
+  const cmp = compareVersions(current, packVersion);
+  if (cmp < 0) {
+    const raw = lines[stampAt];
+    const bom = raw.startsWith('') ? '' : '';
+    lines[stampAt] = bom + raw.slice(bom.length).replace(STAMP, `$1${packVersion}$3`);
+    row(shown, 'stamp', `${current} to ${packVersion}`);
+    changed = true;
+  } else if (cmp > 0) row(shown, 'stamp', `${current} — ahead of this pack; left as it is`);
+  else row(shown, 'stamp', `${current} — current`);
+
+  if (changed) {
+    changedFiles++;
+    if (write) writeFileSync(path, lines.join(''));
+  }
+}
+
+const width = Math.max(...rows.map((r) => r.subject.length), 7);
+const fw = Math.max(...rows.map((r) => r.file.length), 4);
+console.log(`| ${'file'.padEnd(fw)} | ${'section'.padEnd(width)} | action |`);
+console.log(`|${'-'.repeat(fw + 2)}|${'-'.repeat(width + 2)}|--------|`);
+for (const r of rows) console.log(`| ${r.file.padEnd(fw)} | ${r.subject.padEnd(width)} | ${r.action} |`);
+
+const map = mapOf(packText('docs-workflow.md'));
+if (Object.keys(map).length) {
+  console.log('\nyours — what this version\'s skills read from each section (check that yours answers each), and the');
+  console.log('loop passages that echo it (rewrite them too if you replaced the section):');
+  for (const space of OWNED) {
+    const m = map[space.title];
+    if (m) console.log(`- ${space.title}: reads ${m.reads}${m.echoed && m.echoed !== '—' ? `; echoed in ${m.echoed}` : ''}`);
+  }
+}
+
+console.log(`\nloop text — not touched. The pack's own is in ${join(packRoot, 'references').replace(/\\/g, '/')}/ to compare.`);
+if (!changedFiles) console.log('\nnothing to do — every section present, every stamp current.');
+else if (write) console.log(`\nwritten — ${changedFiles} file(s), exactly the rows above.`);
+else console.log('\ndry run — nothing written. Run again with --write to apply exactly the rows above.');

package/skills/spec-child/SKILL.md

@@ -42,7 +42,7 @@ not a missing-file finding. `patterns/codegen.md` is read by any seat that touch
 |---|---|
 | **frontend** | `patterns/state-management.md` · `patterns/ui-style-guide.md` · `patterns/design-tokens.md` · `infrastructure/realtime-events.md` (the poke/refetch concept trips sessions up — read it even for "pure UI" work) · `patterns/codegen.md` when the client consumes generated types |
 | **backend** | `infrastructure/realtime-events.md` (the poke/refetch concept trips sessions up — read it even for "pure API" work) · `infrastructure/background-work.md` · `patterns/long-running-workflows.md` as the task warrants · `patterns/codegen.md` when the server side emits generated code |
-| **mixed** | **NOT every set by default** — read the adds for the surfaces your spec ACTUALLY touches, decided at recon once you have read the spec. **This is the default role and it covers every surface with no role of its own** — a CLI, a sidecar, a worker project; docs work needs nothing beyond the Step 0 floor |
+| **mixed** | **NOT every set by default** — read the adds for the surfaces your spec ACTUALLY touches, decided at recon once you have read the spec. **This is the default role and it covers every surface with no role of its own** — a CLI, a sidecar, a worker project — and its reading list is the rows for those surfaces in `docs/_meta/doc-index.md` § Role reading lists; docs work needs nothing beyond the Step 0 floor |
 
 **This repository's own docs reach you as paths too, not as an index to consult:** the coordinator copies
 your role's rows from `docs/_meta/doc-index.md` § Role reading lists into your prompt's `EXTRA DOCS` line.

package/skills/spec-parent/SKILL.md

@@ -9,6 +9,8 @@ Turn this session into the **coordinator** for a `docs/research/{topic}/` spec p
 phase 3 of the backlog model (`docs-backlog`, `spec-pipeline`, **`spec-parent`**, seats build,
 `docs-process`).
 
+**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.
+
 **You are one of the three kinds that do NOT compose `spec-seat`** — that file is the contract for the
 seats you ARM, and it says so itself. This skill is your whole contract: you write rulings rather than
 receive them, you own the tracker, and you hold the close. The control plane's seed says so out loud
@@ -285,7 +287,7 @@ read the board and answer on first receipt rather than spending a round-trip.
       `.md` files (`live-checks.md`, the numbered specs, the umbrella) are inside your scoped write path —
       same gate, same receipt as your ledger. **This also means a line you have PROVEN false in a spec or
       a live-check row is yours to strike at the source.** Research stage only — after docs-process
-      archives the folder, only the ledger remains writable.
+      files the folder, only the ledger remains writable.
       Every session's TLDR section (e) row belongs there, plus any status only you observed. Unaggregated
       rows are the most common thing to fall through, and the human's sitting is what they are for.
    3. **Run `spec-retro`.** It is written FROM the tracker, which is why step 1 comes first — a retro
@@ -294,8 +296,10 @@ read the board and answer on first receipt rather than spending a round-trip.
       grades stay independent.** Do not reconcile them or soften yours to match; two accounts of one run
       are the point, and whoever reads them both does the reconciling.
    4. **Commit the retro** by explicit path and **write `BUILD COMPLETE`** into `project-status.md`.
-   5. **Push the effort's branch. Create the PR if none is open** (`gh pr create`); if one is already open
-      the push is enough. These are your own git — gated and receipted like any other publish. **The
+   5. **Push the effort's branch. Create the PR if none is open** — 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); if one is already open the push is
+      enough. These are your own git — 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 around it — the deny layer matches TEXT, not parsed verbs, and a decorative
       `=== remote tip ===` header over a read-only block will park.
@@ -306,9 +310,12 @@ read the board and answer on first receipt rather than spending a round-trip.
       are **contingent on the merge**, so say so in the close: the docs describe what the PR will land.
 
       **P MOVES THE EFFORT HOME OUT OF YOUR REACH — the tracker pass in step 1 is your LAST chance at
-      the specs and live-checks.** P `git mv`s `docs/research/{topic}/` to `docs/archive/{topic}/`. The
-      ledger survives the rename (its write predicate admits `docs/{research|archive}/*/project-status.md`),
-      but the effort-home lane (`live-checks.md`, the specs) is research only — the archive is frozen
+      the specs and live-checks.** P `git mv`s `docs/research/{topic}/` to the archive home
+      `docs/_meta/docs-workflow.md` § The archive convention (repository-owned) names, or to the umbrella's
+      `Archive:` line when it carries one. The ledger survives the
+      rename (its write predicate admits `docs/{research|archive}/*/project-status.md`; a home elsewhere
+      is outside it, so there P's write to the tracker is the last one), but the effort-home lane
+      (`live-checks.md`, the specs) is research only — the archive is frozen
       testimony. So finish those before P runs, and record P's own outcome in P's TLDR rather than
       planning to journal it afterwards.
 
@@ -364,6 +371,9 @@ so read them as run-time obligations, not close-out ones:
 - Plan TLDR as **plain text BEFORE any plan-approval mode**; questions as **plain numbered text, then
   STOP** — never an interactive question tool (the human can't copy from it).
 - **No commit/push without your relayed call.** Explicit staging only — never `git add -A`.
+- **This repository's rails add to these rules.** `docs/_meta/engineering-loop.md` § This repository's rails
+  (repository-owned) names the policy, the gates a commit passes, the suite before a PR, the PR route and
+  any stricter staging — bake every rail in beside these, and never let one subtract from them.
 - **The unattended git form, and it binds YOU as much as the seats: one git command per call, no shell
   metacharacters.** The FORM check reads the whole command string, so chaining, redirects or substitution
   disqualify it — `git add … && git commit … && git push …` parks, while the same three sent separately
@@ -488,7 +498,8 @@ REVIEW row (R):
 
 DOCS-PROCESS row (P):
   You are the DOCS-PROCESS seat: invoke the docs-process skill before anything else.
-  Effort: {topic} · archive target: docs/archive/{topic}/
+  Effort: {topic} · archive target: {per docs/_meta/docs-workflow.md § The archive convention
+    (repository-owned), or the umbrella's Archive: line when it carries one} · shape: {as that section says}
   Working docs for THIS effort, and ONLY these: {explicit list — docs/working/ is a shared
     queue and may hold other efforts' docs; do not infer membership from the folder}
   Research/spec docs to archive: docs/research/{topic}/
@@ -563,8 +574,8 @@ PARENT RESPONSE — FINAL TLDR ACCEPTED {(+ what I verified myself)}.
    VERIFY before committing: verify-staged {same list} — commit only on exit 0. Non-zero means
    git add silently dropped files (usually a .gitignore rule); STOP, report the output verbatim,
    and wait — do not force-add, do not widen .gitignore.
-   Message: {conventional message naming the spec}
-   Trailer: {the trailer this repo's commit convention requires, if any — name YOUR model}
+   Message: {a message the rails' commit gates accept, naming the spec}
+   Trailer: {the trailer the rails' commit convention requires, if any — name YOUR model}
    Then push. Post-commit status must show only the known coordinator-owned/unrelated files, and
    the close-out report carries the one-line STAGING VERIFIED receipt — a commit report
    without it is incomplete (the whole defect class is silence; an unrequired receipt is

package/skills/spec-pipeline/SKILL.md

@@ -10,6 +10,8 @@ the two-phase backlog model: `docs-backlog` parks an idea; `spec-pipeline` gradu
 into specs. **The plan is throwaway — the specs carry every crumb.** A future session reads ONE spec + the
 umbrella and can build without the plan or the original conversation.
 
+**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.
+
 ## The two-phase model
 
 | Phase | When | Skill | Output |
@@ -111,8 +113,8 @@ sessions/                        WHO PUTS IT THERE
    **"Do you want DOCS-PROCESS as a row?"** In-pipeline gives you a zero-touch close: living docs patched
    and the effort archived without a second sitting. **State the trade honestly:** `docs-process` is
    designed as a fresh session over *merged* code, so in-pipeline it patches living docs against code that
-   is only **about to be** merged, and the `research/{topic}` to `archive/{topic}` rename rides the same
-   PR. If the PR is not merged, or is partly reverted, those docs describe something absent. **Say in the
+   is only **about to be** merged, and the move from `research/{topic}` into the archive home rides the
+   same PR. If the PR is not merged, or is partly reverted, those docs describe something absent. **Say in the
    brief that the living-doc patches are contingent on the merge.** Out-of-pipeline is equally valid and
    cheap — every artifact is durable, so it runs cold, later, over several efforts at once.
 
@@ -125,7 +127,7 @@ sessions/                        WHO PUTS IT THERE
 
    ```
    02..NN   the build seats
-   {R}      REVIEW      — spec-review, if chosen. Runs on `git diff main...<branch>`; no PR yet
+   {R}      REVIEW      — spec-review, if chosen. Runs on `git diff {base}...<branch>` (the rails' base branch); no PR yet
    {F}      FIXIT       — MAY materialise, one maximum, only if the review classifies an (a)+(b)
                           finding AND the coordinator rules it in. Not authored up front; the
                           coordinator charters it from the review's named list
@@ -146,7 +148,8 @@ sessions/                        WHO PUTS IT THERE
 
 3. **Write the specs**, using the spec-doc template in `docs/_meta/docs-workflow.md`. Each per-seat
    spec opens with the spec-doc blockquote (`Builds on [prior]` + `Source: [umbrella / research]`) and the
-   `<!-- meta: type=spec; status=draft; verified={date}; lineage=N -->` line, so the set stays navigable.
+   machine header `docs/_meta/docs-workflow.md` § Doc metadata (repository-owned) prescribes, at the word for
+   `draft`, so the set stays navigable.
 
    **Six things every slice carries**, each earned by a session that did not have it:
 
@@ -178,7 +181,7 @@ sessions/                        WHO PUTS IT THERE
      bans, and the builder is then forced to choose between the letter and the point. State the property
      and the letter can never contradict it.
    - **A `last verified against` line — the date AND the sha the spec was checked against.** The
-     `meta: verified` stamp records authoring; this tells the BUILDER what the spec's facts are relative
+     header's verified date records authoring; this tells the BUILDER what the spec's facts are relative
      to. **Recon's first act is to test whether the slice is already satisfied** — specs do get overtaken
      between authoring and build, and a session that discovers this at recon closes in minutes while one
      that assumes the work is pending rebuilds what already exists.
@@ -199,7 +202,7 @@ sessions/                        WHO PUTS IT THERE
    which spec moves it, and have the others leave it alone.
 
 4. **Name the RESEARCH the effort came from, in the umbrella, by path.** The idea that fed this work
-   archives *with* it — that is how a topic folder ends up holding the whole arc from "thing we'd like to
+   archives *with* it — that is how its archive home ends up holding the whole arc from "thing we'd like to
    do" to "done." When the research doc already lives at `research/{topic}/`, it travels for free. **When
    it does not** — a standalone `research/{something}.md`, or several — the umbrella's `Source:` / Lineage
    is the only record that it belongs to this effort.
@@ -208,7 +211,13 @@ sessions/                        WHO PUTS IT THERE
    list, and a research doc nobody named is one that stays behind in the running tab after its effort has
    shipped. Two lines in the umbrella now saves a hunt through a shared folder later.
 
-5. **Stop.** The specs stay in `research/{topic}/`. Do NOT implement, do NOT touch living docs, do NOT
+5. **Name the archive destination when only you can.** Read `docs/_meta/docs-workflow.md` § The archive
+   convention (repository-owned). If where a pipeline files depends on something only this session knows
+   (which living feature the effort belongs to, say), resolve it now and write the path into the
+   umbrella's blockquote as an `Archive:` line; `spec-parent` hands it to the docs-process row and
+   `docs-process` files there. A convention that needs nothing from you needs no line.
+
+6. **Stop.** The specs stay in `research/{topic}/`. Do NOT implement, do NOT touch living docs, do NOT
    archive — those are later phases. Output the new files only.
 
 ## The `00-ignition-brief.md` template
@@ -231,7 +240,7 @@ requires no authoring at all.
 
 > You are the COORDINATOR of the {topic} pipeline. Read this, then the umbrella (01-*.md), then the
 > tracker (project-status.md — yours), then EVERY numbered spec before arming the first seat.
-<!-- meta: type=spec; status=draft; verified={date}; lineage=N -->
+{the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for `draft`}
 
 **Last verified against:** {date}, `{sha}`. Ignition re-verifies this brief against live HEAD and
 corrects drift; it does not re-author it.
@@ -320,7 +329,8 @@ stays short because a task buried in a run row cannot be diffed or reviewed the
 ```
 
 **Do not restate the ceremony here.** The coordinator's procedure lives in `spec-parent` and its policy
-rides the un-skippable policy suffix the control plane supplies; a brief that re-teaches them accretes
+is the one § This repository's rails (repository-owned) names, which a hosted run also carries in the
+un-skippable policy suffix the control plane supplies; a brief that re-teaches them accretes
 into prompt-law that breaks the coordinator it was meant to steer. The brief carries THIS RUN's
 choreography and nothing else.
 
@@ -338,7 +348,7 @@ viewer because they are instructions to the coordinator, not content for the hum
 # {Topic} — Project Status
 
 > The coordinator's ledger. Advanced at every session boundary, never reconstructed at close.
-<!-- meta: type=working; status=wip; verified={date}; lineage=N -->
+{the machine header docs/_meta/docs-workflow.md § Doc metadata (repository-owned) prescribes, at the word for `wip`}
 
 ## What this is
 {one paragraph}
@@ -434,9 +444,9 @@ to edit it directly.
   folder), the chat transcript, and any subagent reports vanish. Inline their load-bearing content; never
   point at ephemeral state as the source of truth. Cross-links to *other durable docs* are fine.
 - **Lifecycle.** Specs live in `research/{topic}/` through the build. When the effort ships, `docs-process`
-  archives the umbrella + every spec + the working docs together into `archive/{topic}/` — the spec set
-  *is* the design history.
-- **Anti-fabrication.** A spec's `<!-- meta: verified -->` is the date it was *authored against the code it
+  archives the umbrella + every spec + the working docs together into the home `docs-workflow.md` § The
+  archive convention (repository-owned) names, in its shape — the spec set *is* the design history.
+- **Anti-fabrication.** A spec's header verified date is the date it was *authored against the code it
   cites*, not a promise the code stays unchanged. Only write facts you actually checked this run.
 - **Author against the HEAD the run will start from — and know what that does not buy you.** Authoring close
   to HEAD reduces drift; it does not substitute for a seat reading the code. Specs authored against the

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
@@ -52,8 +54,8 @@ 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/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

@@ -43,7 +43,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} -->
 
 ---