continuous-improvement 3.9.2 → 3.11.0

package/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/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" });
 }

package/hooks/goal-drift-stop.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// goal-drift-stop.mts — Stop hook that scores the turn's activity against the
+// stated goal (task_plan.md ## Goal) and, when the session has DRIFTed on a
+// substantive wrap-up, warns or (opt-in) blocks the close. This is the runtime
+// arm of goal-monitor: it auto-fires the drift check at the Stop phase boundary
+// instead of waiting for someone to run /goal-check.
+//
+// Mode via CLAUDE_GOAL_DRIFT_GATE: "warn" (default) | "block" | "off".
+//   - warn  : print a one-line drift notice to stderr; never blocks.
+//   - block : emit {"decision":"block","reason":...} to re-prompt.
+//   - off   : no-op.
+// The drift status is persisted to
+// ~/.claude/instincts/<project-hash>/goal-drift-state.json every turn.
+//
+// Project-hash resolution is byte-identical to bin/observe.mts so this hook
+// reads the SAME observations.jsonl the observer writes. Fail-open by
+// construction: any error / missing goal / unreadable observations exits 0 and
+// never blocks. No network. 5s hook budget.
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { evaluateGoalDrift } from "../lib/goal-drift-gate.mjs";
+import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
+function readStdinSync() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveMode() {
+    const raw = (process.env.CLAUDE_GOAL_DRIFT_GATE ?? "warn").trim().toLowerCase();
+    return raw === "block" || raw === "off" ? raw : "warn";
+}
+// Mirrors bin/observe.mts:resolveProjectRoot — the same basis the observer uses
+// to bucket observations.jsonl, so the hash here resolves to the same file.
+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 a git repo
+    }
+    return "global";
+}
+function projectHash(root) {
+    return createHash("sha256").update(root).digest("hex").slice(0, 12);
+}
+function readGoalMarkdown(projectRoot, instinctsProjectDir) {
+    const candidates = [join(projectRoot, "task_plan.md"), join(instinctsProjectDir, "goal.md")];
+    for (const file of candidates) {
+        try {
+            if (existsSync(file))
+                return readFileSync(file, "utf8");
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return "";
+}
+function readObservations(instinctsProjectDir) {
+    const file = join(instinctsProjectDir, "observations.jsonl");
+    try {
+        if (!existsSync(file))
+            return [];
+        const lines = readFileSync(file, "utf8")
+            .split("\n")
+            .filter((line) => line.trim().length > 0);
+        const out = [];
+        for (const line of lines.slice(-100)) {
+            const row = safeJsonParse(line);
+            if (!row)
+                continue;
+            out.push({
+                ts: typeof row.ts === "string" ? row.ts : "",
+                tool: typeof row.tool === "string" ? row.tool : "",
+                input_summary: typeof row.input_summary === "string" ? row.input_summary : "",
+                output_summary: typeof row.output_summary === "string" ? row.output_summary : "",
+            });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function lastAssistantTextLength(transcriptPath) {
+    try {
+        const lines = readFileSync(transcriptPath, "utf8").split(/\r?\n/);
+        for (let i = lines.length - 1; i >= 0; i -= 1) {
+            const line = lines[i].trim();
+            if (!line)
+                continue;
+            const obj = safeJsonParse(line);
+            if (!obj || obj.type !== "assistant")
+                continue;
+            const blocks = obj.message?.content;
+            if (!Array.isArray(blocks))
+                continue;
+            const text = blocks
+                .filter((b) => b &&
+                typeof b === "object" &&
+                b.type === "text" &&
+                typeof b.text === "string")
+                .map((b) => b.text)
+                .join("\n");
+            if (text.length === 0)
+                continue;
+            return text.length;
+        }
+    }
+    catch {
+        // fall through to 0
+    }
+    return 0;
+}
+function persistState(instinctsProjectDir, state) {
+    try {
+        mkdirSync(instinctsProjectDir, { recursive: true });
+        writeFileSync(join(instinctsProjectDir, "goal-drift-state.json"), JSON.stringify({ ts: new Date().toISOString(), ...state }) + "\n", "utf8");
+    }
+    catch {
+        // state persistence is best-effort; never throw
+    }
+}
+function main() {
+    const mode = resolveMode();
+    if (mode === "off")
+        return;
+    const stdin = readStdinSync();
+    if (!stdin)
+        return;
+    const payload = safeJsonParse(stdin);
+    if (!payload)
+        return;
+    const home = resolveHomeDir();
+    if (!home)
+        return;
+    const projectRoot = resolveProjectRoot();
+    const instinctsProjectDir = join(home, ".claude", "instincts", projectHash(projectRoot));
+    const goalMarkdown = readGoalMarkdown(projectRoot, instinctsProjectDir);
+    const observations = readObservations(instinctsProjectDir);
+    const textLength = payload.transcript_path && existsSync(payload.transcript_path)
+        ? lastAssistantTextLength(payload.transcript_path)
+        : 0;
+    const decision = evaluateGoalDrift({ goalMarkdown, observations, textLength, mode });
+    persistState(instinctsProjectDir, {
+        status: decision.status,
+        score: decision.score,
+        action: decision.action,
+    });
+    if (decision.action === "block") {
+        process.stdout.write(JSON.stringify({ decision: "block", reason: decision.reason }) + "\n");
+    }
+    else if (decision.action === "warn") {
+        process.stderr.write(`[continuous-improvement] goal-drift: ${decision.reason}\n`);
+    }
+}
+try {
+    main();
+}
+catch {
+    // fail open — never block the session due to a hook bug
+}

package/hooks/observe.sh

@@ -101,6 +101,20 @@ fi
 # ---------------------------------------------------------------------------
 # Compute project hash and name
 # ---------------------------------------------------------------------------
+# Canonicalize MSYS-mounted Windows paths (/d/Path) to native form (D:/Path)
+# so the bash fallback hashes to the same project bucket as the Node observer.
+# Without this, Git Bash on Windows produces /d/Ai/repo from `git rev-parse`
+# while Node's child_process produces D:/Ai/repo for the same physical path,
+# splitting telemetry between two SHA-256 buckets per project.
+# Pattern matches /<single-letter>/... only — Linux/macOS paths like /usr,
+# /home, /Users are unaffected.
+case "$PROJECT_ROOT" in
+  /[a-zA-Z]/*)
+    drive_letter="$(printf '%s' "$PROJECT_ROOT" | cut -c2 | tr '[:lower:]' '[:upper:]')"
+    PROJECT_ROOT="${drive_letter}:$(printf '%s' "$PROJECT_ROOT" | cut -c3-)"
+    ;;
+esac
+
 PROJECT_HASH="$(printf '%s' "$PROJECT_ROOT" | sha256sum | cut -c1-12)"
 PROJECT_NAME="$(basename "${PROJECT_ROOT%.git}")"
 
@@ -119,7 +133,7 @@ if [[ -f "$OBS_FILE" ]]; then
   LINE_COUNT="$(wc -l < "$OBS_FILE")"
   if (( LINE_COUNT >= 10000 )); then
     mv "$OBS_FILE" "${PROJECT_DIR}/observations.$(date -u +"%Y-%m-%d-%H%M%S").jsonl"
-    
+
     # Clean up old archives - keep only 10 most recent
     ls -t "${PROJECT_DIR}"/observations.*.jsonl 2>/dev/null | tail -n +11 | xargs -r rm -f
   fi