@naswerks/engineering-loop 0.2.0 → 0.4.0

package/skills/docs-process/SKILL.md

@@ -5,8 +5,10 @@ description: Patch the living docs from a session doc's "Living Docs to Update"
 
 # docs-process
 
-The **second** half of the bookend. Take a finished session doc (in `docs/working/` or its topic
-folder under `docs/archive/`) and bring the living docs up to current state.
+The **second** half of the bookend. Take a finished session doc (in `docs/working/`, or already filed
+in its archive home) and bring the living docs up to current state.
+
+**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.
 
 ## Running as a pipeline row (`docs-process` seat)
 
@@ -31,8 +33,8 @@ branch, which is the truth for that PR, and you say so at close.
 1. **Read the session doc(s) for the effort** from `docs/working/` — that's where `docs-write` leaves
    them (it does not archive). A folder's `README.md` is never a queue entry. One effort may be a **SEQUENCE of working docs** across sessions (each
    `Builds on` the prior, all sharing one `Source:` research doc); treat the sequence as one unit. The
-   combined **Living Docs to Update** sections are your checklist; the `## Archive` line names the topic
-   folder you'll file everything into in the last step. Run this when the effort is done (it's the
+   combined **Living Docs to Update** sections are your checklist; the `## Archive` line names the archive
+   home you'll file everything into in the last step. Run this when the effort is done (it's the
    finalizer) — mid-effort, just keep adding working docs and continue.
 
    **`docs/working/` is a SHARED QUEUE — it may hold other efforts' docs.** Invoked by hand you scope
@@ -58,28 +60,31 @@ branch, which is the truth for that PR, and you say so at close.
    - Read the living doc and the session doc's description of what changed.
    - **Patch the stale sections** — don't rewrite. Preserve everything still accurate.
    - **Verify against code** — open the actual source file for each claimed change. Code is truth.
-   - **Leave the "Last verified" date alone.** You verified the *specific* checklist changes against
-     code — but you did NOT re-read the whole doc against the whole codebase, and "Last verified" is a
-     *whole-doc* claim. Stamping it for a targeted patch (rename or substantive alike) overclaims and
-     hides real staleness in the untouched sections from the next `docs-status` scan. That date is
-     `docs-audit-feature`'s to set (it does the full doc-vs-code pass — see its anti-fabrication rule).
-     **Exception:** a doc you *create from scratch* here by reading the code is verified-today by
-     definition — set its date.
+   - **Leave the verified date alone.** You verified the *specific* checklist changes against
+     code — but you did NOT re-read the whole doc against the whole codebase, and the verified date (wherever
+     § Doc metadata (repository-owned) says it lives) is a *whole-doc* claim. Stamping it for a targeted patch
+     (rename or substantive alike) overclaims and hides real staleness in the untouched sections from the next
+     `docs-status` scan. That date is `docs-audit-feature`'s to set (it does the full doc-vs-code pass — see
+     its anti-fabrication rule). **Exception:** a doc you *create from scratch* here by reading the code is
+     verified-today by definition — set its date.
    - **Update the Key Files table** if files were renamed, created, or deleted.
