continuous-improvement 3.20.4 → 3.22.0

package/bin/reconcile.mjs

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+/**
+ * reconcile (`ci-reconcile`).
+ *
+ * Run the `reconcile` skill's ground-truth pass and print the resolved-state
+ * block, so Law 1 is a command an agent runs rather than prose it claims to
+ * have followed.
+ *
+ *   node bin/reconcile.mjs                    resolved-state block; exit 1 on a blocker
+ *   node bin/reconcile.mjs --json             the same state as JSON
+ *   node bin/reconcile.mjs --snapshot         one-line envelope, field-compatible
+ *                                             with scripts/git-state-snapshot.sh
+ *   node bin/reconcile.mjs --verify-push <br> prove a push landed on origin/<br>
+ *   node bin/reconcile.mjs --explain          print the probe set and why each runs
+ *   node bin/reconcile.mjs --cwd <dir>        run against another repo root
+ *
+ * Portability: every probe is `git` argv spawned with `shell: false`. No bash,
+ * no coreutils, no `.git/`-relative paths — so it behaves the same in PowerShell,
+ * cmd, Git Bash, WSL and a POSIX shell, and it stays correct inside a linked
+ * worktree where `.git` is a file rather than a directory.
+ *
+ * Exit codes:
+ *   0 — ground truth established, nothing blocks a mutation
+ *   1 — at least one blocker (detached HEAD, in-progress op, unknown upstream)
+ *   2 — not a git repository, or git is unavailable
+ */
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { argv, cwd, exit, stderr, stdout } from "node:process";
+import { GROUND_TRUTH_PROBES, IN_PROGRESS_MARKERS, accountDirty, assessGitState, classifyHead, classifyUpstream, hasBlockers, isSafeRefName, parseRevListCounts, renderResolvedState, verifyPushLanded, } from "../lib/git-state.mjs";
+const NOT_A_REPO = 2;
+/** Spawn `git` with no shell. A missing git binary reads as a failed probe. */
+function git(args, root) {
+    const result = spawnSync("git", [...args], {
+        cwd: root,
+        encoding: "utf8",
+        shell: false,
+        windowsHide: true,
+    });
+    if (result.error) {
+        return { stdout: "", stderr: result.error.message, code: 127 };
+    }
+    return {
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        code: typeof result.status === "number" ? result.status : 1,
+    };
+}
+function parseArgs(args) {
+    const options = {
+        json: false,
+        snapshot: false,
+        explain: false,
+        verifyPush: null,
+        root: cwd(),
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--json")
+            options.json = true;
+        else if (arg === "--snapshot")
+            options.snapshot = true;
+        else if (arg === "--explain")
+            options.explain = true;
+        else if (arg === "--verify-push") {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error("--verify-push requires a branch name");
+            }
+            if (!isSafeRefName(value)) {
+                throw new Error(`--verify-push branch is not a usable ref name: ${value}`);
+            }
+            options.verifyPush = value;
+            i++;
+        }
+        else if (arg === "--cwd") {
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error("--cwd requires a directory");
+            }
+            options.root = value;
+            i++;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            options.explain = true;
+        }
+        else {
+            throw new Error(`unknown argument: ${arg}`);
+        }
+    }
+    return options;
+}
+/** Probe each in-progress marker through `--git-path`, which is worktree-correct. */
+function probeInProgress(root) {
+    const present = [];
+    for (const marker of IN_PROGRESS_MARKERS) {
+        const resolved = git(["rev-parse", "--git-path", marker.gitPath], root);
+        // A failed resolve leaves the marker unprobed rather than absent; the
+        // classifier reports that explicitly instead of implying a clean tree.
+        if (resolved.code !== 0)
+            continue;
+        const path = resolved.stdout.trim();
+        if (path.length > 0 && existsSync(path))
+            present.push(marker.id);
+    }
+    return present;
+}
+function explain() {
+    const rows = GROUND_TRUTH_PROBES.map((probe) => `  git ${probe.args.join(" ")}\n      ${probe.purpose}` +
+        (probe.tolerateFailure ? "\n      (a non-zero exit is an answer, not a failure)" : ""));
+    const markers = IN_PROGRESS_MARKERS.map((marker) => `  git rev-parse --git-path ${marker.gitPath}   # ${marker.label}`);
+    return [
+        "reconcile ground-truth probes (source: src/lib/git-state.mts):",
+        ...rows,
+        "",
+        "in-progress operation markers:",
+        ...markers,
+    ].join("\n");
+}
+function main() {
+    let options;
+    try {
+        options = parseArgs(argv.slice(2));
+    }
+    catch (error) {
+        stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        exit(NOT_A_REPO);
+        return;
+    }
+    if (options.explain) {
+        stdout.write(`${explain()}\n`);
+        exit(0);
+        return;
+    }
+    const root = git(["rev-parse", "--show-toplevel"], options.root);
+    if (root.code !== 0) {
+        if (options.snapshot) {
+            stdout.write('{"error":"not-a-git-repo"}\n');
+        }
+        else {
+            stderr.write("not a git repository (or git is unavailable)\n");
+        }
+        exit(NOT_A_REPO);
+        return;
+    }
+    const repoRoot = root.stdout.trim();
+    const headSha = git(["rev-parse", "HEAD"], options.root);
+    const branchProbe = git(["symbolic-ref", "--quiet", "--short", "HEAD"], options.root);
+    const head = classifyHead(branchProbe.stdout, branchProbe.code);
+    const upstreamProbe = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], options.root);
+    const upstreamRef = upstreamProbe.code === 0 ? upstreamProbe.stdout.trim() || null : null;
+    // Only ask for counts once an upstream is known to exist — the bare command
+    // exits 128 with `fatal: no upstream configured` otherwise.
+    const countsProbe = upstreamRef === null
+        ? null
+        : git(["rev-list", "--left-right", "--count", "@{u}...HEAD"], options.root);
+    const counts = countsProbe !== null && countsProbe.code === 0
+        ? parseRevListCounts(countsProbe.stdout)
+        : null;
+    const status = git(["status", "--porcelain=v1"], options.root);
+    const drift = git(["diff", "--name-only", "--ignore-all-space"], options.root);
+    const dirty = accountDirty(status.code === 0 ? status.stdout : null, drift.code === 0 ? drift.stdout : null);
+    if (options.snapshot) {
+        // Field-compatible with scripts/git-state-snapshot.sh, plus `contentDrift`
+        // and `inProgress`, which the shell version cannot report.
+        const upstreamSha = upstreamRef === null ? "none" : git(["rev-parse", "--short", "@{u}"], options.root).stdout.trim() || "none";
+        stdout.write(`${JSON.stringify({
+            head: git(["rev-parse", "--short", "HEAD"], options.root).stdout.trim(),
+            upstream: upstreamSha,
+            dirty: dirty.reported,
+            root: repoRoot,
+            branch: head.branch ?? "detached",
+            contentDrift: dirty.contentDrift,
+            inProgress: probeInProgress(options.root),
+        })}\n`);
+        exit(0);
+        return;
+    }
+    if (options.verifyPush !== null) {
+        const lsRemote = git(["ls-remote", "origin", `refs/heads/${options.verifyPush}`], options.root);
+        const verdict = verifyPushLanded({
+            localHead: headSha.stdout.trim(),
+            lsRemoteStdout: lsRemote.stdout,
+            lsRemoteExitCode: lsRemote.code,
+        });
+        const line = `push ${options.verifyPush}: ${verdict.verdict} — ${verdict.reason}`;
+        if (options.json)
+            stdout.write(`${JSON.stringify({ branch: options.verifyPush, ...verdict })}\n`);
+        else
+            stdout.write(`${line}\n`);
+        exit(verdict.verdict === "landed" ? 0 : 1);
+        return;
+    }
+    const inProgress = probeInProgress(options.root);
+    const findings = assessGitState({
+        head,
+        upstreamRef,
+        counts,
+        inProgress,
+        dirty,
+    });
+    const stashes = git(["stash", "list"], options.root);
+    const stashCount = stashes.code === 0
+        ? stashes.stdout.split(/\r?\n/).filter((line) => line.trim().length > 0).length
+        : null;
+    findings.push({
+        id: "stashes",
+        label: "stashes",
+        detail: stashCount === null
+            ? "unprobed"
+            : stashCount === 0
+                ? "none"
+                : `${stashCount} — may hold uncommitted work from an earlier session`,
+        severity: stashCount === null ? "warn" : "ok",
+    });
+    const worktrees = git(["worktree", "list", "--porcelain"], options.root);
+    const worktreeCount = worktrees.code === 0
+        ? worktrees.stdout.split(/\r?\n/).filter((line) => line.startsWith("worktree ")).length
+        : null;
+    findings.push({
+        id: "worktrees",
+        label: "worktrees",
+        detail: worktreeCount === null
+            ? "unprobed"
+            : worktreeCount <= 1
+                ? "1 (this one)"
+                : `${worktreeCount} — a concurrent writer may hold another; re-read HEAD immediately before each mutation`,
+        severity: worktreeCount === null || (worktreeCount ?? 0) > 1 ? "warn" : "ok",
+    });
+    const blocked = hasBlockers(findings);
+    if (options.json) {
+        stdout.write(`${JSON.stringify({
+            root: repoRoot,
+            head: headSha.stdout.trim(),
+            branch: head.branch,
+            headKind: head.kind,
+            upstream: upstreamRef,
+            relation: classifyUpstream(counts, upstreamRef !== null),
+            counts,
+            inProgress,
+            dirty,
+            stashes: stashCount,
+            worktrees: worktreeCount,
+            findings,
+            blocked,
+        }, null, 2)}\n`);
+    }
+    else {
+        stdout.write(`${renderResolvedState(findings)}\n`);
+        if (blocked) {
+            stdout.write("\nBLOCKED — resolve every blocker above before mutating this tree.\n");
+        }
+    }
+    exit(blocked ? 1 : 0);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("reconcile.mjs")) {
+    main();
+}

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/reconcile.md

