continuous-improvement 3.1.0 → 3.9.1

package/bin/check-docs-substrings.mjs

@@ -0,0 +1,333 @@
+#!/usr/bin/env node
+/**
+ * Docs Substring Check
+ *
+ * Verifies that every substring this repo's tests assert on inside a real
+ * `*.md` file is currently present in that file. Mechanical enforcement of
+ * the "Test/docs sync rule" in CONTRIBUTING.md: a wholesale docs rewrite
+ * (README.md, CHANGELOG.md, skill markdown) must preserve the substrings
+ * the test suite expects, or update the tests in the same PR.
+ *
+ * The full test suite (`npm test`) already runs each `assert.match` and
+ * fails on drift. This lint adds three things on top:
+ *   1. A focused, fast (<500ms) check that only verifies prose substrings.
+ *   2. A clean failure surface — it names (target file, expected substring,
+ *      originating test) instead of dumping the full doc content into stderr.
+ *   3. A standalone CI step that fails before the broader test job has a
+ *      chance to bury the drift in unrelated output.
+ *
+ * The manifest below is the spec. When you add or change a prose-substring
+ * assertion in `src/test/*.mts`, add or update the corresponding entry here
+ * in the same PR (per the Test/docs sync rule).
+ *
+ * Usage:
+ *   node bin/check-docs-substrings.mjs              # Check the current repo
+ *   node bin/check-docs-substrings.mjs <repo-root>  # Check a specific repo root
+ *   node bin/check-docs-substrings.mjs --list       # Print the inventory and exit
+ *
+ * Exit codes:
+ *   0 — every substring matches
+ *   1 — at least one assertion failed (target file is missing or doesn't
+ *       contain the expected substring)
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+export const DOCS_ASSERTIONS = [
+    // README.md (src/test/community.test.mts)
+    { file: "README.md", pattern: /planning-with-files/i, source: "community.test.mts:88" },
+    { file: "README.md", pattern: /task_plan\.md/, source: "community.test.mts:89" },
+    { file: "README.md", pattern: /ci_plan_init/, source: "community.test.mts:90" },
+    // README.md install hero — locked 2026-05-05 to prevent silent rewording of
+    // the install decision rule. The whole install section was restructured to
+    // lead with this one line because the previous "pick one path" framing left
+    // first-time installers comparison-shopping. Drop or rewrite this and
+    // beginner-vs-expert ambiguity returns immediately.
+    { file: "README.md", pattern: "If you don't know which to pick, use Beginner.", source: "docs-substrings-manifest:readme-install-decision-rule" },
+    // CONTRIBUTING.md (src/test/community.test.mts)
+    { file: "CONTRIBUTING.md", pattern: /Contributing/, source: "community.test.mts:16" },
+    { file: "CONTRIBUTING.md", pattern: /npm test/, source: "community.test.mts:17" },
+    // CONTRIBUTING.md Law Coverage Matrix anchor — locked 2026-05-05. The README
+    // points to this section via #law-coverage-matrix; renaming the heading
+    // creates a silent 404 in the README link. Lint catches it.
+    { file: "CONTRIBUTING.md", pattern: "## Law Coverage Matrix", source: "docs-substrings-manifest:contributing-law-coverage-anchor" },
+    // CODE_OF_CONDUCT.md (src/test/community.test.mts)
+    { file: "CODE_OF_CONDUCT.md", pattern: /Code of Conduct/, source: "community.test.mts:24" },
+    { file: "CODE_OF_CONDUCT.md", pattern: /Contributor Covenant/, source: "community.test.mts:25" },
+    // SECURITY.md (src/test/community.test.mts)
+    { file: "SECURITY.md", pattern: /Security/, source: "community.test.mts:32" },
+    { file: "SECURITY.md", pattern: /Reporting/i, source: "community.test.mts:33" },
+    { file: "SECURITY.md", pattern: /Vulnerabilit/i, source: "community.test.mts:34" },
+    // .github/ISSUE_TEMPLATE/bug_report.md (src/test/community.test.mts)
+    { file: ".github/ISSUE_TEMPLATE/bug_report.md", pattern: /Bug/, source: "community.test.mts:99" },
+    { file: ".github/ISSUE_TEMPLATE/bug_report.md", pattern: /Steps to reproduce/, source: "community.test.mts:100" },
+    // .github/ISSUE_TEMPLATE/feature_request.md (src/test/community.test.mts)
+    { file: ".github/ISSUE_TEMPLATE/feature_request.md", pattern: /Feature/, source: "community.test.mts:107" },
+    { file: ".github/ISSUE_TEMPLATE/feature_request.md", pattern: /law/i, source: "community.test.mts:108" },
+    // SKILL.md (src/test/skill.test.mts)
+    { file: "SKILL.md", pattern: /^---\r?\n/, source: "skill.test.mts:19" },
+    { file: "SKILL.md", pattern: /name: continuous-improvement/, source: "skill.test.mts:20" },
+    { file: "SKILL.md", pattern: /description:/, source: "skill.test.mts:21" },
+    { file: "SKILL.md", pattern: /Law 1.*Research Before Executing/s, source: "skill.test.mts:25" },
+    { file: "SKILL.md", pattern: /Law 2.*Plan Is Sacred/s, source: "skill.test.mts:26" },
+    { file: "SKILL.md", pattern: /Law 3.*One Thing at a Time/s, source: "skill.test.mts:27" },
+    { file: "SKILL.md", pattern: /Law 4.*Verify Before Reporting/s, source: "skill.test.mts:28" },
+    { file: "SKILL.md", pattern: /Law 5.*Reflect After/s, source: "skill.test.mts:29" },
+    { file: "SKILL.md", pattern: /Law 6.*Iterate/s, source: "skill.test.mts:30" },
+    { file: "SKILL.md", pattern: /Law 7.*Learn From Every Session/s, source: "skill.test.mts:31" },
+    { file: "SKILL.md", pattern: /Research.*Plan.*Execute.*Verify.*Reflect.*Learn.*Iterate/s, source: "skill.test.mts:36" },
+    { file: "SKILL.md", pattern: /Mulahazah/i, source: "skill.test.mts:42" },
+    { file: "SKILL.md", pattern: /confidence/i, source: "skill.test.mts:43" },
+    { file: "SKILL.md", pattern: /Auto-Level/i, source: "skill.test.mts:44" },
+    { file: "SKILL.md", pattern: /id:/, source: "skill.test.mts:48" },
+    { file: "SKILL.md", pattern: /trigger:/, source: "skill.test.mts:49" },
+    { file: "SKILL.md", pattern: /confidence:/, source: "skill.test.mts:50" },
+    { file: "SKILL.md", pattern: /Planning-With-Files/i, source: "skill.test.mts:54" },
+    { file: "SKILL.md", pattern: /opt-in/i, source: "skill.test.mts:55" },
+    { file: "SKILL.md", pattern: /task_plan\.md/, source: "skill.test.mts:56" },
+    // commands/discipline.md (src/test/commands.test.mts)
+    { file: "commands/discipline.md", pattern: /^---\r?\n/, source: "commands.test.mts:20" },
+    { file: "commands/discipline.md", pattern: /name: discipline/, source: "commands.test.mts:21" },
+    { file: "commands/discipline.md", pattern: /description:/, source: "commands.test.mts:22" },
+    { file: "commands/discipline.md", pattern: /Research Before Executing/, source: "commands.test.mts:26" },
+    { file: "commands/discipline.md", pattern: /Plan Is Sacred/, source: "commands.test.mts:27" },
+    { file: "commands/discipline.md", pattern: /One Thing at a Time/, source: "commands.test.mts:28" },
+    { file: "commands/discipline.md", pattern: /Verify Before Reporting/, source: "commands.test.mts:29" },
+    { file: "commands/discipline.md", pattern: /Reflect After Sessions/, source: "commands.test.mts:30" },
+    { file: "commands/discipline.md", pattern: /Iterate One Change/, source: "commands.test.mts:31" },
+    { file: "commands/discipline.md", pattern: /Learn From Every Session/, source: "commands.test.mts:32" },
+    { file: "commands/discipline.md", pattern: /I'll just quickly/, source: "commands.test.mts:36" },
+    { file: "commands/discipline.md", pattern: /This should work/, source: "commands.test.mts:37" },
+    { file: "commands/discipline.md", pattern: /Code runs without errors/, source: "commands.test.mts:41" },
+    { file: "commands/discipline.md", pattern: /Build passes/, source: "commands.test.mts:42" },
+    // commands/dashboard.md (src/test/commands.test.mts)
+    { file: "commands/dashboard.md", pattern: /^---\r?\n/, source: "commands.test.mts:56" },
+    { file: "commands/dashboard.md", pattern: /name: dashboard/, source: "commands.test.mts:57" },
+    { file: "commands/dashboard.md", pattern: /Dashboard/, source: "commands.test.mts:61" },
+    { file: "commands/dashboard.md", pattern: /Observations/, source: "commands.test.mts:62" },
+    { file: "commands/dashboard.md", pattern: /Instincts/, source: "commands.test.mts:63" },
+    { file: "commands/dashboard.md", pattern: /Health/, source: "commands.test.mts:64" },
+    { file: "commands/dashboard.md", pattern: /CAPTURE/, source: "commands.test.mts:68" },
+    { file: "commands/dashboard.md", pattern: /ANALYZE/, source: "commands.test.mts:69" },
+    { file: "commands/dashboard.md", pattern: /beginner|expert/, source: "commands.test.mts:70" },
+    // commands/planning-with-files.md (src/test/commands.test.mts)
+    { file: "commands/planning-with-files.md", pattern: /^---\r?\n/, source: "commands.test.mts:91" },
+    { file: "commands/planning-with-files.md", pattern: /name: planning-with-files/, source: "commands.test.mts:92" },
+    { file: "commands/planning-with-files.md", pattern: /description:/, source: "commands.test.mts:93" },
+    { file: "commands/planning-with-files.md", pattern: /task_plan\.md/, source: "commands.test.mts:97" },
+    { file: "commands/planning-with-files.md", pattern: /findings\.md/, source: "commands.test.mts:98" },
+    { file: "commands/planning-with-files.md", pattern: /progress\.md/, source: "commands.test.mts:99" },
+    { file: "commands/planning-with-files.md", pattern: /init/i, source: "commands.test.mts:100" },
+    { file: "commands/planning-with-files.md", pattern: /status/i, source: "commands.test.mts:101" },
+    { file: "commands/planning-with-files.md", pattern: /checkpoint/i, source: "commands.test.mts:102" },
+    { file: "commands/planning-with-files.md", pattern: /recover/i, source: "commands.test.mts:103" },
+    // Reflection-block mirror files (src/test/reflection-iteration-field.test.mts)
+    // Each must contain the literal "Iteration — Next best recommendations (ranked, top 3)" string.
+    { file: "SKILL.md", pattern: "Iteration — Next best recommendations (ranked, top 3)", source: "reflection-iteration-field.test.mts:43" },
+    { file: "commands/continuous-improvement.md", pattern: "Iteration — Next best recommendations (ranked, top 3)", source: "reflection-iteration-field.test.mts:43" },
+    { file: "plugins/continuous-improvement/skills/continuous-improvement/SKILL.md", pattern: "Iteration — Next best recommendations (ranked, top 3)", source: "reflection-iteration-field.test.mts:43" },
+    { file: "plugins/continuous-improvement/commands/continuous-improvement.md", pattern: "Iteration — Next best recommendations (ranked, top 3)", source: "reflection-iteration-field.test.mts:43" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "Iteration — Next best recommendations (ranked, top 3)", source: "reflection-iteration-field.test.mts:43" },
+    // Past Mistake Acknowledgment Gate / P-MAG (src/test/past-mistake-gate.test.mts)
+    // Source skill + plugin mirror must both contain the Phase 0 heading, the negative-prompt field marker,
+    // and the Stop Conditions clearance bullet. Dropping any of the three silently removes part of the gate.
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "Phase 0: Acknowledge (Past Mistake Acknowledgment Gate / P-MAG)", source: "past-mistake-gate.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "Phase 0: Acknowledge (Past Mistake Acknowledgment Gate / P-MAG)", source: "past-mistake-gate.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "Will NOT repeat:", source: "past-mistake-gate.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "Will NOT repeat:", source: "past-mistake-gate.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "Prior-mistake residue still present", source: "past-mistake-gate.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "Prior-mistake residue still present", source: "past-mistake-gate.test.mts" },
+    // P-MAG third surface (auto-memory feedback_*.md) — locked 2026-05-07 after PR #83.
+    // Rule 1 of Phase 0 was upgraded from scanning two surfaces to scanning three so
+    // the operator's named past-mistake corrections (which live in
+    // ~/.claude/projects/<hash>/memory/feedback_*.md) cannot be silently skipped.
+    // Each assertion below catches a specific class of regression:
+    //   - "Scan three surfaces"           → reverting the surface count back to two
+    //   - "memory/feedback_*.md"          → dropping the glob pattern entirely
+    //   - "feedback_past_mistake_gate.md" → generic rewording that loses the concrete anchor
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "Scan three surfaces", source: "past-mistake-gate.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "Scan three surfaces", source: "past-mistake-gate.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "memory/feedback_*.md", source: "past-mistake-gate.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "memory/feedback_*.md", source: "past-mistake-gate.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "feedback_past_mistake_gate.md", source: "past-mistake-gate.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "feedback_past_mistake_gate.md", source: "past-mistake-gate.test.mts" },
+    // workspace-surface-audit Environment Grain — locked 2026-05-07 (PR A of second-release train).
+    // Phase 1 of the audit gained an Environment Grain subsection that records shell flavor,
+    // autocrlf state, jq availability, case-sensitive filesystem flag, CWD baseline, and a
+    // parallel-actor expectation flag — the per-host facts that root the report's
+    // "command failed / wrong approach" friction class. Each assertion catches a specific
+    // class of regression:
+    //   - "#### Environment Grain"      → removing the whole subsection
+    //   - "core.autocrlf"               → dropping the Windows-line-endings probe
+    //   - "Parallel-actor expectation"  → losing the cross-skill integration with gateguard PR #83
+    { file: "skills/workspace-surface-audit.md", pattern: "#### Environment Grain", source: "docs-substrings-manifest:workspace-surface-audit-environment-grain" },
+    { file: "plugins/continuous-improvement/skills/workspace-surface-audit/SKILL.md", pattern: "#### Environment Grain", source: "docs-substrings-manifest:workspace-surface-audit-environment-grain" },
+    { file: "skills/workspace-surface-audit.md", pattern: "core.autocrlf", source: "docs-substrings-manifest:workspace-surface-audit-environment-grain" },
+    { file: "plugins/continuous-improvement/skills/workspace-surface-audit/SKILL.md", pattern: "core.autocrlf", source: "docs-substrings-manifest:workspace-surface-audit-environment-grain" },
+    { file: "skills/workspace-surface-audit.md", pattern: "Parallel-actor expectation", source: "docs-substrings-manifest:workspace-surface-audit-environment-grain" },
+    { file: "plugins/continuous-improvement/skills/workspace-surface-audit/SKILL.md", pattern: "Parallel-actor expectation", source: "docs-substrings-manifest:workspace-surface-audit-environment-grain" },
+    // superpowers Stacked-PR Plan Precondition — locked 2026-05-07 (PR B of second-release train).
+    // The dispatcher gained a non-negotiable rule for ≥3-file changes: produce a stacked-PR plan
+    // (per-PR table, dependency graph, worktree-per-PR, out-of-scope) before the first edit. The
+    // rule excludes markdown-only / lockfile-only / generated-only / vendor-refresh / skill-mirror
+    // changes. Each assertion below catches a specific class of regression:
+    //   - "## Stacked-PR Plan Precondition (≥3 files)" → removing the whole rule heading
+    //   - "Per-PR table"                                → losing the required-output enumeration
+    { file: "skills/superpowers.md", pattern: "## Stacked-PR Plan Precondition (≥3 files)", source: "docs-substrings-manifest:superpowers-stacked-pr-precondition" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "## Stacked-PR Plan Precondition (≥3 files)", source: "docs-substrings-manifest:superpowers-stacked-pr-precondition" },
+    { file: "skills/superpowers.md", pattern: "Per-PR table", source: "docs-substrings-manifest:superpowers-stacked-pr-precondition" },
+    { file: "plugins/continuous-improvement/skills/superpowers/SKILL.md", pattern: "Per-PR table", source: "docs-substrings-manifest:superpowers-stacked-pr-precondition" },
+    // verification-loop per-project ladder — locked 2026-05-07 (PR C of second-release train).
+    // Phase 0 (Ladder Resolution) was added so Phases 1–6 read the project's actual build/typecheck/
+    // lint/test/security/deploy_receipt invocations from .claude/verify-ladder.json (or sniff /
+    // ask fallback) instead of hardcoded npm run X. Phase 8 wires deploy-receipt (PR #83) for
+    // auto-deploy projects. Each assertion below catches a specific class of regression:
+    //   - "### Phase 0: Resolve the Ladder" → removing the whole resolution phase
+    //   - ".claude/verify-ladder.json"      → renaming or moving the manifest path
+    //   - "verify-ladder (resolved):"       → losing the resolved-ladder output contract
+    //   - "### Phase 8: Deploy Receipt"     → losing the cross-skill integration with PR #83
+    { file: "skills/verification-loop.md", pattern: "### Phase 0: Resolve the Ladder", source: "docs-substrings-manifest:verification-loop-per-project-ladder" },
+    { file: "plugins/continuous-improvement/skills/verification-loop/SKILL.md", pattern: "### Phase 0: Resolve the Ladder", source: "docs-substrings-manifest:verification-loop-per-project-ladder" },
+    { file: "skills/verification-loop.md", pattern: ".claude/verify-ladder.json", source: "docs-substrings-manifest:verification-loop-per-project-ladder" },
+    { file: "plugins/continuous-improvement/skills/verification-loop/SKILL.md", pattern: ".claude/verify-ladder.json", source: "docs-substrings-manifest:verification-loop-per-project-ladder" },
+    { file: "skills/verification-loop.md", pattern: "verify-ladder (resolved):", source: "docs-substrings-manifest:verification-loop-per-project-ladder" },
+    { file: "plugins/continuous-improvement/skills/verification-loop/SKILL.md", pattern: "verify-ladder (resolved):", source: "docs-substrings-manifest:verification-loop-per-project-ladder" },
+    { file: "skills/verification-loop.md", pattern: "### Phase 8: Deploy Receipt", source: "docs-substrings-manifest:verification-loop-per-project-ladder" },
+    { file: "plugins/continuous-improvement/skills/verification-loop/SKILL.md", pattern: "### Phase 8: Deploy Receipt", source: "docs-substrings-manifest:verification-loop-per-project-ladder" },
+    // /harvest slash command + Law-7 prose — locked 2026-05-07 (PR E, follow-up to PR D #88).
+    // The deferred follow-up landed: commands/harvest.md (+ plugin mirror) and a Friction Harvest
+    // Pipeline subsection inside SKILL.md Law 7 (+ plugin mirror). Each assertion below catches
+    // a specific class of regression:
+    //   - "name: harvest" frontmatter         → renaming the slash command
+    //   - "Friction Harvest Pipeline"         → losing the SKILL.md Law-7 subsection title
+    //   - "dedup_key = sha1(type + tool"      → losing the idempotency contract documentation
+    { file: "commands/harvest.md", pattern: "name: harvest", source: "docs-substrings-manifest:harvest-slash-command-and-law7-prose" },
+    { file: "plugins/continuous-improvement/commands/harvest.md", pattern: "name: harvest", source: "docs-substrings-manifest:harvest-slash-command-and-law7-prose" },
+    { file: "SKILL.md", pattern: "Friction Harvest Pipeline", source: "docs-substrings-manifest:harvest-slash-command-and-law7-prose" },
+    { file: "plugins/continuous-improvement/skills/continuous-improvement/SKILL.md", pattern: "Friction Harvest Pipeline", source: "docs-substrings-manifest:harvest-slash-command-and-law7-prose" },
+    { file: "SKILL.md", pattern: "dedup_key = sha1(type + tool", source: "docs-substrings-manifest:harvest-slash-command-and-law7-prose" },
+    { file: "plugins/continuous-improvement/skills/continuous-improvement/SKILL.md", pattern: "dedup_key = sha1(type + tool", source: "docs-substrings-manifest:harvest-slash-command-and-law7-prose" },
+    // wild-risa-balance recommendation floor (src/test/wild-risa-floor.test.mts)
+    // Source skill + plugin mirror must both contain the literal "2 WILD + 5 RISA = 7 items minimum".
+    { file: "skills/wild-risa-balance.md", pattern: "2 WILD + 5 RISA = 7 items minimum", source: "wild-risa-floor.test.mts:38" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "2 WILD + 5 RISA = 7 items minimum", source: "wild-risa-floor.test.mts:38" },
+    // wild-risa-balance audience tiers (src/test/wild-risa-tiers.test.mts)
+    // Source + plugin mirror must contain the tier headings, item-count rule, and model-version lock.
+    // Dropping any one downgrades the tier contract back to a flat expert-only block.
+    { file: "skills/wild-risa-balance.md", pattern: "## Audience Tiers (beginner vs expert)", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "## Audience Tiers (beginner vs expert)", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/wild-risa-balance.md", pattern: "### Beginner tier (lite shape)", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "### Beginner tier (lite shape)", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/wild-risa-balance.md", pattern: "### Expert tier", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "### Expert tier", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/wild-risa-balance.md", pattern: "### Tier signal in the 3-section close", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "### Tier signal in the 3-section close", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/wild-risa-balance.md", pattern: "3 minimum, 5 maximum", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "3 minimum, 5 maximum", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/wild-risa-balance.md", pattern: "Opus 4.7", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "Opus 4.7", source: "wild-risa-tiers.test.mts" },
+    // wild-risa-balance "no" escape valve (src/test/wild-risa-tiers.test.mts)
+    // Both tiers must allow `Recommendation: no` when no real recommendation exists; padding to hit
+    // the floor is the failure mode. Heading + literal phrase + handoff-action clause are locked.
+    { file: "skills/wild-risa-balance.md", pattern: `### The "no" escape valve (both tiers)`, source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: `### The "no" escape valve (both tiers)`, source: "wild-risa-tiers.test.mts" },
+    { file: "skills/wild-risa-balance.md", pattern: "Recommendation: no", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "Recommendation: no", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/wild-risa-balance.md", pattern: "switch context", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/wild-risa-balance/SKILL.md", pattern: "switch context", source: "wild-risa-tiers.test.mts" },
+    // proceed-with-the-recommendation tier-aware contract (src/test/wild-risa-tiers.test.mts)
+    // Phase 1 must accept beginner blocks (3..5 unlabeled); Phase 7 close must render the tier suffix.
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "Beginner tier:**", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "Beginner tier:**", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "3 ≤ n ≤ 5", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "3 ≤ n ≤ 5", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "Tier signal in the heading", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "Tier signal in the heading", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "## Recommendation (expert)", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "## Recommendation (expert)", source: "wild-risa-tiers.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "## Recommendation (beginner)", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "## Recommendation (beginner)", source: "wild-risa-tiers.test.mts" },
+    // proceed-with-the-recommendation "no" escape valve in Phase 7 close (src/test/wild-risa-tiers.test.mts)
+    // Phase 7 must instruct renderer to ship `no` + the tier-suffixed heading when the surface is exhausted.
+    { file: "skills/proceed-with-the-recommendation.md", pattern: `The "no" escape valve (both tiers)`, source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: `The "no" escape valve (both tiers)`, source: "wild-risa-tiers.test.mts" },
+    { file: "skills/proceed-with-the-recommendation.md", pattern: "explicit handoff signal", source: "wild-risa-tiers.test.mts" },
+    { file: "plugins/continuous-improvement/skills/proceed-with-the-recommendation/SKILL.md", pattern: "explicit handoff signal", source: "wild-risa-tiers.test.mts" },
+];
+export function checkAssertions(repoRoot, assertions = DOCS_ASSERTIONS) {
+    const fileCache = new Map();
+    const failures = [];
+    for (const a of assertions) {
+        const fullPath = join(repoRoot, a.file);
+        let content = fileCache.get(fullPath);
+        if (content === undefined) {
+            try {
+                content = readFileSync(fullPath, "utf8");
+            }
+            catch {
+                content = null;
+            }
+            fileCache.set(fullPath, content);
+        }
+        if (content === null) {
+            failures.push({ assertion: a, reason: "target-missing" });
+            continue;
+        }
+        const matched = typeof a.pattern === "string"
+            ? content.includes(a.pattern)
+            : a.pattern.test(content);
+        if (!matched) {
+            failures.push({ assertion: a, reason: "pattern-not-found" });
+        }
+    }
+    return failures;
+}
+function describePattern(p) {
+    return typeof p === "string" ? `"${p}"` : p.toString();
+}
+function printList() {
+    const grouped = new Map();
+    for (const a of DOCS_ASSERTIONS) {
+        const list = grouped.get(a.file) ?? [];
+        list.push(a);
+        grouped.set(a.file, list);
+    }
+    console.log(`docs-substrings inventory (${DOCS_ASSERTIONS.length} assertions across ${grouped.size} files):\n`);
+    const files = [...grouped.keys()].sort();
+    for (const f of files) {
+        const items = grouped.get(f);
+        console.log(`  ${f}  (${items.length})`);
+        for (const a of items) {
+            console.log(`    - ${describePattern(a.pattern)}  [${a.source}]`);
+        }
+    }
+}
+function main() {
+    const args = argv.slice(2);
+    if (args.includes("--list")) {
+        printList();
+        exit(0);
+    }
+    const repoRoot = args[0] ?? cwd();
+    const failures = checkAssertions(repoRoot);
+    if (failures.length === 0) {
+        console.log(`OK docs-substrings: all ${DOCS_ASSERTIONS.length} substring assertion(s) match their target files.`);
+        exit(0);
+    }
+    console.error(`FAIL docs-substrings: ${failures.length} of ${DOCS_ASSERTIONS.length} assertion(s) failed.\n`);
+    for (const f of failures) {
+        const a = f.assertion;
+        if (f.reason === "target-missing") {
+            console.error(`  - ${a.file}: target file not found (asserted by ${a.source}).`);
+        }
+        else {
+            console.error(`  - ${a.file}: missing expected substring ${describePattern(a.pattern)} (asserted by ${a.source}).`);
+        }
+    }
+    console.error("\nFix per CONTRIBUTING.md \"Test/docs sync rule\": tests asserting on prose content must ship in the same PR as the docs change adding the asserted substring. A wholesale docs rewrite must preserve every existing substring — or update the test in the same PR.");
+    exit(1);
+}
+const invokedDirectly = argv[1]?.endsWith("check-docs-substrings.mjs");
+if (invokedDirectly) {
+    main();
+}

package/bin/check-everything-mirror.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * Everything Mirror Check
+ *
+ * Verifies that every non-skill, non-manifest file under
+ * plugins/continuous-improvement/ has a byte-identical sibling at the same
+ * relative path under the repo root. Catches drift across commands/, hooks/
+ * (excluding the plugin-only hooks.json), instinct-packs/, templates/, lib/,
+ * bin/, and the LICENSE file — surfaces that check-skill-mirror.mjs does not
+ * cover.
+ *
+ * Skills are intentionally excluded because their flat-vs-plugin layout is
+ * structurally different (skills/<name>.md vs plugins/.../skills/<name>/SKILL.md)
+ * and check-skill-mirror.mjs already enforces that pair. A few plugin-only
+ * surfaces are explicitly allowlisted: the .claude-plugin/ manifests, the
+ * generated bundle README.md and skills/README.md, and hooks/hooks.json.
+ *
+ * Usage:
+ *   node bin/check-everything-mirror.mjs              # Check the current repo
+ *   node bin/check-everything-mirror.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every mirrored file matches its flat-tree sibling
+ *   1 — at least one drift detected (missing flat sibling or content mismatch)
+ */
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const PLUGIN_ROOT_REL = "plugins/continuous-improvement";
+// Paths under PLUGIN_ROOT_REL that are intentionally plugin-only (no flat
+// sibling expected) or are covered by another lint. Stored with forward
+// slashes; matched against the file's relative-to-plugin-root path normalized
+// the same way.
+const EXCLUDE_FILES = new Set([
+    ".claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
+    "README.md",
+    "hooks/hooks.json",
+    "skills/README.md",
+]);
+// Whole directories under PLUGIN_ROOT_REL that this lint never walks into.
+const EXCLUDE_DIRS = new Set(["skills", ".claude-plugin"]);
+function toForward(p) {
+    return p.split(sep).join("/");
+}
+export function discoverMirrorPairs(repoRoot) {
+    const pluginRoot = join(repoRoot, PLUGIN_ROOT_REL);
+    const out = [];
+    function walk(dir) {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            const full = join(dir, name);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            const relFromPlugin = toForward(relative(pluginRoot, full));
+            if (stat.isDirectory()) {
+                if (EXCLUDE_DIRS.has(relFromPlugin))
+                    continue;
+                walk(full);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            if (EXCLUDE_FILES.has(relFromPlugin))
+                continue;
+            out.push({
+                relPath: relFromPlugin,
+                pluginPath: full,
+                flatPath: join(repoRoot, relFromPlugin),
+            });
+        }
+    }
+    walk(pluginRoot);
+    return out.sort((a, b) => a.relPath.localeCompare(b.relPath));
+}
+export function checkMirrorPairs(repoRoot) {
+    const pairs = discoverMirrorPairs(repoRoot);
+    const drifts = [];
+    for (const pair of pairs) {
+        let flatContent;
+        try {
+            flatContent = readFileSync(pair.flatPath);
+        }
+        catch {
+            drifts.push({
+                relPath: pair.relPath,
+                reason: "missing-flat",
+                pluginPath: pair.pluginPath,
+                flatPath: pair.flatPath,
+            });
+            continue;
+        }
+        const pluginContent = readFileSync(pair.pluginPath);
+        if (!pluginContent.equals(flatContent)) {
+            drifts.push({
+                relPath: pair.relPath,
+                reason: "content-drift",
+                pluginPath: pair.pluginPath,
+                flatPath: pair.flatPath,
+                pluginBytes: pluginContent.length,
+                flatBytes: flatContent.length,
+            });
+        }
+    }
+    return drifts;
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const pairs = discoverMirrorPairs(repoRoot);
+    const drifts = checkMirrorPairs(repoRoot);
+    if (drifts.length === 0) {
+        console.log(`OK everything-mirror: all ${pairs.length} mirrored file(s) match their flat-tree sibling.`);
+        exit(0);
+    }
+    console.error(`FAIL everything-mirror: ${drifts.length} drift(s) detected across ${pairs.length} mirrored file(s).\n`);
+    for (const d of drifts) {
+        if (d.reason === "missing-flat") {
+            console.error(`  - ${d.relPath}: plugin copy exists but flat sibling is missing.`);
+            console.error(`      plugin: ${d.pluginPath}`);
+            console.error(`      flat:   ${d.flatPath} (NOT FOUND)`);
+        }
+        else {
+            console.error(`  - ${d.relPath}: byte drift between plugin and flat copy (${d.pluginBytes} vs ${d.flatBytes} bytes).`);
+            console.error(`      plugin: ${d.pluginPath}`);
+            console.error(`      flat:   ${d.flatPath}`);
+        }
+    }
+    console.error("\nFix: every change to a mirrored file under plugins/continuous-improvement/ must be applied to its flat-tree sibling at the same relative path in the same PR. Plugin-only files (.claude-plugin/manifests, hooks/hooks.json, the bundle README.md, skills/README.md) are allowlisted; skills are covered by check-skill-mirror.mjs.");
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-everything-mirror.mjs")) {
+    main();
+}

