@naswerks/engineering-loop 0.4.0 → 0.5.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "naswerks",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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,40 @@ version is the one in `package.json` and `.claude-plugin/plugin.json`, which mus
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-24
+
+### Fixed
+
+- A doc on a curated menu meets the loop's standard when it names the code it describes in either form: a
+  `## Key Files` section, or a frontmatter `related_files` list. The doctor checked for the heading alone and
+  flagged docs that name their code in frontmatter.
+- A patch release never asks a copy of the method docs to change, so `init doctor` and `init refresh` read a
+  stamp as behind only when its minor version is.
+
+## [0.5.0] - 2026-09-24
+
+### Added
+
+- **The menu declares its shape.** `docs/_meta/doc-index.md` carries `<!-- naswerks-loop: menu=all -->` (it
+  lists every living doc: the repository has no other index; the default, and what a menu with no such line
+  means) or `<!-- naswerks-loop: menu=curated; index={path} -->` (the repository already indexes every doc in
+  `{path}`; the menu lists the docs its seats read). `docs-workflow.md` § The repository-owned sections
+  explains both, and the loop's standard for a doc on a curated menu: a header at a decided status and a
+  `## Key Files` section. `init` writes `menu=curated` when its scan finds an index the repository already
+  keeps; `docs-process` registers a new doc where the shape says; `docs-status` and `docs-audit-full` flag a
+  menu that has drifted; `init doctor` reads the shape, FAILs a doc the menu names that does not exist,
+  flags a living doc an all-menu misses, and holds every doc a curated menu names to the standard.
+  `pins/menu.test.mjs` holds both shapes.
+
+### Changed
+
+- The map's Doc metadata row no longer asks whether the menu is kept by hand; the menu's shape line says
+  what the menu is.
+- `docs-workflow.md` § The repository-owned sections no longer says which words this repository writes for
+  the loop's states; that is § Doc metadata's to say, so a repository that pastes the section verbatim no
+  longer inherits a line that is untrue for it.
+- README: taking a new release is `claude plugin update`; the pins and the release path read as they are.
+
 ## [0.4.0] - 2026-09-23
 
 ### Changed

package/README.md

@@ -20,7 +20,8 @@ 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.
+To pick up a new release later: `claude plugin marketplace update engineering-loop`, then
+`claude plugin update naswerks@engineering-loop` (an install over an existing install does nothing).
 
 Skills are namespaced by the plugin: `/naswerks:docs-write`, `/naswerks:spec-pipeline`, `/naswerks:init`.
 