@@ -13,15 +13,36 @@ Snapshots the full git state in one pass, detects a concurrent writer, classifie
 
 ## Establish ground truth
 
+One command, cross-platform, no shell required:
+
+```
+npx ci-reconcile              # resolved-state block; exit 0 clear / 1 blocked / 2 not a repo
+npx ci-reconcile --json       # machine-readable
+npx ci-reconcile --explain    # the probe set and why each probe runs
+```
+
+The same pass by hand. `src/lib/git-state.mts` is the source of truth for this list, and `npm run verify:reconcile-parity` fails if this file drifts from it:
+
 ```
-git branch --show-current
-git status --porcelain=v1                     # but trust git diff --stat for real drift (autocrlf)
-git rev-list --left-right --count '@{u}...HEAD'  # behind / ahead (quote the ref — bare @{u} trips the Bash parser)
+git rev-parse --show-toplevel                          # inside a work tree, and where
+git rev-parse HEAD                                     # the sha every later claim is relative to
+git symbolic-ref --quiet --short HEAD                  # branch; NON-ZERO EXIT = detached HEAD
+git rev-parse --abbrev-ref --symbolic-full-name @{u}   # upstream, or non-zero = none configured
+git rev-list --left-right --count @{u}...HEAD          # behind/ahead — only after the line above succeeded
+git status --porcelain=v1                              # reported changes (inflated by autocrlf)
+git diff --name-only --ignore-all-space                # real content drift — the number to trust
 git stash list
-git worktree list
-ls .git/MERGE_HEAD .git/rebase-merge .git/rebase-apply 2>/dev/null  # in-progress op = another actor; do not race
+git worktree list --porcelain
+git rev-parse --git-path MERGE_HEAD                    # in-progress op: test the RESOLVED path
 ```
 
