@naswerks/engineering-loop 0.1.0

package/skills/docs-status/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: docs-status
+description: Read-only orientation at session start — what's recently archived, what's in progress in working/, and what ideas are waiting in research/. Use at session start or when the user asks for docs status, or runs docs-status.
+---
+
+# docs-status
+
+A quick, read-only pulse of the docs pipeline. No files created. Report by name with context, not
+just counts.
+
+## Steps
+
+1. **`working/` — in flight.** List each doc in `docs/working/` with a one-line "what it's about /
+   how far along." A folder's `README.md` is never a queue entry — skip it. These are active efforts; a non-empty queue means living docs may be going stale.
+
+2. **`research/` — waiting ideas.** List each doc in `docs/research/` (and topic subfolders) by name
+   with a one-line hook. This is the backlog of things to pick up next.
+
+3. **`archive/` — recently done.** List the most recently modified topic folders / session docs in
+   `docs/archive/` (a handful, newest first) so the user can see what just shipped.
+
+4. **Meta sweep — the condensed status table.** Run `rg -o '<!-- meta:.*-->' docs/` and parse each
+   `type · status · verified · lineage` into a compact one-line-per-doc table (group by folder). This is the
+   headline pulse — richer than the old date-only scan. Read-only; do not write anything. Flag, in order of
+   concern:
+   - **missing-meta** — a living doc (`guides/ patterns/ infrastructure/ features/`) with no `<!-- meta:`
+     comment. Read its blockquote `Last verified` instead (back-compat: read either, **prefer the
+     comment**) and list it as a gap to fill.
+   - **stale** — `verified` older than ~14 days, a candidate for `docs-audit-feature` (the existing nudge;
+     note the harder 90-day line the future `docs_freshness` tool will use).
+   - **dead lineage** — a `## Lineage` link whose target file no longer exists (a broken breadcrumb).
+   - **low-lineage feature** — `lineage=0` on a `type=feature` doc = ungrounded; worth wiring its lineage.
+
+5. **Open issues.** Grep living docs for an `## Open Issues` section; list which docs/features carry
+   unresolved, code-verified problems (and how many) so known risks surface at orientation instead of
+   rotting silently. These are candidates to fix, or to graduate into a `working/` effort.
+
+6. **Recommend a next action, escalating by scale:**
+   - Working queue non-empty: "process the working doc X" first.
+   - Clear: "pick up research idea Y" (with a one-line why).
+   - A few stale docs: `docs-audit-feature` on those specific docs.
+   - **Many stale docs, or a long absence (~30+ days of no doc activity)**: recommend `docs-audit-full`
+     to get a prioritized re-verify plan instead of one-off audits.
+
+## Notes
+- Output is a conversational summary only. There is no backlog doc and no release doc to read —
+  `working/`, `research/`, and `archive/` ARE the status.

