@naswerks/engineering-loop 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "engineering-loop",
+  "owner": { "name": "naswerks" },
+  "metadata": {
+    "description": "The engineering loop as a Claude Code plugin: docs-* (knowledge), spec-* (execution), init."
+  },
+  "plugins": [
+    {
+      "name": "naswerks",
+      "description": "The engineering loop: docs-* knowledge loop, spec-* execution loop, and init for a fresh repository.",
+      "version": "0.1.0",
+      "source": "./"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "naswerks",
+  "version": "0.1.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",
+  "keywords": ["skills", "engineering-loop", "spec-pipeline", "docs"]
+}

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this package are recorded here. The format follows Keep a Changelog; the
+version is the one in `package.json` and `.claude-plugin/plugin.json`, which must agree.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-20
+
+### Added
+
+- The fourteen loop skills as a plugin: `docs-audit-feature`, `docs-audit-full`, `docs-backlog`,
+  `docs-process`, `docs-status`, `docs-write`, `spec-child`, `spec-ignite`, `spec-parent`,
+  `spec-pipeline`, `spec-retro`, `spec-review`, `spec-seat`, `spec-witness`.
+- `references/docs-workflow.md` and `references/engineering-loop.md`, the method documents a
+  repository copies into `docs/_meta/`, each stamped with the pack version.
+- `bin/verify-staged.mjs`, the staging receipt: proves every path handed to `git add` actually
+  landed, naming the ignore rule that ate any that did not.
+- `init`: makes a repository ready for both loops. Creates the `docs/` shape with a README per folder,
+  copies the two method documents with the pack's version stamp, writes `docs/_meta/doc-index.md` with
+  the sections the skills read, drafts first versions of every document the skills send a reader to by
+  scanning the repository (and the four stack-conditional ones only where the stack is found), adds
+  the start-here stanza to `CLAUDE.md` and `AGENTS.md` where they exist, and the plugin pin to
+  `.claude/settings.json`. Idempotent: a second run writes nothing and reports. `init doctor`
+  (`skills/init/scripts/doctor.mjs`) grades a repository FAIL / DEGRADE / ok per row.
+- The skills describe the method for any repository: repository-specific knowledge moved to the
+  documents `init` writes, one plane's retired vocabulary left, hosted-control-plane recipes are marked
+  as such.
+- The pins (`npm test`): manifest and package versions agree, every skill directory carries a
+  `SKILL.md` whose `name` is its folder, no byte-order marks, the vocabulary censuses, and the content
+  censuses (no private product or dated incident, no glyphs, no link into an archived effort, every
+  document a skill names is one `init` writes, the parser contracts a control plane reads).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 naswerks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# engineering-loop
+
+The engineering loop as a Claude Code plugin: a **knowledge loop** (`docs-*`) that keeps a repository's
+living documentation true, and an **execution loop** (`spec-*`) that turns an approved plan into a numbered
+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.
+
+## Install
+
+**In your own Claude Code** (every repository on the machine):
+
+```
+claude plugin marketplace add naswerks/engineering-loop
+claude plugin install naswerks@engineering-loop
+```
+
+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):
+
+```
+npm i -g @naswerks/engineering-loop
+```
+
+then point the runner at `$(npm root -g)/@naswerks/engineering-loop` — with periscope, the
+`PERISCOPE_PLUGIN_DIRS` key, or the Plugins field on the control plane's runner page.
+
+**In a repository** (so everyone who clones it gets the loop): `/naswerks:init` writes the `docs/`
+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.
+
+## What is in the box
+
+| Skill | Loop | One line |
+|---|---|---|
+| `docs-backlog` | docs | park an idea as a research doc |
+| `docs-status` | docs | orient at session start: archived, in flight, waiting |
+| `docs-write` | docs | finalize the session's working doc |
+| `docs-process` | docs | patch living docs from working docs, verified against code, then archive |
+| `docs-audit-feature` · `docs-audit-full` | docs | audit living docs against code |
+| `spec-pipeline` | spec | explode an approved plan into numbered specs |
+| `spec-parent` | spec | the coordinator seat |
+| `spec-seat` | spec | the contract every armed seat follows |
+| `spec-child` | spec | the build job for one spec |
+| `spec-review` | spec | the outside look before the retrospective |
+| `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 |
+
+`references/` carries the two method documents a repository copies into `docs/_meta/`;
+`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`.
+
+Running a skill through a child `claude -p` from inside another Claude Code session: scrub the
+`CLAUDE_CODE_*` variables from the child's environment and name the repository root in the prompt,
+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.
+
+## 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.
+
+## License
+
+MIT.

package/bin/verify-staged.mjs

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+// The staging receipt.
+//
+// `git add <dir>` skips gitignored children with exit 0 and no output, and `git status` cannot show
+// the loss: an ignored file is neither staged nor dirty, so a silently skipped add makes status look
+// CLEANER, not worse. Run this between `git add` and `git commit` over the SAME path list you gave to
+// `git add`; a non-zero exit names every file that did not land and the ignore rule that ate it.
+//
+//   verify-staged docs/research/topic/sessions/slug src/x.cs
+//   verify-staged --from-file .staging-list.txt --against head
+//   verify-staged --self-test
+//
+// States. Red: IGNORED, NEVER-ADDED, NOT-STAGED, MISSING-FROM-DISK, TOO-BROAD, ERROR.
+// Green (notes): STAGED, IN-HEAD, ALREADY-COMMITTED-CLEAN.
+//
+// Deliberately not a fix for .gitignore: widening or anchoring a repository's ignore rules is a
+// repository decision, and force-adding against one is a ruling, not a default.
+//
+// Paths with embedded newlines are not supported (line-delimited git output, core.quotepath=false).
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, sep } from 'node:path';
+
+const DIR_EXPANSION_CAP = 2000;
+
+function git(root, args) {
+  try {
+    const out = execFileSync('git', ['-C', root, '-c', 'core.quotepath=false', ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { ok: true, exit: 0, lines: out.split(/\r?\n/).filter((l) => l.length > 0) };
+  } catch (e) {
+    const out = typeof e.stdout === 'string' ? e.stdout : '';
+    return { ok: false, exit: typeof e.status === 'number' ? e.status : 1, lines: out.split(/\r?\n/).filter((l) => l.length > 0) };
+  }
+}
+
+function toRepoRelative(root, input) {
+  let p = input.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+  if (isAbsolute(p) || /^[A-Za-z]:\//.test(p)) {
+    const rootNorm = root.replace(/\\/g, '/').replace(/\/+$/, '');
+    if (!p.toLowerCase().startsWith(rootNorm.toLowerCase())) return null;
+    p = p.slice(rootNorm.length).replace(/^\/+/, '');
+  }
+  return p.length === 0 ? null : p;
+}
+
+export function testStagedList(root, paths, mode = 'index') {
+  const findings = [];
+  const notes = [];
+  const top = git(root, ['rev-parse', '--show-toplevel']);
+  if (!top.ok || top.lines.length === 0) {
+    findings.push({ file: root, state: 'ERROR', detail: 'not inside a git repository (rev-parse --show-toplevel failed)' });
+    return { ok: false, findings, notes, expected: 0, green: 0 };
+  }
+  const repoTop = top.lines[0];
+  const igc = git(root, ['config', 'core.ignorecase']);
+  const caseInsensitive = igc.ok && igc.lines[0]?.trim() === 'true';
+  const key = (s) => (caseInsensitive ? s.toLowerCase() : s);
+  const setOf = (lines) => new Set(lines.map(key));
+
+  const tracked = setOf(git(root, ['ls-files', '--cached']).lines);
+  let head = null;
+  let staged = null;
+  let dirty = null;
+  if (mode === 'head') {
+    const lsTree = git(root, ['ls-tree', '-r', '--name-only', 'HEAD']);
+    head = setOf(lsTree.lines);
+    if (!lsTree.ok) notes.push('HEAD is unreadable (empty repository?) - every expected file will read as missing from HEAD');
+  } else {
+    staged = setOf(git(root, ['diff', '--cached', '--no-renames', '--name-only']).lines);
+    dirty = setOf(git(root, ['diff', '--name-only']).lines);
+  }
+
+  const expected = [];
+  const seen = new Set();
+  for (const raw of paths) {
+    if (!raw || raw.trim().length === 0) continue;
+    const rel = toRepoRelative(repoTop, raw);
+    if (rel === null) {
+      findings.push({ file: raw, state: 'ERROR', detail: 'path is outside the repository (or empty after normalization)' });
+      continue;
+    }
+    const onDisk = join(repoTop, rel.split('/').join(sep));
+    if (existsSync(onDisk) && statSync(onDisk).isDirectory()) {
+      const inDir = [];
+      for (const spec of [
+        ['ls-files', '--cached', '--', rel],
+        ['ls-files', '--others', '--exclude-standard', '--', rel],
+        ['ls-files', '--others', '--ignored', '--exclude-standard', '--', rel],
+      ]) {
+        inDir.push(...git(root, spec).lines);
+      }
+      if (inDir.length > DIR_EXPANSION_CAP) {
+        findings.push({ file: rel, state: 'TOO-BROAD', detail: `directory expands to ${inDir.length} files (cap ${DIR_EXPANSION_CAP}) - name explicit paths` });
+        continue;
+      }
+      if (inDir.length === 0) {
+        findings.push({ file: rel, state: 'MISSING-FROM-DISK', detail: 'directory exists but contains no files git can see - an empty filing is a citation to nothing' });
+        continue;
+      }
+      for (const f of inDir) if (!seen.has(key(f))) { seen.add(key(f)); expected.push(f); }
+    } else if (!seen.has(key(rel))) {
+      seen.add(key(rel));
+      expected.push(rel);
+    }
+  }
+
+  let green = 0;
+  for (const f of expected) {
+    const onDisk = join(repoTop, f.split('/').join(sep));
+    const exists = existsSync(onDisk) && statSync(onDisk).isFile();
+    const k = key(f);
+    if (mode === 'head') {
+      if (head.has(k)) { green++; continue; }
+    } else if (staged.has(k)) {
+      green++;
+      continue;
+    } else if (tracked.has(k) && !dirty.has(k)) {
+      notes.push(`already committed, clean: ${f}`);
+      green++;
+      continue;
+    }
+    if (mode !== 'head' && tracked.has(k)) {
+      findings.push({ file: f, state: 'NOT-STAGED', detail: 'tracked and MODIFIED (or deleted) but the change was never added' });
+    } else if (exists) {
+      const ci = git(root, ['check-ignore', '-v', '--', f]);
+      if (ci.exit === 0 && ci.lines.length > 0) {
+        const rule = ci.lines[0].split('\t')[0];
+        findings.push({ file: f, state: 'IGNORED', detail: `eaten by ${rule} - git add skipped it with exit 0 and NO output` });
+      } else {
+        findings.push({ file: f, state: 'NEVER-ADDED', detail: 'on disk, not ignored, and not staged - the add never named it (path typo, or the add ran from the wrong directory?)' });
+      }
+    } else {
+      findings.push({ file: f, state: 'MISSING-FROM-DISK', detail: 'named in the list but no such file exists - a committed citation to this path would point at nothing' });
+    }
+  }
+  return { ok: findings.length === 0, findings, notes, expected: expected.length, green };
+}
+
+function report(result, mode, pathCount) {
+  for (const n of result.notes) console.log(`  note: ${n}`);
+  if (result.ok) {
+    console.log(`STAGING VERIFIED: ${pathCount} path(s) -> ${result.expected} file(s), all accounted for (against ${mode}).`);
+    return;
+  }
+  console.log(`STAGING INCOMPLETE: ${result.findings.length} of ${result.expected} expected file(s) are NOT accounted for (against ${mode}).`);
+  for (const f of result.findings) {
+    console.log(`  MISSING (${f.state}): ${f.file}`);
+    console.log(`      ${f.detail}`);
+  }
+  console.log('  A silently-skipped add is INVISIBLE to git status. Do NOT commit.');
+  console.log('  Moves: rename the artifact off the ignored pattern, or raise the question for a ruling.');
+  console.log('  git add -f is a ruling, not a default, and .gitignore is never edited from a seat.');
+}
+
+function selfTest() {
+  const tmp = mkdtempSync(join(tmpdir(), 'verify-staged-selftest-'));
+  const cases = [];
+  try {
+    git(tmp, ['init', '-q']);
+    writeFileSync(join(tmp, '.gitignore'), 'bin/\n*.log\n');
+    mkdirSync(join(tmp, 'docs', 'session'), { recursive: true });
+    mkdirSync(join(tmp, 'src', 'bin'), { recursive: true });
+    writeFileSync(join(tmp, 'docs', 'session', 'a.md'), 'artifact\n');
+    writeFileSync(join(tmp, 'docs', 'session', 'receipt.log'), 'receipt\n');
+    writeFileSync(join(tmp, 'src', 'bin', 'tool.txt'), 'composition root\n');
+    writeFileSync(join(tmp, 'loose.txt'), 'never added\n');
+    git(tmp, ['add', 'docs/session', 'src']);
+
+    cases.push({ name: '*.log eats a receipt under an added dir', shouldFail: true, result: testStagedList(tmp, ['docs/session']), expect: 'IGNORED', detail: '.gitignore:2' });
+    cases.push({ name: 'unanchored bin/ eats src/bin at depth', shouldFail: true, result: testStagedList(tmp, ['src']), expect: 'IGNORED', detail: '.gitignore:1' });
+    cases.push({ name: 'a not-ignored miss reads NEVER-ADDED', shouldFail: true, result: testStagedList(tmp, ['loose.txt']), expect: 'NEVER-ADDED', detail: '' });
+    cases.push({ name: 'a citation to a path that does not exist', shouldFail: true, result: testStagedList(tmp, ['docs/session/scratch-notes.md']), expect: 'MISSING-FROM-DISK', detail: '' });
+    cases.push({ name: 'positive control: a staged file verifies green', shouldFail: false, result: testStagedList(tmp, ['docs/session/a.md']) });
+    git(tmp, ['-c', 'user.name=selftest', '-c', 'user.email=selftest@local', 'commit', '-q', '-m', 'selftest']);
+    cases.push({ name: 'positive control: committed-clean is a note, not a red', shouldFail: false, result: testStagedList(tmp, ['docs/session/a.md']) });
+    cases.push({ name: 'head mode: the eaten receipt is absent from the commit', shouldFail: true, result: testStagedList(tmp, ['docs/session'], 'head'), expect: 'IGNORED', detail: '' });
+
+    let failed = 0;
+    for (const c of cases) {
+      let verdict;
+      if (c.shouldFail) {
+        const hit = c.result.findings.filter((f) => f.state === c.expect);
+        if (c.result.ok) verdict = 'DID NOT FIRE - the detector is broken';
+        else if (hit.length === 0) verdict = `fired with the WRONG state (wanted ${c.expect})`;
+        else if (c.detail && !hit[0].detail.includes(c.detail)) verdict = `fired without naming the rule (wanted '${c.detail}' in: ${hit[0].detail})`;
+        else verdict = 'PASS - fired, named correctly';
+      } else {
+        verdict = c.result.ok ? 'PASS - stayed green on good input' : 'FIRED on good input - false positive';
+      }
+      if (!verdict.startsWith('PASS')) failed++;
+      console.log(`  [${verdict.startsWith('PASS') ? 'PASS' : 'FAIL'}] ${c.name}: ${verdict}`);
+    }
+    if (failed === 0) {
+      console.log('SELF-TEST PASSED: the detector fires on both ignore sightings, discriminates never-added from ignored, and stays silent on good input.');
+      return 0;
+    }
+    console.log(`SELF-TEST FAILED: ${failed} case(s) - do not trust this detector until it fires correctly.`);
+    return 1;
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function main(argv) {
+  const paths = [];
+  let fromFile = '';
+  let against = 'index';
+  let root = process.cwd();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--self-test') return selfTest();
+    if (a === '--from-file') { fromFile = argv[++i] ?? ''; continue; }
+    if (a === '--against') { against = (argv[++i] ?? 'index').toLowerCase(); continue; }
+    if (a === '--repo-root') { root = argv[++i] ?? root; continue; }
+    paths.push(a);
+  }
+  if (against !== 'index' && against !== 'head') {
+    console.log(`STAGING INCOMPLETE: --against must be index or head, not '${against}'.`);
+    return 1;
+  }
+  if (fromFile) {
+    if (!existsSync(fromFile)) {
+      console.log(`STAGING INCOMPLETE: --from-file '${fromFile}' does not exist - the staging list itself is missing.`);
+      return 1;
+    }
+    for (const line of readFileSync(fromFile, 'utf8').split(/\r?\n/)) {
+      const t = line.trim();
+      if (t.length > 0 && !t.startsWith('#')) paths.push(t);
+    }
+  }
+  if (paths.length === 0) {
+    console.log('STAGING INCOMPLETE: no paths were given - an empty staging list verifies nothing (pass the SAME list you gave to git add).');
+    return 1;
+  }
+  const result = testStagedList(root, paths, against);
+  report(result, against, paths.length);
+  return result.ok ? 0 : 1;
+}
+
+if (process.argv[1] && /verify-staged\.mjs$/.test(process.argv[1].replace(/\\/g, '/'))) {
+  process.exit(main(process.argv.slice(2)));
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@naswerks/engineering-loop",
+  "version": "0.1.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",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "verify-staged": "bin/verify-staged.mjs"
+  },
+  "files": [
+    ".claude-plugin/",
+    "skills/",
+    "references/",
+    "templates/",
+    "bin/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"pins/*.test.mjs\"",
+    "check:publish": "node pins/publish-gate.mjs",
+    "verify-staged": "node bin/verify-staged.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/naswerks/engineering-loop.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}