+Four boundaries where the obvious command lies:
+
+- **No upstream** — asking `git rev-list` for counts against `@{u}` exits 128; it does not return zeros. Resolve the upstream first.
+- **Detached HEAD** — the `--show-current` form of `git branch` prints "" and exits 0, indistinguishable from success. `symbolic-ref --quiet` exits non-zero instead. Detached blocks.
+- **Linked worktree** — `.git` is a *file* there, so a `.git/`-relative marker probe exits 2 exactly as it does on a clean tree: a real conflicted merge reads as clean. Use `rev-parse --git-path`.
+- **autocrlf** — `git status` overstates drift. Stage by explicit filename, never `git add -A`.
+
 ## Then act, with gates
 
 ```
@@ -51,9 +72,12 @@ gh pr create --fill --base main                      # open one PR, then STOP
 ## Verify the push landed
 
 ```
-git ls-remote origin refs/heads/<branch>   # remote tip must equal local HEAD, else it did not land
+npx ci-reconcile --verify-push <branch>    # exit 0 only when the remote tip equals local HEAD
+git ls-remote origin refs/heads/<branch>   # by hand: remote tip must equal local HEAD
 ```
 
+Three outcomes, never two: **landed** (tip matches), **not-landed** (probe succeeded, ref absent or different sha), **unverified** (`ls-remote` itself failed — you do not know; retry, and report neither success nor failure).
+
 ## Sync the default branch after the PR merges
 
 "Latest work on main" is true only once the PR merges, and on a protected branch that merge is a human action. After it lands:

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 is installed before WSL Bash on PATH, 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
 

package/hooks/session.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
+function read(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function eventFromStdin() {
+    const raw = read(0);
+    if (!raw)
+        return null;
+    try {
+        const payload = JSON.parse(raw);
+        if (!payload || typeof payload !== "object" || Array.isArray(payload))
+            return null;
+        const event = payload.hook_event_name ?? payload.hook_type ?? payload.event_type;
+        return event === "SessionStart" || event === "SessionEnd" ? event : "unknown";
+    }
+    catch {
+        return null;
+    }
+}
+function projectRoot() {
+    if (process.env.CLAUDE_PROJECT_DIR)
+        return process.env.CLAUDE_PROJECT_DIR;
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim() || "global";
+    }
+    catch {
+        return "global";
+    }
+}
+function yamlFiles(dir) {
+    try {
+        return readdirSync(dir)
+            .filter((name) => name.endsWith(".yaml"))
+            .map((name) => join(dir, name));
+    }
+    catch {
+        return [];
+    }
+}
+function main() {
+    const event = eventFromStdin();
+    if (event === null)
+        return;
+    if (event === "SessionEnd") {
+        process.stderr.write("[continuous-improvement] Session ending. Run /continuous-improvement to reflect and capture learnings.\n");
+        return;
+    }
+    const home = resolveHomeDir();
+    if (!home)
+        return;
+    const instinctsRoot = join(home, ".claude", "instincts");
+    const hash = createHash("sha256").update(projectRoot()).digest("hex").slice(0, 12);
+    const projectDir = join(instinctsRoot, hash);
+    const files = [...yamlFiles(projectDir), ...yamlFiles(join(instinctsRoot, "global"))];
+    const observations = read(join(projectDir, "observations.jsonl")).split(/\r?\n/).filter(Boolean).length;
+    let level = observations >= 20 || files.length > 0 ? "ANALYZE" : "CAPTURE";
+    for (const file of files) {
+        const value = Number(read(file).match(/^confidence:\s*([0-9]*\.?[0-9]+)/m)?.[1]);
+        if (Number.isFinite(value) && value >= 0.7) {
+            level = "AUTO-APPLY";
+            break;
+        }
+        if (Number.isFinite(value) && value >= 0.5)
+            level = "SUGGEST";
+    }
+    process.stderr.write(`[continuous-improvement] Level: ${level} | Observations: ${observations} | Instincts: ${files.length}\n`);
+}
+try {
+    main();
+}
+catch {
+}