package/skills/docs-write/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: docs-write
+description: Finalize the working doc at the end of an implementation session and leave it in docs/working/ as the queue for docs-process to patch + file. Use at the end of a coding session, when the user says to write up the work, document the session, book-end it, or run docs-write.
+---
+
+# docs-write
+
+Capture an implementation session into a finished session doc that **stays in `docs/working/`** as the
+queue for `docs-process`. This is the **first** half of the bookend — it does NOT patch living docs and
+does NOT archive. Both happen in `docs-process`, once the living docs are patched and verified against
+code. Leaving the doc in `working/` is what makes `working/` a real queue (`docs-status` reads it) and
+keeps the doc editable until its living-doc obligations are discharged.
+
+## Steps
+
+1. **Review what happened** — prefer conversation memory (you just did the work). Use `git diff --stat` only as a fallback to confirm file paths.
+
+2. **Write/finish the working doc.** If a doc for this effort already exists in `docs/working/`, finish it; otherwise create `docs/working/{topic}-{description}.md`. Use the session-doc template in `docs/_meta/docs-workflow.md`. Required sections:
+   - Title + one-line summary; completion date; branch
+   - **Meta-comment** — directly below the blockquote, emit one line: `<!-- meta: type=working; status={wip|shipped}; verified={today}; lineage=N -->` (see "Doc metadata" in `docs-workflow.md`). `lineage` = the count of provenance links the doc carries (`Source:` + `Builds on` + any `## Lineage` rows).
+   - **Session-comment** — next line: `<!-- session: claude-session-id={the harness's session id} -->` (Claude Code: `$CLAUDE_CODE_SESSION_ID` / `$env:CLAUDE_CODE_SESSION_ID`). Applies to EVERY session that writes a working doc — solo sessions with no pipeline, no coordinator, and no research doc included; the id alone is the point. Append `; name={...}` only when the session actually has a human-given window name (pipeline seats do; most solo sessions won't — omit it, never invent one). The harness's transcript store is ephemeral (a retention window, and the format moves between releases); this line is the durable link from the work to its conversation, so audit-grade sessions can be found later.
+   - **Builds on** — if this continues prior work, link the prior doc: `Builds on [prior](prior.md)`
+   - **Source** — if idea-driven, link the `research/` doc
+   - **The Problem** / **The Target**
+   - **Research & Decisions** — options, verdicts, rationale (table). Write this for **future us**: capture **what we actually did vs. what we set out to do** (where the plan changed and why), **what we tried that didn't work** (dead-ends, gotchas, abandoned approaches — so nobody re-walks them), and **every decision we made** with its reasoning. The point of a session doc is the narrative a later session can't reconstruct from the diff: the diff shows the final state, not the choices or the things that failed on the way there.
+   - **Implementation** — what changed, before/after where useful
+   - **Change shape** — orientation, NOT a file-by-file inventory (the commit is the inventory). Name the key new/moved pieces and the structural facts a later session needs; defer the full list to the commit. A file-by-file dump makes the doc read like a review.
+   - **Verification** — build/test results; what's tested, what isn't
+   - **Watch-Outs** — edge cases, gotchas
+   - **Living Docs to Update** — the bridge to `docs-process`. For each stale living doc, name it and say what changed and in what form. Be specific ("references `OldEntity`, should be `NewEntity`"), not vague.
+
+3. **Record the archive target — don't move the file.** Add an `## Archive` line to the doc naming the intended **topic folder** under `docs/archive/{topic}/` (reuse an existing topic folder; descriptive name, **no numeric prefixes** — the `Builds on` link is the ordering). `docs-process` files it there later. The doc itself **stays in `docs/working/`**.
+
+4. **Stop.** The finished doc sits in `docs/working/` as the queue. Do NOT patch living docs, do NOT grep for stale references, do NOT move it to `archive/` — all of that is `docs-process`.
+
+## Notes
+- **Provenance carries into the living docs.** The `Source:` (research) and `Builds on` (prior working) links
+  in the blockquote already *are* lineage edges — at `docs-process` time they populate the living doc's
+  `## Lineage` (`Idea` / `Built` rows). Optionally also render a `## Lineage` block in the working doc itself
+  for symmetry, but the blockquote links are the load-bearing record.
+- **Write for future us, not for review.** Record **what we did vs. what we thought we were going to do**, **what we tried that didn't work**, and **the decisions we made (and why)**. Those three are the load-bearing content — the commit already captures the final file state; the doc captures the reasoning, the reversals, and the dead-ends so the next session doesn't repeat them.
+- The doc becomes frozen history only when `docs-process` files it into `docs/archive/` (after the living docs are patched). Until then it's editable in `working/`.
+- If the work was pure research/exploration with no code change, use `docs-backlog` instead.

package/skills/init/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: init
+description: Make a repository able to run the loop — create the docs/ shape, the two method docs, a scanned first draft of every doc the loop's skills read, the doc-index menu with the repo's own slots, the Start-here stanza and the plugin pin; then say what is still missing. Run init in a repository that has none of this; run init doctor to check one that does. A second init writes nothing and prints the doctor report.
+---
+
+# init
+
+Every seat the loop arms reads `docs/_meta/*` and a floor of `patterns/*` docs before it writes a line;
+the coordinator keeps a tracker in `docs/research/{topic}/`; `docs-write` files into `docs/working/`; the
+control plane admits a spec folder only when the repository carries `docs/_meta/docs-workflow.md`.
+`init` creates all of that in a repository that has none of it — as REAL first drafts scanned off the
+repo, never as empty headings — and `init doctor` says, per path, whether the loop can run.
+
+**Two invocations:** `init` (create what is missing, then the report) · `init doctor` (the report only).
+A second `init` writes nothing and IS the doctor report.
+
+**The law of the draft:** a section is filled only from files the scan opened, and every drafted doc
+names them in its provenance line. Stack, trees, commands, config keys and Key Files are copied verbatim.
+**Rules and gotchas are never invented** — a rule is written only when the repository already wrote it
+down somewhere (a CONTRIBUTING, an analyzer config, a lint rule, a base-class docstring), and the bullet
+cites that file. A section with nothing to fill carries the literal absent-line and nothing else:
+
+```
+No {X} detected — fill this in: {what the section must answer}.
+```
+
+The loop itself supplies exactly three seed rules that need no source: never hand-write a generated
+folder (when one exists); suites run serially with the output captured to a UTF-8 file and the summary
+block read, never the exit code alone; a pin must be able to fail.
+
+## What init creates — the closed set
+
+```
+docs/
+  _meta/docs-workflow.md          a byte copy of the pack's references/docs-workflow.md (stamped)
+  _meta/engineering-loop.md       a byte copy of references/engineering-loop.md (stamped)
+  _meta/doc-index.md              the menu, written LAST — every doc that exists + three repo slots:
+                                  ## Role reading lists · ## Apps and their build commands · ## The evidence tools
+  research/ working/ archive/ guides/ patterns/ infrastructure/ features/     each with a README.md
+  patterns/vertical-slice-anatomy.md  patterns/backend-patterns.md  patterns/frontend-patterns.md
+  patterns/testing.md  patterns/codegen.md                          the floor — always drafted
+  patterns/state-management.md  patterns/ui-style-guide.md
+  infrastructure/realtime-events.md  infrastructure/background-work.md   only when the scan finds the concern
+CLAUDE.md                          the Start-here stanza appended (created with only the stanza if absent)
+AGENTS.md                          the same stanza, only when the file already exists
+.claude/settings.json              the plugin pin merged in (never clobbers existing keys)
+```
+
+Eight folders, and the set is closed. Anything else already under `docs/` is left alone and reported as
+"outside the loop's shape — not touched" — never an error, never a queue entry.
+
+**Every template lives at the pack root under `templates/`** (`templates/docs/patterns/*.md`,
+`templates/docs/infrastructure/*.md`, `templates/docs/_meta/doc-index.md`, `templates/docs/readme-*.md`,
+`templates/claude-md-stanza.md`, `templates/settings-pin.json`). Under Claude Code the pack root is
+`${CLAUDE_PLUGIN_ROOT}` and this skill's own folder is `${CLAUDE_SKILL_DIR}`; in another harness, the
+pack root is the folder that holds `.claude-plugin/plugin.json` — two levels above this SKILL.md.
+
+## The scan — read everything first, write nothing yet
+
+Run all three passes with your file tools before the first write. Keep a table in your turn — `file ·
+what it says` — and cite from it. A draft written mid-scan is a draft written from memory.
+
+1. **Refuse outside a git repository**: `git rev-parse --show-toplevel` (the refusal is
+   `init-needs-a-git-repository`). Everything below is relative to that root.
+2. **The stacks.** `*.sln`, `*.slnx`, `*.csproj`, `Directory.Build.props`, `Directory.Packages.props` ·
+   `package.json` (+ lockfile, `workspaces`), `pnpm-workspace.yaml` · `pyproject.toml`, `setup.cfg`,
+   `requirements*.txt` · `go.mod` · `Cargo.toml` · `Gemfile` · `pom.xml`, `build.gradle*`. Frameworks and
+   versions by dependency name.
+3. **The commands and the shape.** Test runners and scripts (`package.json` `scripts`, `Makefile`,
+   `justfile`, `scripts/*`) · CI workflow files (`.github/workflows/*.yml`, `azure-pipelines.yml`,
+   `.gitlab-ci.yml`) — the jobs are the lanes · app roots (`angular.json` projects, `apps/*`,
+   `packages/*`, `web/*` and `services/*` under `src/`, `cmd/*`, an executable `*.csproj`) · `generated/` folders
+   and codegen configs (`codegen.ts`, `codegen.yml`, `openapi*`, `*.proto`, `tgconfig.json`, `prisma/`) ·
+   the folder layout two deep · `git log --oneline -20` (the message convention) · a realtime library
+   (signalr, socket.io, ws, sse, pusher, ably) · a state library (ngxs, ngrx, redux, zustand, pinia,
+   mobx) · a UI library or tokens file (tailwind, daisyui, mui, chakra, bootstrap, shadcn) · a queue,
+   worker or scheduler (a service bus, RabbitMQ, SQS, BullMQ, Hangfire, Quartz, Celery, sidekiq).
+4. **The rules the repository already wrote down.** `CONTRIBUTING.md`, `CLAUDE.md`, `AGENTS.md`, a
+   README "Conventions" section · `.editorconfig`, eslint / biome / prettier / stylelint configs ·
+   analyzer configs (`.stylecop`, `.globalconfig`, `Directory.Build.props` rules such as
+   `TreatWarningsAsErrors`, `Nullable`, banned-API lists) · `tsconfig*.json` strictness ·
+   `BannedSymbols.txt`, `FLAKY-TESTS.md` · CODEOWNERS · `.husky/`, `.githooks/` · PR templates · the
+   existing `docs/` tree · `.claude/settings.json`.
+
+## The write order — create-if-missing at every step
+
+An existing file always wins and is reported `repo-owned`, whether it is a draft or not, loop-shaped or
+not. `init` never overwrites, never reorders, never deletes.
+
+1. The seven folders, each with its `README.md` from `templates/docs/readme-{folder}.md` — the README is
+   the only file init writes into a folder that already exists.
+2. `docs/_meta/docs-workflow.md` and `docs/_meta/engineering-loop.md` — byte copies of the pack's
+   `references/*` (their first line is the version stamp; copy it with the file).
+3. The five floor drafts from `templates/docs/patterns/*.md`, filled as below.
+4. The conditional drafts — `state-management`, `ui-style-guide`, `realtime-events`, `background-work` —
+   only where pass 3 found the concern.
+5. `docs/_meta/doc-index.md` from its template, LAST, listing every doc that now exists under the four
+   living folders (drafted or repo-owned), the three repo slots filled from the scan.
+6. The Start-here stanza (`templates/claude-md-stanza.md`) appended to `CLAUDE.md` (created if absent)
+   and to `AGENTS.md` (only if present); skipped when the opening marker
+   `<!-- naswerks-loop:start-here -->` is already there.
+7. `.claude/settings.json` — merge the two keys from `templates/settings-pin.json`; create the file if
+   absent; never remove or reorder existing keys.
+
+Then the report: one table, one row per path — `created` · `repo-owned` · `skipped: marker present` —
+followed by the doctor verdict line.
+
+## Filling a template
+
+Every template section carries an `<!-- init: scan … fill … absent … -->` instruction with three parts:
+**scan** (what to read), **fill** (what a real fill looks like — a fenced command, a tree, a table row),
+**absent** (the exact line to write when nothing was found). Replace the comment with the fill or the
+absent-line; **never leave an `<!-- init: -->` comment in the output** (`doctor` reads one as DEGRADE).
+Replace `{today}` with today's date and `{files}` in the provenance line with the comma-separated files
+the scan opened for that doc.
+
+The shape every drafted doc keeps — because it is the shape the seats know how to read:
+
+1. the H1, the one-line blockquote ending `Last verified {today}.`, the `<!-- meta: … status=draft … -->`
+   line, the `<!-- naswerks-loop: draft; scanned=… -->` line;
+2. Overview, then Stack, then the shape (a tree copied from a REAL folder), then one section per
+   concept in the micro-grammar *prose rule, a REAL example, `### Rules`, `### Gotcha:`*;
+3. decision tables that decide, checklists whose items are real paths, a `Legacy (never use)` column
+   where the repo has one;
+4. exact commands in fenced blocks; identifiers in backticks;
+5. `## Key Files`, `## Lineage`.
+
+A section the scan can only half-fill says which half. A rule with no cited source is not written.
+
+## doctor
+
+`node ${CLAUDE_SKILL_DIR}/scripts/doctor.mjs [repo-root]` — the `scripts/` folder beside this SKILL.md;
+Node 22 or later, no dependencies. It prints one row per thing the skills read and exits non-zero on any
+FAIL, so a CI job or a control plane can call it.
+
+| Row | FAIL | DEGRADE | ok |
+|---|---|---|---|
+| each of the eight folders | missing | README missing | present |
+| `_meta/docs-workflow.md`, `_meta/engineering-loop.md` | missing, or no stamp on line 1 | stamp behind the pack's version | stamp equals it |
+| `_meta/doc-index.md` and its three slot sections | missing | a slot carries only the absent-line | filled |
+| the five floor docs | missing | `status=draft`, or an `<!-- init: -->` left in | `status=current` |
+| the four conditional docs | — | `status=draft` when present | present and current, or absent |
+| `CLAUDE.md` / `AGENTS.md` stanza · `.claude/settings.json` pin | — | missing | present |
+| `verify-staged` | — | not on PATH (the row carries the fallback) | resolvable |
+| every `docs/research/*/00-ignition-brief.md` | the five problems the control plane's parser emits (no `## The kick`; the kick has no blockquote; no `## The sequence`; the sequence holds no table; a row names no kind from `coordinator build fixit review retro witness docs-process`), or a spec a row names is missing from disk | — | clean |
+| every `docs/working/*.md` | — | lacks `## Living Docs to Update` or `## Archive` | carries both |
+| anything else under `docs/` | — | — | "outside the loop's shape — not touched" |
+
+**If `node` is absent**, walk the same rows by hand with your file tools, in that order, and print the
+same table: the checks are file existence, a first-line stamp, a heading grep, a `status=` read, and the
+brief's two sections.
+
+A repository fresh from `init` reads DEGRADE on every draft and ok on the shape. That is the intended
+state: the owner promotes each draft to `status=current` as they confirm it, section by section.
+
+## Notes
+
+- `init` is the front door of the pack; `docs-status` is the pulse after it. Run `docs-status` once the
+  drafts are promoted to see the queue the way a session will.
+- The floor is always drafted, even in a repository with no frontend or no codegen — the reading floor
+  must RESOLVE for every seat kind, and "No frontend detected — fill this in" is an honest doc.
+- Counterpart skills: `spec-seat` (reads the floor), `spec-child` (reads the role rows), `spec-pipeline`
+  (writes the brief `doctor` checks), `docs-write` / `docs-process` (the queue `doctor` reads).

package/skills/init/scripts/doctor.mjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// doctor — can the loop run in this repository? One row per thing the skills read, a verdict per row,
+// non-zero exit on any FAIL. Node >= 22, no dependencies. Usage: node doctor.mjs [repo-root]
+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';
+
+const repo = resolve(process.argv[2] || process.cwd());
+const packRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const rows = [];
+const row = (verdict, subject, detail = '') => rows.push({ verdict, subject, detail });
+const read = (p) => (existsSync(p) ? readFileSync(p, 'utf8').replace(/\r\n/g, '\n') : null);
+const rel = (p) => p.slice(repo.length + 1).replace(/\\/g, '/');
+
+// ── the pack's own version, for the stamp check ─────────────────────────────────────────────────
+let packVersion = null;
+try { packVersion = JSON.parse(readFileSync(join(packRoot, '.claude-plugin', 'plugin.json'), 'utf8')).version; } catch { /* reported below */ }
+
+// ── 1. the eight folders ────────────────────────────────────────────────────────────────────────
+const FOLDERS = ['_meta', 'research', 'working', 'archive', 'guides', 'patterns', 'infrastructure', 'features'];
+if (!existsSync(join(repo, 'docs'))) row('FAIL', 'docs/', 'missing — run init');
+for (const f of FOLDERS) {
+  const p = join(repo, 'docs', f);
+  if (!existsSync(p)) row('FAIL', `docs/${f}/`, 'missing');
+  else if (f !== '_meta') row(existsSync(join(p, 'README.md')) ? 'ok' : 'DEGRADE', `docs/${f}/README.md`, existsSync(join(p, 'README.md')) ? '' : 'missing (init writes it)');
+}
+
+// ── 2. the two method docs and their stamp ──────────────────────────────────────────────────────
+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; }
+  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}`);
+  else row('ok', `docs/_meta/${name}`, `stamp ${m[1]}`);
+}
+
+// ── 3. doc-index and its three repo slots ───────────────────────────────────────────────────────
+{
+  const p = join(repo, 'docs', '_meta', 'doc-index.md');
+  const text = read(p);
+  if (text === null) row('FAIL', 'docs/_meta/doc-index.md', 'missing');
+  else {
+    for (const heading of ['## Role reading lists', '## Apps and their build commands', '## The evidence tools']) {
+      const section = sectionOf(text, heading);
+      if (section === null) row('FAIL', `doc-index.md ${heading}`, 'section missing');
+      else if (/fill this in|\(none detected\)/i.test(section)) row('DEGRADE', `doc-index.md ${heading}`, 'present, carries only the absent-line');
+      else row('ok', `doc-index.md ${heading}`, '');
+    }
+  }
+}
+
+// ── 4. the reading floor and the conditional docs ───────────────────────────────────────────────
+const FLOOR = ['patterns/vertical-slice-anatomy.md', 'patterns/backend-patterns.md', 'patterns/frontend-patterns.md', 'patterns/testing.md', 'patterns/codegen.md'];
+const CONDITIONAL = ['patterns/state-management.md', 'patterns/ui-style-guide.md', 'infrastructure/realtime-events.md', 'infrastructure/background-work.md'];
+for (const d of FLOOR) docRow(d, true);
+for (const d of CONDITIONAL) docRow(d, false);
+function docRow(relPath, required) {
+  const text = read(join(repo, 'docs', relPath));
+  if (text === null) { row(required ? 'FAIL' : 'ok', `docs/${relPath}`, required ? 'missing' : 'absent (drafted only when the scan finds the concern)'); 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]}`);
+  if (/<!-- init:/.test(text)) row('DEGRADE', `docs/${relPath}`, 'an <!-- init: --> instruction was left in the file');
+}
+
+// ── 5. CLAUDE.md / AGENTS.md stanza, settings pin ───────────────────────────────────────────────
+for (const name of ['CLAUDE.md', 'AGENTS.md']) {
+  const text = read(join(repo, name));
+  if (text === null) { if (name === 'CLAUDE.md') row('DEGRADE', name, 'missing (init creates it with the stanza)'); continue; }
+  row(text.includes('<!-- naswerks-loop:start-here -->') ? 'ok' : 'DEGRADE', `${name} stanza`, text.includes('<!-- naswerks-loop:start-here -->') ? '' : 'the Start-here stanza is not present');
+}
+{
+  const p = join(repo, '.claude', 'settings.json');
+  const text = read(p);
+  if (text === null) row('DEGRADE', '.claude/settings.json', 'missing (init writes the plugin pin)');
+  else {
+    try {
+      const j = JSON.parse(text);
+      const mk = j.extraKnownMarketplaces && j.extraKnownMarketplaces['engineering-loop'];
+      const en = j.enabledPlugins && j.enabledPlugins['naswerks@engineering-loop'] === true;
+      row(mk && en ? 'ok' : 'DEGRADE', '.claude/settings.json pin', mk && en ? '' : `${mk ? '' : 'extraKnownMarketplaces.engineering-loop missing; '}${en ? '' : 'enabledPlugins["naswerks@engineering-loop"] missing'}`);
+    } catch { row('DEGRADE', '.claude/settings.json', 'not valid JSON'); }
+  }
+}
+
+// ── 6. verify-staged resolvable ─────────────────────────────────────────────────────────────────
+{
+  let ok = false;
+  for (const [cmd, args] of [['verify-staged', ['--help']], ['npx', ['--no-install', 'verify-staged', '--help']]]) {
+    try { execFileSync(cmd, args, { stdio: 'ignore', shell: process.platform === 'win32', timeout: 15000 }); ok = true; break; } catch { /* next */ }
+  }
+  const packBin = join(packRoot, 'bin', 'verify-staged.mjs');
+  if (ok) row('ok', 'verify-staged', 'on PATH');
+  else if (existsSync(packBin)) row('DEGRADE', 'verify-staged', `not on PATH; the skills' fallback is: node ${packBin.replace(/\\/g, '/')} {list}`);
+  else row('DEGRADE', 'verify-staged', 'not on PATH and the pack bin was not found — install the pack (npm i -g @naswerks/engineering-loop)');
+}
+
+// ── 7. every ignition brief, checked the way the control plane checks it ────────────────────────
+const KINDS = new Set(['coordinator', 'build', 'fixit', 'review', 'retro', 'witness', 'docs-process']);
+const researchDir = join(repo, 'docs', 'research');
+if (existsSync(researchDir)) {
+  for (const topic of readdirSync(researchDir)) {
+    const briefPath = join(researchDir, topic, '00-ignition-brief.md');
+    if (!statSync(join(researchDir, topic)).isDirectory() || !existsSync(briefPath)) continue;
+    const text = read(briefPath);
+    const problems = [];
+    const kick = sectionOf(text, '## The kick');
+    if (kick === null) problems.push('the brief has no `## The kick` section, so the task text could not be read');
+    else if (!kick.split('\n').some((l) => l.trimStart().startsWith('>'))) problems.push('the `## The kick` section carries no blockquote; its whole text stands in for the task');
+    const seq = sectionOf(text, '## The sequence');
+    if (seq === null) problems.push('the brief has no `## The sequence` section, so no seats could be read');
+    else {
+      const tableRows = seq.split('\n').filter((l) => l.trim().startsWith('|'));
+      if (tableRows.length === 0) problems.push('the `## The sequence` section holds no table, so no seats could be read');
+      for (const line of tableRows.slice(1)) {
+        const cells = line.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map((c) => c.trim().replace(/^`|`$/g, '').trim());
+        if (cells.every((c) => /^[-: ]*$/.test(c))) continue;
+        if (!cells.some((c) => KINDS.has(c))) { problems.push(`a sequence row names no seat kind and composes nothing: \`${line.trim()}\``); continue; }
+        const spec = cells.map((c) => /\b(\d{2}-[A-Za-z0-9._-]*?\.md)\b/.exec(c)).find(Boolean);
+        if (spec && !existsSync(join(researchDir, topic, spec[1]))) problems.push(`the sequence names \`${spec[1]}\` and it is missing from disk`);
+      }
+    }
+    if (problems.length) for (const pr of problems) row('FAIL', `docs/research/${topic}/00-ignition-brief.md`, pr);
+    else row('ok', `docs/research/${topic}/00-ignition-brief.md`, 'the kick and the sequence read clean');
+  }
+}
+
+// ── 8. the working queue's shape ────────────────────────────────────────────────────────────────
+const workingDir = join(repo, 'docs', 'working');
+if (existsSync(workingDir)) {
+  for (const f of readdirSync(workingDir).filter((f) => f.endsWith('.md') && f !== 'README.md')) {
+    const text = read(join(workingDir, f));
+    const missing = ['## Living Docs to Update', '## Archive'].filter((h) => !text.includes(h));
+    row(missing.length ? 'DEGRADE' : 'ok', `docs/working/${f}`, missing.length ? `lacks ${missing.join(' and ')}` : 'carries its checklist and its archive target');
+  }
+}
+
+// ── 9. anything else under docs/ ────────────────────────────────────────────────────────────────
+if (existsSync(join(repo, 'docs'))) {
+  for (const entry of readdirSync(join(repo, 'docs'))) {
+    if (FOLDERS.includes(entry)) continue;
+    row('ok', `docs/${entry}`, 'outside the loop\'s shape — not touched');
+  }
+}
+
+// ── report ──────────────────────────────────────────────────────────────────────────────────────
+const width = Math.max(...rows.map((r) => r.subject.length), 10);
+console.log(`doctor — ${repo}${packVersion ? ` — pack ${packVersion}` : ''}\n`);
+console.log(`| verdict | subject${' '.repeat(width - 7)} | detail |`);
+console.log(`|---------|${'-'.repeat(width + 2)}|--------|`);
+for (const r of rows) console.log(`| ${r.verdict.padEnd(7)} | ${r.subject.padEnd(width)} | ${r.detail} |`);
+const count = (v) => rows.filter((r) => r.verdict === v).length;
+console.log(`\nFAIL ${count('FAIL')} · DEGRADE ${count('DEGRADE')} · ok ${count('ok')}`);
+process.exit(count('FAIL') ? 1 : 0);
+
+// ── helpers ─────────────────────────────────────────────────────────────────────────────────────
+function sectionOf(text, heading) {
+  const lines = text.split('\n');
+  const start = lines.findIndex((l) => l.trimEnd().toLowerCase().startsWith(heading.toLowerCase()));
+  if (start < 0) return null;
+  const body = [];
+  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;
+}