-   - **Write / update the meta-comment + `## Lineage`** (see "Doc metadata" in `docs-workflow.md`):
-     - *Creating a doc from scratch* here: emit the `<!-- meta: type=…; status=current; verified={today};
-       lineage=N -->` line (its `verified` = today, matching the blockquote you just set) **and** a
-       `## Lineage` footer. You already know the `Source:` research doc (the `Idea` row), any spec pipeline
-       (the `Spec` row), and the working-doc sequence / `## Archive` target (the `Built` row); derive `Related` from
-       existing peer links. Set `lineage=N` to the link count. **Keep `Spec` and `Built` symmetric** —
-       list **every per-slice spec that a `Built` session implemented** (the umbrella + `00-operating-frame`
-       go in `Idea`, not `Spec`); a `Built` session whose spec is missing from `Spec` is the smell (see the
-       Lineage rules in `docs-workflow.md`).
-     - *Patching an existing doc*: bump `status` if it changed and recompute `lineage=N`; append any new
-       `Built`/`Spec` rows for this effort. **Do NOT restamp `verified`** — same anti-fabrication rule as the
-       `Last verified` date above (a targeted patch is not a whole-doc re-verify).
-     - **Migrate `## Related Docs`.** If the doc still carries a `## Related Docs` section, fold its links into
-       the `## Lineage` `Related` row and remove the old section (the convention supersedes it).
+   - **Write / update the header + `## Lineage`** — the header is the one `docs/_meta/docs-workflow.md`
+     § Doc metadata (repository-owned) prescribes, in its words, and `## Lineage` is written where that
+     section keeps it:
+     - *Creating a doc from scratch* here: write the header at the word for `current`, its verified date
+       today, **and** a `## Lineage` footer. You already know the `Source:` research doc (the `Idea` row), any
+       spec pipeline (the `Spec` row), and the working-doc sequence / `## Archive` target (the `Built` row);
+       derive `Related` from existing peer links. Compute any field the header derives from those links the
+       way the section says. **Keep `Spec` and `Built` symmetric** — list **every per-slice spec that a
+       `Built` session implemented** (the umbrella + `00-operating-frame` go in `Idea`, not `Spec`); a `Built`
+       session whose spec is missing from `Spec` is the smell (the `## Lineage` rules § Doc metadata
+       (repository-owned) gives).
+     - *Patching an existing doc*: update the status if it changed and recompute any field the header
+       derives; append any new `Built`/`Spec` rows for this effort. **Do NOT restamp the verified date** — same
+       anti-fabrication rule as above (a targeted patch is not a whole-doc re-verify).
+     - **Migrate `## Related Docs`.** If the doc still carries a `## Related Docs` section and the section
+       keeps `## Lineage`, fold its links into the `## Lineage` `Related` row and remove the old section (the
+       convention supersedes it).
    - **Flag code risks you spot.** If you notice a genuine bug / risk / tech-debt *outside* what you're
      documenting — while verifying against code, or as a still-unresolved item in the working doc's
      **Watch-Outs** — add a dated one-line bullet (with `file:line`) to that doc's `## Open Issues`
@@ -88,52 +93,44 @@ branch, which is the truth for that PR, and you say so at close.
      surfaces these so they aren't lost.
 
 3. **New feature?** If the work added a feature, ensure it has a doc in `docs/features/` (one doc per
-   feature) and add it to the menu in `docs/_meta/doc-index.md`.
+   feature) and add it to the menu in `docs/_meta/doc-index.md` — unless `docs-workflow.md` § Doc metadata
+   (repository-owned) says a repository tool generates the menu, in which case leave it alone.
 
 4. **Closing grep** — if the session doc notes deletions or renames, grep all living
    docs (`guides/ patterns/ infrastructure/ features/ _meta/`) for stale references and fix them. Do
-   NOT touch `archive/` — that's frozen history.
-
-5. **Archive the effort — research/spec docs AND working doc(s), together.** Now that the living docs are
-   patched and verified, file the whole effort into one **topic folder** under `docs/archive/{topic}/`
-   (use the `## Archive` line; reuse the folder if it exists, create it if new; descriptive names, **no
-   numeric prefixes on working docs** — `Builds on` is the ordering):
-
-   **FIRST, RECONCILE THE DESTINATIONS — `rg '^\s*`?docs/archive/' <every working doc in the effort>`.**
-   This step says *"one topic folder"* and *"use the `## Archive` line"* — a singular read over a PLURAL
+   NOT touch a filed doc — wherever § The archive convention (repository-owned) files them, they are frozen
+   history.
+
+5. **File the effort — research/spec docs AND working doc(s), together.** Now that the living docs are
+   patched and verified, file the whole effort where `docs/_meta/docs-workflow.md` § The archive convention
+   (repository-owned) says, in the shape it gives for this kind of effort (a small effort, a spec pipeline,
+   a follow-on round). That section holds the destination, the shape and the links a move repairs; this
+   step holds the procedure, which is the same everywhere. A pipeline whose umbrella carries an `Archive:`
+   line files there.
+
+   **FIRST, RECONCILE THE DESTINATIONS — `rg -A1 '^## Archive' <every working doc in the effort>`, plus
+   the umbrella's `Archive:` line when there is a pipeline.**
+   This step says *"one archive home"* and *"use the `## Archive` line"* — a singular read over a PLURAL
    source, so the set is checked before any move. **If the docs disagree, STOP and ask.** Do not pick the
    majority, do not pick the first, and do not pick the one you happen to be reading. The failure is not
