@naswerks/engineering-loop 0.2.1 → 0.5.0

package/skills/init/scripts/doctor.mjs

@@ -5,6 +5,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
+import { OWNED, compareVersions, linesOf, bare, h2Index, findSection, railsItems } from './owned.mjs';
 
 const repo = resolve(process.argv[2] || process.cwd());
 const packRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
@@ -27,17 +28,54 @@ for (const f of FOLDERS) {
 }
 
 // ── 2. the two method docs and their stamp ──────────────────────────────────────────────────────
+// A repository rewrites the repository-owned sections of these two files to its own conventions, and the
+// loop text around them is its copy from whenever it was taken — the doctor grades neither. It reads the
+// version stamp (line 1, or the first line after a leading frontmatter block when the repository's own gate
+// requires one on every file under docs/) and whether each repository-owned heading is where a skill looks.
 const STAMP = /^<!-- naswerks-loop: version=([0-9]+\.[0-9]+\.[0-9]+[^ ]*) -->/m;
 for (const name of ['docs-workflow.md', 'engineering-loop.md']) {
   const p = join(repo, 'docs', '_meta', name);
   const text = read(p);
   if (text === null) { row('FAIL', `docs/_meta/${name}`, 'missing'); continue; }
-  const m = STAMP.exec(text.split('\n', 1)[0]);
-  if (!m) { row('FAIL', `docs/_meta/${name}`, 'no naswerks-loop stamp on line 1 — an unstamped copy cannot be told from a stale one'); continue; }
+  const m = STAMP.exec(firstBodyLine(text));
+  if (!m) { row('FAIL', `docs/_meta/${name}`, 'no naswerks-loop stamp on line 1 (or on the first line after a frontmatter block) — an unstamped copy cannot be told from a stale one'); continue; }
   if (!packVersion) { row('DEGRADE', `docs/_meta/${name}`, `stamped ${m[1]}; the pack's own version could not be read`); continue; }
   const cmp = compareVersions(m[1], packVersion);
-  if (cmp < 0) row('DEGRADE', `docs/_meta/${name}`, `stamp ${m[1]} is behind the pack ${packVersion} — diff against the pack's references/${name}`);
+  if (cmp < 0) row('DEGRADE', `docs/_meta/${name}`, `stamp ${m[1]} is behind the pack ${packVersion} — run init refresh: it adds this version's repository-owned sections and restamps, and never touches the loop text`);
   else row('ok', `docs/_meta/${name}`, `stamp ${m[1]}`);
+
+  // ── 2b. the repository-owned sections: present under the heading a skill looks them up by ─────────
+  const lines = linesOf(text);
+  const headings = h2Index(lines).map((h) => h.heading);
+  for (const space of OWNED.filter((o) => o.file === name)) {
+    if (headings.includes(space.heading)) row('ok', `docs/_meta/${name} ${space.heading}`, 'present');
+    else {
+      const was = space.earlier.find((h) => headings.includes(h));
+      row('DEGRADE', `docs/_meta/${name} ${space.heading}`, was
+        ? `unmarked (the copy says "${was}") — a skill finds this section by its heading; init refresh marks it`
+        : 'missing — a skill finds this section by its heading; init refresh adds it');
+    }
+  }
+
+  // ── 2c. the rails: every item the pack names is present, and none still carries its absent-line ───
+  const rails = OWNED.find((o) => o.file === name && o.heading.includes('rails'));
+  const sec = rails ? findSection(lines, rails.heading) : null;
+  if (sec) {
+    const section = lines.slice(sec.start, sec.end);
+    const items = railsItems(section);
+    const packItems = (() => {
+      const t = read(join(packRoot, 'references', name));
+      if (t === null) return [];
+      const pl = linesOf(t);
+      const ps = findSection(pl, rails.heading);
+      return ps ? railsItems(pl.slice(ps.start, ps.end)).map((it) => it.name) : [];
+    })();
+    for (const n of packItems.filter((n) => !items.some((it) => it.name.toLowerCase() === n.toLowerCase()))) {
+      row('DEGRADE', `rails: ${n}`, 'missing — init refresh adds it as its absent-line');
+    }
+    for (const it of items) row(/fill this in/i.test(it.text) ? 'DEGRADE' : 'ok', `rails: ${it.name}`, /fill this in/i.test(it.text) ? 'still the absent-line — fill it in (init drafts it from the scan)' : 'recorded');
+    if (!items.length && /fill this in/i.test(section.map(bare).join('\n'))) row('DEGRADE', 'rails', 'carries only the absent-line');
+  }
 }
 
 // ── 3. doc-index and its three repo slots ───────────────────────────────────────────────────────
