continuous-improvement 3.9.2 → 3.11.0

package/hooks/route-prompt.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * Runtime UserPromptSubmit prompt-router hook.
+ *
+ * Reads the user prompt, matches it against patterns in
+ * hooks/route-table.json, and emits a single `<system-reminder>` recommending
+ * the matched skill. When no row matches, the hook emits nothing — the prompt
+ * passes through untouched.
+ *
+ * Stdin  : JSON { prompt, session_id?, transcript_path?, cwd? }
+ * Stdout : JSON { hookSpecificOutput: { hookEventName: "UserPromptSubmit",
+ *                                       additionalContext: string } }
+ *          OR empty when there is no match.
+ * Exit   : 0 always — routing decisions live in stdout, never in exit code.
+ *
+ * Fail-open: any unexpected error reading stdin / parsing the route table /
+ * compiling a pattern → emit nothing and exit 0. The hook never blocks a
+ * prompt on its own bugs.
+ *
+ * Telemetry: each match appends one JSONL line to
+ * ~/.claude/instincts/<project-hash>/route-prompt.jsonl with the row index,
+ * skill, and pattern. Telemetry failures never change the decision.
+ *
+ * Route table schema (hooks/route-table.json):
+ *   {
+ *     "rows": [
+ *       { "pattern": "regex source", "flags": "i", "skill": "skill-name",
+ *         "reason": "one-line description" }
+ *     ]
+ *   }
+ * Rows are evaluated in order; first match wins.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+function readStdin() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+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, "route-prompt.jsonl");
+}
+function writeTelemetry(home, event) {
+    try {
+        const path = telemetryPath(home);
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        appendFileSync(path, `${JSON.stringify(event)}\n`);
+    }
+    catch {
+        // fail-open
+    }
+}
+function loadRouteTable() {
+    // Hook lives at <plugin-root>/hooks/route-prompt.mjs at runtime; the table
+    // sits next to it. import.meta.url gives the file:// URL of the compiled
+    // .mjs.
+    try {
+        const here = fileURLToPath(new URL(".", import.meta.url));
+        const tablePath = join(here, "route-table.json");
+        const raw = readFileSync(tablePath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!parsed || !Array.isArray(parsed.rows))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function findMatch(prompt, table) {
+    for (let i = 0; i < table.rows.length; i++) {
+        const row = table.rows[i];
+        if (!row || typeof row.pattern !== "string" || typeof row.skill !== "string") {
+            continue;
+        }
+        let rx;
+        try {
+            rx = new RegExp(row.pattern, row.flags ?? "");
+        }
+        catch {
+            continue;
+        }
+        if (rx.test(prompt)) {
+            return { row, index: i };
+        }
+    }
+    return null;
+}
+function buildContext(row) {
+    const reason = row.reason
+        ? `${row.reason}\nConsider invoking \`/${row.skill}\` now.`
+        : `Consider invoking \`/${row.skill}\` now.`;
+    return `<system-reminder>\nPrompt-router suggestion: ${reason}\n</system-reminder>`;
+}
+function emit(output) {
+    if (output !== null) {
+        process.stdout.write(`${JSON.stringify(output)}\n`);
+    }
+    process.exit(0);
+}
+function main() {
+    const raw = readStdin();
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        emit(null);
+        return;
+    }
+    const prompt = payload.prompt;
+    if (typeof prompt !== "string" || prompt.length === 0) {
+        emit(null);
+        return;
+    }
+    const table = loadRouteTable();
+    if (!table) {
+        emit(null);
+        return;
+    }
+    const match = findMatch(prompt, table);
+    const home = resolveHome();
+    if (!match) {
+        writeTelemetry(home, {
+            ts: new Date().toISOString(),
+            hook: "route-prompt",
+            matched: false,
+        });
+        emit(null);
+        return;
+    }
+    writeTelemetry(home, {
+        ts: new Date().toISOString(),
+        hook: "route-prompt",
+        matched: true,
+        row_index: match.index,
+        skill: match.row.skill,
+        pattern: match.row.pattern,
+    });
+    emit({
+        hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: buildContext(match.row),
+        },
+    });
+}
+main();

package/hooks/route-table.json