-   recoverable by you: one working doc naming a different, populated effort's folder is enough to sweep
-   this effort's docs into a neighbour's archive, and `archive/` is frozen history. No seat can see it
+   recoverable by you: one working doc naming a different, populated effort's home is enough to sweep
+   this effort's docs into a neighbour's, and a filed effort is frozen history. No seat can see it
    alone — each wrote one working doc and each line is individually plausible; the divergence exists only
    in the SET, which is why the check belongs here and not upstream.
-   - Move **every working doc** in the effort from `docs/working/` into the topic folder.
-   - Move the **`Source:`** research/spec docs from `docs/research/` into the **same** topic folder — the
-     idea and the work that delivered it are filed together. Do NOT delete and do NOT leave in `research/`
-     (that's what kept shipped ideas cluttering the running tab).
-   - **Pick the folder shape** (see "Two topic-folder shapes" in `docs-workflow.md`):
-     - **Flat** (no spec pipeline — the default for small/single-session efforts): working doc(s) + any
-       research doc at the topic-folder root.
-     - **Split** (the effort used `spec-pipeline`, so a numbered spec set exists): `git mv` the numbered
-       specs + umbrella into **`specs/`**, the working docs into **`implementation/`**, and leave
-       **`project-status.md` at the topic-folder root** as the index, plus any `live-checks.md`; a
-       `sessions/` folder (**two files per session — the filed `plan.md` + `tldr.md`**; older archives may
-       also hold `questions.md` / `status-after-*.md`, which is historical record, not the convention)
-       moves wholesale alongside them. `git mv` STAGES immediately — in a shared working tree, another
-       session's commit can silently sweep your staged renames. Commit promptly after the moves, or
-       announce the staged state before yielding the tree.
-     - **Follow-on round** (the effort continues an already-archived family — e.g. a round-2 pipeline for
-       a shipped feature): its own **sibling** topic folder with the full split shape, named
-       `{family-prefix}-{subtopic}` — **never file into the frozen prior-round folder**. The family
-       index is the living feature doc's `## Lineage` (append this round's Idea/Spec/Built rows beside
-       the prior round's); the new round's back-links to the old archive stay as-is (historical
-       cross-effort links). See the section named `Follow-on pipelines` in `docs-workflow.md`.
-   - **Repair the intra-effort links the move breaks** (relative depths change). On a split, fix: each
-     working doc's `Source:` becomes `../specs/NN-*.md`; the spec / `project-status` links; and the **live feature
-     doc's `## Lineage`** rows (`Spec` to `…/specs/…`, `Built` to `…/implementation/…`). On a flat archive, a
-     working doc's `Source: ../research/{topic}/x.md` becomes the now-sibling `x.md`. **Leave pre-existing
-     cross-effort links** (to *other* topic folders / research folders) as historical record. Verify with a
-     link-resolution pass before finishing.
+   - Move **every working doc** in the effort from `docs/working/` into that home, in the section's shape.
+   - Move the **`Source:`** research/spec docs from `docs/research/` into the **same** home — the idea and
+     the work that delivered it are filed together. Do NOT delete and do NOT leave in `research/` (that's
+     what kept shipped ideas cluttering the running tab).
+   - **`git mv` STAGES immediately** — in a shared working tree, another session's commit can silently sweep
+     your staged renames. Commit promptly after the moves, or announce the staged state before yielding
+     the tree.
+   - **A `sessions/` folder moves wholesale and byte-untouched** — it is testimony, and no link repair
+     reaches into it.
+   - **Never file into a frozen effort.** An effort that continues one already filed (a follow-on round)
+     goes where the section puts a follow-on — never inside the earlier round's home.
+   - **Repair the links the move breaks** — the ones the section names (relative depths change), inside the
+     effort and in the live feature doc that points at it. **Leave pre-existing cross-effort links** as
+     historical record. Verify with a link-resolution pass before finishing.
    This clears both the `working/` queue and the research idea. After this the docs are frozen history.
 
 6. **Summary** — list which living docs were updated, what changed in each, which source files you read
@@ -141,6 +138,6 @@ branch, which is the truth for that PR, and you say so at close.
 
 ## Notes
 - Skip doc updates for pure bug fixes that restored behavior the doc already described correctly.
-- `docs-write` leaves the doc in `working/`; **this skill is what archives it** (step 5) — only after the
+- `docs-write` leaves the doc in `working/`; **this skill is what files it** (step 5) — only after the
   living docs are current. That keeps `working/` an honest queue of unprocessed sessions.
 - No releases/changelog step — git history covers that.

package/skills/docs-status/SKILL.md

@@ -8,6 +8,8 @@ description: Read-only orientation at session start — what's recently archived
 A quick, read-only pulse of the docs pipeline. No files created. Report by name with context, not
 just counts.
 
+**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.
+
 ## Steps
 
 1. **`working/` — in flight.** List each doc in `docs/working/` with a one-line "what it's about /
@@ -16,20 +18,24 @@ just counts.
 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.
+3. **Recently done.** List the most recently modified filed efforts in the archive home
+   `docs/_meta/docs-workflow.md` § The archive convention (repository-owned) names (a handful, newest first)
+   so the user can see what just shipped.
+
+4. **Meta sweep — the condensed status table.** Run the sweep command `docs/_meta/docs-workflow.md` § Doc
+   metadata (repository-owned) gives — it is spelled there for whichever header this repository writes.
+   Parse each doc's status and verified date (and any other field that header carries) into a compact
+   one-line-per-doc table (group by folder), in that section's status words. This is the headline pulse —
+   richer than the old date-only scan. Read-only; do not write anything. Flag, in order of concern:
+   - **missing header** — a living doc (`guides/ patterns/ infrastructure/ features/`) the sweep does not
+     list. Read its verified date from wherever else the section says it may live, **prefer the header**,
+     and list it as a gap to fill.
+   - **stale** — a verified date 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** — where the section keeps `## Lineage`: a link whose target file no longer exists (a
+     broken breadcrumb).
+   - **low-lineage feature** — where the section keeps `## Lineage`: a feature doc with no Lineage rows =
+     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
@@ -44,4 +50,4 @@ just counts.
 
 ## 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.
+  `working/`, `research/`, and the archive home ARE the status.

package/skills/docs-write/SKILL.md

@@ -11,13 +11,15 @@ does NOT archive. Both happen in `docs-process`, once the living docs are patche
 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.
 
+**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.
+
 ## 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).
+   - **Header** — the machine header `docs/_meta/docs-workflow.md` § Doc metadata (repository-owned) prescribes, in that section's own words: the doc's type is working, its status the word for `wip` while the effort continues or the word for `shipped` on its last session, its verified date today, and any field that section derives (a count of the doc's provenance links, say) computed the way it says.
    - **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
@@ -29,15 +31,16 @@ keeps the doc editable until its living-doc obligations are discharged.
    - **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/`**.
+3. **Record the archive target — don't move the file.** Add an `## Archive` line to the doc, in the form the session template gives it (`docs/_meta/docs-workflow.md` § Templates (repository-owned)), naming where § The archive convention (repository-owned) files this effort — reuse what that section says to reuse, and name it the way that section names things. When the effort has a spec pipeline whose umbrella carries an `Archive:` line, that path is the target. `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`.
+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 file it — 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.
+  `## Lineage` (`Idea` / `Built` rows), where § Doc metadata (repository-owned) keeps that footer. 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/`.
+- The doc becomes frozen history only when `docs-process` files it into its archive home (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

@@ -1,6 +1,6 @@
 ---
 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.
+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; run init refresh to bring a repository's copies of the method docs up to a newer pack (it writes only their repository-owned sections and the stamp). A second init writes nothing and prints the doctor report.
 ---
 
 # init
@@ -11,8 +11,11 @@ control plane admits a spec folder only when the repository carries `docs/_meta/
 `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.
+**Three invocations:** `init` (create what is missing, then the report) · `init doctor` (the report only) ·
+`init refresh` (a newer pack's repository-owned sections into the copies that exist — see § refresh). A
+second `init` writes nothing and IS the doctor report.
+
+**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 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.
@@ -32,8 +35,9 @@ block read, never the exit code alone; a pin must be able to fail.
 
 ```
 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/docs-workflow.md          a copy of the pack's references/docs-workflow.md (stamped); its sections marked
+                                  (repository-owned) are the repository's to rewrite to its own conventions
+  _meta/engineering-loop.md       a copy of references/engineering-loop.md (stamped), under the same rule
   _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
@@ -90,7 +94,8 @@ what it says` — and cite from it. A draft written mid-scan is a draft written
    `.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
+   the folder layout two deep · `git log --oneline -20` (the message convention) · the remote's default
+   branch (`git symbolic-ref refs/remotes/origin/HEAD`) · 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).
@@ -108,8 +113,20 @@ 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).
+2. `docs/_meta/docs-workflow.md` and `docs/_meta/engineering-loop.md` — copies of the pack's
+   `references/*` (their first line is the version stamp; copy it with the file). **If the repository
+   already carries a copy, read its repository-owned sections before writing any draft:** the header every
+   draft below carries is the one that copy's § Doc metadata (repository-owned) prescribes, not the
+   templates' own line. An existing copy is never rewritten by `init`; `init refresh` is the one path that
+   writes into a copy, and only into its repository-owned sections. When the repository's own gate requires
+   frontmatter on every file under `docs/`, the block may sit above the stamp; the doctor reads the stamp
+   after it.
+
+   **When `init` writes the copies itself, it drafts § This repository's rails (repository-owned)** in the
+   new `engineering-loop.md` from the scan, under the law of the draft: each item carries only what a file
+   the scan opened states — CONTRIBUTING, `CLAUDE.md` / `AGENTS.md`, `.husky/` / `.githooks/`, the CI
+   workflows, a pull-request template, CODEOWNERS, the remote's default branch — and cites it, or keeps
+   its absent-line.
 3. The four floor drafts (`code-organization`, `backend-patterns`, `frontend-patterns`, `testing`) from
    `templates/docs/patterns/*.md`, filled as below.
 4. The standard-set drafts — `codegen`, `state-management`, `ui-style-guide`, `design-tokens`,