@@ -48,6 +49,11 @@ sections lists what each must answer. One grep lists the four:
 rg -n '^#+ .*\(repository-owned\)' docs/_meta/
 ```
 
+If the repository already keeps an index of every doc, declare the loop's menu curated — put
+`<!-- naswerks-loop: menu=curated; index=docs/INDEX.md -->` (your index's path) in `docs/_meta/doc-index.md`
+— and the menu lists only the docs your seats read, each held to the loop's standard; every other doc stays
+in your own index. A repository with no index of its own keeps the default, a menu of every living doc.
+
 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 —
@@ -70,7 +76,7 @@ and never touches the rest of the text.
 | `spec-retro` | spec | the coordinator's close-out audit |
 | `spec-witness` | spec | a read-only verifier |
 | `spec-ignite` | spec | the ignition copilot for a hosted run |
-| `init` | — | make a repository ready for both loops |
+| `init` | — | make a repository ready for both loops; `init doctor` checks one, `init refresh` takes a newer pack's repository-owned sections |
 
 `references/` carries the two method documents a repository copies into `docs/_meta/` and then
 rewrites where they say (repository-owned);
@@ -84,19 +90,26 @@ or the child may resolve `docs/` paths against the parent session's workspace.
 
 ## Does it work
 
-`npm test` runs the pins: one version across the package, the plugin manifest and the marketplace
-entry; every skill directory carries a `SKILL.md` named for its folder; no byte-order marks; the
-method documents carry the version stamp; the vocabulary censuses. `node bin/verify-staged.mjs
---self-test` drives the receipt against a throwaway repository and reports each case.
+`npm test` runs the pins: one version across the package, the plugin manifest, the marketplace entry and
+both method documents' stamps; every skill directory carries a `SKILL.md` named for its folder; no
+byte-order marks; the vocabulary and content censuses; no skill states a format a repository owns, and
+every skill that needs one carries the same find-format line; exactly four repository-owned sections, found
+by the one grep; the loop's own preferences stay stated in the method documents; the menu's two shapes; `init refresh` leaves
+every line outside those sections byte for byte. `node bin/verify-staged.mjs --self-test` drives the
+receipt against a throwaway repository and reports each case.
 
 ## Releasing
 
-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. 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).
+The version lives in `package.json`, `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
+(they must agree), in both method documents' stamps, and in a CHANGELOG section. 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.
+
+To release: push the release commit to `main`, publish it to npm from the repository root (`npm login`,
+then `npm publish --access public`), then push its `v*` tag. The tag's workflow runs the pins, finds the
+version already on the registry and skips its own publish, and creates the GitHub release from the
+CHANGELOG section. With a trusted publisher linked on npmjs.com for this repository and `release.yml`,
+pushing the tag alone publishes; the workflow prints that remedy when a publish is refused.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naswerks/engineering-loop",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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.4.0 -->
+<!-- naswerks-loop: version=0.5.1 -->
 # Docs Workflow
 
 > How knowledge flows through `docs/`: the loop, the folder rules, the templates, and the `docs-*` skills.
@@ -84,12 +84,12 @@ 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` |
+| **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 | 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.
+writes for each.
 
 | State | Written by | Means |
 |-------|------------|-------|
@@ -100,8 +100,22 @@ writes for each. Here the words are the states themselves.
 
 *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
+**The menu.** `doc-index.md` is the menu the seats read, and the whole file is the repository's: `init` writes
+it once and never again. A line near its top says which of two shapes it has, and one grep reads it:
+`rg -n 'naswerks-loop: menu=' docs/_meta/doc-index.md`.
+
+| Shape line | The menu lists | A new living doc goes |
+|------------|----------------|-----------------------|
+| `<!-- naswerks-loop: menu=all -->` | every living doc — the repository has no other index | onto the menu |
+| `<!-- naswerks-loop: menu=curated; index={path} -->` | the docs this repository's seats read; `{path}` indexes every doc | into `{path}`, the way that index is kept, and onto the menu only when it meets the loop's standard and a seat should read it |
+
+**The loop's standard for a doc on a curated menu:** it exists, it carries the header § Doc metadata
+prescribes at a decided status (not the word for `draft`), and it names the code it describes — a
+`## Key Files` section, or a frontmatter `related_files` list. `init doctor` checks exactly that, for every doc
+a curated menu names.
+
+**Silence.** A section that says nothing about an item leaves the loop's default: a menu with no shape line
+lists every living doc (`menu=all`), 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.
@@ -131,8 +145,12 @@ Keep what the skills need to find, change the words to yours:
   `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.
+- **Your menu.** A repository that already indexes its docs declares its menu curated and names that index:
+  the menu then lists only the docs its seats read, each meeting the loop's standard, and every other doc
+  stays in the repository's own index, kept the way it already is.
 
-**The version stamp** on line 1 names the pack version whose repository-owned sections this copy carries.
+**The version stamp** on line 1 names the pack version whose repository-owned sections this copy carries. A
+patch release never asks a copy to change, so a stamp is behind only when its minor version is.
 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.

package/references/engineering-loop.md

@@ -1,4 +1,4 @@
-<!-- naswerks-loop: version=0.4.0 -->
+<!-- naswerks-loop: version=0.5.1 -->
 # 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-*`

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

@@ -18,7 +18,10 @@ what to audit next.
    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.
