continuous-improvement 3.9.2 → 3.11.0

package/plugins/continuous-improvement/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/plugins/continuous-improvement/lib/gateguard-state.mjs

@@ -0,0 +1,137 @@
+/**
+ * Gateguard per-session state.
+ *
+ * State file: <sessionDir>/gateguard-session.json. sessionDir resolves to
+ * GATEGUARD_SESSION_DIR (env override, used by tests) or
+ * ~/.claude/instincts/<projectHash>/ in production.
+ *
+ * V1 limitations (documented for honesty, not mitigated in code):
+ * - Honor system: clearance is granted whenever the agent sets
+ *   `_gateguard_facts_presented: true` in tool_input or has a prior per-file
+ *   marker. The hook cannot verify that real investigation occurred.
+ * - State-file deletion: rm'ing the state file resets every gate in the
+ *   session. Defensible because the session itself is the trust boundary;
+ *   the cap below limits cumulative damage.
+ * - Concurrency: two parallel hook invocations can race the read+write.
+ *   Acceptable trade-off vs OS-specific atomic-rename complexity on Windows.
+ * - Cap: MAX_CLEARED_FILES caps the number of distinct files a single
+ *   session can clear, bounding stuck-loop / rogue-agent damage.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const MAX_CLEARED_FILES = 50;
+export function resolveSessionDir() {
+    const fromEnv = process.env.GATEGUARD_SESSION_DIR;
+    if (fromEnv)
+        return fromEnv;
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    const projectRoot = resolveProjectRoot();
+    const projectHash = createHash("sha256").update(canonicalizeProjectRoot(projectRoot)).digest("hex").slice(0, 12);
+    return join(home, ".claude", "instincts", projectHash);
+}
+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";
+}
+export function loadState(sessionDir) {
+    const path = join(sessionDir, "gateguard-session.json");
+    if (!existsSync(path)) {
+        return { created_at: new Date().toISOString(), cleared_files: {} };
+    }
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            created_at: parsed.created_at ?? new Date().toISOString(),
+            cleared_files: parsed.cleared_files ?? {},
+        };
+    }
+    catch {
+        return { created_at: new Date().toISOString(), cleared_files: {} };
+    }
+}
+export function saveState(sessionDir, state) {
+    if (!existsSync(sessionDir))
+        mkdirSync(sessionDir, { recursive: true });
+    writeFileSync(join(sessionDir, "gateguard-session.json"), `${JSON.stringify(state, null, 2)}\n`);
+}
+export function isCapReached(state) {
+    return Object.keys(state.cleared_files).length >= MAX_CLEARED_FILES;
+}
+export function markFileCleared(state, filePath) {
+    return {
+        ...state,
+        cleared_files: {
+            ...state.cleared_files,
+            [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/plugins/continuous-improvement/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 };
+}