@@ -0,0 +1,35 @@
+{
+  "description": "Declarative prompt-router for the continuous-improvement UserPromptSubmit hook. Each row maps a regex (prompt-side trigger) to a skill the agent should consider invoking. First match wins; rows are evaluated in order. Edit this file to grow the routing table — no code change required.",
+  "rows": [
+    {
+      "pattern": "\\b(write|add|new)\\s+(a\\s+)?(failing\\s+)?test\\b|\\btdd\\b|\\bred[- ]green[- ]refactor\\b",
+      "flags": "i",
+      "skill": "tdd-workflow",
+      "reason": "Prompt mentions writing tests, TDD, or RED-GREEN-REFACTOR."
+    },
+    {
+      "pattern": "\\b(verify|verification|prove\\s+it\\s+works|smallest\\s+check|check\\s+it\\s+passes)\\b",
+      "flags": "i",
+      "skill": "verification-loop",
+      "reason": "Prompt asks for verification before declaring done."
+    },
+    {
+      "pattern": "\\b(plan|blueprint|design\\s+(the\\s+)?approach|step[- ]by[- ]step\\s+plan|roadmap)\\b",
+      "flags": "i",
+      "skill": "planning-with-files",
+      "reason": "Prompt asks for a plan, blueprint, or design before implementation."
+    },
+    {
+      "pattern": "\\b(security\\s+review|threat\\s+model|owasp|vulnerab|auth(entication|orization)\\s+check)\\b",
+      "flags": "i",
+      "skill": "security-review",
+      "reason": "Prompt touches security review, threat modeling, or auth surface."
+    },
+    {
+      "pattern": "\\b(code\\s+review|review\\s+(my|the|this)\\s+(code|pr|diff|patch)|critique\\s+(the|this)\\s+code)\\b",
+      "flags": "i",
+      "skill": "code-review",
+      "reason": "Prompt asks for a code review on existing changes."
+    }
+  ]
+}

package/hooks/three-section-close.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// three-section-close.mjs — Stop hook that requires every substantive
+// three-section-close.mts — Stop hook that requires every substantive
 // assistant reply to close with three named sections:
 //   "What has been done", "What is next", "Recommendation".
 //
@@ -19,163 +19,165 @@
 // Telemetry: best-effort JSONL line per gated invocation written to
 // ~/.claude/hook-telemetry/<project-hash>.jsonl. Never throws, never
 // blocks the response. No network. No transcript content recorded.
-
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { platform } from "node:os";
 import { dirname, join } from "node:path";
 import { performance } from "node:perf_hooks";
-
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
-
 const MIN_LENGTH_TO_GATE = 600;
-
 const REQUIRED_SECTIONS = [
-  {
-    heading: "What has been done",
-    hint: "concrete summary of changes/findings from this turn",
-    pattern: /^#+ +What has been done(?:\s|$)/m,
-  },
-  {
-    heading: "What is next",
-    hint: "minimum 5 specific, actionable bullets",
-    pattern: /^#+ +What is next(?:\s|$)/m,
-  },
-  {
-    heading: "Recommendation",
-    hint: "ranked descending by impact, or write \"no\" if there is no recommendation",
-    pattern: /^#+ +Recommendation(?:\s|$)/m,
-  },
+    {
+        heading: "What has been done",
+        hint: "concrete summary of changes/findings from this turn",
+        pattern: /^#+ +What has been done(?:\s|$)/m,
+    },
+    {
+        heading: "What is next",
+        hint: "minimum 5 specific, actionable bullets",
+        pattern: /^#+ +What is next(?:\s|$)/m,
+    },
+    {
+        heading: "Recommendation",
+        hint: "ranked descending by impact, or write \"no\" if there is no recommendation",
+        pattern: /^#+ +Recommendation(?:\s|$)/m,
+    },
 ];
-
 function readStdinSync() {
-  try {
-    return readFileSync(0, "utf8");
-  } catch {
-    return "";
-  }
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
 }
-
 function safeJsonParse(text) {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return null;
-  }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
 }
