continuous-improvement 3.9.2 → 3.11.0

package/plugins/continuous-improvement/commands/recall.md

@@ -0,0 +1,49 @@
+---
+name: recall
+description: Search past tool-call observations with BM25 ranking to answer "have I seen this before?" before re-deriving a fix or repeating a mistake. Enforces Law 1 (Research Before Executing).
+---
+
+# /recall — Episodic Search Over Past Sessions
+
+Search this project's observation history for relevant prior activity and return the most relevant past tool calls, ranked.
+
+## What it does
+
+Builds an in-memory BM25 index over `~/.claude/instincts/<project-hash>/observations.jsonl` and returns the top matches with redacted snippets, relevance scores, and timestamps. Backed by the `ci_recall` MCP tool (expert mode) and the `recall` skill.
+
+## How to invoke
+
+```
+ci_recall query="permission denied push"     # top 5 matches
+ci_recall query="jq command not found" k=3    # cap results
+ci_recall query="auth login" since=7d          # only the last 7 days
+```
+
+`since` accepts an ISO timestamp or a relative window: `7d`, `24h`, `30m`.
+
+## Output shape
+
+```
+## Recall: "permission denied push"
+
+2 match(es), most relevant first:
+
+- [2026-05-20T10:00:00Z] **Bash** (score 3.41)
+  …git push origin main  Permission denied: harness blocked direct push to main…
+- ...
+```
+
+## Privacy
+
+Snippets are passed through a secret redactor (AWS keys, JWT-shaped triplets, bearer tokens, KEY/SECRET/TOKEN/PASSWORD assignments, long hex strings) before display.
+
+## Notes
+
+- **Lexical, not semantic** — search with the vocabulary that actually appeared in the tool calls; try several phrasings if the first returns nothing.
+- Searches the full captured history, not just the recent window.
+
+## Pairs with
+
+- **`recall`** skill — the discipline this command runs.
+- **`continuous-improvement`** (core SKILL.md, Law 1 — Research Before Executing).
+- **`gateguard`** — recall a past failure before clearing a high-risk action.

package/plugins/continuous-improvement/commands/reconcile.md

@@ -0,0 +1,47 @@
+---
+name: reconcile
+description: Establish git ground truth (branch, status, stashes, worktrees, ahead/behind) before any mutation, halt on protected or destructive operations, and verify a push actually landed. Enforces Law 1 (Research Before Executing).
+---
+
+# /reconcile — Ground-Truth Git State Before You Touch It
+
+Read the repo's real state before acting on it: a branch that shifted, a push that did not land, or another session mid-merge will burn a whole session if you assume instead of check.
+
+## What it does
+
+Snapshots the full git state in one pass, detects a concurrent writer, classifies the upstream relationship, then acts only on the known state — stopping at every operation that is hard to reverse. Backed by the `reconcile` skill.
+
+## Establish ground truth
+
+```
+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
+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
+```
+
+## Then act, with gates
+
+```
+even      -> safe to branch (confirm local base == origin/base first)
+ahead     -> push or PR, AFTER the protected-op gate
+behind    -> git pull --ff-only
+diverged  -> rebase/merge deliberately; never blind --force
+```
+
+STOP for authorization before: pushing to a protected branch (this repo = feature branch + PR, never direct push to main), `--force` / `--force-with-lease`, `reset --hard`, `clean -fd`, or removing a dirty worktree. Never stage with `git add -A` on a Windows autocrlf tree (it commits phantom line-ending-only changes) — stage by explicit filename.
+
+## Verify the push landed
+
+```
+git ls-remote origin refs/heads/<branch>   # remote tip must equal local HEAD, else it did not land
+```
+
+## Pairs with
+
+- **`reconcile`** skill — the discipline this command runs.
+- **`gateguard`** / **`safety-guard`** — runtime + destructive-op guardrails.
+- **`recall`** — recall whether the same git op failed here before.
+- **`audit`** — the loop that often produces the fix `reconcile` then ships.

package/plugins/continuous-improvement/commands/superpowers.md

