@naswerks/engineering-loop 0.5.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.5.0",
+      "version": "0.5.1",
       "source": "./"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "naswerks",
-  "version": "0.5.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,16 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naswerks/engineering-loop",
-  "version": "0.5.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.5.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.
@@ -110,8 +110,9 @@ it once and never again. A line near its top says which of two shapes it has, an
 | `<!-- 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 has a `## Key Files` section. `init doctor`
-checks exactly that, for every doc a curated menu names.
+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
@@ -148,7 +149,8 @@ Keep what the skills need to find, change the words to yours:
   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.5.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-status/SKILL.md

@@ -39,7 +39,8 @@ just counts.
    - **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).
+     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

@@ -190,13 +190,13 @@ 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 `## Key Files` | meets the loop's standard |
+| 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 |
 | `CLAUDE.md` / `AGENTS.md` stanza · `.claude/settings.json` pin | — | missing | present |

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);
@@ -123,7 +122,7 @@ function docRow(relPath, required) {
 // 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 a `## Key Files` section.
+// 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) {
@@ -151,7 +150,7 @@ function docRow(relPath, required) {
         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)) short.push('no ## Key Files');
+        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') {

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) {