+   folder mode): any features in code with no doc, or docs whose feature is gone. Then the menu against its
+   shape line (`rg -n 'naswerks-loop: menu=' docs/_meta/doc-index.md`; none means `menu=all`): on
+   `menu=all`, living docs it does not name; on `menu=curated`, docs it names that fall short of the loop's
+   standard (`docs/_meta/docs-workflow.md` § The repository-owned sections).
 
 3. **Convention spot-check** — sample 2-3 source files per major convention against the
    `docs/patterns/` docs; note drift.

package/skills/docs-process/SKILL.md

@@ -92,9 +92,13 @@ 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` — unless `docs-workflow.md` § Doc metadata
-   (repository-owned) says a repository tool generates the menu, in which case leave it alone.
+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

package/skills/docs-status/SKILL.md

@@ -36,6 +36,11 @@ just counts.
      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 its code named in a `## Key Files`
+     section or a frontmatter `related_files` list).
 
 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

package/skills/init/SKILL.md

@@ -38,7 +38,8 @@ docs/
   _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:
+  _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
@@ -104,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
 
@@ -134,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.
@@ -183,13 +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 (or on the first line after a frontmatter block) | stamp behind the pack's version (`init refresh` restamps) | 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's minor version behind the pack's (`init refresh` restamps; a patch never asks a copy to change) | stamp's minor equals the pack's |
 | 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 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 named code (a `## Key Files` section or a frontmatter `related_files` list) | 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 |
-| 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 |
 | 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 |

package/skills/init/scripts/doctor.mjs

@@ -5,7 +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';
+import { OWNED, compareVersions, compareMinor, frontmatterListCount, linesOf, bare, h2Index, findSection, railsItems } from './owned.mjs';
 
 const repo = resolve(process.argv[2] || process.cwd());
 const packRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
@@ -40,9 +40,8 @@ for (const name of ['docs-workflow.md', 'engineering-loop.md']) {
   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} — 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]}`);
+  if (compareMinor(m[1], packVersion) < 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}`, compareVersions(m[1], packVersion) < 0 ? `stamp ${m[1]} (the pack is ${packVersion}: a patch never asks a copy to change)` : `stamp ${m[1]}`);
 
   // ── 2b. the repository-owned sections: present under the heading a skill looks them up by ─────────
   const lines = linesOf(text);
@@ -118,13 +117,46 @@ function docRow(relPath, required) {
   if (/<!-- init:/.test(text)) row('DEGRADE', `docs/${relPath}`, 'an <!-- init: --> instruction was left in the file');
 }
 