@@ -7,9 +7,9 @@ description: "Law activator and dispatcher — route the task to the right Law-a
 
 `/superpowers` is **the dispatcher**, not a peer skill. It does not do work itself; it routes each user task to the correct Law-aligned specialist so the right discipline fires automatically instead of the agent skipping a step.
 
-The 7 Laws define *what* discipline must be applied. `/superpowers` decides *which specialist* enforces it for this specific task, across five sources installed from this marketplace.
+The 7 Laws define *what* discipline must be applied. `/superpowers` decides *which specialist* enforces it for this specific task, across four sources installed from this marketplace.
 
-## Routing surface (five sources)
+## Routing surface (four sources)
 
 | Source | Where it lives | Examples of what it routes to |
 |---|---|---|

package/plugins/continuous-improvement/commands/verify-install.md

@@ -0,0 +1,55 @@
+---
+name: verify-install
+description: Walk the post-install verification in one shot — confirm slash commands loaded, the gateguard runtime hook fires, and observation capture is recording — then print a single ✓ wired / ✗ missing line.
+---
+
+# /verify-install
+
+Replaces the manual post-install dance (restart, run `/discipline`, hand-write a
+hostile prompt, eyeball `/dashboard`) with one command that runs all three
+checks and reports a single line.
+
+Run the three checks **in order**. Do not skip a check because an earlier one
+passed — each proves a different layer.
+
+## Check 1 — slash commands loaded
+
+If this command is executing, the marketplace did pick the plugin up and the
+command registry loaded it. Record `commands: ✓`.
+
+If you are reading this file directly rather than running it as `/verify-install`,
+stop — the command is not registered. The fix is a Claude Code session restart
+(slash commands load on session start). Record `commands: ✗ (restart the session)`.
+
+## Check 2 — gateguard runtime hook fires
+
+The runtime gate ships as a PreToolUse hook (`hooks/gateguard.mjs`). Probe it:
+attempt to `Write` a throwaway file at a sandbox path (`./.ci-verify-install-probe.txt`
+with the text `probe`) **without presenting any research first**.
+
+- If the hook **blocks** the write with a fact-list reason — the runtime layer is
+  wired. Record `gateguard: ✓`. Do not retry the write; the block is the pass.
+- If the write **goes through** with no pause — the hook did not load. Record
+  `gateguard: ✗ (hooks/gateguard.mjs not wired — see README → Troubleshooting install)`.
+  Delete the probe file if it was created.
+
+## Check 3 — observation capture recording
+
+The observation hook appends one row per tool call to
+`~/.claude/instincts/<project-hash>/observations.jsonl`. Read that file (resolve
+`<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)`.
+
+## Report
+
+Emit exactly one summary line, nothing else after it:
+
+- All three passed: `✓ wired — commands, gateguard, observe all confirmed.`
+- Any failed: `✗ <comma-separated failing checks with their fix hints>.`
+
+Do not claim "should be fine" for a check you could not actually run. If a check
+is genuinely unrunnable (e.g. no repo context for the project hash), mark it
+`unverified` with the reason rather than `✓`.

package/plugins/continuous-improvement/hooks/companion-preference.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Runtime PreToolUse companion-preference hook.
+ *
+ * Reads ~/.claude/settings.json → continuous_improvement.companion_preference
+ * and enforces the Companion-Preference Override contract documented in
+ * skills/superpowers.md for `Skill` tool calls.
+ *
+ *   ci-first       (default): no-op, allow.
+ *   companions-first        : advisory stderr on mapped CI→companion pair; allow.
+ *   strict-companions       : block mapped CI route. Reason names the companion
+ *                             (when installed) or the install hint (when not).
+ *
+ * Fail-open: any unexpected error reading stdin / parsing settings / probing
+ * the filesystem → emit { decision: "allow" } and exit 0. The hook never
+ * blocks on its own bugs.
+ *
+ * Stdin  : JSON { tool_name, tool_input }
+ * Stdout : JSON { decision: "allow" | "block", reason?: string }
+ * Exit   : 0 always — decision lives in stdout, never in the exit code.
+ *
+ * OVERRIDES map must stay row-aligned with skills/superpowers.md
+ * § "Which rows the override affects" — drift will surface when the test
+ * suite or a follow-up audit walks the table against this map.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const OVERRIDES = {
+    "tdd-workflow": {
+        companion: "superpowers:test-driven-development",
+        plugin: "superpowers",
+    },
+    "verification-loop": {
+        companion: "superpowers:verification-before-completion",
+        plugin: "superpowers",
+    },
+    "context-budget": {
+        companion: "agent-skills:context-engineering",
+        plugin: "agent-skills",
+    },
+    ralph: {
+        companion: "oh-my-claudecode:ultrawork",
+        plugin: "oh-my-claudecode",
+    },
+    "learn-eval": {
+        companion: "oh-my-claudecode:retrospective",
+        plugin: "oh-my-claudecode",
+    },
+};
+function emitAndExit(d) {
+    process.stdout.write(`${JSON.stringify(d)}\n`);
+    process.exit(0);
+}
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function readMode(home) {
+    try {
+        const raw = readFileSync(join(home, ".claude", "settings.json"), "utf8");
+        const settings = JSON.parse(raw);
+        const mode = settings.continuous_improvement?.companion_preference;
+        if (mode === "companions-first" || mode === "strict-companions")
+            return mode;
+        return "ci-first";
+    }
+    catch {
+        return "ci-first";
+    }
+}
+function isCompanionInstalled(home, plugin) {
+    try {
+        return existsSync(join(home, ".claude", "plugins", plugin));
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeSkill(skill) {
+    return skill.startsWith("ci:") ? skill.slice(3) : skill;
+}
+function resolveHome() {
+    return process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+}
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (root)
+            return root;
+    }
+    catch {
+        // not in a git repo
+    }
+    return "global";
+}
+function telemetryPath(home) {
+    const hash = createHash("sha256")
+        .update(resolveProjectRoot())
+        .digest("hex")
+        .slice(0, 12);
+    return join(home, ".claude", "instincts", hash, "companion-preference.jsonl");
+}
+/**
+ * Append one JSONL line per hook decision. Wrapped to fail open: any write
+ * error (read-only dir, disk full, race on mkdir) is swallowed and the hook
+ * decision proceeds. Telemetry must never block tool calls.
+ */
+function writeTelemetry(home, event) {
+    try {
+        const path = telemetryPath(home);
+        const dir = join(path, "..");
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        appendFileSync(path, `${JSON.stringify(event)}\n`);
+    }
+    catch {
+        // fail-open — telemetry failure never changes the decision
+    }
+}
+function main() {
+    const raw = readStdin();
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        emitAndExit({ decision: "allow" });
+    }
+    if (payload.tool_name !== "Skill") {
+        emitAndExit({ decision: "allow" });
+    }
+    const skill = payload.tool_input?.skill;
+    if (typeof skill !== "string" || skill.length === 0) {
+        emitAndExit({ decision: "allow" });
+    }
+    const normalized = normalizeSkill(skill);
+    const override = OVERRIDES[normalized];
+    if (!override) {
+        emitAndExit({ decision: "allow" });
+    }
+    const home = resolveHome();
+    const mode = readMode(home);
+    const installed = isCompanionInstalled(home, override.plugin);
+    const baseEvent = {
+        ts: new Date().toISOString(),
+        hook: "companion-preference",
+        ci_skill: normalized,
+        companion: override.companion,
+        plugin: override.plugin,
+        companion_installed: installed,
+    };
+    if (mode === "ci-first") {
+        // Shadow row: what companions-first would have done. This is the data
+        // set that earns a future default-flip decision.
+        writeTelemetry(home, { ...baseEvent, mode, action: "observation" });
+        emitAndExit({ decision: "allow" });
+    }
+    if (mode === "companions-first") {
+        process.stderr.write(`[continuous-improvement] companion_preference=companions-first → prefer \`${override.companion}\` over \`ci:${normalized}\`.\n`);
+        writeTelemetry(home, { ...baseEvent, mode, action: "advisory" });
+        emitAndExit({ decision: "allow" });
+    }
+    // strict-companions: always block; reason depends on install state.
+    if (installed) {
+        writeTelemetry(home, { ...baseEvent, mode, action: "block" });
+        emitAndExit({
+            decision: "block",
+            reason: `companion_preference=strict-companions: route to \`${override.companion}\` instead of \`ci:${normalized}\`. The CI fallback is suppressed by your setting.`,
+        });
+    }
+    writeTelemetry(home, { ...baseEvent, mode, action: "block-not-installed" });
+    emitAndExit({
+        decision: "block",
+        reason: `companion_preference=strict-companions: companion plugin \`${override.plugin}\` is not installed. Install with \`/plugin install ${override.plugin}@continuous-improvement\` or relax the setting to \`companions-first\` or \`ci-first\` in ~/.claude/settings.json.`,
+    });
+}
+main();