@@ -56,6 +94,9 @@ for (const name of ['docs-workflow.md', 'engineering-loop.md']) {
 }
 
 // ── 4. the reading floor and the conditional docs ───────────────────────────────────────────────
+// A doc's status is read from whichever header the repository writes: the loop's own <!-- meta --> line,
+// or a YAML frontmatter block with a status key. The one word the doctor needs is `draft`, which both forms
+// spell the same way.
 const FLOOR = ['patterns/code-organization.md', 'patterns/backend-patterns.md', 'patterns/frontend-patterns.md', 'patterns/testing.md'];
 const STANDARD = ['patterns/codegen.md', 'patterns/state-management.md', 'patterns/ui-style-guide.md', 'patterns/design-tokens.md', 'patterns/long-running-workflows.md', 'infrastructure/realtime-events.md', 'infrastructure/background-work.md'];
 const roleRows = (() => { const t = read(join(repo, 'docs', '_meta', 'doc-index.md')); return t === null ? null : sectionOf(t, '## Role reading lists'); })();
@@ -70,20 +111,53 @@ function docRow(relPath, required) {
     else row('FAIL', `docs/${relPath}`, 'absent with no doc-index row saying it was not detected — a seat meeting this path has no answer');
     return;
   }
-  const meta = /<!-- meta:[^>]*status=([a-z]+)/.exec(text);
-  if (!meta) row('DEGRADE', `docs/${relPath}`, 'no <!-- meta --> line');
-  else if (meta[1] === 'draft') row('DEGRADE', `docs/${relPath}`, 'status=draft — scanned, not decided');
-  else row('ok', `docs/${relPath}`, `status=${meta[1]}`);
+  const status = statusOf(text);
+  if (status === null) row('DEGRADE', `docs/${relPath}`, 'no status in either header form (<!-- meta --> line or frontmatter status key)');
+  else if (status.value === 'draft') row('DEGRADE', `docs/${relPath}`, `status=draft (${status.layer}) — scanned, not decided`);
+  else row('ok', `docs/${relPath}`, `status=${status.value} (${status.layer})`);
   if (/<!-- init:/.test(text)) row('DEGRADE', `docs/${relPath}`, 'an <!-- init: --> instruction was left in the file');
 }
 