-// ── 4b. every path a Role reading lists row names resolves ─────────────────────────────────────
-if (roleRows !== null) {
-  for (const line of roleRows.split('\n').filter((l) => l.trim().startsWith('|') && !/^\|\s*-/.test(l.trim()) && !/^\|\s*Doc\s*\|/i.test(l.trim()))) {
-    for (const m of line.matchAll(/`((?:patterns|infrastructure|guides|features)\/[A-Za-z0-9_.-]+\.md)`|\]\((?:\.\.\/)?((?:patterns|infrastructure|guides|features)\/[A-Za-z0-9_.-]+\.md)\)/g)) {
-      const p = m[1] || m[2];
-      if (/not detected/i.test(line)) continue;
-      row(existsSync(join(repo, 'docs', p)) ? 'ok' : 'FAIL', `doc-index row: docs/${p}`, existsSync(join(repo, 'docs', p)) ? '' : 'the row names a path that does not exist');
+// ── 4b. the menu: its shape, and every doc it names ────────────────────────────────────────────
+// doc-index.md declares one of two shapes (docs-workflow.md § The repository-owned sections): menu=all lists
+// every living doc; menu=curated lists the docs the seats read and names the index that lists every doc. A
+// menu with no shape line is menu=all. Every doc a menu names must exist (a row saying `not detected` is
+// exempt); a curated menu's docs must also meet the loop's standard: a status in either header form, not
+// draft, and names the code it describes: a `## Key Files` section, or a frontmatter `related_files` list.
+{
+  const menu = read(join(repo, 'docs', '_meta', 'doc-index.md'));
+  if (menu !== null) {
+    const line = /<!-- naswerks-loop: menu=([A-Za-z-]+)(?:;\s*index=(\S+?))?\s*-->/.exec(menu);
+    const shape = line ? line[1] : 'all';
+    if (!['all', 'curated'].includes(shape)) row('FAIL', 'menu shape', `menu=${shape} is not a shape the loop knows (all | curated)`);
+    else if (shape === 'curated') {
+      const index = line[2];
+      if (!index) row('DEGRADE', 'menu shape', 'menu=curated names no index of every doc, so docs-process cannot say where a new doc is registered');
+      else if (!existsSync(join(repo, index))) row('DEGRADE', 'menu shape', `menu=curated; its index ${index} does not exist`);
+      else row('ok', 'menu shape', `menu=curated; index=${index}`);
+    } else row('ok', 'menu shape', line ? 'menu=all' : 'menu=all (no shape line: the default)');
+
+    const named = new Set();
+    for (const l of menu.split('\n')) {
+      if (/not detected/i.test(l)) continue;
+      for (const m of l.matchAll(/(?:\]\(|`)(?:\.\.\/)?((?:guides|patterns|infrastructure|features)\/[A-Za-z0-9_./-]+\.md)/g)) named.add(m[1]);
+    }
+    const missing = [...named].filter((p) => !existsSync(join(repo, 'docs', p))).sort();
+    for (const p of missing) row('FAIL', `menu: docs/${p}`, 'the menu names a doc that does not exist');
+    if (shape === 'curated') {
+      for (const p of [...named].filter((q) => !missing.includes(q)).sort()) {
+        const text = read(join(repo, 'docs', p));
+        const short = [];
+        const st = statusOf(text);
+        if (st === null) short.push('no status in either header form');
+        else if (st.value === 'draft') short.push('status draft');
+        if (!/^## Key Files\b/m.test(text) && frontmatterListCount(text, 'related_files') === 0) short.push('names no code (no ## Key Files section, no related_files list)');
+        row(short.length ? 'DEGRADE' : 'ok', `menu: docs/${p}`, short.length ? `below the loop's standard: ${short.join(', ')}` : "meets the loop's standard");
+      }
+    } else if (shape === 'all') {
+      const unnamed = livingDocs().filter((p) => !named.has(p) && !menu.includes(p));
+      for (const p of unnamed) row('DEGRADE', `menu: docs/${p}`, 'a living doc the menu does not name (menu=all) — add its row, or declare the menu curated');
+      if (!unnamed.length && !missing.length) row('ok', 'menu entries', `names every living doc (${named.size}), each present`);
     }
   }
 }
@@ -249,6 +281,24 @@ function frontmatterOf(text) {
   }
   return out;
 }
+// The living docs a menu=all menu lists: every .md directly under the four living folders, and each
+// feature folder's own docs one level down (a filed effort's notes sit deeper and are history, not living).
+function livingDocs() {
+  const out = [];
+  for (const f of ['guides', 'patterns', 'infrastructure', 'features']) {
+    const dir = join(repo, 'docs', f);
+    if (!existsSync(dir)) continue;
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isFile() && e.name.endsWith('.md') && e.name !== 'README.md') out.push(`${f}/${e.name}`);
+      else if (f === 'features' && e.isDirectory()) {
+        for (const g of readdirSync(join(dir, e.name), { withFileTypes: true })) {
+          if (g.isFile() && g.name.endsWith('.md') && g.name !== 'README.md') out.push(`features/${e.name}/${g.name}`);
+        }
+      }
+    }
+  }
+  return out.sort();
+}
 function firstBodyLine(text) {
   let body = text;
   if (text.startsWith('---\n')) { const end = text.indexOf('\n---', 4); if (end >= 0) body = text.slice(end + 4).replace(/^\n+/, ''); }

package/skills/init/scripts/owned.mjs

@@ -27,6 +27,32 @@ export function compareVersions(a, b) {
   return 0;
 }
 
+// A patch release never changes what a copy of the method docs carries, so a stamp is behind only when its
+// major.minor is.
+export function compareMinor(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 < 2; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); }
+  return 0;
+}
+
+// How many entries a frontmatter key lists: an inline `[a, b]`, indented `- item` lines, or one scalar. Zero
+// when the key is absent or empty.
+export function frontmatterListCount(text, key) {
+  const t = text.replace(/\r\n/g, '\n');
+  if (!t.startsWith('---\n')) return 0;
+  const end = t.indexOf('\n---', 4);
+  if (end < 0) return 0;
+  const lines = t.slice(4, end).split('\n');
+  const i = lines.findIndex((l) => l.startsWith(`${key}:`));
+  if (i < 0) return 0;
+  const inline = lines[i].slice(key.length + 1).trim();
+  if (inline.startsWith('[')) return inline.replace(/^\[|\]$/g, '').split(',').map((x) => x.trim()).filter(Boolean).length;
+  if (inline) return 1;
+  let n = 0;
+  for (let j = i + 1; j < lines.length && /^\s+-\s*\S/.test(lines[j]); j++) n++;
+  return n;
+}
+
 // A file as lines that keep their own terminators, so an untouched line is written back byte for byte.
 export function linesOf(text) {
   return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];

