continuous-improvement 3.9.2 → 3.12.3

package/instinct-packs/react.json

@@ -1,58 +1,58 @@
-[
-  {
-    "id": "react-check-existing-components",
-    "trigger": "when creating a new React component",
-    "body": "Search the codebase for existing components that solve the same problem before creating new ones. Check shared/, components/, and ui/ directories.",
-    "confidence": 0.65,
-    "domain": "workflow"
-  },
-  {
-    "id": "react-prefer-server-components",
-    "trigger": "when creating components in Next.js App Router",
-    "body": "Default to Server Components. Only add 'use client' when the component needs useState, useEffect, event handlers, or browser APIs.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-key-prop-lists",
-    "trigger": "when rendering lists with .map()",
-    "body": "Always use a stable, unique key prop. Never use array index as key unless the list is static and never reordered.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-effect-cleanup",
-    "trigger": "when writing useEffect with subscriptions or timers",
-    "body": "Always return a cleanup function from useEffect when setting up subscriptions, event listeners, or timers to prevent memory leaks.",
-    "confidence": 0.7,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-memo-expensive",
-    "trigger": "when a component re-renders with expensive calculations",
-    "body": "Use useMemo for expensive computations and React.memo for components that receive the same props frequently. Don't memo everything — only what's measurably slow.",
-    "confidence": 0.6,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-form-validation",
-    "trigger": "when building forms",
-    "body": "Check if react-hook-form or zod is already in the project before building custom form validation. Prefer library solutions over hand-rolled validation.",
-    "confidence": 0.65,
-    "domain": "tooling"
-  },
-  {
-    "id": "react-error-boundary",
-    "trigger": "when adding a new page or route",
-    "body": "Ensure error boundaries exist around new pages/routes. In Next.js App Router, add error.tsx. In other React apps, wrap with ErrorBoundary component.",
-    "confidence": 0.6,
-    "domain": "patterns"
-  },
-  {
-    "id": "react-test-user-behavior",
-    "trigger": "when writing React component tests",
-    "body": "Test user behavior, not implementation details. Use @testing-library/react. Query by role, label, or text — not by class name or test ID.",
-    "confidence": 0.65,
-    "domain": "testing"
-  }
-]
+[
+  {
+    "id": "react-check-existing-components",
+    "trigger": "when creating a new React component",
+    "body": "Search the codebase for existing components that solve the same problem before creating new ones. Check shared/, components/, and ui/ directories.",
+    "confidence": 0.65,
+    "domain": "workflow"
+  },
+  {
+    "id": "react-prefer-server-components",
+    "trigger": "when creating components in Next.js App Router",
+    "body": "Default to Server Components. Only add 'use client' when the component needs useState, useEffect, event handlers, or browser APIs.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-key-prop-lists",
+    "trigger": "when rendering lists with .map()",
+    "body": "Always use a stable, unique key prop. Never use array index as key unless the list is static and never reordered.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-effect-cleanup",
+    "trigger": "when writing useEffect with subscriptions or timers",
+    "body": "Always return a cleanup function from useEffect when setting up subscriptions, event listeners, or timers to prevent memory leaks.",
+    "confidence": 0.7,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-memo-expensive",
+    "trigger": "when a component re-renders with expensive calculations",
+    "body": "Use useMemo for expensive computations and React.memo for components that receive the same props frequently. Don't memo everything — only what's measurably slow.",
+    "confidence": 0.6,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-form-validation",
+    "trigger": "when building forms",
+    "body": "Check if react-hook-form or zod is already in the project before building custom form validation. Prefer library solutions over hand-rolled validation.",
+    "confidence": 0.65,
+    "domain": "tooling"
+  },
+  {
+    "id": "react-error-boundary",
+    "trigger": "when adding a new page or route",
+    "body": "Ensure error boundaries exist around new pages/routes. In Next.js App Router, add error.tsx. In other React apps, wrap with ErrorBoundary component.",
+    "confidence": 0.6,
+    "domain": "patterns"
+  },
+  {
+    "id": "react-test-user-behavior",
+    "trigger": "when writing React component tests",
+    "body": "Test user behavior, not implementation details. Use @testing-library/react. Query by role, label, or text — not by class name or test ID.",
+    "confidence": 0.65,
+    "domain": "testing"
+  }
+]

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 };
+}

