@sabaiway/agent-workflow-engine 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog — @sabaiway/agent-workflow-engine
+
+All notable changes to the methodology engine. Versions are this **package's** npm versions;
+they are distinct from the **deployment-lineage** stamp written into a project's `docs/ai/`
+(which tracks the shared `agent-workflow` lineage, head `1.3.0`).
+
+## 1.0.0
+
+First publish. The canonical home of the `agent-workflow` planning methodology is now an
+installable, `available:true` npm package — no longer a declared, content-only stub.
+
+### Added
+- Standalone npm package + `bin/install.mjs` installer targeting
+  `~/.claude/skills/agent-workflow-engine` (`AGENT_WORKFLOW_ENGINE_DIR`), with a
+  symlink-traversal guard — the installer never writes *through* a destination symlink
+  (root / intermediate / leaf), and never copies the npm wrapper into the skill dir.
+- `capability.json` flipped to `available:true` with `detect.installed` +
+  `install.npm` (`@sabaiway/agent-workflow-engine`). It still only `provides: ["plan"]`
+  (the methodology text) with no callable command — it mutates nothing.
+
+### Notes
+- The canon itself — `references/planning.md` (the full methodology) and
+  `references/methodology-slot.md` (the bounded slot fragment) — is unchanged; this release
+  packages it for npm.
+- The composition root (`agent-workflow-kit`) still consumes a **byte-identical,
+  drift-guarded mirror** of this canon bundled inside the kit. The live `kit → engine` read
+  and retiring that mirror land in the next slice.
+- The deployment-lineage head stays **`1.3.0`** — packaging the engine changes only the npm
+  axis, not any deployed project's `docs/ai` structure.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sabaiway
+
+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,55 @@
+# @sabaiway/agent-workflow-engine
+
+**The canonical home of the `agent-workflow` planning methodology.** It owns the
+methodology *text* — the Plan → Phase → Step vocabulary, the plan-file lifecycle
+(`docs/plans/*.md`, ephemeral, never committed), the `queue.md` series index, the mandatory
+final **Phase: Cleanup**, and the bounded methodology slot fragment the family kit injects
+into a deployed project's `AGENTS.md`.
+
+This is the **methodology engine** of the `agent-workflow` family — the canonical source the
+rest of the family builds on. It is **content**, not a runtime: it reads nothing, writes
+nothing, and mutates no project file. It deliberately **knows nobody else** in the family —
+it only *provides* the methodology; the family composition root (`agent-workflow-kit`) is the
+one that injects it. The kit currently consumes a **byte-identical, drift-guarded mirror** of
+this canon bundled inside the kit; the live `kit → engine` read (and retiring that mirror)
+lands in the next slice.
+
+## Install
+
+```bash
+npx @sabaiway/agent-workflow-engine@latest init
+```
+
+Installs/refreshes the canon at `~/.claude/skills/agent-workflow-engine` (override with
+`--dir <path>` or `AGENT_WORKFLOW_ENGINE_DIR`). `init` is additive — it never deletes your
+files and never writes through a symlink. Re-running with `@latest` is how you refresh the
+installed canon to the current version.
+
+This is a **content** skill (`disable-model-invocation`): it is not a project deploy and is
+not model-invoked. There is nothing to "run" inside an agent — installing it places the
+methodology canon on disk for the family to read.
+
+## Use
+
+The methodology is consumed by the family composition root, not invoked directly. Day to day
+you install and use the **kit** (`@sabaiway/agent-workflow-kit`), which injects the
+methodology slot into your project's `AGENTS.md`. Install the engine standalone when you want
+the canonical methodology reference on disk:
+
+- [`references/planning.md`](references/planning.md) — the **full methodology**: the
+  Plan → Phase → Step vocabulary, the plan-file lifecycle, the `queue.md` series index, the
+  mandatory final **Phase: Cleanup**, and the plan-then-execute split.
+- [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded**
+  fragment the composition root injects into a deployed `AGENTS.md` (a short summary +
+  pointer, kept under the entry point's line cap).
+
+## What this package ships
+
+`SKILL.md` (the canon overview + ownership rule), `references/` (the full methodology
+reference + the bounded slot fragment), `capability.json` (the family manifest), and this
+installer. It ships **no** family-wide tooling (the schema/validator/injection live in the
+composition root) and mutates nothing — preserving "knows nobody".
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: agent-workflow-engine
+description: Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step→Substep vocabulary, plan lifecycle, queue.md series index, mandatory Cleanup phase, and the bounded methodology slot fragment. A published, installable npm package (available:true) that *provides* the methodology text; it mutates nothing. The composition root (agent-workflow-kit) currently keeps byte-identical mirror copies of this text (drift-guarded) and injects the slot from its mirror; the live kit → engine read + mirror retirement land in the next slice.
+disable-model-invocation: true
+metadata:
+  version: '1.0.0'
+---
+
+# agent-workflow-engine
+
+The **canonical source of truth** for the `agent-workflow` planning methodology. It is a
+**published, installable npm package** (`capability.json` → `available:true`): it holds the
+methodology text and **provides** it, but it ships no runtime and mutates no files. The kit
+currently keeps **byte-identical mirror copies** of these files so the live injection + fallback
+keep working with no new dependency; a drift-guard test pins the mirrors to this canon. The live
+`kit → engine` read (and retiring the mirror) lands in the next slice.
+
+## What it provides (`provides: ["plan"]`)
+
+- [`references/planning.md`](references/planning.md) — the **full methodology**: the
+  Plan→Phase→Step→Substep vocabulary, plan-file lifecycle (`docs/plans/*.md`, gitignored, never
+  committed), the `queue.md` series index, the mandatory final **Phase: Cleanup**, the
+  plan-then-execute split, and the session-continuity heuristic.
+- [`references/methodology-slot.md`](references/methodology-slot.md) — the **bounded** fragment the
+  composition root injects into a deployed project's `AGENTS.md`, between the
+  `<!-- workflow:methodology:start -->` / `<!-- workflow:methodology:end -->` markers. A short
+  summary + pointer, not the full reference, so the entry point stays under its line cap.
+
+## Ownership rule (the engine knows nobody)
+
+The engine only **provides** text. It never reads, writes, or mutates any project file or any
+sibling skill — in particular it never touches a deployed `AGENTS.md`. **Only the composition root
+(`agent-workflow-kit`) injects the methodology slot.** This keeps the family a DAG: the engine has
+no outbound edges.
+
+## Status & roadmap
+
+The engine is **no longer a stub**: it is a published, `available:true`, installable npm package
+(`@sabaiway/agent-workflow-engine`). The kit currently keeps **byte-identical mirror copies** of
+this canon (drift-guarded), so the live injection + fallback keep working with no new dependency.
+The live `kit → engine` read (the kit reading this canon from the installed engine instead of its
+bundled mirror) and **retiring that mirror** land in the next slice. See the kit's
+`tools/inject-methodology.mjs` for the marker contract and the slot reconciliation the kit runs on
+bootstrap + upgrade.

package/bin/install.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// One-shot installer for @sabaiway/agent-workflow-engine.
+//
+//   npx @sabaiway/agent-workflow-engine init
+//
+// Copies the methodology canon into the canonical skill home
+// (~/.claude/skills/agent-workflow-engine, override with --dir or
+// AGENT_WORKFLOW_ENGINE_DIR). Re-running refreshes the canon to this package's
+// version — that is how you update the installed canon:
+//
+//   npx @sabaiway/agent-workflow-engine@latest init
+//
+// The engine is the methodology canon the family kit builds on; it is content,
+// not a project deploy and not a model-invoked skill — there is nothing to "run"
+// inside an agent.
+//
+// No telemetry, no phone-home. Dependency-free, Node >= 18.
+
+import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
+import { existsSync, lstatSync } from 'node:fs';
+import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+
+// The deployable skill = everything except the npm wrapper (package.json, bin/).
+// Enumerated explicitly (mirrors package.json "files") so a missing payload entry
+// is a loud failure, not a silent partial install.
+const PAYLOAD = [
+  'SKILL.md',
+  'README.md',
+  'CHANGELOG.md',
+  'LICENSE',
+  'capability.json',
+  'references',
+];
+
+const tildify = (path) => path.replace(homedir(), '~');
+
+const readVersion = async () => {
+  try {
+    const pkg = JSON.parse(await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8'));
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
+// lstat without following symlinks; null when the path does not exist. Using lstat (not
+// existsSync, which FOLLOWS symlinks and so reports a *dangling* symlink as absent) is what
+// makes the guard below catch a dangling destination symlink too.
+const lstatNoFollow = (path) => {
+  try {
+    return lstatSync(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err; // EACCES/EIO etc. must NOT fail open (be read as "not a symlink")
+  }
+};
+
+// Symlink-traversal guard: refuse to write *through* any symlink at or above `dest`
+// within `root`. Walks `root` plus each existing path component down to `dest`; if the
+// root, an intermediate dir, or the leaf is a symlink (including a dangling one), a copy
+// could escape the target — STOP rather than follow it. Also refuses a dest outside `root`.
+const assertContainedRealPath = (root, dest) => {
+  const rel = relative(root, dest);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`[agent-workflow-engine] refusing to write outside the target dir: ${dest}`);
+  }
+  if (lstatNoFollow(root)?.isSymbolicLink()) {
+    throw new Error(`[agent-workflow-engine] refusing to install into a symlinked target dir: ${root}`);
+  }
+  const walk = (acc, part) => {
+    const cur = join(acc, part);
+    if (lstatNoFollow(cur)?.isSymbolicLink()) {
+      throw new Error(
+        `[agent-workflow-engine] refusing to write through a symlink at ${cur} (would escape ${root}).`,
+      );
+    }
+    return cur;
+  };
+  rel.split(sep).filter(Boolean).reduce(walk, root);
+};
+
+const copyRecursive = async (src, dest, root) => {
+  assertContainedRealPath(root, dest); // never write through a dest symlink (root/intermediate/leaf)
+  const stat = await lstat(src);
+  if (stat.isSymbolicLink()) {
+    if (existsSync(dest)) return; // additive: never delete/replace an existing entry
+    const linkTarget = await readlink(src);
+    await symlink(linkTarget, dest);
+  } else if (stat.isDirectory()) {
+    await mkdir(dest, { recursive: true });
+    const entries = await readdir(src);
+    await Promise.all(entries.map((entry) => copyRecursive(join(src, entry), join(dest, entry), root)));
+  } else {
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(src, dest);
+  }
+};
+
+const parseArgs = (argv) => {
+  const dirFlag = argv.indexOf('--dir');
+  return {
+    help: argv.includes('--help') || argv.includes('-h'),
+    version: argv.includes('--version') || argv.includes('-v'),
+    dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
+  };
+};
+
+const resolveTarget = (dirArg) => {
+  if (dirArg) return resolve(dirArg);
+  if (process.env.AGENT_WORKFLOW_ENGINE_DIR) return resolve(process.env.AGENT_WORKFLOW_ENGINE_DIR);
+  return resolve(homedir(), '.claude/skills/agent-workflow-engine');
+};
+
+const printHelp = (version) => {
+  console.log(`agent-workflow-engine ${version}
+
+Usage:
+  npx @sabaiway/agent-workflow-engine init [--dir <path>]
+  npx @sabaiway/agent-workflow-engine --version
+  npx @sabaiway/agent-workflow-engine --help
+
+Installs/refreshes the methodology canon at ~/.claude/skills/agent-workflow-engine
+  (override with --dir <path> or AGENT_WORKFLOW_ENGINE_DIR). init is additive —
+  it never deletes your files and never writes through a symlink.
+
+The engine is the methodology canon the family kit builds on — it is content, not a
+project deploy and not a model-invoked skill, so there is nothing to run inside an agent.
+Re-run this command to update the installed canon:
+  npx @sabaiway/agent-workflow-engine@latest init`);
+};
+
+const main = async () => {
+  const version = await readVersion();
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) return printHelp(version);
+  if (args.version) return console.log(version);
+
+  const missing = PAYLOAD.filter((entry) => !existsSync(resolve(PKG_ROOT, entry)));
+  if (missing.includes('SKILL.md')) {
+    console.error('[agent-workflow-engine] package payload missing (no SKILL.md) — corrupt install?');
+    process.exit(1);
+  }
+  if (missing.length > 0) {
+    console.error(`[agent-workflow-engine] package payload incomplete — missing: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+
+  const target = resolveTarget(args.dir);
+  const wasPresent = existsSync(resolve(target, 'SKILL.md'));
+  // If the target dir itself is a symlink (incl. dangling), refuse before writing through it.
+  // (copyRecursive re-checks per entry; this fails fast with a clear message.)
+  if (lstatNoFollow(target)?.isSymbolicLink()) {
+    console.error(`[agent-workflow-engine] target dir is a symlink — refusing to write through it: ${tildify(target)}`);
+    process.exit(1);
+  }
+  await mkdir(target, { recursive: true });
+  await Promise.all(
+    PAYLOAD.map((entry) => copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target)),
+  );
+  console.log(
+    `[agent-workflow-engine] ${wasPresent ? 'updated the canon to' : 'installed'} v${version} -> ${tildify(target)}`,
+  );
+
+  console.log(`
+This installed the methodology canon at ${tildify(target)}. The engine is content the
+family kit builds on — there is nothing to run inside an agent.
+To update it later, re-run:  npx @sabaiway/agent-workflow-engine@latest init`);
+};
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/capability.json

@@ -0,0 +1,23 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "agent-workflow-engine",
+  "kind": "methodology-engine",
+  "version": "1.0.0",
+  "available": true,
+  "provides": ["plan"],
+  "roles": {},
+  "detect": {
+    "installed": {
+      "env": "AGENT_WORKFLOW_ENGINE_DIR",
+      "default": "~/.claude/skills/agent-workflow-engine",
+      "file": "SKILL.md"
+    }
+  },
+  "install": { "npm": "@sabaiway/agent-workflow-engine" },
+  "uninstall": {
+    "removeResolved": "detect.installed",
+    "note": "init copies into the skill dir; uninstall removes the resolved detect.installed dir — not an npm dependency"
+  },
+  "provenance": { "author": "sabaiway", "source": "github:sabaiway/agent-workflow" }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sabaiway/agent-workflow-engine",
+  "version": "1.0.0",
+  "description": "Canonical home of the agent-workflow planning methodology — the Plan→Phase→Step vocabulary, plan lifecycle, queue.md series index, and mandatory Cleanup phase, consumed by the kit (composition root). The methodology engine of the agent-workflow family.",
+  "keywords": [
+    "ai-agents",
+    "ai-coding",
+    "coding-agent",
+    "llm",
+    "ai-tools",
+    "claude-code",
+    "agents-md",
+    "workflow",
+    "planning",
+    "methodology",
+    "developer-tools"
+  ],
+  "homepage": "https://github.com/sabaiway/agent-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/sabaiway/agent-workflow/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sabaiway/agent-workflow.git",
+    "directory": "agent-workflow-engine"
+  },
+  "license": "MIT",
+  "author": "sabaiway",
+  "type": "module",
+  "bin": {
+    "agent-workflow-engine": "bin/install.mjs"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "capability.json",
+    "references/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/methodology-slot.md

@@ -0,0 +1 @@
+> **Workflow methodology** — plan → execute → review. Plans are ephemeral `docs/plans/*.md` (gitignored, **never committed**); every Plan ends with a mandatory **Phase: Cleanup**; series order lives in `docs/plans/queue.md`. Full vocabulary, lifecycle, and the plan-then-execute split live in the project's **planning skill** (it overrides the generic `writing-plans`); summary in `docs/ai/agent_rules.md` §5.

package/references/planning.md

@@ -0,0 +1,105 @@
+# Planning Workflow
+
+Source of truth for **how plans are written, stored, executed, and torn down**. Overrides the generic `writing-plans` skill — if both trigger, this one wins. Runtime series status (which plan is Current / Pending) lives in `docs/plans/queue.md`.
+
+---
+
+## 1. Plan vocabulary
+
+Strict four-level hierarchy, used in plan files (`docs/plans/*.md`) and in verbal summaries:
+
+- **Plan** — top-level container = the plan file itself. One file = one Plan. A series of related plans is not grouped under any wrapper noun; refer to them as "Plan 1 of N", "the next plan". Series order lives in `queue.md` (§3).
+- **Phase** — a large block inside the Plan. Exactly one execution session. Ends with its own verification block. `## Phase 1: …`, `## Phase 2: …`.
+- **Step** — an atomic change inside a Phase. Numbered `<phase>.<step>`: `### 1.1. …`. One Step → one logical commit.
+- **Substep** — optional split of a complex Step. Lettered: `**1.2.a**`, `**1.2.b**`. Use only when a Step cannot be one command.
+
+Reserve the word "task" for the todo list and `active_plan.md` — not for plan structure.
+
+## 2. Plan directory & lifecycle
+
+Plan files are **ephemeral, machine-local scratch space**, gitignored (`.gitignore` contains `docs/plans/`).
+
+**Lifecycle:** Creation (untracked file) → Execution (Phases 1..N-1) → mandatory **Phase N: Cleanup** (§4) → Post-deletion (only `changelog.md` + ADRs remain). Plans are **NEVER committed** — full stop. Even if a plan looks load-bearing (referenced by an ADR), inline the load-bearing content into a persistent doc and delete the plan file.
+
+**Forbidden:** `git add` of any plan file; plan-file paths in committed docs; leaving plan files on disk after Cleanup. If the user says "commit the plan" — ask back: "the plan is ephemeral — what exactly should I inline into `decisions.md` / `changelog.md`?".
+
+## 3. Series & queue.md
+
+A **series** = 2+ related plans that share a roadmap. The index lives at `docs/plans/queue.md` (gitignored, machine-local):
+
+```markdown
+## Series: <name>
+
+### Current
+- **Plan N / M** — <slug> — <one-line description>
+
+### Pending
+- **Plan N+1 / M** — <slug or TBD> — <description>
+
+### Done
+- **Plan K / M** — <slug> — done YYYY-MM-DD. Outputs: <pointers>.
+```
+
+`queue.md` is initialised when the **first** plan of a series is written, not during its Cleanup — without an upfront index the execution agent has no map of the series. Each plan's Cleanup then marks itself Done (with outputs) and promotes the next plan to Current. A single, unrelated plan does not need a series entry.
+
+## 4. Required Cleanup phase
+
+Every Plan MUST end with a final **Phase N: Cleanup** — the last numbered Phase. Without it the Plan is not done.
+
+Minimum content:
+
+- **Migrate outputs** → `docs/ai/decisions.md` (AD-XXX), `changelog.md`, `known_issues.md` (Issue-XXX), `current_state.md`, `pages/<page>.md`.
+- **Inline cross-references** — `grep -rn "<plan-slug>" docs/` must be empty. Every pointer is rewritten inline or removed.
+- **Update `queue.md`** — if part of a series, mark Done + promote next.
+- **Delete the plan file** — `rm docs/plans/<slug>.md`.
+- **Verification** — `grep -rn "<slug>" .` empty; `ls docs/plans/<slug>.md` → No such file; docs cap-validator green.
+
+If a Plan is aborted mid-flight, Cleanup still runs — partial outputs land in `known_issues.md`, then the file is deleted.
+
+## 5. All work in plans
+
+Anything required for the task is a **Step inside the Plan**. Nothing "before the plan", "between plans", or "don't forget" — those evaporate at execution time because the execution agent reads only the plan file, not chat scrollback. Every dependency, check, and install is its own Step or Substep. The final "Next steps" section contains **only user-actionable** items.
+
+## 6. Plan-then-execute split
+
+Default workflow for non-trivial features (multi-file change, new service + hook + UI, architectural choices): write a **self-contained Plan** and stop. Implementation runs in a fresh session via the `executing-plans` skill.
+
+- Triggers: any feature, refactor, or change touching more than ~1 file, or non-obvious architectural choices.
+- Does NOT apply to typos, one-line fixes, doc-only edits, or pure "where is X" research — those run inline.
+- The Plan must be readable cold by a fresh agent: file paths, contracts, execution order, verification, gotchas — all inside the file.
+
+This split is a token-efficiency strategy: exploration context stays out of the execution window.
+
+### Session-continuity heuristic (split vs continue)
+
+The volume trigger above (files / LoC / tokens) is necessary but not sufficient. The deeper question is whether the planning context is the execution **payload** or **noise**:
+
+- **Split** (fresh session) when planning exploration was *broad fan-out* — many files skimmed, sub-agent dumps, wide searches to *locate* things. That context is noise for execution; discard it.
+- **Continue** in the current session when ALL hold: (1) exploration was *targeted-deep* — you read the exact files to be created/modified/copied, so execution would just re-read them; (2) no new heavy exploration is needed to execute; (3) the context budget is healthy (far from the window limit / Lost-in-the-Middle).
+- When continuing, each Phase's Verification block is a natural checkpoint. If different Phases need different cold context, continue only through the warm Phases, then split.
+
+## 7. Plan-document structure
+
+```
+# Plan: <human-readable title>
+
+## Context              ← why this Plan exists, current state, why now (reads cold)
+## Approach             ← chosen design + an explicit "What we are NOT doing"
+## Phase 1: <name>
+   ### 1.1. <step>      ← exact paths + commands
+## Phase 2: <name>
+   ...
+## Phase N: Cleanup     ← mandatory (§4)
+## Critical files       ← table: file → change kind (new / modify / delete / move)
+## Reuse                ← pointers to existing patterns/snippets to copy, not re-derive
+## Verification         ← full check sequence (mechanical + behavioural)
+## Next steps           ← user-actionable only (§5)
+```
+
+## 8. Self-review checklist (before finalizing a Plan)
+
+- Every Step has exact file paths and exact commands.
+- Every recommendation that used to live outside the Plan is now a Step (§5).
+- Vocabulary is strict (§1); the Plan ends with **Phase N: Cleanup** (§4).
+- If part of a series: `queue.md` is initialised / updated (§3).
+- No `git add <plan>` and no "commit the plan" wording in the final report.