-
 function extractLastAssistantText(transcriptPath) {
-  const raw = readFileSync(transcriptPath, "utf8");
-  const lines = raw.split(/\r?\n/);
-  for (let i = lines.length - 1; i >= 0; i--) {
-    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 texts = blocks
-      .filter((b) => b && b.type === "text" && typeof b.text === "string")
-      .map((b) => b.text);
-    if (texts.length === 0) continue;
-    return texts.join("\n");
-  }
-  return null;
+    const raw = readFileSync(transcriptPath, "utf8");
+    const lines = raw.split(/\r?\n/);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        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 texts = blocks
+            .filter((b) => b &&
+            typeof b === "object" &&
+            b.type === "text" &&
+            typeof b.text === "string")
+            .map((b) => b.text);
+        if (texts.length === 0)
+            continue;
+        return texts.join("\n");
+    }
+    return null;
 }
-
 function emitBlock(missing) {
-  const bullets = missing
-    .map(
-      (s) =>
-        `- "## ${s.heading}" — ${s.hint}`,
-    )
-    .join("\n");
-  const reason =
-    `Your reply is missing the required 3-section close. Add these sections at the end of the reply with these exact headings:\n${bullets}`;
-  process.stdout.write(JSON.stringify({ decision: "block", reason }) + "\n");
+    const bullets = missing
+        .map((s) => `- "## ${s.heading}" — ${s.hint}`)
+        .join("\n");
+    const reason = `Your reply is missing the required 3-section close. Add these sections at the end of the reply with these exact headings:\n${bullets}`;
+    process.stdout.write(JSON.stringify({ decision: "block", reason }) + "\n");
 }
-
 function projectHashFor(transcriptPath) {
-  const dir = dirname(transcriptPath);
-  let normalized = dir.split("\\").join("/");
-  if (platform() === "win32") normalized = normalized.toLowerCase();
-  return createHash("sha256").update(normalized).digest("hex").slice(0, 12);
+    const dir = dirname(transcriptPath);
+    let normalized = dir.split("\\").join("/");
+    if (platform() === "win32")
+        normalized = normalized.toLowerCase();
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 12);
 }