package/bin/check-routing-targets.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Routing-Target Invariant Check
+ *
+ * Verifies that every routing target named in the orchestrator skill at
+ * skills/proceed-with-the-recommendation.md § "Routing Table (with Inline
+ * Fallbacks)" either:
+ *   (a) ships bundled at plugins/continuous-improvement/skills/<name>/SKILL.md, or
+ *   (b) is declared in the root-level optional-companions.json file.
+ *
+ * Catches: a routing-table row that names a skill the bundle does not ship and
+ * the maintainer has not declared as an optional companion. Without this gate,
+ * such drift only surfaces at runtime when the orchestrator routes to a target
+ * that resolves to neither a bundled skill nor an inline fallback the
+ * maintainer was tracking.
+ *
+ * Usage:
+ *   node bin/check-routing-targets.mjs              # Check the current repo
+ *   node bin/check-routing-targets.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — every routing target is accounted for (bundled or optional-declared)
+ *   1 — at least one routing target is unaccounted for
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+const ORCHESTRATOR_SKILL_PATH = "skills/proceed-with-the-recommendation.md";
+const OPTIONAL_COMPANIONS_PATH = "optional-companions.json";
+const PLUGIN_SKILLS_DIR = "plugins/continuous-improvement/skills";
+const SECTION_HEADER = "### Routing Table (with Inline Fallbacks)";
+export function discoverBundledSkills(repoRoot) {
+    const dir = join(repoRoot, PLUGIN_SKILLS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return new Set();
+    }
+    const names = new Set();
+    for (const name of entries) {
+        const skillFile = join(dir, name, "SKILL.md");
+        try {
+            const stat = statSync(skillFile);
+            if (stat.isFile())
+                names.add(name);
+        }
+        catch {
+            /* not a skill dir */
+        }
+    }
+    return names;
+}
+export function loadOptionalCompanions(repoRoot) {
+    const path = join(repoRoot, OPTIONAL_COMPANIONS_PATH);
+    const raw = readFileSync(path, "utf8");
+    const data = JSON.parse(raw);
+    if (!Array.isArray(data.optional_companions)) {
+        throw new Error(`${OPTIONAL_COMPANIONS_PATH}: missing or non-array "optional_companions" field`);
+    }
+    return new Set(data.optional_companions);
+}
+export function extractRoutingTargets(orchestratorMarkdown) {
+    const lines = orchestratorMarkdown.split(/\r?\n/);
+    const headerIdx = lines.findIndex((line) => line.trim() === SECTION_HEADER);
+    if (headerIdx === -1) {
+        throw new Error(`Routing-table section header not found: "${SECTION_HEADER}"`);
+    }
+    const targets = [];
+    let inTable = false;
+    let sawHeaderRow = false;
+    let sawDividerRow = false;
+    for (let i = headerIdx + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (trimmed.startsWith("## ") || trimmed.startsWith("### "))
+            break;
+        if (!trimmed.startsWith("|")) {
+            if (inTable)
+                break;
+            continue;
+        }
+        if (!sawHeaderRow) {
+            sawHeaderRow = true;
+            inTable = true;
+            continue;
+        }
+        if (!sawDividerRow) {
+            sawDividerRow = true;
+            continue;
+        }
+        const cells = trimmed.split("|").map((c) => c.trim());
+        // cells[0] and cells[last] are empty strings from leading/trailing pipes.
+        // cells[1] = "Recommendation type", cells[2] = "Preferred skill", cells[3] = "Inline fallback".
+        const preferredCell = cells[2] ?? "";
+        const tokens = [...preferredCell.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
+        for (const token of tokens) {
+            targets.push({
+                rowIndex: targets.length,
+                recommendationType: cells[1] ?? "",
+                target: token,
+            });
+        }
+    }
+    return targets;
+}
+export function checkRoutingTargets(repoRoot) {
+    const orchestratorPath = join(repoRoot, ORCHESTRATOR_SKILL_PATH);
+    const orchestratorContent = readFileSync(orchestratorPath, "utf8");
+    const targets = extractRoutingTargets(orchestratorContent);
+    const bundled = discoverBundledSkills(repoRoot);
+    const optional = loadOptionalCompanions(repoRoot);
+    const drifts = [];
+    for (const t of targets) {
+        if (bundled.has(t.target))
+            continue;
+        if (optional.has(t.target))
+            continue;
+        drifts.push(t);
+    }
+    return {
+        targets,
+        drifts,
+        bundledCount: bundled.size,
+        optionalCount: optional.size,
+    };
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const { targets, drifts, bundledCount, optionalCount } = checkRoutingTargets(repoRoot);
+    if (drifts.length === 0) {
+        console.log(`OK routing-targets: all ${targets.length} routing target(s) accounted for ` +
+            `(${bundledCount} bundled skill(s), ${optionalCount} optional companion(s) declared).`);
+        exit(0);
+    }
+    console.error(`FAIL routing-targets: ${drifts.length} unaccounted target(s) in ${ORCHESTRATOR_SKILL_PATH}.\n`);
+    for (const d of drifts) {
+        console.error(`  - "${d.target}" — referenced by row "${d.recommendationType}"`);
+        console.error(`      Not bundled at ${PLUGIN_SKILLS_DIR}/${d.target}/SKILL.md`);
+        console.error(`      Not declared in ${OPTIONAL_COMPANIONS_PATH}`);
+    }
+    console.error(`\nFix: either bundle the skill (add plugins/continuous-improvement/skills/<name>/SKILL.md ` +
+        `via the source skill + 'npm run build'), OR declare it in ${OPTIONAL_COMPANIONS_PATH} ` +
+        `with a pointer note in docs/audits/.`);
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-routing-targets.mjs")) {
+    main();
+}