@naswerks/engineering-loop 0.2.1 → 0.5.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`
@@ -87,53 +92,49 @@ branch, which is the truth for that PR, and you say so at close.
      speculation. A sizable design idea goes to `docs-backlog` (research/) instead. `docs-status`
      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`.
+3. **A new living doc?** If the work added a feature, ensure it has a doc in `docs/features/` (one doc per
+   feature). Then register every living doc this run created where the menu's shape line says
+   (`rg -n 'naswerks-loop: menu=' docs/_meta/doc-index.md`; `docs/_meta/docs-workflow.md` § The
+   repository-owned sections explains the two shapes). **`menu=all`, or no shape line:** add its row to the
+   menu in `docs/_meta/doc-index.md`. **`menu=curated; index={path}`:** add it to `{path}` the way that
+   index is kept — a generated index is never edited by hand — and add a menu row only when the doc meets
+   the loop's standard and a seat should read it; say which you did in the summary.
 
 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 +142,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,28 @@ 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.
+   - **menu drift** — read the menu's shape line (`rg -n 'naswerks-loop: menu=' docs/_meta/doc-index.md`;
+     none means `menu=all`). On `menu=all`: a living doc the menu does not name. On `menu=curated`: a doc the
+     menu names that falls short of the loop's standard (`docs/_meta/docs-workflow.md` § The
+     repository-owned sections — a header at a decided status and a `## Key Files` section).
 
 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 +54,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,9 +35,11 @@ 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/doc-index.md              the menu, written LAST — every doc that exists + three repo slots:
+  _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 — its shape line (menu=all: every doc that exists;
+                                  menu=curated: the docs init drafted, when the repository indexes its own) + 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/code-organization.md  patterns/backend-patterns.md
@@ -90,7 +95,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).
@@ -99,7 +105,9 @@ what it says` — and cite from it. A draft written mid-scan is a draft written
    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`.
+   existing `docs/` tree · `.claude/settings.json` · an index the repository already keeps of every doc (a
+   `docs/INDEX.md` or `docs/index.md` that lists them, a `docs/SUMMARY.md`, a `mkdocs.yml` nav, a
+   docusaurus or vitepress sidebar).
 
 ## The write order — create-if-missing at every step
 
@@ -108,8 +116,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`,
@@ -117,8 +137,12 @@ not. `init` never overwrites, never reorders, never deletes.
    Evidence per concern: a `generated/` folder or codegen config; a state library; a UI library; a tokens
    file or token layer; a saga / workflow / state-machine mechanism; a realtime library on either side; a
    queue, worker or scheduler.
-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.
+5. `docs/_meta/doc-index.md` from its template, LAST, with its shape line (`docs/_meta/docs-workflow.md`
+   § The repository-owned sections, the menu). **`menu=all`** when the repository keeps no other index: the
+   menu lists every doc that now exists under the four living folders (drafted or repo-owned). **`menu=curated;
+   index={path}`** when pass 4 found an index the repository already keeps of every doc: the menu lists only
+   the docs `init` drafted, and the report says the owner adds each further doc that meets the loop's
+   standard. Either way, the three repo slots are 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.
@@ -139,14 +163,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,11 +190,15 @@ 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 |
-| every path a § Role reading lists row names | the row's path does not exist | — | resolves |
+| the menu's shape line | an unknown shape | a curated menu names no index, or an index that does not exist | `menu=all` (also a menu with no shape line), or `menu=curated` with its index |
+| every living doc a `menu=all` menu should list | — | a doc under the four living folders the menu does not name | named |
+| every doc a menu names | the path does not exist (a row saying `not detected` is exempt) | on a curated menu: no status in either header form, the word `draft`, or no `## Key Files` | meets the loop's standard |
+| 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 |
 | `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 |
@@ -171,11 +206,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