package/skills/spec-child/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: spec-child
+description: The BUILD JOB for a pipeline seat — one spec, the role's reading list, the pin taxonomy, the suite protocol, and the fixit variant. Composed AFTER spec-seat, which carries the seat contract (blackboard, question lane, verdicts, FINAL TLDR, close-out). Use when a prompt says you are a build or fixit session, or run spec-child {role} {spec-path}. Roles: backend | frontend | mixed.
+---
+
+# spec-child
+
+**Your seat contract is `spec-seat` — invoke it first if you have not.** It carries the blackboard, the
+question lane, the parked-call discriminator, the verdict vocabulary, the BELIEFS sha, git shapes, the
+six-section FINAL TLDR, and the close-out order. **This file is the BUILD JOB only**, and it refines that
+contract — where the two genuinely conflict, that is a finding to report, not a fork to resolve quietly.
+
+You build exactly one spec. The coordinator judges and rules; you recon, plan, build, and report honestly.
+Hand-cranked, a human relays messages; hosted inside a pipeline, your coordinator drives you itself and
+the relay is machine-carried — **your contract is identical either way.**
+
+Invoked as `spec-child {role} {spec-path}`, or told "you are a build session" with the spec path.
+
+## Step 1 — with your role and spec in hand
+
+**If your prompt handed you a MANIFEST, that manifest is your reading list and this section does not
+apply** (`spec-seat`, Step 0). This list is for a build seat working from a spec.
+
+1. **Your spec** — fully, INCLUDING any Addendum sections. It is self-contained.
+2. **The umbrella** (`01-{topic}.md`) — settled decisions; don't relitigate them.
+3. **The tracker** — `docs/research/{topic}/project-status.md`. The coordinator's live journal and
+   READ-ONLY to you. Prior session rows, deferred findings, and process incidents are your contract: build
+   against what ACTUALLY shipped, not the spec's guesses. **If anything in it disagrees with your spec or
+   doesn't make sense, say so in your PLAN TLDR** — asking is always allowed.
+4. **Your role's adds** (below) + any extra docs the prompt names.
+5. **Grep the living docs' `## Open Issues` for your subject.** One command, and it is the step efforts
+   keep skipping: a defect can sit dated and described in a living doc while several seats check the code
+   and conclude it is new.
+
+## Role — the adds, on top of spec-seat's Step 0 floor
+
+| Role | Adds |
+|---|---|
+| **frontend** | `patterns/state-management.md` · `patterns/ui-style-guide.md` · `infrastructure/realtime-events.md` (the poke/refetch concept trips sessions up — read it even for "pure UI" work) · plus your role's rows in `docs/_meta/doc-index.md` § Role reading lists |
+| **backend** | `infrastructure/realtime-events.md` (the poke/refetch concept trips sessions up — read it even for "pure API" work) · `infrastructure/background-work.md` as the task warrants · plus your role's rows in `docs/_meta/doc-index.md` § Role reading lists |
+| **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 surface the repo names only in `docs/_meta/doc-index.md` § Role reading lists (a sidecar, a CLI, a worker) reads the row there; docs work needs nothing beyond the Step 0 floor |
+
+A role is *which docs does this build session read* — nothing else. Jobs are SEAT KINDS, not roles:
+`docs-process` is a session type of its own, and a spec that touches a surface with no role of its own is
+`mixed` with that surface's row. A doc-index row that says "no X detected" is an honest answer from `init`:
+that concern is not in this repo yet, and there is nothing to read for it.
+
+## Recon — the build seat's first act
+
+**Re-verify EVERY anchor your spec cites against HEAD** — specs age and prior sessions move line numbers,
+so **report drift, don't trust**. **Recon's first act is to test whether the slice is already satisfied**:
+specs do get overtaken between authoring and build, and discovering that at recon closes a session in
+minutes while assuming the work is pending rebuilds what already exists.
+
+Run `git status`; identify which dirty files are yours-to-be vs NOT yours (coordinator-owned docs appear
+mid-run — never stage them). Answer any STANDING RECON QUESTION your spec or prompt carries.
+
+**Measure your own baseline for any lane you touch, BEFORE you edit.** A same-day coordinator-verified
+baseline is an acceptable substitute when cited, but measuring your own is the norm — and a number you
+cannot reproduce is a finding.
+
+## Build
+
+State your HEAD sha again in your FIRST implementation message (the coordinator diffs your beliefs
+against its ledger — stale-tree catches come from this).
+
+**If HEAD moves mid-build**: disclose FIRST in your next report — old sha to new sha, clean-ancestor or
+not, `git diff --stat` overlap with YOUR files, and proof of coexistence if any overlap (marker greps +
+suite on the combined tree). **Absorb-and-prove, never silently rebase your beliefs.**
+
+**Before you delete a pin, ask what it encodes.** A pin that describes the **MECHANISM** you are removing
+dies with it ("this verb is seat evidence"). A pin that encodes a **DECISION** — a boundary verdict, an
+accepted residual, a known-positive control — dies with nothing, and removing it vacates a ruling nobody
+made. **When in doubt it is a DECISION: say so and ask.**
+
+**If ANY existing test requires modification to pass, STOP and report.** A test needing an edit is the
+signal that a VERDICT changed, not that the test is stale.
+
+## The suite protocol
+
+Run the suite lanes **SERIALLY** — the lanes and their exact invocations are `patterns/testing.md`
+§ Running tests; concurrent runs flake.
+
+**Capture FULL runner output to a UTF-8 file and search failures by name** — redirect to a file, then
+search `^failed ` / `Failed!`. Piping through a "last N lines" filter destroys failure names.
+
+### USE `rg`, NOT `grep`, FOR ANYTHING THAT MIGHT NOT BE ASCII — AND NEVER TRUST A LOCAL TEST
+
+**Two instruments return `0` for text that is present.** Both are silent: they exit clean and read as
+"not found", which is indistinguishable from a correct negative.
+
+| instrument | the lie | measured |
+|---|---|---|
+| `grep` on a non-ASCII pattern | **locale-dependent** — the SAME binary on the SAME file | `LANG` unset: 64 · `LC_ALL=C`: 64 · `LANG=en_US.UTF-8`: 0 |
+| PowerShell `Get-Content -Raw` | reads UTF-8 as the ANSI codepage | with `-Encoding utf8`: 83 · without: 0 |
+
+**THE LOCALE ONE IS WHY "IT WORKS FOR ME" IS NOT EVIDENCE.** Whether your shell exports `LANG` is not
+something you chose or can see, two seats on one machine can disagree, and an ASCII control passes in both
+— so a test that "proves" grep is fine proves only that your environment is the lucky one. `rg` is
+unaffected under every locale above.
+
+**So:** `rg` for content search, always. `Get-Content` only with `-Encoding utf8`. And author regexes with
+your file tools, never through a shell heredoc — a heredoc can collapse `\\s` to `\s` and break both a pin
+and that pin's own control, so neither can announce the other.
+
+**PowerShell 5.1 `Tee-Object` writes UTF-16** — `rg` detects the BOM and reads it; plain `grep` finds
+nothing. Prefer a UTF-8 path anyway so the file is legible to everything.
+
+**Read the build's exit code BEFORE trusting a green summary** — a stale binary passes every assertion
+in it. And **require the summary block itself**: a run that printed no totals ran nothing, whatever its
+exit code said. Disclose every red run WITH its rerun; never present a flake as clean.
+
+**Any session that touched frontend code ALSO runs the production build** — a test transform does NOT
+catch what the strict production compiler rejects: duplicate class members, cross-session member
+collisions, private-in-template. A green test run can sit over a broken build. The build receipt goes in
+FINAL TLDR section (b) alongside the suite.
+
+**`cd` INTO THE APP YOU TOUCHED — a repo can hold several, and the wrong one builds green.** The apps
+and their test and production-build commands are `docs/_meta/doc-index.md` § Apps and their build
+commands. An instruction that named ONE app for years sent seats on other surfaces to run a production
+build over a tree they had not touched, and they got a **passing receipt that proved nothing** — the
+false-green genus, embedded in the manual instead of in a test. Name the app you edited and run its
+commands from its root.
+
+## Fix-it variant (`spec-child fixit`)
+
+No spec — your contract is the prompt + the coordinator's ledger (READ-ONLY). **STEP 0 — INVESTIGATE,
+REPORT, STOP:** (1) reproduce/characterize cheaply, (2) find the cheapest reliable RECEIPT for the fixed
+state, (3) report the verdict as plain text — root cause, evidence, proposed fix shape + blast radius —
+then STOP for the coordinator's go. After the go: the minimal fix + MAKE THE FAILURE LOUD (log + trace row
+— never silent) + a regression pin + an E2E receipt re-running the original failing scenario
++ **SWEEP THE RECEIPTS YOUR FIX INVALIDATED** (`spec-seat`'s close-out step, and a fixit is the diff
+most likely to need it — you are changing behaviour something already made a claim about). A fixit that
+repairs a pane silently re-makes a `superseded` live-check TRUE, so its "do not run this" marker becomes
+false. **Grep `live-checks.md`, the tracker and the working docs for every behaviour you changed**,
+correct what is yours in the same commit, and hand back what is not.
+
+**A fixit chartered from a review's findings inherits no escape hatch** — every numbered spec carries one
+because `spec-pipeline` requires it, and you have no spec. If the charter you were handed did not state
+what a truthful partial looks like per named item, **ask for it** before you start designing.
+
+## Notes
+
+- **The spec's anchors are hypotheses; HEAD is the truth.** The biggest catches — stale trees, false
+  greens, dropped rulings — are all belief-vs-ledger mismatches. Your beliefs block exists so the
+  coordinator can catch them cheaply.
+- Counterpart skills: `spec-seat` (your contract) · `spec-parent` (the seat that arms you) ·
+  `spec-pipeline` (how your spec came to exist). The hosted version of you runs THIS same pair — the
+  control plane's seed names both skills, in this order.