package/plugins/continuous-improvement/hooks/gateguard.mjs

@@ -9,8 +9,10 @@
  * Three-stage gate per skills/gateguard.md:
  * - DENY  : first mutating tool call per file, with fact-list reason
  * - FORCE : agent presents facts (model-side; out of band)
- * - ALLOW : retry once `_gateguard_facts_presented: true` is set or the
- *           per-file marker is recorded in session state
+ * - ALLOW : retry once the per-file marker is recorded in session state
+ *           (harness-portable, written out of band via Bash), or
+ *           `_gateguard_facts_presented: true` is set where the harness
+ *           forwards unknown tool params
  *
  * Read-only and exploratory tools (Read, Grep, Glob, routine Bash) bypass
  * unconditionally. Destructive Bash gates EVERY call, not just first.
@@ -18,12 +20,15 @@
  * V1 honest limitations (see src/lib/gateguard-state.mts header):
  *   honor-system flag, state-file deletion, parallel-hook race.
  *
- * MultiEdit handling (V1): gates on edits[0].file_path only. Per-file
- * batching is not implemented — TODO: extend to gate every entry in
- * edits[]. Tracked in issue #106 acceptance criteria item 5.
+ * MultiEdit handling gates every edited file individually. The hook blocks
+ * unless all edited paths are already cleared, or the agent presents facts
+ * for the call and the hook records clearance for each edited path.
+ * Block reasons now name the whole batch instead of just the first uncleared
+ * path.
  */
 import { readFileSync } from "node:fs";
