@naswerks/engineering-loop 0.2.1 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -10,12 +10,8 @@
     {
       "name": "naswerks",
       "description": "The engineering loop: docs-* knowledge loop, spec-* execution loop, and init for a fresh repository.",
-      "version": "0.2.1",
-      "source": {
-        "source": "npm",
-        "package": "@naswerks/engineering-loop",
-        "version": "0.2.1"
-      }
+      "version": "0.4.0",
+      "source": "./"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "naswerks",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "The engineering loop: a knowledge loop (docs-*) and an execution loop (spec-*) for repositories driven by hosted agent sessions, plus init to make a repository ready for both.",
   "author": { "name": "naswerks" },
   "license": "MIT",

package/CHANGELOG.md

@@ -5,6 +5,76 @@ version is the one in `package.json` and `.claude-plugin/plugin.json`, which mus
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-23
+
+### Changed
+
+- **The two method documents state one way of running the loop, opinionated on purpose, and name the four
+  places a repository replaces with its own.** Each is a whole section whose heading ends
+  `(repository-owned)`: in `docs-workflow.md`, The archive convention, Doc metadata and Templates; in
+  `engineering-loop.md`, This repository's rails. One grep lists them and nothing else:
+  `rg -n '^#+ .*\(repository-owned\)' docs/_meta/`. The heading is the contract: a repository keeps it and
+  replaces the body in its `docs/_meta/` copy, in its own words. The loop's own preferences stay stated
+  concretely in the references: the `<!-- meta -->` header and its Obsidian interop, `## Lineage`, the
+  topic folders under `archive/{topic}/`, flat and split.
+- `docs-workflow.md` gains § The repository-owned sections: what the skills read from each section, where
+  the two documents echo it in passing, the loop's four states (`draft`, `wip`, `current`, `shipped`) and
+  who writes each, what silence in a section means, how to replace one (filing a pipeline as one package
+  into a home the repository already has among the examples), and what the version stamp means.
+- `engineering-loop.md` § This repository's rails is six items, each an absent-line until the repository
+  fills it: Policy, Gates a commit passes, Before a PR, Where a PR goes, Staging, Skills a seat meets here.
+  They add to the Hard rules and never subtract. The POLICY row of where-a-rule-lives points at the rails'
+  policy document, and in hosted mode at the control plane's suffix.
+- **The skills name the section and the concept, never the value.** A header is written at the word for a
+  loop state, "the verified date" is wherever § Doc metadata keeps it, an effort files into "the archive
+  home" § The archive convention names, and the base branch and the PR route come from the rails. Every
+  skill that needs a format carries the same line near its top, "Find the format first", with the grep.
+  `docs-process` holds the filing procedure only; the shapes and the link repairs are the archive
+  convention's. `spec-review` and `spec-pipeline` diff against the rails' base branch; `spec-parent` and
+  `spec-retro` open the PR where and how the rails say.
+- The templates keep the loop's own header; their init instruction drops the blockquote date where
+  § Doc metadata keeps none. `init` writes the Start-here stanza's and the folder READMEs' echo lines in the
+  copy's words when the copy has replaced the section they echo, and drafts § This repository's rails from
+  the scan.
+- `init doctor` reads a doc's status from either header form unaided, the loop's meta line or a
+  frontmatter `status:` key, needing only the word `draft`; reads the version stamp after a leading
+  frontmatter block; and reports each repository-owned heading (unmarked or missing: DEGRADE) and each
+  rails item (missing, or still its absent-line: DEGRADE). It never grades the loop text or the content of
+  a repository-owned section.
+- The marketplace entry sources the plugin from this repository (`./`) instead of the npm package at a
+  pinned version. `claude plugin install naswerks@engineering-loop` no longer depends on a registry that
+  can lag a tag; npm remains the runner lane (`npm i -g @naswerks/engineering-loop`). A pin keeps it so.
+- The release workflow names the remedy when a publish is refused: the package has no trusted publisher
+  linked on npmjs.com for this repository and `release.yml`.
+
+### Added
+
+- `init refresh` (`skills/init/scripts/refresh.mjs`): brings a repository's copies of the method documents
+  up to this pack by writing only their repository-owned sections and the stamp. A dry run by default, one
+  row per section (kept, heading marked, added, item added, stamp); `--write` applies exactly those rows. It
+  never touches the loop text, never deletes, never reorders, keeps every line's own ending, and a second
+  run writes nothing.
+- `skills/init/scripts/owned.mjs`: the one list of repository-owned sections the doctor, refresh and the
+  pins share.
+- Pins: a census that no skill spells the loop's own header or archive destination; the one-grep pin
+  (exactly four marked headings, equal to `owned.mjs`, no partial marker); section citations by exact
+  heading only; the loop states a skill names; the find-format line; `pins/preferences.test.mjs`, which
+  keeps the loop's own preferences in the references; `pins/refresh.test.mjs`.
+
+### Fixed
+
+- `docs-audit-full` named `docs-write` as the skill that files a finished working doc; it is
+  `docs-process`.
+- `spec-review` wrote its report at a status no loop state names; it writes the word for `shipped`.
+
+## [0.2.2] - 2026-09-21
+
+### Changed
+
+- `spec-child`'s `mixed` row names where its reading list lives — the rows for those surfaces in
+  `docs/_meta/doc-index.md` § Role reading lists — so the default role is no longer the one role told to
+  read "the adds for the surfaces your spec touches" without a path to them.
+
 ## [0.2.1] - 2026-09-20
 
 ### Changed

package/README.md

@@ -5,8 +5,9 @@ living documentation true, and an **execution loop** (`spec-*`) that turns an ap
 pipeline of agent sessions with a coordinator, build seats, a review seat and a retrospective. `init`
 makes a fresh repository ready for both.
 
-The package root is the plugin root: `.claude-plugin/` and `skills/` sit at the top, so one artifact serves
-a person's CLI, a hosted runner, and a repository's pin.
+The package root is the plugin root: `.claude-plugin/` and `skills/` sit at the top, so the same tree serves
+a person's CLI (through the marketplace, from this repository), a hosted runner (through npm), and a
+repository's pin.
 
 ## Install
 
@@ -17,6 +18,10 @@ claude plugin marketplace add naswerks/engineering-loop
 claude plugin install naswerks@engineering-loop
 ```
 
+The marketplace is this repository, and the plugin is sourced from it: no registry sits between you and a
+release. Plugins load at session start, so start a new session (or run `/reload-plugins`) after installing.
+To pick up a new release later: `claude plugin marketplace update engineering-loop`, then the install line again.
+
 Skills are namespaced by the plugin: `/naswerks:docs-write`, `/naswerks:spec-pipeline`, `/naswerks:init`.
 
 **On a runner** (sessions started through the Agent SDK load a plugin only from a local path):
@@ -32,6 +37,22 @@ then point the runner at `$(npm root -g)/@naswerks/engineering-loop` — with pe
 structure the skills read, the two method documents, a `CLAUDE.md` pointer and the plugin pin in
 `.claude/settings.json`. A team member still installs the plugin once per machine; the pin enables it.
 
+**In a repository that already has a docs convention** (frontmatter on every file, a pre-commit
+validator, an indexer): the two method documents state one way of running the loop, opinionated on
+purpose, and mark the four sections that are yours to replace — the header every doc carries, where a
+finished effort is filed, the templates' header lines, the rails a commit passes. Keep each heading and
+rewrite its body in your `docs/_meta/` copies, in your own words; `docs-workflow.md` § The repository-owned
+sections lists what each must answer. One grep lists the four:
+
+```
+rg -n '^#+ .*\(repository-owned\)' docs/_meta/
+```
+
+Every skill names the section it needs and never states the format itself, so the pack stays generic and
+your conventions live in your repository. **Taking a newer pack:** `/naswerks:init refresh` writes only
+those four sections and the version stamp into your copies — a dry run first, then `--write` on your word —
+and never touches the rest of the text.
+
 ## What is in the box
 
 | Skill | Loop | One line |
@@ -51,7 +72,8 @@ structure the skills read, the two method documents, a `CLAUDE.md` pointer and t
 | `spec-ignite` | spec | the ignition copilot for a hosted run |
 | `init` | — | make a repository ready for both loops |
 
-`references/` carries the two method documents a repository copies into `docs/_meta/`;
+`references/` carries the two method documents a repository copies into `docs/_meta/` and then
+rewrites where they say (repository-owned);
 `bin/verify-staged` is the staging receipt the seats run between `git add` and `git commit`. A
 marketplace install puts nothing on PATH: `npm i -g @naswerks/engineering-loop` does, and the skills
 carry the fallback `node <pack root>/bin/verify-staged.mjs`.
@@ -71,7 +93,10 @@ method documents carry the version stamp; the vocabulary censuses. `node bin/ver
 
 The version lives in `package.json` and `.claude-plugin/plugin.json` (they must agree). A `v*` tag
 runs the pins and publishes to npm through trusted publishing; the GitHub release notes are the
-CHANGELOG section for that version.
+CHANGELOG section for that version. The marketplace serves the plugin from this repository at whatever
+`main` holds, so a CLI install never waits on npm; npm is the runner lane, and a refused publish leaves
+runners one version behind until the trusted publisher on npmjs.com matches this repository and
+`release.yml` (the workflow prints that remedy when it happens).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naswerks/engineering-loop",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "The engineering loop as a Claude Code plugin: a knowledge loop (docs-*), an execution loop (spec-*), and init for a fresh repository. The package root is the plugin root.",
   "license": "MIT",
   "type": "module",

package/references/docs-workflow.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.2.1 -->
+<!-- naswerks-loop: version=0.4.0 -->
 # Docs Workflow
 
 > How knowledge flows through `docs/`: the loop, the folder rules, the templates, and the `docs-*` skills.
@@ -40,10 +40,10 @@ narrative. That's also why it's a separate session, not the tail of the implemen
 
 | Folder | What it holds | Lifecycle |
 |--------|---------------|-----------|
-| `_meta/` | This system — `doc-index` (the menu) + `docs-workflow` (this file) | Maintained as the system evolves |
+| `_meta/` | This system — `doc-index` (the menu) + `docs-workflow` (this file) + `engineering-loop` (the seats and the ceremony) | Maintained as the system evolves; the sections marked **(repository-owned)** are rewritten by each repository to its own conventions |
 | `research/` | The running tab of ideas to do, not yet built. The folder is the queue. | Created by `docs-backlog`; stays through the build, then **archived with its working doc(s)** by `docs-process` |
 | `working/` | Active + finished-but-unprocessed session docs (one effort may chain several). The folder is the queue. | **Leaves via `docs-process`** — research + the whole chain archived together once the living docs are patched |
-| `archive/` | Completed/abandoned session docs, grouped into **topic** folders | Write-once. Frozen history — never edit archived docs |
+| `archive/` | Completed/abandoned session docs, grouped into **topic** folders (or the home "The archive convention" below names for them) | Write-once. Frozen history — never edit archived docs |
 | `guides/` | How to ADD a new thing — step-by-step walkthroughs | Living — patched by `docs-process` |
 | `patterns/` | Conventions to FOLLOW when writing code | Living — patched by `docs-process` |
 | `infrastructure/` | What runs under the hood (technologies/plumbing) | Living — patched by `docs-process` |
@@ -62,7 +62,89 @@ is usually a code problem to flag, not a doc to rewrite (unless the rule itself
 
 ---
 
-## The archive convention
+## The repository-owned sections
+
+This file and [engineering-loop](engineering-loop.md) state one way of running the loop, and they are
+opinionated on purpose. Where a repository's conventions differ, they differ in four places only — the
+sections whose heading ends **(repository-owned)**. Each one declares this repository's preference for one
+thing; another repository **keeps the heading and replaces the body** in its `docs/_meta/` copy, in its own
+words. Every other section is the loop and reads the same everywhere. One grep lists the four, with their
+line numbers; each runs to the next `## ` heading:
+
+```
+rg -n '^#+ .*\(repository-owned\)' docs/_meta/
+```
+
+**The skills read these sections and never restate them.** A skill names the section and the thing it
+needs from it — *the header § Doc metadata prescribes*, *the archive home § The archive convention names*,
+*the base branch § This repository's rails names* — and takes the value from this repository's copy. What
+each section answers, and where the two method docs echo the preference in passing (the lines a repository
+that replaces the section rewrites alongside it):
+
+| Section | What the skills read from it | Also echoed in |
+|---------|------------------------------|----------------|
+| **The archive convention** (this file) | the archive home for each kind of effort (hand-cranked, spec pipeline, follow-on round) and for audit reports · the shape inside it · what a working doc's `## Archive` line says, and whether an umbrella carries an `Archive:` line · the links a move repairs · what is frozen once filed | The Loop (the diagram and its prose) · Folders (`research/`, `working/`, `archive/`) · "Living docs vs session docs" · the skills table (`docs-process`) · Conventions (incident receipts, archived docs) · `engineering-loop.md` "The loop at a glance" |
+| **Doc metadata** (this file) | the header — its form and its place · the sweep: one command, one line per doc · the word for each loop state (below) · where the verified date lives, and the rule that moves it · whether `## Lineage` stays · the gates a doc passes, and the folders they exempt · whether `doc-index.md` is kept by hand or generated | the skills table (`docs-status`) · Conventions (the machine layer; dates in the header) · `engineering-loop.md`'s own header line and its `## Lineage` |
+| **Templates** (this file) | each template's header lines, at the state its writer names | — |
+| **This repository's rails** (`engineering-loop.md`) | the policy document, and how a seat reaches it · the gates a commit passes · the suite before a PR · the base branch, the PR target, the branch names and how a PR is opened · the staging rule · the repository's own skills a seat meets | the POLICY row of "Where a rule lives" · the Hard rules, which the rails add to and never subtract from |
+
+**The loop's states.** The skills speak in four states, and § Doc metadata says which word this repository
+writes for each. Here the words are the states themselves.
+
+| State | Written by | Means |
+|-------|------------|-------|
+| `draft` | `init`, `spec-pipeline`, `docs-backlog` | scanned or authored, not yet decided or verified |
+| `wip` | `docs-write` mid-effort, the pipeline's tracker | in progress |
+| `current` | `docs-process` for a doc it creates, `docs-audit-feature` | describes the code as it is |
+| `shipped` | `docs-write` for an effort's last session, `spec-review`'s report | finished — frozen once filed |
+
+*Stale* is a date, not a state: `docs-status` computes it from the verified date, and no seat writes it.
+
+**Silence.** A section that says nothing about an item leaves the loop's default: the menu is kept by hand
+(`docs-process` adds a row for a new feature doc), no gate runs on a commit, the base branch is the remote's
+default (`git symbolic-ref refs/remotes/origin/HEAD`), and a seat with no PR route asks the human once and
+suggests recording the answer in the rails. Any other unanswered item is a question for the human, never a
+guess.
+
+### Replacing a section
+
+Keep what the skills need to find, change the words to yours:
+- **The header and how to sweep it.** Name the fields (a status, a verified date, a type) and where they
+  live, and give the one command `docs-status` runs to list every doc's status in one line each. For the
+  loop's own header that command is `rg -o '<!-- meta:.*-->' docs/`; for a frontmatter convention it is a
+  grep over the keys.
+- **The status words.** Say which word of yours a seat writes for each loop state above, in one line — *"a
+  seat that would write `current` or `shipped` writes `stable`; `wip` and `draft` are `draft`"*. `draft` is
+  the one word `init doctor` looks for, in either header form.
+- **What the verified date means.** It moves only when a doc is checked against code in that run, whatever
+  it is called; state the rule in your words so the anti-fabrication rule survives the rename.
+- **Whether `## Lineage` stays.** It is the footer that carries Idea, Spec, Built and Related; a repository
+  whose own tooling derives that graph may drop it and say so.
+- **Your gates.** Name the validator or index a commit must pass, and which of the loop's folders it
+  exempts. The loop's session folders (`research/`, `working/`, `archive/`) hold breadcrumbs, not living
+  docs, and are the usual exemption.
+- **Your archive home.** A repository whose living docs already have a home for an effort's history (a
+  feature's own folder, say) may file a spec pipeline **as one package** into that home: nothing is
+  re-sorted, every file keeps its name and its place, `sessions/` rides along untouched, and the effort's
+  working docs join the package under `implementation/`, with the tracker still the "read me first" at its
+  root. When where a pipeline files depends on something only its authoring session knows, say so —
+  `spec-pipeline` then records the resolved path in the umbrella's blockquote as an `Archive:` line.
+- **Your rails.** Fill each item of `engineering-loop.md` § This repository's rails from what the
+  repository already wrote down — a policy document, hooks, CI, a pull-request template.
+
+**The version stamp** on line 1 names the pack version whose repository-owned sections this copy carries.
+The loop text around them is this repository's copy from whenever it was taken: `init doctor` never grades
+it, and `init refresh` never touches it — refresh adds a section or a rails item a newer pack reads, and
+restamps.
+
+---
+
+## The archive convention (repository-owned)
+
+> **Repository-owned.** This section says where a finished effort is filed and in what shape. A
+> repository whose living docs already have a home for an effort's history rewrites it in its
+> `docs/_meta/` copy; every skill that files a doc reads this copy, never its own text.
+> [The repository-owned sections](#the-repository-owned-sections) lists what it must answer.
 
 A multi-session effort becomes a **topic folder** under `archive/` (e.g. `archive/{topic}/`).
 Docs are **not numbered** — they use descriptive names and chain via a header link:
@@ -113,8 +195,7 @@ one** (via `spec-pipeline`). The trigger for the layout is simply *"does this ef
                                record, not the convention.
   ```
 
-**Follow-on pipelines (multi-round families).** *(Renamed at the v2 cutover — this section was
-`Follow-on chains`; skills citing the old heading mean this one.)* A second (third, …) spec pipeline that continues an
+**Follow-on pipelines (multi-round families).** A second (third, …) spec pipeline that continues an
 already-archived effort gets its **own sibling topic folder**, never filed inside the frozen one.
 Rules: (a) name the new topic `{family-prefix}-{subtopic}` so the family groups
 alphabetically; (b) each folder keeps the full split shape (own `project-status.md` at root); (c) the
@@ -137,7 +218,14 @@ report sits beside the docs it audits. The cross-cutting `health-report-{date}.m
 
 ---
 
-## Doc metadata (header + lineage)
+## Doc metadata (repository-owned)
+
+> **Repository-owned.** This section prescribes the machine header every doc the loop writes carries.
+> What follows is the loop's own header. A repository whose docs already carry a metadata convention
+> (YAML frontmatter with its own keys and status words, a validator, an indexer) rewrites this section
+> and the templates below in its `docs/_meta/` copy to say that convention, in one voice; every skill
+> that writes a doc takes the header from this copy. [The repository-owned sections](#the-repository-owned-sections)
+> lists what it must answer.
 
 Two additive machine layers wrap a doc's unchanged human content: an invisible **header meta-comment**
 (greppable status/identity) and a visible **`## Lineage` footer** (the clickable provenance breadcrumb).
@@ -219,7 +307,10 @@ Obsidian; don't imitate it.
 
 ---
 
-## Templates
+## Templates (repository-owned)
+
+> **Repository-owned.** A repository that rewrote "Doc metadata" rewrites each template's header lines
+> here to match; the sections beneath them are the loop's and stay.
 
 ### Session / working doc (created during a session, archived by `docs-write`)
 
@@ -355,7 +446,9 @@ spec set *is* the design history.
 **`spec-*` = the execution loop** (how big work gets built: graduate a plan, a coordinator seat,
 build seats). They hand off at both ends: research docs feed `spec-pipeline`; every build session
 closes with `docs-write`; `docs-process` compiles the results back into living docs. A seat prompt
-never restates a rule a skill holds — the prompt points, the skill holds it.
+never restates a rule a skill holds — the prompt points, the skill holds it. And a skill never restates
+what this file's repository-owned sections hold: the header a doc carries and where an effort is filed
+come from this copy, so a repository changes them once, here.
 
 | Skill | When | What it does |
 |-------|------|-------------|
@@ -411,7 +504,7 @@ never restates a rule a skill holds — the prompt points, the skill holds it.
   the actual source. For prescriptive docs (`patterns/`, `guides/`) the doc is the decided rule — check
   that code conforms to it instead (see "Two kinds of living doc" above).
 - **Every living / spec / working doc carries the machine layer** — a one-line `<!-- meta: … -->` header
-  below the blockquote + a `## Lineage` footer (see "Doc metadata (header + lineage)" above). The meta
+  below the blockquote + a `## Lineage` footer (see "Doc metadata (repository-owned)" above). The meta
   `verified` date moves with the blockquote's `Last verified` and obeys the same anti-fabrication rule:
   only stamp it for a doc actually checked against code this run.
 - **Don't edit archived docs** — stale references there are historical record.

package/references/engineering-loop.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.2.1 -->
+<!-- naswerks-loop: version=0.4.0 -->
 # The Engineering Loop — flow, seats, skills, and the ceremony
 
 > The quick intro to how work gets built with this loop: the two loops (`docs-*` knowledge, `spec-*`
@@ -77,6 +77,31 @@ effort wants a review row and a docs-process row, and writes them into the row t
 learns the shape by reading its own sequence, and nothing needs a toggle. A pipeline can be plain,
 `+review`, `+review +process`, or `+process`.
 
+**Sections marked (repository-owned), here and in `docs-workflow.md`, are this repository's.** They say
+how a doc's header is written, where a finished effort is filed, and which rails a commit passes here.
+Every other section is the loop and reads the same in every repository. The coordinator and every seat
+read both documents at Step 0, so a repository's conventions reach them without a line in any prompt,
+and a skill that writes or files a doc takes those two facts from `docs-workflow.md`, never from its
+own text. One grep lists every such section — `rg -n '^#+ .*\(repository-owned\)' docs/_meta/` — and
+`docs-workflow.md` § The repository-owned sections lists what each answers and where it is echoed.
+
+## This repository's rails (repository-owned)
+
+What a commit and a PR pass here, beyond the loop. These add to the Hard rules below; they never subtract.
+
+- **Policy.** No policy document recorded — fill this in: the document every seat is bound by, and how a
+  seat reaches it.
+- **Gates a commit passes.** No commit gates recorded — fill this in: the hooks and checks a commit must
+  pass, and what each validates.
+- **Before a PR.** No pre-PR suite recorded — fill this in: the suite that runs before a PR, and where its
+  commands live.
+- **Where a PR goes.** No PR route recorded — fill this in: the base branch, the host, the branch names,
+  and how a PR is opened.
+- **Staging.** No staging rule recorded — fill this in: anything stricter than the Hard rules' explicit
+  paths and `verify-staged`.
+- **Skills a seat meets here.** No repository skills recorded — fill this in: the repository's own skills
+  a seat invokes by name, and when.
+
 ## Two loops — both hand-crankable
 
 - **`docs-*` is the knowledge loop** and runs standalone, forever: small/everyday efforts are
@@ -128,7 +153,7 @@ The thing that keeps prompts and skills from drifting apart:
 
 | Kind | Home | Why there |
 |---|---|---|
-| **POLICY** | the un-skippable system-prompt suffix the control plane supplies at open | cannot be skipped, present on every turn |
+| **POLICY** | the policy document § This repository's rails names — and, hosted, the un-skippable system-prompt suffix the control plane supplies at open | cannot be skipped, present on every turn |
 | **PROCEDURE — shared** | `spec-seat` | the contract for ANY seat the coordinator arms: blackboard, question lane, parked-call discriminator, verdicts, BELIEFS sha, git shapes, six-section FINAL TLDR, close-out order |
 | **PROCEDURE — per job** | `spec-child` · `spec-review` · `docs-process` | what THIS seat does. The job skill **refines** the seat contract and never contradicts it; a genuine conflict is a finding, not a fork |
 | **TASK** | the seed prompt + the pipeline's `00-ignition-brief.md` | per-run; dies with the run |

package/skills/docs-audit-feature/SKILL.md

@@ -10,6 +10,8 @@ docs, or a whole folder — in `docs/features/`, `docs/infrastructure/`, or `doc
 the one audit skill for "does this doc still match the code"; it produces both the **audit report**
 and the **corrected living doc**.
 
+**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 system:** `docs/_meta/doc-index.md` (the menu of living docs) + `docs/_meta/docs-workflow.md`
 > (the loop, folders, templates) explain how the docs are organized. Skim them if you need to place a
 > doc or find its siblings.
@@ -30,28 +32,29 @@ writes across docs. End with a one-line-per-doc summary (stale-count / added-cou
 1. **Read the living doc** (`docs/features/{x}.md`, `docs/infrastructure/{x}.md`, or
    `docs/patterns/{x}.md`).
 
-2. **Read the corresponding code** — the backend `Features/{Feature}/` slice and matching frontend
-   feature folder for feature docs; the relevant subsystem for infrastructure/pattern docs. Confirm
-   entities, endpoints, stores, routes, services, config, key files.
+2. **Read the corresponding code** — the feature's code on each side, wherever
+   `docs/patterns/code-organization.md` says a feature lives, for feature docs; the relevant subsystem for
+   infrastructure/pattern docs. Confirm entities, endpoints, stores, routes, services, config, key files.
 
 3. **Check against conventions** — cross-check the doc's claims against `docs/patterns/` (and
    `docs/infrastructure/` where relevant) so the doc matches how things are actually built.
 
-4. **Report findings** — write a short audit report to `docs/archive/audit/{group}/{doc-name}-audit.md`,
-   where `{group}` mirrors the living doc's folder (`guides/`, `patterns/`, `infrastructure/`, or
-   `features/`; create the subfolder if absent). Date in header: what was accurate, what was stale,
+4. **Report findings** — write a short audit report where `docs/_meta/docs-workflow.md` § The archive
+   convention (repository-owned) files audit reports, named for the doc it audits and grouped the way that
+   section groups them (create the folder if absent). Date in header: what was accurate, what was stale,
    what's undocumented, and any **code risks / bugs / tech-debt** you noticed against the source.
-   (The master `health-report-*.md` from `docs-audit-full` stays at the `audit/` root — it's cross-cutting.)
-
-5. **Update the living doc** with the corrections and bump its "Last verified" date — **and refresh the
-   `<!-- meta: … -->` line in lockstep** (`verified` = today, update `status`, recompute `lineage=N`). This is
-   allowed here only because you just did the full doc-vs-code pass; the meta `verified` obeys the same
-   anti-fabrication rule as the blockquote date (the two always move together). **Verify the `## Lineage`
-   footer** — check every link resolves; flag any dead breadcrumb into `## Open Issues` (or the audit report)
-   and recompute `lineage=N` to match. **Soft-check `Spec` / `Built` symmetry** — for a spec-driven feature, a
+   (The master health report from `docs-audit-full` sits where that section puts it — it's cross-cutting.)
+
+5. **Update the living doc** with the corrections and set its verified date to today — **every place
+   `docs/_meta/docs-workflow.md` § Doc metadata (repository-owned) keeps that date moves in lockstep**, along
+   with its status and any field the header derives. This is allowed here only because you just did the full
+   doc-vs-code pass; the verified date obeys the anti-fabrication rule below. **Verify the `## Lineage`
+   footer** (where that section keeps it) — check every link resolves; flag any dead breadcrumb into
+   `## Open Issues` (or the audit report) and recompute any field the header derives from it. **Soft-check
+   `Spec` / `Built` symmetry** — for a spec-driven feature, a
 `Built` session whose per-slice spec is absent from `Spec` (or vice-versa) is usually an under-scoped row;
 note it and complete it *unless* the doc is deliberately scoped tighter than the effort (judgment, not a hard
-fail — see the Lineage rules in `docs-workflow.md`). **Reconcile its `## Open Issues` section** — add any real, code-verified
+fail — the `## Lineage` rules § Doc metadata (repository-owned) gives). **Reconcile its `## Open Issues` section** — add any real, code-verified
    risk/bug/tech-debt you found (dated, with `file:line`), and remove any listed issue the code now resolves.
    (The archived report is the history; `## Open Issues` is the live signal `docs-status` reads.)
 
@@ -65,8 +68,8 @@ is missed:
 - **Both exist**: run the per-doc audit above.
 
 For `docs/features/`, the folder (one doc per feature) IS the inventory — there is no separate
-catalog. Build the real list from `Features/` + the frontend feature folders/routes via actual
-`ls`/`find` output in this run, then diff.
+catalog. Build the real list from where `docs/patterns/code-organization.md` says features live — each
+side, routes included — via actual `ls`/`find` output in this run, then diff.
 
 ## Anti-fabrication rule
 
@@ -76,10 +79,11 @@ catalog. Build the real list from `Features/` + the frontend feature folders/rou
 - **Every claim traces to a file you opened in this run** — entity names, endpoints, routes, key
   files, line references. No identifiers or dates from memory. When listing a folder, build the
   feature/doc lists from real `ls`/`find` output, not memory.
-- Only stamp **"Last verified: <today>"** on a doc you actually checked against code in this run.
+- Only stamp **the verified date** (today) on a doc you actually checked against code in this run.
   Stamping a date you didn't verify is the exact failure this rule exists to prevent.
-- The `<!-- meta: verified=… -->` date is bound by the **same** rule and always equals the blockquote's
-  `Last verified` — refresh `verified` / `status` / `lineage=N` only after the full doc-vs-code pass this run.
+- Every place § Doc metadata (repository-owned) keeps that date, whatever it calls it, is bound by the
+  **same** rule and moves together — refresh it, the status and any derived field only after the full
+  doc-vs-code pass this run.
 
 ## Notes
 - **Descriptive docs (`infrastructure/`, `features/`):** code is truth — where doc and code disagree,

package/skills/docs-audit-full/SKILL.md

@@ -8,10 +8,14 @@ description: Master health check across all docs — staleness/age scan, convent
 A deep-clean sweep. Does NOT re-audit every feature in depth — it produces the prioritized plan of
 what to audit next.
 
+**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. **Freshness scan** — read "Last verified" dates across all living docs (`guides/ patterns/
-   infrastructure/ features/`). Flag anything older than ~14 days; sort oldest-first.
+1. **Freshness scan** — read the verified dates across all living docs (`guides/ patterns/
+   infrastructure/ features/`), wherever `docs/_meta/docs-workflow.md` § Doc metadata (repository-owned)
+   says that date lives (its sweep command reads them all at once). Flag anything older than ~14 days; sort
+   oldest-first.
 
 2. **Feature completeness** — quick `docs/features/` folder pass (per `docs-audit-feature`'s
    folder mode): any features in code with no doc, or docs whose feature is gone.
@@ -23,14 +27,15 @@ what to audit next.
    graduated/removed) and ideas worth surfacing.
 
 5. **Working/archive sanity** — note any docs lingering in `docs/working/` that look done (should be
-   filed via `docs-write`), and confirm `archive/` topic folders are intact.
+   filed via `docs-process`), and confirm the filed efforts are intact where § The archive convention
+   (repository-owned) puts them.
 
-6. **Read the previous report first.** Before writing anything, find the most recent
-   `docs/archive/audit/health-report-*.md` and read it in full. The new report continues from it:
-   note what was flagged last time and is now fixed, what's still outstanding, and anything that
-   regressed. If there is **no** prior report, say so — this run is the baseline.
+6. **Read the previous report first.** Before writing anything, find the most recent health report —
+   where § The archive convention (repository-owned) files audit reports — and read it in full. The new
+   report continues from it: note what was flagged last time and is now fixed, what's still outstanding,
+   and anything that regressed. If there is **no** prior report, say so — this run is the baseline.
 
-7. **Produce a health report** at `docs/archive/audit/health-report-{date}.md` with a prioritized,
+7. **Produce a health report** — `health-report-{date}.md`, beside the previous one — with a prioritized,
    actionable list (which `docs-audit-feature` runs, which docs to re-verify, which research to clear).
    Open with a **"Since last report"** section that diffs against the report from step 6 (or marks this
    as the baseline if none existed).

package/skills/docs-backlog/SKILL.md

@@ -7,6 +7,8 @@ description: Capture an idea, improvement, or future-state design as a research
 
 Capture ideas as research docs. `docs/research/` is the idea inbox — the folder itself is the queue.
 
+**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. **Scan existing research titles** in `docs/research/` — quick check for an obvious duplicate or a
@@ -14,7 +16,8 @@ Capture ideas as research docs. `docs/research/` is the idea inbox — the folde
 
 2. **For each idea, create a research doc** at `docs/research/{topic}.md` using the research-doc
    template in `docs/_meta/docs-workflow.md`: Current State, Desired End State, Design Options /
-   Recommendation, Open Questions. Capture the idea while it's fresh — verify "Current State" against
+   Recommendation, Open Questions. Its header is the one that file's § Doc metadata (repository-owned)
+   prescribes, at the word for `draft`. Capture the idea while it's fresh — verify "Current State" against
    code if quick, otherwise note it's unverified.
 
    **The research doc must be self-contained.** It's the durable jump-off point; assume everything else
@@ -37,5 +40,5 @@ Capture ideas as research docs. `docs/research/` is the idea inbox — the folde
 - When an idea is later picked up and built, link it via the session doc's **Source** field. The
   research doc **stays in `research/` through the build** (it's the running tab, and a build may span
   several sessions / working docs). When the effort finishes, `docs-process` archives the research doc
-  **alongside its working doc(s)** in the same `archive/{topic}/` folder — research and the work that
-  delivered it are filed together, not deleted.
+  **alongside its working doc(s)** in the same archive home (`docs-workflow.md` § The archive convention
+  (repository-owned)) — research and the work that delivered it are filed together, not deleted.