continuous-improvement 3.20.0 → 3.21.0

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
   "plugins": [
     {
       "name": "continuous-improvement",
-      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 27 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.20.0",
+      "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
+      "version": "3.21.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this skill are documented here.
 
 ---
 
+## [3.21.0] — 2026-07-11
+
+### Added
+
+- **`/simplicity-review`**: a diff-scoped over-engineering reviewer. It reads the current diff and walks a reuse ladder (does it need to exist? already in the codebase? stdlib? native feature? one line?), reporting `GO` or `TRIM` trim findings without editing, with a safety carve-out that never flags input validation, data-loss handling, security, or accessibility. Review-only (Law 4), tier 2, routed into `proceed-with-the-recommendation`. Brings the bundle to 28 skills. (#285)
+
+### Changed
+
+- **`/production-readiness-review` gains a fifth blind reviewer**: a simplicity and over-engineering dimension that delegates to the `simplicity-review` skill, so the readiness gate now spans performance, security, UI/UX, test coverage, and simplicity. (#286)
+
 ## [3.17.0] — 2026-06-28
 
 ### Added

package/QUICKSTART.md

@@ -139,7 +139,7 @@ npx continuous-improvement install --mode expert
 npx continuous-improvement install --pack react   # optional: react | python | go | meta
 ```
 
-Preconditions: Node 18 / 20 / 22, plus bash on Windows (Git Bash or WSL — `hooks/observe.sh` is a bash script). See [README.md § Expert](README.md#expert--adds-mcp-server-observation-hooks-and-instinct-packs) for the full preconditions and troubleshooting matrix.
+Precondition: Node 18 / 20 / 22. Runtime hooks execute Node directly, so Git Bash and `jq` are not required. Re-run the installer once after upgrading to migrate legacy Bash hook rows. See [README.md § Expert](README.md#expert--adds-mcp-server-observation-hooks-and-instinct-packs) for the troubleshooting matrix.
 
 Verify with `/dashboard` — you should see instinct health and observation count.
 

package/README.md

@@ -137,7 +137,7 @@ V1 honest limitations: the runtime gate is honor-system once the agent flips `_g
 
 Pick this if you want the MCP tools (19 of them, including `ci_plan_init` / `ci_plan_status` for `task_plan.md`-style planning), the session hooks that feed Mulahazah, and starter packs.
 
-Preconditions: Node 18 / 20 / 22, plus bash on Windows (Git Bash or WSL — `hooks/observe.sh` is a bash script and silently no-ops without it). **`jq` is no longer required**: as of v3.6.0, `observe.sh` prefers the Node observer (`bin/observe.mjs`) which writes the rich event schema natively without external dependencies. The bash thin-schema path is kept as a two-phase shim, so legacy installs that have not re-run `npx continuous-improvement install` since v3.5.x will still degrade silently without `jq` (`winget install jqlang.jq` on Windows, `brew install jq` on macOS, `apt install jq` on Debian/Ubuntu) — re-running the installer is the cleaner fix and removes the dependency entirely. See [CHANGELOG.md](CHANGELOG.md) `[3.6.0]` for the migration details.
+Precondition: Node 18 / 20 / 22. Observation and session hooks execute Node directly, so Git Bash and `jq` are not required. Re-run the installer once after upgrading to migrate installer-owned `observe.sh` and `session.sh` rows to the Node entrypoints.
 
 ```bash
 npx continuous-improvement install --mode expert
@@ -158,7 +158,7 @@ Three failures account for nearly every install support thread. Try them in orde
 | Symptom | Real cause | Fix |
 |---|---|---|
 | `/discipline` says "command not recognized" right after `/plugin install` | Slash commands load on session start; the marketplace did pick the plugin up | Quit and reopen Claude Code, then run `/discipline` again |
-| Expert mode hooks never fire on Windows | `observe.sh` is bash; PowerShell silently no-ops on it | Install Git Bash (or WSL) and re-run `npx continuous-improvement install --mode expert` |
+| Hooks report Bash path errors after upgrading | Stale installer-owned `observe.sh` or `session.sh` rows remain in `settings.json` | Re-run `npx continuous-improvement install --mode expert`; the installer migrates those rows to Node and preserves foreign hooks |
 | `/plugin marketplace add ...` returned nothing visible | Marketplace add was silent; the plugin is not yet selected | Run `/plugin install continuous-improvement@continuous-improvement` to select and activate it |
 
 If none of those apply, paste the output of `npx continuous-improvement install` into a GitHub issue — that surface logs every step.
@@ -270,7 +270,7 @@ Hooks capture every tool call. After ~20 observations Claude analyzes patterns a
 ## Slash commands
 
 <details>
-<summary><b>All 28 commands (Beginner gets every one)</b></summary>
+<summary><b>All 29 commands (Beginner gets every one)</b></summary>
 
 `/seven-laws` is the canonical reflect-and-learn command. `/continuous-improvement` is kept as an alias for backward compatibility — both run the same workflow.
 
@@ -290,6 +290,7 @@ Hooks capture every tool call. After ~20 observations Claude analyzes patterns a
 /audit                            Audit recent commits for real defects, confirm each before fixing
 /ship                             Single-defect fast path — reconcile, TDD fix, verify, one PR
 /production-readiness-review      Parallel readiness gate — severity-ranked punch-list (reports only)
+/simplicity-review                Judge the current diff for over-engineering (GO / TRIM, reports only)
 /handoff                          End-of-session compaction into mktemp brief for the next agent
 /recall                           BM25 search over past observations — "have I hit this before?"
 /discipline                       Quick reference card of the 7 Laws
@@ -305,7 +306,7 @@ Hooks capture every tool call. After ~20 observations Claude analyzes patterns a
 /swarm                            Fan-out coordination across parallel sub-agents
 ```
 
-All 28 ship in the marketplace bundle. The Beginner install gets all of them — with one caveat: `/learn-eval`, `/harvest`, and `/distill` only produce useful output once Mulahazah has accumulated observation history (~20 observations), so running them on day 1 returns an empty result, not a broken command. `/swarm` and `/release-train` are orchestration commands aimed at larger multi-agent or multi-PR work. In Expert (`npx`) mode, the installer mirrors the full set into `~/.claude/commands/` and additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
+All 29 ship in the marketplace bundle. The Beginner install gets all of them — with one caveat: `/learn-eval`, `/harvest`, and `/distill` only produce useful output once Mulahazah has accumulated observation history (~20 observations), so running them on day 1 returns an empty result, not a broken command. `/swarm` and `/release-train` are orchestration commands aimed at larger multi-agent or multi-PR work. In Expert (`npx`) mode, the installer mirrors the full set into `~/.claude/commands/` and additionally exposes the planning workflow through the MCP tools `ci_plan_init` (initialize `task_plan.md`, `findings.md`, `progress.md` in the project root) and `ci_plan_status` (summarize their current contents).
 
 </details>
 
@@ -313,7 +314,7 @@ All 28 ship in the marketplace bundle. The Beginner install gets all of them —
 
 ## Skills
 
-The plugin ships **27 skills** — 1 core + 1 featured + 6 tier-1 + 16 tier-2 + 3 always-bundled. Beginner install gets tier-1, featured, and the always-bundled companion; Expert adds tier-2, the MCP server, and observation hooks. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 28th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
+The plugin ships **28 skills** — 1 core + 1 featured + 6 tier-1 + 17 tier-2 + 3 always-bundled. Beginner install gets tier-1, featured, and the always-bundled companion; Expert adds tier-2, the MCP server, and observation hooks. Full catalog with per-skill descriptions, Law tagging, and drop-in single-file install: [docs/skills.md](docs/skills.md). Adding a 29th skill: [CONTRIBUTING.md § Evolution — adding a new skill](CONTRIBUTING.md#evolution--adding-a-new-skill).
 
 ---
 
@@ -356,7 +357,7 @@ Proof-format templates ship in [templates/](templates/): `release_receipt_templa
 
 - [QUICKSTART.md](QUICKSTART.md) — 2-minute setup
 - [SKILL.md](SKILL.md) — full 7 Laws spec
-- [docs/skills.md](docs/skills.md) — full 27-skill catalog
+- [docs/skills.md](docs/skills.md) — full 28-skill catalog
 - [examples/](examples/) — bug fix, feature build, refactor walkthroughs
 - [templates/insights-claude-md.md](templates/insights-claude-md.md) — paste-in CLAUDE.md blocks for verification discipline, environment notes, think-before-acting, and git/deploy workflow (sourced from the 28-day usage report)
 - [CONTRIBUTING.md](CONTRIBUTING.md) — architecture, repo internals, adding a new skill

package/bin/check-landing-version.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { argv, cwd } from "node:process";
+import { fileURLToPath } from "node:url";
+const VERSION_RE = "([0-9]+\\.[0-9]+\\.[0-9]+)";
+function firstMatch(content, pattern) {
+    return pattern.exec(content)?.[1] ?? null;
+}
+export function checkLandingVersion(repoRoot) {
+    const packagePath = resolve(repoRoot, "package.json");
+    const landingPath = resolve(repoRoot, "docs", "landing", "index.html");
+    const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+    const packageVersion = typeof packageJson.version === "string" ? packageJson.version : "";
+    const landing = readFileSync(landingPath, "utf8");
+    const markers = {
+        badge: firstMatch(landing, new RegExp(`<span\\b[^>]*class=["'][^"']*\\bver\\b[^"']*["'][^>]*>\\s*v${VERSION_RE}\\s*</span>`, "i")),
+        hero: firstMatch(landing, new RegExp(`<span\\b[^>]*class=["'][^"']*\\bkicker\\b[^"']*["'][^>]*>[\\s\\S]*?\\bREV\\s+${VERSION_RE}[\\s\\S]*?</span>`, "i")),
+        current: firstMatch(landing, new RegExp(`<span\\b[^>]*class=["'][^"']*\\bv\\b[^"']*["'][^>]*>\\s*v${VERSION_RE}\\s*</span>\\s*<span\\b[^>]*class=["'][^"']*\\bk\\b[^"']*["'][^>]*>\\s*Current rev\\s*</span>`, "i")),
+        footer: firstMatch(landing, new RegExp(`<span\\b[^>]*class=["'][^"']*\\bfoot-doc\\b[^"']*["'][^>]*>[\\s\\S]*?\\bREV\\s+${VERSION_RE}[\\s\\S]*?</span>`, "i")),
+    };
+    const errors = [];
+    if (!/^[0-9]+\.[0-9]+\.[0-9]+$/.test(packageVersion)) {
+        errors.push(`package.json has an invalid version: ${packageVersion || "<missing>"}`);
+    }
+    const missing = Object.entries(markers)
+        .filter(([, version]) => version === null)
+        .map(([name]) => name);
+    if (missing.length > 0) {
+        errors.push(`landing release marker(s) missing: ${missing.join(", ")}`);
+    }
+    const landingVersions = [...new Set(Object.values(markers).filter((value) => value !== null))];
+    if (landingVersions.length > 1) {
+        errors.push(`landing release markers are mixed: ${landingVersions.join(", ")}`);
+    }
+    for (const [name, version] of Object.entries(markers)) {
+        if (version !== null && version !== packageVersion) {
+            errors.push(`${name} marker is ${version}; package.json is ${packageVersion}`);
+        }
+    }
+    return { ok: errors.length === 0, packageVersion, markers, errors };
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    try {
+        const result = checkLandingVersion(repoRoot);
+        if (result.ok) {
+            console.log(`OK landing-version: all 4 markers match package.json ${result.packageVersion}.`);
+            return;
+        }
+        console.error(`FAIL landing-version: ${result.errors.join("; ")}`);
+        process.exitCode = 1;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`FAIL landing-version: ${message}`);
+        process.exitCode = 1;
+    }
+}
+const entryPath = argv[1] ? resolve(argv[1]) : "";
+if (entryPath === fileURLToPath(import.meta.url)) {
+    main();
+}

package/bin/check-scripts-citation-drift.mjs

@@ -11,7 +11,7 @@
  * Three sides of the contract are enforced as one invariant:
  *
  *   Side A — every file in scripts/ (excluding README.md) must appear in the
- *            Inventory table's Script column.
+ *            Inventory table, and every inventoried helper must exist on disk.
  *   Side B — for every Inventory row, every `skills/<name>.md` token in the
  *            Cited by cell must reference a file whose body contains the
  *            literal substring `scripts/<script-filename>` for at least one
@@ -85,30 +85,67 @@ function listSkillFiles(repoRoot) {
     const dir = join(repoRoot, SKILLS_DIR);
     if (!existsSync(dir) || !statSync(dir).isDirectory())
         return [];
-    return readdirSync(dir)
-        .filter((entry) => entry.endsWith(".md"))
-        .map((entry) => `${SKILLS_DIR}/${entry}`)
-        .sort();
+    const skills = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name.endsWith(".md")) {
+            skills.push(`${SKILLS_DIR}/${entry.name}`);
+            continue;
+        }
+        if (entry.isDirectory() &&
+            existsSync(join(dir, entry.name, "SKILL.md"))) {
+            skills.push(`${SKILLS_DIR}/${entry.name}.md`);
+        }
+    }
+    return skills.sort();
+}
+function resolveSkillFile(repoRoot, skillPath) {
+    const flatPath = join(repoRoot, skillPath);
+    if (existsSync(flatPath))
+        return flatPath;
+    const bundledSkill = /^skills\/([^/]+)\.md$/.exec(skillPath);
+    if (bundledSkill?.[1]) {
+        return join(repoRoot, SKILLS_DIR, bundledSkill[1], "SKILL.md");
+    }
+    return flatPath;
 }
 function toPosix(relPath) {
     return relPath.split(sep).join(posix.sep);
 }
 export function checkRepo(repoRoot) {
+    const structure = [];
     const sideA = [];
     const sideB = [];
     const sideC = [];
-    const scriptFiles = listScriptFiles(repoRoot);
+    const scriptsPath = join(repoRoot, SCRIPTS_DIR);
     const readmePath = join(repoRoot, SCRIPTS_README);
-    const readmeContent = existsSync(readmePath) ? readFileSync(readmePath, "utf8") : "";
+    const scriptsDirectoryExists = existsSync(scriptsPath) && statSync(scriptsPath).isDirectory();
+    const readmeExists = scriptsDirectoryExists && existsSync(readmePath);
+    const readmeContent = readmeExists ? readFileSync(readmePath, "utf8") : "";
     const rows = parseInventoryTable(readmeContent);
+    if (!scriptsDirectoryExists) {
+        structure.push("scripts/ directory is missing");
+    }
+    else if (!readmeExists) {
+        structure.push("scripts/README.md inventory is missing");
+    }
+    else if (rows.length === 0) {
+        structure.push("scripts/README.md inventory has no rows");
+    }
+    const scriptFiles = listScriptFiles(repoRoot);
     const inventoryScripts = new Set();
     for (const row of rows) {
         for (const s of row.scripts)
             inventoryScripts.add(s);
     }
+    const scriptFileSet = new Set(scriptFiles);
     for (const file of scriptFiles) {
         if (!inventoryScripts.has(file)) {
-            sideA.push(file);
+            sideA.push(`${file} — file is missing from the inventory`);
+        }
+    }
+    for (const inventoryScript of inventoryScripts) {
+        if (!scriptFileSet.has(inventoryScript)) {
+            sideA.push(`${inventoryScript} — inventoried helper file is missing`);
         }
     }
     let citationCount = 0;
@@ -122,7 +159,7 @@ export function checkRepo(repoRoot) {
     for (const row of rows) {
         for (const skillPath of row.skills) {
             citationCount += 1;
-            const fullSkill = join(repoRoot, skillPath);
+            const fullSkill = resolveSkillFile(repoRoot, skillPath);
             let skillBody = "";
             try {
                 skillBody = readFileSync(fullSkill, "utf8");
@@ -142,7 +179,7 @@ export function checkRepo(repoRoot) {
     for (const skillPath of skillFiles) {
         let body = "";
         try {
-            body = readFileSync(join(repoRoot, skillPath), "utf8");
+            body = readFileSync(resolveSkillFile(repoRoot, skillPath), "utf8");
         }
         catch {
             continue;
@@ -160,6 +197,7 @@ export function checkRepo(repoRoot) {
         }
     }
     return {
+        structure,
         sideA,
         sideB,
         sideC,
@@ -170,15 +208,25 @@ export function checkRepo(repoRoot) {
 function main() {
     const repoRoot = argv[2] ?? cwd();
     const result = checkRepo(repoRoot);
-    const totalViolations = result.sideA.length + result.sideB.length + result.sideC.length;
+    const totalViolations = result.structure.length +
+        result.sideA.length +
+        result.sideB.length +
+        result.sideC.length;
     if (totalViolations === 0) {
         console.log(`OK scripts-citation-drift: ${result.scriptCount} script(s), ${result.citationCount} skill citation(s), all three sides reconciled.`);
         exit(0);
     }
     console.error(`FAIL scripts-citation-drift: ${totalViolations} drift(s) across the inventory-citation contract.`);
+    if (result.structure.length > 0) {
+        console.error("");
+        console.error("Contract structure:");
+        for (const v of result.structure) {
+            console.error(`  ${toPosix(v)}`);
+        }
+    }
     if (result.sideA.length > 0) {
         console.error("");
-        console.error("Side A — script files missing from scripts/README.md inventory table:");
+        console.error("Side A — scripts/ files and inventory rows do not match:");
         for (const v of result.sideA) {
             console.error(`  ${toPosix(v)}`);
         }
@@ -198,7 +246,7 @@ function main() {
         }
     }
     console.error("");
-    console.error("Fix: update scripts/README.md inventory (Side A/C) or correct the skill citation (Side B).");
+    console.error("Fix: restore scripts/ and its inventory, update Side A/C, or correct the Side B skill citation.");
     exit(1);
 }
 const scriptPathFromArgv = argv[1];

package/bin/generate-plugin-manifests.mjs

@@ -82,6 +82,7 @@ async function writePluginBundleReadme() {
         "- `commands/`",
         "- `agents/` — `code-reviewer`, `security-auditor`, `test-engineer` personas (auto-discovered Claude Code subagents; pattern from addy/agent-skills)",
         "- `hooks/`",
+        "- `scripts/`",
         "- `bin/mcp-server.mjs`",
         "- `bin/observe.mjs`",
         "- `bin/backfill.mjs`",
@@ -140,6 +141,7 @@ async function writePluginBundle() {
         copyDirectory(join(REPO_ROOT, "commands"), join(PLUGIN_BUNDLE_DIR, "commands")),
         copyDirectory(join(REPO_ROOT, "agents"), join(PLUGIN_BUNDLE_DIR, "agents")),
         copyDirectory(join(REPO_ROOT, "hooks"), join(PLUGIN_BUNDLE_DIR, "hooks")),
+        copyDirectory(join(REPO_ROOT, "scripts"), join(PLUGIN_BUNDLE_DIR, "scripts")),
         copyDirectory(join(REPO_ROOT, "instinct-packs"), join(PLUGIN_BUNDLE_DIR, "instinct-packs")),
         copyDirectory(join(REPO_ROOT, "templates", "planning-with-files"), join(PLUGIN_BUNDLE_DIR, "templates", "planning-with-files")),
         copyFileTo(join(REPO_ROOT, "bin", "mcp-server.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "mcp-server.mjs")),

package/bin/install.mjs

@@ -45,29 +45,25 @@ const SESSION_HOOK_TYPES = ["SessionStart", "SessionEnd"];
 // accidental overlap between HOOK_TYPES and SESSION_HOOK_TYPES never causes
 // a hook bucket to be processed twice.
 const ALL_HOOK_TYPES = Array.from(new Set([...HOOK_TYPES, ...SESSION_HOOK_TYPES]));
-// Our installer writes `bash ".../.claude/instincts/(observe|session).sh"`.
-// Older Windows installs sometimes stored the same command with backslashes in
-// the quoted path; those no-op because bash can't resolve them. We strip only
-// that installer-owned command shape so foreign hooks that merely mention
-// observe.sh/session.sh survive.
-const INSTALLER_OBSERVE_SESSION_COMMAND_RE = /^bash ".*[\\/]\.claude[\\/]instincts[\\/](?:observe|session)\.sh"$/;
-function isBrokenObserveOrSessionCommand(command) {
+// Match only installer-owned lifecycle commands. Bash rows are legacy and get
+// migrated on install; both legacy and current Node rows are removed on uninstall.
+const LEGACY_OBSERVE_SESSION_COMMAND_RE = /^bash ".*[\\/]\.claude[\\/]instincts[\\/](?:observe|session)\.sh"$/;
+const NODE_OBSERVE_SESSION_COMMAND_RE = /^node ".*[\\/]\.claude[\\/]instincts[\\/](?:bin[\\/]observe|session)\.mjs"$/;
+function isLegacyObserveOrSessionCommand(command) {
     if (typeof command !== "string")
         return false;
-    return command.includes("\\") && INSTALLER_OBSERVE_SESSION_COMMAND_RE.test(command);
+    return LEGACY_OBSERVE_SESSION_COMMAND_RE.test(command);
 }
-// Any installer-owned observe.sh / session.sh hook command, broken or clean.
-// Used by uninstall to drop both freshly-installed forward-slash hooks and any
-// stale legacy entries. Pairs with isBrokenObserveOrSessionCommand above.
 function isOurObserveOrSessionCommand(command) {
     if (typeof command !== "string")
         return false;
-    return INSTALLER_OBSERVE_SESSION_COMMAND_RE.test(command);
+    return LEGACY_OBSERVE_SESSION_COMMAND_RE.test(command) ||
+        NODE_OBSERVE_SESSION_COMMAND_RE.test(command);
 }
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
-function toBashPath(filePath) {
+function toCommandPath(filePath) {
     return filePath.replace(/\\/g, "/");
 }
 function isInstallMode(value) {
@@ -84,23 +80,6 @@ function readJsonFile(filePath) {
         return null;
     }
 }
-// The observation hooks (hooks/observe.sh, hooks/session.sh) are bash scripts.
-// On Windows without Git Bash / WSL the hook commands written into settings.json
-// silently no-op, so the user finishes install thinking observation capture is
-// live when it never fires. Refuse the install with one actionable line instead.
-function assertBashAvailableOnWindows() {
-    if (process.platform !== "win32")
-        return;
-    try {
-        execSync("bash --version", { stdio: "ignore" });
-    }
-    catch {
-        console.error("  ✗ Install refused: the observation hooks (hooks/observe.sh, hooks/session.sh) " +
-            "are bash scripts, but `bash --version` is not on PATH. Install Git Bash or WSL, " +
-            "reopen your shell, and re-run — see README → Troubleshooting install.");
-        process.exit(1);
-    }
-}
 // The marketplace `/plugin install` path and this npx installer both write into
 // ~/.claude/. Running both duplicates hooks, commands, and skills. We cannot
 // fully resolve Claude Code's marketplace layout from here, so this is a loud
@@ -164,39 +143,26 @@ function setupMulahazah() {
     const globalDir = join(instinctsDir, "global");
     mkdirSync(globalDir, { recursive: true });
     console.log(`  ✓ Instincts dir → ${instinctsDir}/`);
-    const observeSrc = join(REPO_ROOT, "hooks", "observe.sh");
-    const observeDest = join(instinctsDir, "observe.sh");
-    if (existsSync(observeSrc)) {
-        copyFileSync(observeSrc, observeDest);
-        chmodSync(observeDest, 0o755);
-        console.log(`  ✓ observe.sh → ${observeDest}`);
-    }
-    // Node observer (Phase 1 of the two-phase hook). The bash shim above
-    // exec's this when `node` and the file are both present; otherwise it
-    // falls back to the in-bash thin-schema path. Layout under instinctsDir
-    // mirrors the repo's bin/ + lib/ structure so the relative import in
-    // observe.mjs (`../lib/observe-event.mjs`) resolves correctly.
+    // Layout mirrors bin/ + lib/ so observe.mjs's relative import resolves.
     const observerJsSrc = join(REPO_ROOT, "bin", "observe.mjs");
     const observeEventSrc = join(REPO_ROOT, "lib", "observe-event.mjs");
+    const observerJsDest = join(instinctsDir, "bin", "observe.mjs");
     if (existsSync(observerJsSrc) && existsSync(observeEventSrc)) {
         const binDir = join(instinctsDir, "bin");
         const libDir = join(instinctsDir, "lib");
         mkdirSync(binDir, { recursive: true });
         mkdirSync(libDir, { recursive: true });
-        const observerJsDest = join(binDir, "observe.mjs");
         const observeEventDest = join(libDir, "observe-event.mjs");
         copyFileSync(observerJsSrc, observerJsDest);
         copyFileSync(observeEventSrc, observeEventDest);
         console.log(`  ✓ Node observer → ${observerJsDest}`);
     }
-    if (INSTALL_MODE === "expert") {
-        const sessionSrc = join(REPO_ROOT, "hooks", "session.sh");
-        const sessionDest = join(instinctsDir, "session.sh");
-        if (existsSync(sessionSrc)) {
-            copyFileSync(sessionSrc, sessionDest);
-            chmodSync(sessionDest, 0o755);
-            console.log(`  ✓ session.sh → ${sessionDest}`);
-        }
+    const sessionSrc = join(REPO_ROOT, "hooks", "session.mjs");
+    const sessionDest = join(instinctsDir, "session.mjs");
+    if (existsSync(sessionSrc)) {
+        copyFileSync(sessionSrc, sessionDest);
+        chmodSync(sessionDest, 0o755);
+        console.log(`  ✓ Node session hook → ${sessionDest}`);
     }
     const commandsDir = join(home, ".claude", "commands");
     mkdirSync(commandsDir, { recursive: true });
@@ -208,7 +174,7 @@ function setupMulahazah() {
             console.log(`  ✓ /${commandFile.replace(".md", "")} command → ${commandDest}`);
         }
     }
-    patchClaudeSettings(observeDest);
+    patchClaudeSettings(observerJsDest);
     if (INSTALL_MODE === "expert") {
         setupMcpServer();
     }
@@ -271,6 +237,10 @@ function patchClaudeSettings(observePath) {
     if (!settings.hooks) {
         settings.hooks = {};
     }
+    const preserveSessionHooks = INSTALL_MODE === "expert" || SESSION_HOOK_TYPES.some((hookType) => {
+        const entries = settings.hooks?.[hookType];
+        return Array.isArray(entries) && entries.some((entry) => Array.isArray(entry?.hooks) && entry.hooks.some((hook) => isOurObserveOrSessionCommand(hook?.command)));
+    });
     // Strip broken legacy observe/session hooks at the hook level, not the entry
     // level. A single entry may carry a foreign command alongside a broken hook;
     // dropping the whole entry to remove the broken hook would also wipe the
@@ -289,7 +259,7 @@ function patchClaudeSettings(observePath) {
                 cleanedEntries.push(entry);
                 continue;
             }
-            const filteredHooks = entryHooks.filter((hook) => !isBrokenObserveOrSessionCommand(hook?.command));
+            const filteredHooks = entryHooks.filter((hook) => !isLegacyObserveOrSessionCommand(hook?.command));
             if (filteredHooks.length === entryHooks.length) {
                 cleanedEntries.push(entry);
                 continue;
@@ -308,7 +278,7 @@ function patchClaudeSettings(observePath) {
             changed = true;
         }
     }
-    const observeCommand = `bash "${toBashPath(observePath)}"`;
+    const observeCommand = `node "${toCommandPath(observePath)}"`;
     for (const hookType of HOOK_TYPES) {
         if (!Array.isArray(settings.hooks[hookType])) {
             settings.hooks[hookType] = [];
@@ -327,9 +297,9 @@ function patchClaudeSettings(observePath) {
             changed = true;
         }
     }
-    if (INSTALL_MODE === "expert") {
-        const sessionPath = join(getHomeDir(), ".claude", "instincts", "session.sh");
-        const sessionCommand = `bash "${toBashPath(sessionPath)}"`;
+    if (preserveSessionHooks) {
+        const sessionPath = join(getHomeDir(), ".claude", "instincts", "session.mjs");
+        const sessionCommand = `node "${toCommandPath(sessionPath)}"`;
         for (const hookType of SESSION_HOOK_TYPES) {
             if (!Array.isArray(settings.hooks[hookType])) {
                 settings.hooks[hookType] = [];
@@ -346,7 +316,7 @@ function patchClaudeSettings(observePath) {
     }
     if (changed) {
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-        const hookTypes = INSTALL_MODE === "expert"
+        const hookTypes = preserveSessionHooks
             ? "PreToolUse/PostToolUse/SessionStart/SessionEnd"
             : "PreToolUse/PostToolUse";
         console.log(`  ✓ Patched ~/.claude/settings.json with ${hookTypes} hooks`);
@@ -382,7 +352,7 @@ function uninstallAll() {
             console.error(`  ✗ ${commandName}: ${getErrorMessage(error)}`);
         }
     }
-    for (const hookFile of ["observe.sh", "session.sh"]) {
+    for (const hookFile of ["observe.sh", "session.sh", "session.mjs"]) {
         const filePath = join(home, ".claude", "instincts", hookFile);
         if (!existsSync(filePath)) {
             continue;
@@ -625,7 +595,6 @@ console.log(`
 continuous-improvement (mode: ${INSTALL_MODE})
 Research → Plan → Execute → Verify → Reflect → Learn → Iterate
 `);
-assertBashAvailableOnWindows();
 warnOnMarketplaceCollision();
 console.log("Installing to Claude Code...\n");
 const installed = installSkill() ? 1 : 0;

package/commands/production-readiness-review.md

@@ -1,6 +1,6 @@
 ---
 name: production-readiness-review
-description: "Parallel multi-agent readiness gate — fan blind reviewers across performance, security, UI/UX, and test coverage, each grounding findings in real code/logs/live data, then reconcile into one deduplicated, severity-ranked punch-list. Reports only; never fixes, merges, or deploys."
+description: "Parallel multi-agent readiness gate — fan blind reviewers across performance, security, UI/UX, test coverage, and simplicity, each grounding findings in real code/logs/live data, then reconcile into one deduplicated, severity-ranked punch-list. Reports only; never fixes, merges, or deploys."
 ---
 
 # /production-readiness-review
@@ -20,11 +20,12 @@ Pure routing over existing skills and agents. Adds no new code.
 ## Behavior
 
 1. **Scope** — establish ground truth: the diff under review and which changes are recent (`git diff`; `reconcile` fallback for branch/base state). Recent changes get extra scrutiny because they are the likeliest source of self-inflicted defects.
-2. **Fan out** — `superpowers:dispatching-parallel-agents` launches four reviewers, each blind to the others. Every reviewer is instructed to ground each finding in real code, logs, or live queries, and never to assume or fabricate state:
+2. **Fan out** — `superpowers:dispatching-parallel-agents` launches five reviewers, each blind to the others. Every reviewer is instructed to ground each finding in real code, logs, or live queries, and never to assume or fabricate state:
    - **Performance & bundle-size** — hot paths, N+1 queries, unbounded work, regressions.
    - **Security & data-access** (`security-auditor`) — authn/authz, input handling, injection, secret exposure, unsafe data access.
    - **UI/UX correctness** — verified live with Playwright when the MCP is available, else static review of the changed surface.
    - **Test coverage & flaky/stale mocks** (`test-engineer`) — uncovered branches, stale mocks, timing-flaky tests.
+   - **Simplicity & over-engineering** (`simplicity-review`) — code that could reuse an existing file, a stdlib or native feature, or fewer lines; reports trim opportunities via the reuse ladder and never flags input validation, data-loss handling, security, or accessibility.
 3. **Reconcile** — a final pass dedupes findings across reviewers, ranks each CRITICAL / HIGH / MEDIUM / LOW by severity and confidence, and explicitly flags any defect introduced by the changes under review.
 4. **Present** — emit the consolidated punch-list, severity-ranked, with file references. **Stop.**
 
@@ -42,7 +43,7 @@ Pure routing over existing skills and agents. Adds no new code.
 
 ## Composition
 
-Routes through: `reconcile` (scope/ground truth) → `superpowers:dispatching-parallel-agents` (fan-out) → the `security-auditor` and `test-engineer` agents (two of the four dimensions) → a reconciliation pass that ranks and dedupes. Each step falls back to its inline behavior when the preferred skill or agent is not installed.
+Routes through: `reconcile` (scope/ground truth) → `superpowers:dispatching-parallel-agents` (fan-out) → the `security-auditor` and `test-engineer` agents and the `simplicity-review` skill (three of the five dimensions) → a reconciliation pass that ranks and dedupes. Each step falls back to its inline behavior when the preferred skill or agent is not installed.
 
 ## Example
 
@@ -50,4 +51,4 @@ Routes through: `reconcile` (scope/ground truth) → `superpowers:dispatching-pa
 /production-readiness-review #246
 ```
 
-Scopes PR #246's diff, fans four blind reviewers across performance, security, UI/UX, and test coverage, then returns one deduplicated severity-ranked punch-list — flagging anything the PR's own changes introduced — and stops for you to prioritize.
+Scopes PR #246's diff, fans five blind reviewers across performance, security, UI/UX, test coverage, and simplicity, then returns one deduplicated severity-ranked punch-list — flagging anything the PR's own changes introduced — and stops for you to prioritize.

package/commands/simplicity-review.md

@@ -0,0 +1,35 @@
+---
+name: simplicity-review
+description: Review the current diff for over-engineering — flag code that could reuse an existing file, a stdlib or native feature, or fewer lines — and report GO/TRIM findings without touching code. Enforces Law 4 (Verify Before Reporting).
+---
+
+# /simplicity-review — Judge the Diff Before You Ship It
+
+Read the current change like the laziest senior dev in the room: could this have been smaller? Passing tests prove correctness, not minimality. Backed by the `simplicity-review` skill.
+
+## What it does
+
+Takes the working-tree diff (vs HEAD by default; accepts an optional commit range or file list), reads each changed block, and walks a fixed reuse ladder:
+
+```
+1. Does this need to exist?   -> skip it (YAGNI)
+2. Already in this codebase?  -> reuse it
+3. Stdlib does it?            -> use it
+4. Native platform feature?   -> use it
+5. Installed dependency?      -> use it
+6. One line?                  -> one line
+7. Only then:                    the minimum that works
+```
+
+It reports `file:line`, what is over-built, the specific simpler path, and closes with `GO` (already minimal) or `TRIM` (findings to apply). It does not edit code.
+
+## Default skeptical
+
+A finding is a hypothesis. Read the surrounding code and prove the simpler path exists and preserves behavior before asserting it; a wrong trim is worse than the over-build. Never flag input validation, data-loss-preventing error handling, security, or accessibility — lazy, not negligent.
+
+## Pairs with
+
+- **`simplicity-review`** skill — the discipline this command runs.
+- **`proceed-with-the-recommendation`** — apply the trims under the 7 Laws.
+- **`verification-loop`** — the ladder to re-run on whatever you trim.
+- **`production-readiness-review`** — the sibling diff review for performance, security, UI, and test coverage.

package/commands/verify-install.md

@@ -40,8 +40,8 @@ The observation hook appends one row per tool call to
 `<project-hash>` from the current repo, or check `~/.claude/instincts/global/`).
 
 - If it exists and has at least one row — capture is recording. Record `observe: ✓`.
-- If it is missing or empty — record `observe: ✗ (observation hook not recording —
-  on Windows confirm Git Bash / WSL is installed, then re-run the installer)`.
+- If it is missing or empty, record `observe: ✗ (observation hook not recording; re-run
+  the installer to migrate legacy Bash hook rows to the Node observer)`.
 
 ## Report