@@ -139,14 +156,21 @@ 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;
+1. the H1, the one-line blockquote, the machine header `docs/_meta/docs-workflow.md` § Doc metadata
+   (repository-owned) prescribes at the word for `draft` — placed and spelled as that section says, the
+   verified date included wherever it keeps one (the templates carry the loop's own header, and each
+   template's init instruction says what to drop when this repository's differs) — then 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`.
+5. `## Key Files`, and `## Lineage` where § Doc metadata (repository-owned) keeps it.
+
+**The templates speak the loop's own formats** — the header, the status words in the Start-here stanza and
+the folder READMEs, the archive home in the `archive/` and `working/` READMEs and in the doc-index. When
+this repository's copy has replaced the section a line echoes, write that line in the copy's words instead.
 
 A section the scan can only half-fill says which half. A rule with no cited source is not written.
 
@@ -159,10 +183,12 @@ 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/docs-workflow.md`, `_meta/engineering-loop.md` | missing, or no stamp on line 1 (or on the first line after a frontmatter block) | stamp behind the pack's version (`init refresh` restamps) | stamp equals it |
+| each repository-owned heading, in its file | — | unmarked (an earlier spelling) or missing — `init refresh` marks or adds it | present |
+| each item of § This repository's rails (repository-owned) | — | missing, or still its absent-line | recorded |
 | `_meta/doc-index.md` and its three slot sections | missing | a slot carries only the absent-line | filled |
-| the four floor docs | missing | `status=draft`, or an `<!-- init: -->` left in | `status=current` |
-| the seven standard docs | absent AND no doc-index row saying `not detected` | `status=draft` when present; absent with its row | present and current, or absent with its row |
+| the four floor docs | missing | the word `draft` (read from either header form), or an `<!-- init: -->` left in | a decided status |
+| the seven standard docs | absent AND no doc-index row saying `not detected` | the word `draft` when present; absent with its row | present and decided, or absent with its row |
 | every path a § Role reading lists row names | the row's path does not exist | — | resolves |
 | `CLAUDE.md` / `AGENTS.md` stanza · `.claude/settings.json` pin | — | missing | present |
 | `verify-staged` | — | not on PATH (the row carries the fallback) | resolvable |
@@ -171,11 +197,42 @@ FAIL, so a CI job or a control plane can call it.
 | 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.
+same table: the checks are file existence, a first-line stamp, a heading grep, a `status` read in either
+header form, 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.
+state: the owner promotes each draft to the word for `current` as they confirm it, section by section.
+
+The doctor never grades the loop text of the two method docs, and never their repository-owned sections'
+content: a repository rewrites both as it sees fit. It reads the stamp, the owned headings, and the rails
+items' absent-lines.
+
+## refresh
+
+`node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs [repo-root]` is a dry run; add `--write` to apply it. Node 22
+or later, no dependencies. **What it does, in the line it prints first: it writes only the repository-owned
+sections and the stamp; every other line is left as it is.** A repository updating the pack is taking new
+skills, not new prose — the loop text in its copies is its own, whatever it has done to it, and refresh
+never touches it.
+
+It reads the pack's `references/` for what each repository-owned section is, and prints one row per section:
+
+| Row | When | What `--write` does |
+|---|---|---|
+| **kept** | the copy has the section under its exact heading | nothing — the section is the repository's, byte for byte |
+| **heading marked** | the copy has it under an earlier spelling (`## The archive convention`, `## Doc metadata (header + lineage)`, `## Templates`) | rewrites that one heading line and nothing else |
+| **added** | the copy lacks the section | inserts the pack's default before the first following section the copy also has |
+| **item added** | § This repository's rails (repository-owned) lacks an item this pack names | appends that item's absent-line to the end of the section |
+| **stamp** | the stamp is behind the pack | restamps (after any frontmatter the stamp sits under) |
+
+Then, for each section, what this pack's skills read from it and which loop passages echo it (from the
+pack's § The repository-owned sections), so the owner can check that a rewritten section still answers each
+item. It never deletes, never reorders, keeps every line's own ending, and a second run writes nothing.
+
+**Run it this way:** the dry run first; show the human its table; `--write` only on their word. After the
+write, offer — and ask before doing either — to fill each new absent-line from the scan as `init` would
+(the law of the draft), and to move into its new item any fact the repository had parked in its loop text
+(a paragraph naming its own skills, say). Then run `init doctor`.
 
 ## Notes
 

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,10 +111,10 @@ 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');
 }
 
@@ -187,8 +228,29 @@ 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;
+}
+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];
 }