package/skills/init/scripts/refresh.mjs

@@ -6,7 +6,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { OWNED, STAMP, compareVersions, linesOf, bare, eolOf, h2Index, findSection, railsItems, stampIndex, mapOf } from './owned.mjs';
+import { OWNED, STAMP, compareVersions, compareMinor, linesOf, bare, eolOf, h2Index, findSection, railsItems, stampIndex, mapOf } from './owned.mjs';
 
 const args = process.argv.slice(2);
 const write = args.includes('--write');
@@ -92,13 +92,14 @@ for (const file of ['docs-workflow.md', 'engineering-loop.md']) {
   const stampAt = stampIndex(lines);
   const current = STAMP.exec(bare(lines[stampAt]))[2];
   const cmp = compareVersions(current, packVersion);
-  if (cmp < 0) {
+  if (compareMinor(current, packVersion) < 0) {
     const raw = lines[stampAt];
     const bom = raw.startsWith('') ? '' : '';
     lines[stampAt] = bom + raw.slice(bom.length).replace(STAMP, `$1${packVersion}$3`);
     row(shown, 'stamp', `${current} to ${packVersion}`);
     changed = true;
   } else if (cmp > 0) row(shown, 'stamp', `${current} — ahead of this pack; left as it is`);
+  else if (cmp < 0) row(shown, 'stamp', `${current} — the pack is ${packVersion}, a patch: a patch never asks a copy to change`);
   else row(shown, 'stamp', `${current} — current`);
 
   if (changed) {

package/skills/spec-seat/SKILL.md

@@ -53,7 +53,7 @@ Do this immediately, whatever your assignment turns out to be. It needs no role
 
 | Doc | What it gives you |
 |---|---|
-| `docs/_meta/doc-index.md` | the menu — which living doc answers which question |
+| `docs/_meta/doc-index.md` | the menu — which living doc answers which question: every living doc, or on a curated menu the ones meant for seats (its shape line says which) |
 | `docs/_meta/docs-workflow.md` | the folders, the templates, the two loops — and, in its sections marked (repository-owned), this repository's doc header and where an effort is filed |
 | `docs/_meta/engineering-loop.md` | the seats, the ceremony, **the comms protocol you follow** — and this repository's rails (repository-owned) |
 

package/templates/docs/_meta/doc-index.md

@@ -2,6 +2,12 @@
 
 > The menu. Read this at session start, pick the 2-3 docs that match your task, read those for context.
 > This is the curated short list — the compiled layer you read *before* diving into source.
+<!-- naswerks-loop: menu=all -->
+<!-- init: the shape line above stays in the output. It says menu=all unless the scan found 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); then it says
+     menu=curated; index={that path}, and the tables below list only the docs init drafted plus the Meta
+     rows. The owner adds each further doc that meets the loop's standard. -->
 
 ---