-
 function recordTelemetry(entry, transcriptPath) {
-  try {
-    const home = resolveHomeDir();
-    if (!home) return;
-    const telemetryDir = join(home, ".claude", "hook-telemetry");
     try {
-      mkdirSync(telemetryDir, { recursive: true });
-    } catch {
-      return;
+        const home = resolveHomeDir();
+        if (!home)
+            return;
+        const telemetryDir = join(home, ".claude", "hook-telemetry");
+        try {
+            mkdirSync(telemetryDir, { recursive: true });
+        }
+        catch {
+            return;
+        }
+        const file = join(telemetryDir, `${projectHashFor(transcriptPath)}.jsonl`);
+        try {
+            appendFileSync(file, JSON.stringify(entry) + "\n", "utf8");
+        }
+        catch {
+            return;
+        }
     }
-    const file = join(telemetryDir, `${projectHashFor(transcriptPath)}.jsonl`);
-    try {
-      appendFileSync(file, JSON.stringify(entry) + "\n", "utf8");
-    } catch {
-      return;
+    catch {
+        // belt-and-suspenders: telemetry must never throw
     }
-  } catch {
-    // belt-and-suspenders: telemetry must never throw
-  }
 }
-
 function main() {
-  // Per-operator opt-out. When CLAUDE_THREE_SECTION_CLOSE_DISABLED=1, the hook
-  // short-circuits entirely: no enforcement, no telemetry. Public default is
-  // unchanged (rule still fires for everyone else). See feedback memory
-  // 2026-05-04 for rationale: an audit found 22,876 observations produced
-  // only 2 graduated instincts, so visible end-of-turn reflection earns its
-  // keep poorly enough that operators may want to run it as internal thinking.
-  if (process.env.CLAUDE_THREE_SECTION_CLOSE_DISABLED === "1") return;
-  const startedAt = performance.now();
-  const stdin = readStdinSync();
-  if (!stdin) return;
-
-  const payload = safeJsonParse(stdin);
-  if (!payload || typeof payload.transcript_path !== "string") return;
-  if (!existsSync(payload.transcript_path)) return;
-
-  let lastText;
-  try {
-    lastText = extractLastAssistantText(payload.transcript_path);
-  } catch {
-    return; // fail open on read error
-  }
-  if (!lastText) return;
-
-  const textLength = lastText.length;
-  let action;
-  let missing = [];
-
-  if (textLength < MIN_LENGTH_TO_GATE) {
-    action = "skip-short";
-  } else {
-    missing = REQUIRED_SECTIONS.filter((s) => !s.pattern.test(lastText));
-    if (missing.length === 0) {
-      action = "pass";
-    } else {
-      action = "block";
-      emitBlock(missing);
+    // Per-operator opt-out. When CLAUDE_THREE_SECTION_CLOSE_DISABLED=1, the hook
+    // short-circuits entirely: no enforcement, no telemetry. Public default is
+    // unchanged (rule still fires for everyone else). See feedback memory
+    // 2026-05-04 for rationale: an audit found 22,876 observations produced
+    // only 2 graduated instincts, so visible end-of-turn reflection earns its
+    // keep poorly enough that operators may want to run it as internal thinking.
+    if (process.env.CLAUDE_THREE_SECTION_CLOSE_DISABLED === "1")
+        return;
+    const startedAt = performance.now();
+    const stdin = readStdinSync();
+    if (!stdin)
+        return;
+    const payload = safeJsonParse(stdin);
+    if (!payload || typeof payload.transcript_path !== "string")
+        return;
+    if (!existsSync(payload.transcript_path))
+        return;
+    let lastText;
+    try {
+        lastText = extractLastAssistantText(payload.transcript_path);
+    }
+    catch {
+        return; // fail open on read error
     }
-  }
-
-  const entry = {
-    ts: new Date().toISOString(),
-    hook: "three-section-close",
-    action,
-    textLength,
-    missing: missing.map((s) => s.heading),
-    durationMs: Math.round((performance.now() - startedAt) * 1000) / 1000,
-  };
-  recordTelemetry(entry, payload.transcript_path);
+    if (!lastText)
+        return;
+    const textLength = lastText.length;
+    let action;
+    let missing = [];
+    if (textLength < MIN_LENGTH_TO_GATE) {
+        action = "skip-short";
+    }
+    else {
+        missing = REQUIRED_SECTIONS.filter((s) => !s.pattern.test(lastText));
+        if (missing.length === 0) {
+            action = "pass";
+        }
+        else {
+            action = "block";
+            emitBlock(missing);
+        }
+    }
+    const entry = {
+        ts: new Date().toISOString(),
+        hook: "three-section-close",
+        action,
+        textLength,
+        missing: missing.map((s) => s.heading),
+        durationMs: Math.round((performance.now() - startedAt) * 1000) / 1000,
+    };
+    recordTelemetry(entry, payload.transcript_path);
 }
-
 try {
-  main();
-} catch {
-  // fail open — never block the session due to a hook bug
+    main();
+}
+catch {
+    // fail open — never block the session due to a hook bug
 }

package/lib/gateguard-state.mjs

@@ -29,7 +29,7 @@ export function resolveSessionDir() {
         return fromEnv;
     const home = process.env.HOME || process.env.USERPROFILE || homedir();
     const projectRoot = resolveProjectRoot();
-    const projectHash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    const projectHash = createHash("sha256").update(canonicalizeProjectRoot(projectRoot)).digest("hex").slice(0, 12);
     return join(home, ".claude", "instincts", projectHash);
 }
 function resolveProjectRoot() {
@@ -79,7 +79,59 @@ export function markFileCleared(state, filePath) {
         ...state,
         cleared_files: {
             ...state.cleared_files,
-            [filePath]: { cleared_at: new Date().toISOString() },
+            [canonicalizeFileKey(filePath)]: { cleared_at: new Date().toISOString() },
         },
     };
 }
+// Canonicalize a path so the hook and any clearance helper agree regardless of
+// which process resolved it. Two processes can supply the same directory in
+// different forms — CLAUDE_PROJECT_DIR gives `d:/...` (lowercase drive) while
+// `git rev-parse --show-toplevel` gives `D:/...` (uppercase) — and tool inputs
+// vary by separator. Normalizing the drive-letter case and separators (only;
+// directory/file-name case is preserved) makes the hash and the per-file key
+// stable. Relative and POSIX paths have no drive letter or backslash, so they
+// pass through unchanged and existing relative-key state keeps matching.
+function canonicalizePath(p) {
+    let out = p.replace(/\\/g, "/");
+    if (/^[A-Za-z]:/.test(out)) {
+        out = out.charAt(0).toLowerCase() + out.slice(1);
+    }
+    while (out.length > 1 && out.endsWith("/")) {
+        out = out.slice(0, -1);
+    }
+    return out;
+}
+export function canonicalizeProjectRoot(p) {
+    return canonicalizePath(p);
+}
+export function canonicalizeFileKey(p) {
+    return canonicalizePath(p);
+}
+export function isFileCleared(state, filePath) {
+    return canonicalizeFileKey(filePath) in state.cleared_files;
+}
+// Shared clearance writer used by the MCP tool and the CLI. Loads, marks each
+// not-yet-cleared canonical key (respecting MAX_CLEARED_FILES), and saves once.
+// Idempotent across path forms; returns what it cleared and what it skipped for
+// the cap so callers can report partial results on a MultiEdit-sized batch.
+export function clearFiles(sessionDir, filePaths) {
+    const cleared = [];
+    const skippedForCap = [];
+    let state = loadState(sessionDir);
+    for (const filePath of filePaths) {
+        const key = canonicalizeFileKey(filePath);
+        if (key in state.cleared_files) {
+            continue; // already cleared — idempotent, no cap charge
+        }
+        if (Object.keys(state.cleared_files).length >= MAX_CLEARED_FILES) {
+            skippedForCap.push(filePath);
+            continue;
+        }
+        state = markFileCleared(state, filePath);
+        cleared.push(key);
+    }
+    if (cleared.length > 0) {
+        saveState(sessionDir, state);
+    }
+    return { cleared, skippedForCap };
+}

package/lib/goal-drift-gate.mjs

@@ -0,0 +1,50 @@
+// goal-drift-gate.mts — Pure decision core for the goal-drift Stop hook.
+//
+// No I/O. Given a goal-plan body, recent observations, the length of the last
+// assistant reply, and the operator's mode, decide whether the Stop hook should
+// allow / warn / block. The hook (src/hooks/goal-drift-stop.mts) wires the file
+// reads around this function; keeping it pure lets the unit tests cover every
+// branch without touching the filesystem.
+//
+// Fail-open by construction: any state that is not a confident DRIFT on a
+// substantive wrap-up returns "allow".
+import { parseGoalFromPlan, scoreObservations, } from "./goal-state.mjs";
+// Matches the three-section-close wrap-up threshold: a substantive Stop reply is
+// a completion report. This is the non-lexical "claims done" proxy — no keyword
+// matching, so it cannot false-fire on the word "done" in ordinary prose.
+const MIN_LENGTH_TO_GATE = 600;
+export function evaluateGoalDrift(input) {
+    const { goalMarkdown, observations, textLength, mode } = input;
+    if (mode === "off") {
+        return { action: "allow", status: "no-goal", score: 0, reason: "Goal-drift gate disabled (mode=off)." };
+    }
+    const goal = parseGoalFromPlan(goalMarkdown);
+    if (!goal) {
+        return {
+            action: "allow",
+            status: "no-goal",
+            score: 0,
+            reason: "No '## Goal' section found; nothing to gate against.",
+        };
+    }
+    const report = scoreObservations(observations, goal);
+    if (report.status === "no-data") {
+        return { action: "allow", status: "no-data", score: 0, reason: "Not enough recent observations to judge drift." };
+    }
+    if (report.status === "on-goal") {
+        return { action: "allow", status: "on-goal", score: report.score, reason: report.reason };
+    }
+    // report.status === "drift"
+    if (textLength < MIN_LENGTH_TO_GATE) {
+        return {
+            action: "allow",
+            status: "drift",
+            score: report.score,
+            reason: "Drift detected, but the reply is too short to be a wrap-up; not gating.",
+        };
+    }
+    const pct = Math.round(report.score * 100);
+    const reason = `Session has DRIFTed from the stated goal (${report.matching}/${report.total} recent actions on-goal, ${pct}%). ` +
+        "Re-check the work against the '## Goal' in task_plan.md — or update the goal if it has legitimately changed — before closing.";
+    return { action: mode === "block" ? "block" : "warn", status: "drift", score: report.score, reason };
+}