package/lib/goal-state.mjs

@@ -0,0 +1,285 @@
+// goal-state.mts — Pure goal-drift scorer for the Clear Goal discipline.
+//
+// No I/O. Turns a task_plan.md body + a list of recent observation rows into a
+// DriftReport that says whether recent tool activity still relates to the
+// stated goal. The MCP tool ci_goal_check (src/bin/mcp-server.mts) wires the
+// file reads around these functions; keeping the logic pure lets the unit
+// tests cover the scoring edges without touching the filesystem.
+//
+// Goal source: a markdown plan with a `## Goal` section (seeded by ci_plan_init).
+// Two optional sections sharpen the signal:
+//   ## Goal Keywords   — comma/newline list; overrides auto-extraction
+//   ## Goal Scope       — `paths:` and `forbidden:` glob lists
+// When ## Goal Keywords is absent, keywords are auto-extracted from the prose.
+const STOPWORDS = new Set([
+    "the", "and", "for", "with", "that", "this", "from", "into", "your", "will",
+    "should", "must", "have", "has", "are", "was", "were", "but", "not", "all",
+    "any", "can", "use", "using", "used", "via", "per", "out", "its", "their",
+    "them", "then", "than", "when", "what", "which", "who", "how", "why", "where",
+    "make", "made", "adds", "new", "get", "got", "set", "also", "only", "each",
+    "task", "goal", "plan", "work", "working", "build", "building", "code",
+]);
+// 4 suits Latin/Cyrillic/Thai prose (Thai combining marks are now kept; see
+// extractKeywordsFromProse regex), but it silently drops most Korean words
+// (typically 2 chars). A script-aware floor for Korean is a logged follow-up
+// (see CLAUDE.md Deferred).
+const KEYWORD_MIN_LENGTH = 4;
+const KEYWORD_CAP = 20;
+const DEFAULT_WINDOW = 30;
+const DEFAULT_THRESHOLD = 0.3;
+const MAX_MISMATCHES = 5;
+/**
+ * Extract the body of a `## Heading` section. Stops at the next heading of any
+ * level. Heading match is case-insensitive on the trimmed text. Returns "" when
+ * the section is absent or empty.
+ */
+export function getSection(markdown, heading) {
+    const lines = markdown.split(/\r?\n/);
+    const out = [];
+    let inSection = false;
+    const wanted = heading.trim().toLowerCase();
+    for (const line of lines) {
+        if (/^#{1,6}\s/.test(line)) {
+            if (inSection)
+                break;
+            inSection = line.replace(/^#{1,6}\s+/, "").trim().toLowerCase() === wanted;
+            continue;
+        }
+        if (inSection)
+            out.push(line);
+    }
+    return out.join("\n").trim();
+}
+/**
+ * Tokenize prose into goal keywords: lowercase, split on any non-letter /
+ * non-number / non-mark (Unicode-aware, so accented Latin / Cyrillic / CJK /
+ * Thai survive), drop stopwords, pure-digit tokens, and tokens shorter than
+ * KEYWORD_MIN_LENGTH. Deduped, capped at KEYWORD_CAP.
+ */
+export function extractKeywordsFromProse(prose) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of prose.toLowerCase().split(/[^\p{L}\p{N}\p{M}]+/u)) {
+        const word = raw.trim();
+        if (word.length < KEYWORD_MIN_LENGTH)
+            continue;
+        if (/^\p{N}+$/u.test(word))
+            continue;
+        if (STOPWORDS.has(word))
+            continue;
+        if (seen.has(word))
+            continue;
+        seen.add(word);
+        out.push(word);
+        if (out.length >= KEYWORD_CAP)
+            break;
+    }
+    return out;
+}
+function parseKeywordList(body) {
+    const seen = new Set();
+    const out = [];
+    for (const token of body.split(/[,\n]/)) {
+        const word = token.replace(/^[-*\s]+/, "").trim().toLowerCase();
+        if (!word || seen.has(word))
+            continue;
+        seen.add(word);
+        out.push(word);
+    }
+    return out;
+}
+function parseScopeField(scopeBody, field) {
+    for (const line of scopeBody.split(/\r?\n/)) {
+        const match = line.match(/^\s*[-*]?\s*([A-Za-z_]+)\s*:\s*(.+)$/);
+        if (match && match[1].toLowerCase() === field) {
+            return match[2]
+                .split(",")
+                .map((glob) => glob.trim())
+                .filter((glob) => glob.length > 0);
+        }
+    }
+    return [];
+}
+/**
+ * Parse a plan markdown into a GoalSpec. Returns null when there is no `## Goal`
+ * section (the scorer needs a goal to score against).
+ */
+export function parseGoalFromPlan(planMarkdown) {
+    const prose = getSection(planMarkdown, "Goal");
+    if (!prose)
+        return null;
+    const keywordsSection = getSection(planMarkdown, "Goal Keywords");
+    const scopeSection = getSection(planMarkdown, "Goal Scope");
+    const parsedKeywords = keywordsSection ? parseKeywordList(keywordsSection) : [];
+    // An empty/malformed Goal Keywords section (blank bullets, commas-only) must
+    // degrade to prose extraction, exactly like an absent section — otherwise the
+    // scorer runs with zero keywords and reports all on-goal work as drift.
+    const keywords = parsedKeywords.length > 0 ? parsedKeywords : extractKeywordsFromProse(prose);
+    return {
+        prose,
+        keywords,
+        paths: scopeSection ? parseScopeField(scopeSection, "paths") : [],
+        forbidden: scopeSection ? parseScopeField(scopeSection, "forbidden") : [],
+    };
+}
+function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i += 1) {
+        const char = glob[i];
+        if (char === "*") {
+            if (glob[i + 1] === "*") {
+                re += ".*";
+                i += 1;
+                if (glob[i + 1] === "/")
+                    i += 1;
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if ("\\^$.|?+()[]{}".includes(char)) {
+            re += `\\${char}`;
+        }
+        else {
+            re += char;
+        }
+    }
+    return new RegExp(`^${re}$`);
+}
+/**
+ * Whether a (possibly absolute) path matches a relative glob. Tries the full
+ * normalized path and every `/`-boundary suffix, so `src/auth/**` matches both
+ * `src/auth/x.ts` and `/home/me/repo/src/auth/x.ts`.
+ */
+export function pathMatchesGlob(rawPath, glob) {
+    const path = rawPath.replace(/\\/g, "/");
+    const re = globToRegExp(glob);
+    if (re.test(path))
+        return true;
+    const parts = path.split("/");
+    for (let i = 1; i < parts.length; i += 1) {
+        if (re.test(parts.slice(i).join("/")))
+            return true;
+    }
+    return false;
+}
+/**
+ * Score the most recent `window` observations against the goal. An observation
+ * "matches" when a goal keyword appears in its tool name / input / output, or
+ * its input path falls under a `## Goal Scope` paths glob. An input under a
+ * `forbidden` glob is a hard drift signal regardless of keywords.
+ */
+export function scoreObservations(observations, goal, opts = {}) {
+    // Reject an explicitly-provided out-of-range window instead of silently
+    // coercing it to the default — an operator typo (window=0, -5, 2.5) must not
+    // read as "unset". An absent window legitimately means "use the default".
+    if (opts.window !== undefined && (!Number.isInteger(opts.window) || opts.window <= 0)) {
+        throw new RangeError(`window must be a positive integer; got ${opts.window}. Omit it to use the default of ${DEFAULT_WINDOW}.`);
+    }
+    const window = opts.window ?? DEFAULT_WINDOW;
+    const threshold = typeof opts.threshold === "number" && Number.isFinite(opts.threshold)
+        ? opts.threshold
+        : DEFAULT_THRESHOLD;
+    const recent = observations.slice(-window);
+    const total = recent.length;
+    if (total === 0) {
+        return {
+            status: "no-data",
+            score: 0,
+            threshold,
+            matching: 0,
+            forbidden: 0,
+            total: 0,
+            goalKeywords: goal.keywords,
+            topMismatches: [],
+            reason: "No observations in the window yet.",
+        };
+    }
+    const keywords = goal.keywords.map((kw) => kw.toLowerCase()).filter((kw) => kw.length > 0);
+    let matching = 0;
+    let forbidden = 0;
+    const mismatches = [];
+    for (const obs of recent) {
+        const input = (obs.input_summary ?? "").toString();
+        const output = (obs.output_summary ?? "").toString();
+        const tool = (obs.tool ?? "").toString();
+        const haystack = `${tool}\n${input}\n${output}`.toLowerCase();
+        const record = { ts: (obs.ts ?? "").toString(), tool, summary: input || output };
+        const isForbidden = goal.forbidden.length > 0 &&
+            input.length > 0 &&
+            goal.forbidden.some((glob) => pathMatchesGlob(input, glob));
+        if (isForbidden) {
+            forbidden += 1;
+            mismatches.push(record);
+            continue;
+        }
+        const keywordHit = keywords.some((kw) => haystack.includes(kw));
+        const pathHit = goal.paths.length > 0 &&
+            input.length > 0 &&
+            goal.paths.some((glob) => pathMatchesGlob(input, glob));
+        if (keywordHit || pathHit) {
+            matching += 1;
+        }
+        else {
+            mismatches.push(record);
+        }
+    }
+    const score = matching / total;
+    let status;
+    let reason;
+    if (forbidden > 0) {
+        status = "drift";
+        reason = `${forbidden} of ${total} recent observations touched forbidden paths.`;
+    }
+    else if (score >= threshold) {
+        status = "on-goal";
+        reason = `${matching}/${total} recent observations relate to the goal (threshold ${threshold}).`;
+    }
+    else {
+        status = "drift";
+        reason = `Only ${matching}/${total} recent observations relate to the goal (threshold ${threshold}).`;
+    }
+    return {
+        status,
+        score,
+        threshold,
+        matching,
+        forbidden,
+        total,
+        goalKeywords: goal.keywords,
+        topMismatches: mismatches.slice(-MAX_MISMATCHES).reverse(),
+        reason,
+    };
+}
+/**
+ * Render a DriftReport as a markdown block for the MCP tool output. Pure
+ * string -> string so the formatting is unit-testable.
+ */
+export function formatDriftReport(report) {
+    const label = report.status === "on-goal"
+        ? "ON GOAL"
+        : report.status === "drift"
+            ? "DRIFT"
+            : "NO DATA";
+    const pct = Math.round(report.score * 100);
+    const lines = [
+        `**Status:** ${label}`,
+        `**Score:** ${pct}% (${report.matching}/${report.total} matched, threshold ${Math.round(report.threshold * 100)}%)`,
+        `**Reason:** ${report.reason}`,
+    ];
+    if (report.goalKeywords.length > 0) {
+        lines.push(`**Goal keywords:** ${report.goalKeywords.join(", ")}`);
+    }
+    if (report.topMismatches.length > 0) {
+        lines.push("", `**Top off-goal activity (most recent ${report.topMismatches.length}):**`);
+        for (const mismatch of report.topMismatches) {
+            const stamp = mismatch.ts ? `[${mismatch.ts}] ` : "";
+            const summary = mismatch.summary.length > 100 ? `${mismatch.summary.slice(0, 100)}…` : mismatch.summary;
+            lines.push(`- ${stamp}${mismatch.tool || "(tool?)"} — ${summary || "(no summary)"}`);
+        }
+    }
+    if (report.status === "drift") {
+        lines.push("", "_Drift detected. Either steer back to the goal, or update the `## Goal` section in your plan if the goal has legitimately changed._");
+    }
+    return lines.join("\n");
+}