-import { isCapReached, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
+import { join } from "node:path";
+import { MAX_CLEARED_FILES, canonicalizeFileKey, isCapReached, isFileCleared, loadState, markFileCleared, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
 const TOOL_ROUTE = {
     Read: "allow",
     Grep: "allow",
@@ -71,30 +76,54 @@ function classifyTool(toolName, toolInput) {
     }
     return "allow";
 }
-function extractFilePath(toolInput) {
+function extractFilePaths(toolInput) {
     if (typeof toolInput.file_path === "string")
-        return toolInput.file_path;
-    // MultiEdit V1: first edit's file_path is the canonical key.
+        return [toolInput.file_path];
     if (Array.isArray(toolInput.edits) && toolInput.edits.length > 0) {
-        const first = toolInput.edits[0];
-        if (first && typeof first.file_path === "string")
-            return first.file_path;
+        return toolInput.edits
+            .map((edit) => (edit && typeof edit.file_path === "string" ? edit.file_path : ""))
+            .filter((filePath) => filePath !== "");
     }
     if (typeof toolInput.command === "string")
-        return toolInput.command;
-    return "";
+        return [toolInput.command];
+    return [];
 }
-function buildMutatingFileReason(toolName, filePath) {
+// The call site only reads this inside the block branch, where at least one
+// path is uncleared; an all-cleared batch returns "" and is never consumed.
+function firstUnclearedFilePath(toolInput, state) {
+    return extractFilePaths(toolInput).find((path) => !isFileCleared(state, path)) ?? "";
+}
+function countDistinctNewFilePaths(filePaths, state) {
+    return new Set(filePaths.filter((path) => !isFileCleared(state, path)).map((path) => canonicalizeFileKey(path))).size;
+}
+function formatFileTarget(filePaths) {
+    const nonEmpty = filePaths.filter((path) => path !== "");
+    if (nonEmpty.length === 0)
+        return "<unknown>";
+    if (nonEmpty.length === 1)
+        return nonEmpty[0];
+    return `${nonEmpty.length} files (${nonEmpty.join(", ")})`;
+}
+function buildMutatingFileReason(toolName, filePaths, stateFilePath) {
+    const target = formatFileTarget(filePaths);
+    const pathList = filePaths.filter((p) => p !== "");
+    const jsonArray = (pathList.length > 0 ? pathList : [target]).map((p) => JSON.stringify(p)).join(", ");
+    const cliArgs = (pathList.length > 0 ? pathList : [target]).map((p) => JSON.stringify(p)).join(" ");
     return [
-        `Before ${toolName === "Write" ? "creating" : "editing"} ${filePath || "<unknown>"}, present these facts:`,
+        `Before ${toolName === "Write" ? "creating" : "editing"} ${target}, present these facts:`,
         "",
         "  1. List ALL files that import/require this file (use Grep)",
         "  2. List the public functions/classes affected by this change",
         "  3. If this file reads/writes data files, show field names, structure, and date format",
         "  4. Quote the user's current instruction verbatim",
         "",
-        "After presenting the facts, retry with `_gateguard_facts_presented: true` in tool_input,",
-        "or with the same file_path after a previous clearance has been recorded for this session.",
+        "Then clear the gate and retry the same call. Any one of:",
+        `  A. MCP tool:  ci_gateguard_clear  {file_paths: [${jsonArray}]}`,
+        `  B. CLI (Bash, never gated): node "\${CLAUDE_PLUGIN_ROOT}/bin/gateguard-clear.mjs" ${cliArgs}`,
+        `  C. Manual: append each path to "cleared_files" in ${stateFilePath} via a non-destructive Bash write.`,
+        "  Clearance matches regardless of drive-letter case or path separator.",
+        "  (On harnesses that forward unknown tool params you may instead retry with",
+        "  `_gateguard_facts_presented: true`; Claude Code's strict schema rejects that, so use A/B/C.)",
     ].join("\n");
 }
 function buildDestructiveBashReason(command) {
@@ -110,7 +139,7 @@ function buildDestructiveBashReason(command) {
 }
 function buildCapReachedReason() {
     return [
-        "Gateguard session clearance cap reached (50 distinct files).",
+        `Gateguard session clearance cap reached (${MAX_CLEARED_FILES} distinct files).`,
         "Start a new Claude Code session to reset the gate. The cap exists to bound",
         "stuck-loop or rogue-agent clearance from compounding within a single session.",
     ].join("\n");
@@ -150,22 +179,28 @@ function main() {
     }
     // mutating-file
     const sessionDir = resolveSessionDir();
+    const stateFilePath = join(sessionDir, "gateguard-session.json");
     const state = loadState(sessionDir);
-    const filePath = extractFilePath(toolInput);
+    const filePaths = extractFilePaths(toolInput);
+    const filePath = firstUnclearedFilePath(toolInput, state);
     const factsFlagged = toolInput._gateguard_facts_presented === true;
-    const alreadyCleared = filePath !== "" && filePath in state.cleared_files;
+    const alreadyCleared = filePaths.length > 0 && filePaths.every((path) => isFileCleared(state, path));
+    const newFileCount = countDistinctNewFilePaths(filePaths, state);
     if (!factsFlagged && !alreadyCleared) {
-        emit({ decision: "block", reason: buildMutatingFileReason(toolName, filePath) });
+        emit({ decision: "block", reason: buildMutatingFileReason(toolName, filePaths.length > 0 ? filePaths : [filePath], stateFilePath) });
         return;
     }
     if (factsFlagged && !alreadyCleared) {
-        if (isCapReached(state)) {
+        if (isCapReached(state) || Object.keys(state.cleared_files).length + newFileCount > MAX_CLEARED_FILES) {
             emit({ decision: "block", reason: buildCapReachedReason() });
             return;
         }
-        if (filePath !== "") {
-            saveState(sessionDir, markFileCleared(state, filePath));
+        let nextState = state;
+        for (const path of filePaths) {
+            nextState = markFileCleared(nextState, path);
         }
+        if (filePaths.length > 0)
+            saveState(sessionDir, nextState);
     }
     emit({ decision: "allow" });
 }