-// ── 4b. every path a Role reading lists row names resolves ─────────────────────────────────────
-if (roleRows !== null) {
-  for (const line of roleRows.split('\n').filter((l) => l.trim().startsWith('|') && !/^\|\s*-/.test(l.trim()) && !/^\|\s*Doc\s*\|/i.test(l.trim()))) {
-    for (const m of line.matchAll(/`((?:patterns|infrastructure|guides|features)\/[A-Za-z0-9_.-]+\.md)`|\]\((?:\.\.\/)?((?:patterns|infrastructure|guides|features)\/[A-Za-z0-9_.-]+\.md)\)/g)) {
-      const p = m[1] || m[2];
-      if (/not detected/i.test(line)) continue;
-      row(existsSync(join(repo, 'docs', p)) ? 'ok' : 'FAIL', `doc-index row: docs/${p}`, existsSync(join(repo, 'docs', p)) ? '' : 'the row names a path that does not exist');
+// ── 4b. the menu: its shape, and every doc it names ────────────────────────────────────────────
+// doc-index.md declares one of two shapes (docs-workflow.md § The repository-owned sections): menu=all lists
+// every living doc; menu=curated lists the docs the seats read and names the index that lists every doc. A
+// menu with no shape line is menu=all. Every doc a menu names must exist (a row saying `not detected` is
+// exempt); a curated menu's docs must also meet the loop's standard: a status in either header form, not
+// draft, and a `## Key Files` section.
+{
+  const menu = read(join(repo, 'docs', '_meta', 'doc-index.md'));
+  if (menu !== null) {
+    const line = /<!-- naswerks-loop: menu=([A-Za-z-]+)(?:;\s*index=(\S+?))?\s*-->/.exec(menu);
+    const shape = line ? line[1] : 'all';
+    if (!['all', 'curated'].includes(shape)) row('FAIL', 'menu shape', `menu=${shape} is not a shape the loop knows (all | curated)`);
+    else if (shape === 'curated') {
+      const index = line[2];
+      if (!index) row('DEGRADE', 'menu shape', 'menu=curated names no index of every doc, so docs-process cannot say where a new doc is registered');
+      else if (!existsSync(join(repo, index))) row('DEGRADE', 'menu shape', `menu=curated; its index ${index} does not exist`);
+      else row('ok', 'menu shape', `menu=curated; index=${index}`);
+    } else row('ok', 'menu shape', line ? 'menu=all' : 'menu=all (no shape line: the default)');
+
+    const named = new Set();
+    for (const l of menu.split('\n')) {
+      if (/not detected/i.test(l)) continue;
+      for (const m of l.matchAll(/(?:\]\(|`)(?:\.\.\/)?((?:guides|patterns|infrastructure|features)\/[A-Za-z0-9_./-]+\.md)/g)) named.add(m[1]);
+    }
+    const missing = [...named].filter((p) => !existsSync(join(repo, 'docs', p))).sort();
+    for (const p of missing) row('FAIL', `menu: docs/${p}`, 'the menu names a doc that does not exist');
+    if (shape === 'curated') {
+      for (const p of [...named].filter((q) => !missing.includes(q)).sort()) {
+        const text = read(join(repo, 'docs', p));
+        const short = [];
+        const st = statusOf(text);
+        if (st === null) short.push('no status in either header form');
+        else if (st.value === 'draft') short.push('status draft');
+        if (!/^## Key Files\b/m.test(text)) short.push('no ## Key Files');
+        row(short.length ? 'DEGRADE' : 'ok', `menu: docs/${p}`, short.length ? `below the loop's standard: ${short.join(', ')}` : "meets the loop's standard");
+      }
+    } else if (shape === 'all') {
+      const unnamed = livingDocs().filter((p) => !named.has(p) && !menu.includes(p));
+      for (const p of unnamed) row('DEGRADE', `menu: docs/${p}`, 'a living doc the menu does not name (menu=all) — add its row, or declare the menu curated');
+      if (!unnamed.length && !missing.length) row('ok', 'menu entries', `names every living doc (${named.size}), each present`);
     }
   }
 }
@@ -187,8 +261,47 @@ function sectionOf(text, heading) {
   for (let i = start + 1; i < lines.length; i++) { if (lines[i].startsWith('## ')) break; body.push(lines[i]); }
   return body.join('\n');
 }
-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 doc's status from whichever header it carries: the <!-- meta --> line first, then a frontmatter
+// `status:` key. Returns { value, layer } or null.
+function statusOf(text) {
+  const m = /<!-- meta:[^>]*\bstatus=([A-Za-z-]+)/.exec(text);
+  if (m) return { value: m[1], layer: 'meta line' };
+  const fm = frontmatterOf(text);
+  if (fm && fm.status !== undefined) return { value: fm.status, layer: 'frontmatter' };
+  return null;
+}
+// The leading YAML frontmatter block as flat key: value pairs (scalars only — that is all the doctor reads).
+function frontmatterOf(text) {
+  if (!text.startsWith('---\n')) return null;
+  const end = text.indexOf('\n---', 4);
+  if (end < 0) return null;
+  const out = {};
+  for (const line of text.slice(4, end).split('\n')) {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+    if (m) out[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+// The living docs a menu=all menu lists: every .md directly under the four living folders, and each
+// feature folder's own docs one level down (a filed effort's notes sit deeper and are history, not living).
+function livingDocs() {
+  const out = [];
+  for (const f of ['guides', 'patterns', 'infrastructure', 'features']) {
+    const dir = join(repo, 'docs', f);
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith('.md') && e.name !== 'README.md') out.push(`${f}/${e.name}`);
+      else if (f === 'features' && e.isDirectory()) {
+        for (const g of readdirSync(join(dir, e.name), { withFileTypes: true })) {
+          if (g.isFile() && g.name.endsWith('.md') && g.name !== 'README.md') out.push(`features/${e.name}/${g.name}`);
+        }
+      }
+    }
+  }
+  return out.sort();
+}
+function firstBodyLine(text) {
+  let body = text;
+  if (text.startsWith('---\n')) { const end = text.indexOf('\n---', 4); if (end >= 0) body = text.slice(end + 4).replace(/^\n+/, ''); }
+  return body.split('\n', 1)[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