continuous-improvement 3.18.0 → 3.20.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "continuous-improvement",
       "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 27 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.18.0",
+      "version": "3.20.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/README.md

@@ -174,8 +174,10 @@ The framework has documented operator-level modes that change hook behavior with
 |---|---|---|
 | `CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` | `three-section-close.mjs` short-circuits before any enforcement or telemetry. Use when end-of-turn reflection should run as internal thinking rather than visible "What has been done / What is next / Recommendation" sections. Public default unchanged — the rule still fires for everyone else. | bash/zsh: `export CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_THREE_SECTION_CLOSE_DISABLED=1` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_THREE_SECTION_CLOSE_DISABLED','1','User')` (persistent). |
 | `CLAUDE_GOAL_DRIFT_GATE` | `goal-drift-stop.mjs` (a `Stop` hook) scores each turn's activity against the `## Goal` in `task_plan.md` and acts on drift. `warn` (default) prints a one-line stderr notice and never blocks; `block` re-prompts a substantive wrap-up that has drifted off-goal so the goal gates the close; `off` disables it. Reads the same observation feed as Mulahazah; fails open on any error. | bash/zsh: `export CLAUDE_GOAL_DRIFT_GATE=block` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_GOAL_DRIFT_GATE='block'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_GOAL_DRIFT_GATE','block','User')` (persistent). |
+| `CLAUDE_TYPECHECK_GATE` | `hooks/typecheck-stop.mjs` (a `Stop` hook) runs the project typecheck (the `typecheck` npm script, else a local `tsc --noEmit`) on changed TS files at turn end and feeds a failure back to the model. `off` (default) is a no-op — the global advisory `typecheck-changed.sh` stays the default layer; `warn` prints a one-line stderr notice; `block` re-prompts with the tsc output so a headless/autonomous `-p` loop fixes its own type errors before ending the turn. Skips non-TS repos and turns where no TS file changed; fails open on any error or timeout. | bash/zsh: `export CLAUDE_TYPECHECK_GATE=block` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_TYPECHECK_GATE='block'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_TYPECHECK_GATE','block','User')` (persistent). |
 | `CLAUDE_RECALL_BRIEFING=1` | `hooks/recall-briefing.mjs` (a UserPromptSubmit hook) makes episodic memory proactive: on the first substantive prompt of a session it searches this project's past observations (BM25) and injects a one-time `<system-reminder>` with the most relevant prior activity, so the agent reuses a past fix instead of re-deriving it. Opt-in and default off; it is an amplifier, never a gate — it cannot block a prompt and fails open. The `ci_recall` MCP tool stays available for explicit, deeper searches. | bash/zsh: `export CLAUDE_RECALL_BRIEFING=1` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_RECALL_BRIEFING=1` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_RECALL_BRIEFING','1','User')` (persistent). |
 | `CLAUDE_WORKFLOW_DISTILL_NUDGE=on` | `hooks/workflow-distill.mjs` (a `Stop` hook) closes the orchestration-to-memory loop: when a native Workflow run's output then passed a verify in the same session, it prints a one-line stderr nudge to run the `ci_distill_from_workflow` MCP tool, so an expensive multi-agent run leaves a durable Mulahazah draft instinct instead of evaporating. `on` enables it; default (unset or any other value) is off. Opt-in amplifier, never a gate — it cannot block the Stop, dedupes per run, and fails open. | bash/zsh: `export CLAUDE_WORKFLOW_DISTILL_NUDGE=on` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_WORKFLOW_DISTILL_NUDGE='on'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_WORKFLOW_DISTILL_NUDGE','on','User')` (persistent). |
+| `CLAUDE_QUERY_COST_NUDGE=on` | `hooks/query-cost-nudge.mjs` (a `Stop` hook) guards against surprise DB bills: when the working tree has changed DB/query files (`.sql`, `.prisma`, `migrations/`, `/db/`, `schema.*`, `drizzle`) at turn end, it injects a once-per-session `additionalContext` reminder to run a D1-aware cost audit — dispatch the `database-reviewer` agent or check EXPLAIN QUERY PLAN, index coverage, N+1, and D1 `rows_read` billing before finishing. `on` enables it; default (unset) is off. Opt-in amplifier, never a gate; dedupes per session and fails open. | bash/zsh: `export CLAUDE_QUERY_COST_NUDGE=on` in `~/.bashrc` / `~/.zshrc`. PowerShell: `$env:CLAUDE_QUERY_COST_NUDGE='on'` (session) or `[Environment]::SetEnvironmentVariable('CLAUDE_QUERY_COST_NUDGE','on','User')` (persistent). |
 
 </details>
 

package/bin/generate-plugin-manifests.mjs

@@ -156,6 +156,8 @@ async function writePluginBundle() {
         copyFileTo(join(REPO_ROOT, "lib", "recall-index.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "recall-index.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "recall-briefing.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "recall-briefing.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "skill-distill.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "skill-distill.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "typecheck-gate.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "typecheck-gate.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "query-cost-gate.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "query-cost-gate.mjs")),
         copyFileTo(join(REPO_ROOT, "LICENSE"), join(PLUGIN_BUNDLE_DIR, "LICENSE")),
         writePluginBundleReadme(),
     ]);

package/hooks/query-cost-nudge.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * query-cost-nudge.mts — Stop hook that nudges a D1-aware query-cost audit when
+ * the working tree has changed DB/query files at turn end (RISA 5 / G5).
+ *
+ * The `database-reviewer` agent already carries the cost checklist, but nothing
+ * dispatched it on DB edits, so cost regressions (the surprise-D1-bill class)
+ * shipped unaudited. This injects a once-per-session reminder via Stop
+ * `additionalContext` — a Stop hook (not PostToolUse) because only PreToolUse /
+ * UserPromptSubmit / Stop / SubagentStop support additionalContext; PostToolUse
+ * could only emit a user-facing systemMessage that never reaches the model.
+ *
+ * Opt-in via CLAUDE_QUERY_COST_NUDGE=on (default off). Once-per-session dedup
+ * keyed on the Stop stdin session_id (falls back to a per-day key) — without it,
+ * additionalContext "keeps the turn going" and would re-fire every turn while
+ * the DB files stay dirty. Never blocks; fail-open on any error.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { buildQueryCostReminder, changedQueryPaths, parseChangedFiles, resolveQueryCostNudge, } from "../lib/query-cost-gate.mjs";
+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 && fromEnv.trim())
+        return fromEnv.trim();
+    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 collectChangedFiles(root) {
+    const run = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            return "";
+        }
+    };
+    return [
+        ...parseChangedFiles(run(["diff", "--name-only", "--diff-filter=ACMR"])),
+        ...parseChangedFiles(run(["diff", "--cached", "--name-only", "--diff-filter=ACMR"])),
+    ];
+}
+// Marker key: the sanitized session_id when present (the normal case), else a
+// per-day key so a missing id self-heals daily instead of blocking forever.
+function markerKey(sessionId) {
+    const sanitized = (sessionId ?? "").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+    return sanitized || `day-${new Date().toISOString().slice(0, 10)}`;
+}
+function markerPath(home, projectRoot, sessionId) {
+    const hash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    return join(home, ".claude", "instincts", hash, "query-cost-nudge", `${markerKey(sessionId)}.nudged`);
+}
+function main() {
+    if (resolveQueryCostNudge(process.env.CLAUDE_QUERY_COST_NUDGE) === "off")
+        return;
+    let sessionId;
+    try {
+        const payload = JSON.parse(readStdin());
+        if (typeof payload.session_id === "string")
+            sessionId = payload.session_id;
+    }
+    catch {
+        // stdin optional — proceed without a session id (per-day dedup)
+    }
+    const root = resolveProjectRoot();
+    if (root === "global")
+        return; // no repo → nothing to diff
+    const changed = changedQueryPaths(collectChangedFiles(root));
+    if (changed.length === 0)
+        return;
+    const marker = markerPath(resolveHome(), root, sessionId);
+    try {
+        if (existsSync(marker))
+            return; // already nudged this session
+        mkdirSync(dirname(marker), { recursive: true });
+        writeFileSync(marker, `${new Date().toISOString()}\n`);
+    }
+    catch {
+        // if the marker can't be written, nudge anyway (no dedup) rather than stay silent
+    }
+    process.stdout.write(`${JSON.stringify({
+        hookSpecificOutput: { hookEventName: "Stop", additionalContext: buildQueryCostReminder(changed) },
+    })}\n`);
+}
+try {
+    main();
+}
+catch {
+    // fail open — never trap a turn on a hook bug
+}

package/hooks/typecheck-stop.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * typecheck-stop.mts — Stop hook that runs the project typecheck on changed TS
+ * files and, when opted in, returns a block decision so the failure re-enters
+ * model context and the agent fixes it before ending the turn — in all modes,
+ * including headless `-p` runs where Stop still fires (RISA 4 / G4).
+ *
+ * Ports the proven detection logic of ~/.claude/scripts/typecheck-changed.sh
+ * (skip non-TS repos, skip TS repos with no changed TS file, prefer the npm
+ * `typecheck` script) and adds the block mechanism of goal-drift-stop.mts.
+ *
+ * Mode via CLAUDE_TYPECHECK_GATE: "off" (default) | "warn" | "block".
+ *   off   : no-op (the global script's advisory systemMessage stays the default
+ *           layer; this hook is the opt-in enforcement layer — zero regression).
+ *   warn  : one-line stderr notice; never blocks.
+ *   block : {"decision":"block","reason":...} to re-prompt the model.
+ *
+ * Fail-open by construction: any error, missing root, non-TS repo, no changed
+ * TS file, no runnable typecheck, or a run that times out exits 0 (allow). No
+ * network. The wiring gives this hook a longer timeout than the 5s hooks
+ * because `tsc` is slower; on the internal timeout it fails open.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decideTypecheckAction, formatTypecheckReason, hasChangedTsFile, parseChangedFiles, pickTypecheckKind, resolveTypecheckMode, } from "../lib/typecheck-gate.mjs";
+const SPAWN_TIMEOUT_MS = 25_000;
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return root || null;
+    }
+    catch {
+        return null;
+    }
+}
+function collectChangedFiles(root) {
+    const run = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            return "";
+        }
+    };
+    const unstaged = run(["diff", "--name-only", "--diff-filter=ACMR"]);
+    const staged = run(["diff", "--cached", "--name-only", "--diff-filter=ACMR"]);
+    return [...parseChangedFiles(unstaged), ...parseChangedFiles(staged)];
+}
+function hasNpmTypecheckScript(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return typeof pkg.scripts?.typecheck === "string";
+    }
+    catch {
+        return false;
+    }
+}
+function localTscPath(root) {
+    // node_modules/typescript/bin/tsc is a Node script — invoking it via `node`
+    // is cross-platform, unlike node_modules/.bin/tsc (a shell script / .cmd).
+    const path = join(root, "node_modules", "typescript", "bin", "tsc");
+    return existsSync(path) ? path : null;
+}
+function runTypecheck(root) {
+    const tscPath = localTscPath(root);
+    const kind = pickTypecheckKind(hasNpmTypecheckScript(root), tscPath !== null);
+    if (!kind)
+        return { ran: false, rc: 0, output: "" };
+    const result = kind === "npm"
+        ? spawnSync("npm", ["run", "--silent", "typecheck"], {
+            cwd: root,
+            encoding: "utf8",
+            shell: true,
+            timeout: SPAWN_TIMEOUT_MS,
+        })
+        : spawnSync(process.execPath, [tscPath, "--noEmit"], {
+            cwd: root,
+            encoding: "utf8",
+            timeout: SPAWN_TIMEOUT_MS,
+        });
+    // A timeout or spawn failure leaves error set / status null — inconclusive, so
+    // fail open (do not block on a check that never produced a verdict).
+    if (result.error || typeof result.status !== "number")
+        return { ran: false, rc: 0, output: "" };
+    return { ran: true, rc: result.status, output: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+}
+function main() {
+    const mode = resolveTypecheckMode(process.env.CLAUDE_TYPECHECK_GATE);
+    if (mode === "off")
+        return;
+    const root = resolveProjectRoot();
+    if (!root || !existsSync(join(root, "tsconfig.json")))
+        return; // not a TS project
+    if (!hasChangedTsFile(collectChangedFiles(root)))
+        return; // nothing TS changed — near-zero cost
+    const { ran, rc, output } = runTypecheck(root);
+    const action = decideTypecheckAction({ mode, ranTypecheck: ran, rc });
+    if (action === "block") {
+        process.stdout.write(`${JSON.stringify({ decision: "block", reason: formatTypecheckReason(output) })}\n`);
+    }
+    else if (action === "warn") {
+        process.stderr.write(`[continuous-improvement] typecheck: ${formatTypecheckReason(output)}\n`);
+    }
+}
+try {
+    main();
+}
+catch {
+    // fail open — never trap a turn on a hook bug
+}

package/lib/plugin-metadata.mjs

@@ -497,6 +497,19 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/workflow-distill.mjs\"",
         timeout: 5,
     };
+    const typecheckStopCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/typecheck-stop.mjs\"",
+        // Longer than the 5s hooks: tsc is slower. Opt-in via CLAUDE_TYPECHECK_GATE
+        // (off by default) and near-zero cost when off / no TS file changed; on an
+        // internal timeout it fails open (allow) rather than blocking.
+        timeout: 30,
+    };
+    const queryCostNudgeCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/query-cost-nudge.mjs\"",
+        timeout: 5,
+    };
     const routePromptCommand = {
         type: "command",
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/route-prompt.mjs\"",
@@ -508,7 +521,7 @@ export function getPluginHooksConfig() {
         timeout: 5,
     };
     return {
-        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
+        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, opt-in typecheck Stop gate, opt-in query-cost Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
         hooks: {
             // gateguard runs FIRST on PreToolUse so its block decision short-circuits
             // before companion-preference sees the call. companion-preference runs
@@ -532,7 +545,7 @@ export function getPluginHooksConfig() {
             UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
-            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand] }],
+            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand, typecheckStopCommand, queryCostNudgeCommand] }],
         },
     };
 }

package/lib/query-cost-gate.mjs

@@ -0,0 +1,53 @@
+/**
+ * Pure helpers for the query-cost nudge Stop hook (RISA 5 / G5).
+ *
+ * The hook (src/hooks/query-cost-nudge.mts) does the I/O — git, the per-session
+ * dedup marker, emitting the reminder. Everything here is pure and unit-tested.
+ *
+ * Opt-in via CLAUDE_QUERY_COST_NUDGE=on (default off). When on and the working
+ * tree has changed DB/query files at turn end, the hook injects a once-per-session
+ * reminder (via Stop `additionalContext`) to run a D1-aware cost audit before
+ * finishing — the surprise-D1-bill class the insights flagged. Never blocks.
+ */
+export function resolveQueryCostNudge(raw) {
+    return (raw ?? "").trim().toLowerCase() === "on" ? "on" : "off";
+}
+// DB / query source paths. Case-insensitive; the caller passes forward-slash
+// paths straight from `git diff --name-only` (git always uses forward slashes).
+const QUERY_PATH_RES = [
+    /\.sql$/i,
+    /\.prisma$/i,
+    /(^|\/)migrations?\//i,
+    /(^|\/)db\//i,
+    /(^|\/)schema\.(ts|js|mjs|cjs|cts|mts|prisma|sql)$/i,
+    /drizzle/i,
+];
+export function isQueryPath(filePath) {
+    const path = (filePath ?? "").replace(/\\/g, "/").trim();
+    if (path === "")
+        return false;
+    return QUERY_PATH_RES.some((re) => re.test(path));
+}
+export function parseChangedFiles(gitOutput) {
+    return (gitOutput ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+export function changedQueryPaths(files) {
+    return files.filter((file) => isQueryPath(file));
+}
+export function buildQueryCostReminder(paths) {
+    const list = paths.slice(0, 8).map((path) => path.replace(/\\/g, "/")).join(", ");
+    return [
+        "<system-reminder>",
+        `Query-cost check: you changed DB/query file(s) this session (${list}).`,
+        "Before finishing, audit cost — dispatch the database-reviewer agent, or check directly:",
+        "  - EXPLAIN QUERY PLAN each new/changed query; no full table SCAN on a hot path.",
+        "  - Every WHERE / JOIN / ORDER BY column is index-covered; no N+1 loops.",
+        "  - D1: rows_read is billed per row SCANNED (not returned) — add covering indexes and cache hot reads (KV) instead of re-querying.",
+        "  - No unbounded query — add LIMIT / pagination.",
+        "One-time per-session reminder (CLAUDE_QUERY_COST_NUDGE).",
+        "</system-reminder>",
+    ].join("\n");
+}

package/lib/typecheck-gate.mjs

@@ -0,0 +1,62 @@
+/**
+ * Pure decision helpers for the typecheck Stop gate (RISA 4 / G4).
+ *
+ * The hook (src/hooks/typecheck-stop.mts) does the I/O — git, spawning the
+ * typecheck, emitting the decision. Everything here is pure and unit-tested so
+ * the mode/selection/formatting logic is provable without spawning a compiler.
+ *
+ * Mode via CLAUDE_TYPECHECK_GATE: "off" (default) | "warn" | "block".
+ *   - off   : no-op. The default. The global ~/.claude typecheck-changed.sh
+ *             already emits an advisory systemMessage; this hook stays silent
+ *             until opted in, so there is no double-advisory and no regression.
+ *   - warn  : print a one-line notice to stderr; never blocks.
+ *   - block : emit {"decision":"block","reason":...} so the failure re-enters
+ *             model context — the fix headless/autonomous -p loops need.
+ */
+export function resolveTypecheckMode(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    return value === "block" || value === "warn" ? value : "off";
+}
+// Matches the extensions typecheck-changed.sh screens for. `.d.ts` ends in
+// `.ts` so it counts — a changed ambient declaration can still break the build.
+const TS_FILE_RE = /\.(ts|tsx|mts|cts)$/;
+export function hasChangedTsFile(files) {
+    return files.some((file) => TS_FILE_RE.test(file.trim()));
+}
+// Split a `git diff --name-only` blob into a clean path list (drops blank lines).
+export function parseChangedFiles(gitOutput) {
+    return (gitOutput ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+// Prefer the project's own `typecheck` npm script (authoritative — it encodes
+// the project's exact flags), else a local tsc, else null (a TS project with no
+// runnable typecheck stays silent rather than guessing).
+export function pickTypecheckKind(hasNpmTypecheckScript, hasLocalTsc) {
+    if (hasNpmTypecheckScript)
+        return "npm";
+    if (hasLocalTsc)
+        return "tsc";
+    return null;
+}
+export function formatTypecheckReason(output, maxLines = 15) {
+    const tail = (output ?? "")
+        .split(/\r?\n/)
+        .filter((line) => line.length > 0)
+        .slice(-maxLines)
+        .join("\n");
+    return `Typecheck FAILED on changed TS files — fix before ending the turn:\n${tail}`;
+}
+// The single decision point. `ranTypecheck` is false when the gate short-circuited
+// (mode off, no TS project, no changed TS file, no runnable typecheck, or the run
+// timed out) — all of which allow. A conclusive non-zero rc maps to the mode.
+export function decideTypecheckAction(input) {
+    if (input.mode === "off")
+        return "allow";
+    if (!input.ranTypecheck)
+        return "allow";
+    if (input.rc === 0)
+        return "allow";
+    return input.mode;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.18.0",
+  "version": "3.20.0",
   "description": "Claude Code that gets sharper every session: the persistent-memory and runtime-discipline layer built on the 7 Laws of AI Agent Discipline. It grounds every edit in real facts before it lands and, through the Mulahazah engine, turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Shipped as 27 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts. Beginner: one /plugin install command. Expert: adds MCP tools and session hooks.",
   "keywords": [
     "claude-code",

package/plugins/beginner.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.18.0",
+  "version": "3.20.0",
   "mode": "beginner",
   "description": "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles three grounding skills (gateguard, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
   "tools": [

package/plugins/continuous-improvement/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "continuous-improvement",
       "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 27 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.18.0",
+      "version": "3.20.0",
       "source": "./",
       "author": {
         "name": "naimkatiman"

package/plugins/continuous-improvement/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.18.0",
+  "version": "3.20.0",
   "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 27 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
   "author": {
     "name": "naimkatiman",

package/plugins/continuous-improvement/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
+  "description": "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, opt-in typecheck Stop gate, opt-in query-cost Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
   "hooks": {
     "PreToolUse": [
       {
@@ -93,6 +93,16 @@
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/workflow-distill.mjs\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/typecheck-stop.mjs\"",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/query-cost-nudge.mjs\"",
+            "timeout": 5
           }
         ]
       }

package/plugins/continuous-improvement/hooks/query-cost-nudge.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * query-cost-nudge.mts — Stop hook that nudges a D1-aware query-cost audit when
+ * the working tree has changed DB/query files at turn end (RISA 5 / G5).
+ *
+ * The `database-reviewer` agent already carries the cost checklist, but nothing
+ * dispatched it on DB edits, so cost regressions (the surprise-D1-bill class)
+ * shipped unaudited. This injects a once-per-session reminder via Stop
+ * `additionalContext` — a Stop hook (not PostToolUse) because only PreToolUse /
+ * UserPromptSubmit / Stop / SubagentStop support additionalContext; PostToolUse
+ * could only emit a user-facing systemMessage that never reaches the model.
+ *
+ * Opt-in via CLAUDE_QUERY_COST_NUDGE=on (default off). Once-per-session dedup
+ * keyed on the Stop stdin session_id (falls back to a per-day key) — without it,
+ * additionalContext "keeps the turn going" and would re-fire every turn while
+ * the DB files stay dirty. Never blocks; fail-open on any error.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { buildQueryCostReminder, changedQueryPaths, parseChangedFiles, resolveQueryCostNudge, } from "../lib/query-cost-gate.mjs";
+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 && fromEnv.trim())
+        return fromEnv.trim();
+    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 collectChangedFiles(root) {
+    const run = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            return "";
+        }
+    };
+    return [
+        ...parseChangedFiles(run(["diff", "--name-only", "--diff-filter=ACMR"])),
+        ...parseChangedFiles(run(["diff", "--cached", "--name-only", "--diff-filter=ACMR"])),
+    ];
+}
+// Marker key: the sanitized session_id when present (the normal case), else a
+// per-day key so a missing id self-heals daily instead of blocking forever.
+function markerKey(sessionId) {
+    const sanitized = (sessionId ?? "").replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+    return sanitized || `day-${new Date().toISOString().slice(0, 10)}`;
+}
+function markerPath(home, projectRoot, sessionId) {
+    const hash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    return join(home, ".claude", "instincts", hash, "query-cost-nudge", `${markerKey(sessionId)}.nudged`);
+}
+function main() {
+    if (resolveQueryCostNudge(process.env.CLAUDE_QUERY_COST_NUDGE) === "off")
+        return;
+    let sessionId;
+    try {
+        const payload = JSON.parse(readStdin());
+        if (typeof payload.session_id === "string")
+            sessionId = payload.session_id;
+    }
+    catch {
+        // stdin optional — proceed without a session id (per-day dedup)
+    }
+    const root = resolveProjectRoot();
+    if (root === "global")
+        return; // no repo → nothing to diff
+    const changed = changedQueryPaths(collectChangedFiles(root));
+    if (changed.length === 0)
+        return;
+    const marker = markerPath(resolveHome(), root, sessionId);
+    try {
+        if (existsSync(marker))
+            return; // already nudged this session
+        mkdirSync(dirname(marker), { recursive: true });
+        writeFileSync(marker, `${new Date().toISOString()}\n`);
+    }
+    catch {
+        // if the marker can't be written, nudge anyway (no dedup) rather than stay silent
+    }
+    process.stdout.write(`${JSON.stringify({
+        hookSpecificOutput: { hookEventName: "Stop", additionalContext: buildQueryCostReminder(changed) },
+    })}\n`);
+}
+try {
+    main();
+}
+catch {
+    // fail open — never trap a turn on a hook bug
+}

package/plugins/continuous-improvement/hooks/typecheck-stop.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * typecheck-stop.mts — Stop hook that runs the project typecheck on changed TS
+ * files and, when opted in, returns a block decision so the failure re-enters
+ * model context and the agent fixes it before ending the turn — in all modes,
+ * including headless `-p` runs where Stop still fires (RISA 4 / G4).
+ *
+ * Ports the proven detection logic of ~/.claude/scripts/typecheck-changed.sh
+ * (skip non-TS repos, skip TS repos with no changed TS file, prefer the npm
+ * `typecheck` script) and adds the block mechanism of goal-drift-stop.mts.
+ *
+ * Mode via CLAUDE_TYPECHECK_GATE: "off" (default) | "warn" | "block".
+ *   off   : no-op (the global script's advisory systemMessage stays the default
+ *           layer; this hook is the opt-in enforcement layer — zero regression).
+ *   warn  : one-line stderr notice; never blocks.
+ *   block : {"decision":"block","reason":...} to re-prompt the model.
+ *
+ * Fail-open by construction: any error, missing root, non-TS repo, no changed
+ * TS file, no runnable typecheck, or a run that times out exits 0 (allow). No
+ * network. The wiring gives this hook a longer timeout than the 5s hooks
+ * because `tsc` is slower; on the internal timeout it fails open.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decideTypecheckAction, formatTypecheckReason, hasChangedTsFile, parseChangedFiles, pickTypecheckKind, resolveTypecheckMode, } from "../lib/typecheck-gate.mjs";
+const SPAWN_TIMEOUT_MS = 25_000;
+function resolveProjectRoot() {
+    const fromEnv = process.env.CLAUDE_PROJECT_DIR;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    try {
+        const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return root || null;
+    }
+    catch {
+        return null;
+    }
+}
+function collectChangedFiles(root) {
+    const run = (args) => {
+        try {
+            return execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            return "";
+        }
+    };
+    const unstaged = run(["diff", "--name-only", "--diff-filter=ACMR"]);
+    const staged = run(["diff", "--cached", "--name-only", "--diff-filter=ACMR"]);
+    return [...parseChangedFiles(unstaged), ...parseChangedFiles(staged)];
+}
+function hasNpmTypecheckScript(root) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        return typeof pkg.scripts?.typecheck === "string";
+    }
+    catch {
+        return false;
+    }
+}
+function localTscPath(root) {
+    // node_modules/typescript/bin/tsc is a Node script — invoking it via `node`
+    // is cross-platform, unlike node_modules/.bin/tsc (a shell script / .cmd).
+    const path = join(root, "node_modules", "typescript", "bin", "tsc");
+    return existsSync(path) ? path : null;
+}
+function runTypecheck(root) {
+    const tscPath = localTscPath(root);
+    const kind = pickTypecheckKind(hasNpmTypecheckScript(root), tscPath !== null);
+    if (!kind)
+        return { ran: false, rc: 0, output: "" };
+    const result = kind === "npm"
+        ? spawnSync("npm", ["run", "--silent", "typecheck"], {
+            cwd: root,
+            encoding: "utf8",
+            shell: true,
+            timeout: SPAWN_TIMEOUT_MS,
+        })
+        : spawnSync(process.execPath, [tscPath, "--noEmit"], {
+            cwd: root,
+            encoding: "utf8",
+            timeout: SPAWN_TIMEOUT_MS,
+        });
+    // A timeout or spawn failure leaves error set / status null — inconclusive, so
+    // fail open (do not block on a check that never produced a verdict).
+    if (result.error || typeof result.status !== "number")
+        return { ran: false, rc: 0, output: "" };
+    return { ran: true, rc: result.status, output: `${result.stdout ?? ""}${result.stderr ?? ""}` };
+}
+function main() {
+    const mode = resolveTypecheckMode(process.env.CLAUDE_TYPECHECK_GATE);
+    if (mode === "off")
+        return;
+    const root = resolveProjectRoot();
+    if (!root || !existsSync(join(root, "tsconfig.json")))
+        return; // not a TS project
+    if (!hasChangedTsFile(collectChangedFiles(root)))
+        return; // nothing TS changed — near-zero cost
+    const { ran, rc, output } = runTypecheck(root);
+    const action = decideTypecheckAction({ mode, ranTypecheck: ran, rc });
+    if (action === "block") {
+        process.stdout.write(`${JSON.stringify({ decision: "block", reason: formatTypecheckReason(output) })}\n`);
+    }
+    else if (action === "warn") {
+        process.stderr.write(`[continuous-improvement] typecheck: ${formatTypecheckReason(output)}\n`);
+    }
+}
+try {
+    main();
+}
+catch {
+    // fail open — never trap a turn on a hook bug
+}

package/plugins/continuous-improvement/lib/plugin-metadata.mjs

@@ -497,6 +497,19 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/workflow-distill.mjs\"",
         timeout: 5,
     };
+    const typecheckStopCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/typecheck-stop.mjs\"",
+        // Longer than the 5s hooks: tsc is slower. Opt-in via CLAUDE_TYPECHECK_GATE
+        // (off by default) and near-zero cost when off / no TS file changed; on an
+        // internal timeout it fails open (allow) rather than blocking.
+        timeout: 30,
+    };
+    const queryCostNudgeCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/query-cost-nudge.mjs\"",
+        timeout: 5,
+    };
     const routePromptCommand = {
         type: "command",
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/route-prompt.mjs\"",
@@ -508,7 +521,7 @@ export function getPluginHooksConfig() {
         timeout: 5,
     };
     return {
-        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
+        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, opt-in workflow-distill Stop nudge, opt-in typecheck Stop gate, opt-in query-cost Stop nudge, and UserPromptSubmit lazy-routing plus opt-in proactive recall-briefing hooks for continuous-improvement.",
         hooks: {
             // gateguard runs FIRST on PreToolUse so its block decision short-circuits
             // before companion-preference sees the call. companion-preference runs
@@ -532,7 +545,7 @@ export function getPluginHooksConfig() {
             UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
-            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand] }],
+            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand, typecheckStopCommand, queryCostNudgeCommand] }],
         },
     };
 }

package/plugins/continuous-improvement/lib/query-cost-gate.mjs

@@ -0,0 +1,53 @@
+/**
+ * Pure helpers for the query-cost nudge Stop hook (RISA 5 / G5).
+ *
+ * The hook (src/hooks/query-cost-nudge.mts) does the I/O — git, the per-session
+ * dedup marker, emitting the reminder. Everything here is pure and unit-tested.
+ *
+ * Opt-in via CLAUDE_QUERY_COST_NUDGE=on (default off). When on and the working
+ * tree has changed DB/query files at turn end, the hook injects a once-per-session
+ * reminder (via Stop `additionalContext`) to run a D1-aware cost audit before
+ * finishing — the surprise-D1-bill class the insights flagged. Never blocks.
+ */
+export function resolveQueryCostNudge(raw) {
+    return (raw ?? "").trim().toLowerCase() === "on" ? "on" : "off";
+}
+// DB / query source paths. Case-insensitive; the caller passes forward-slash
+// paths straight from `git diff --name-only` (git always uses forward slashes).
+const QUERY_PATH_RES = [
+    /\.sql$/i,
+    /\.prisma$/i,
+    /(^|\/)migrations?\//i,
+    /(^|\/)db\//i,
+    /(^|\/)schema\.(ts|js|mjs|cjs|cts|mts|prisma|sql)$/i,
+    /drizzle/i,
+];
+export function isQueryPath(filePath) {
+    const path = (filePath ?? "").replace(/\\/g, "/").trim();
+    if (path === "")
+        return false;
+    return QUERY_PATH_RES.some((re) => re.test(path));
+}
+export function parseChangedFiles(gitOutput) {
+    return (gitOutput ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+export function changedQueryPaths(files) {
+    return files.filter((file) => isQueryPath(file));
+}
+export function buildQueryCostReminder(paths) {
+    const list = paths.slice(0, 8).map((path) => path.replace(/\\/g, "/")).join(", ");
+    return [
+        "<system-reminder>",
+        `Query-cost check: you changed DB/query file(s) this session (${list}).`,
+        "Before finishing, audit cost — dispatch the database-reviewer agent, or check directly:",
+        "  - EXPLAIN QUERY PLAN each new/changed query; no full table SCAN on a hot path.",
+        "  - Every WHERE / JOIN / ORDER BY column is index-covered; no N+1 loops.",
+        "  - D1: rows_read is billed per row SCANNED (not returned) — add covering indexes and cache hot reads (KV) instead of re-querying.",
+        "  - No unbounded query — add LIMIT / pagination.",
+        "One-time per-session reminder (CLAUDE_QUERY_COST_NUDGE).",
+        "</system-reminder>",
+    ].join("\n");
+}

package/plugins/continuous-improvement/lib/typecheck-gate.mjs

@@ -0,0 +1,62 @@
+/**
+ * Pure decision helpers for the typecheck Stop gate (RISA 4 / G4).
+ *
+ * The hook (src/hooks/typecheck-stop.mts) does the I/O — git, spawning the
+ * typecheck, emitting the decision. Everything here is pure and unit-tested so
+ * the mode/selection/formatting logic is provable without spawning a compiler.
+ *
+ * Mode via CLAUDE_TYPECHECK_GATE: "off" (default) | "warn" | "block".
+ *   - off   : no-op. The default. The global ~/.claude typecheck-changed.sh
+ *             already emits an advisory systemMessage; this hook stays silent
+ *             until opted in, so there is no double-advisory and no regression.
+ *   - warn  : print a one-line notice to stderr; never blocks.
+ *   - block : emit {"decision":"block","reason":...} so the failure re-enters
+ *             model context — the fix headless/autonomous -p loops need.
+ */
+export function resolveTypecheckMode(raw) {
+    const value = (raw ?? "").trim().toLowerCase();
+    return value === "block" || value === "warn" ? value : "off";
+}
+// Matches the extensions typecheck-changed.sh screens for. `.d.ts` ends in
+// `.ts` so it counts — a changed ambient declaration can still break the build.
+const TS_FILE_RE = /\.(ts|tsx|mts|cts)$/;
+export function hasChangedTsFile(files) {
+    return files.some((file) => TS_FILE_RE.test(file.trim()));
+}
+// Split a `git diff --name-only` blob into a clean path list (drops blank lines).
+export function parseChangedFiles(gitOutput) {
+    return (gitOutput ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+// Prefer the project's own `typecheck` npm script (authoritative — it encodes
+// the project's exact flags), else a local tsc, else null (a TS project with no
+// runnable typecheck stays silent rather than guessing).
+export function pickTypecheckKind(hasNpmTypecheckScript, hasLocalTsc) {
+    if (hasNpmTypecheckScript)
+        return "npm";
+    if (hasLocalTsc)
+        return "tsc";
+    return null;
+}
+export function formatTypecheckReason(output, maxLines = 15) {
+    const tail = (output ?? "")
+        .split(/\r?\n/)
+        .filter((line) => line.length > 0)
+        .slice(-maxLines)
+        .join("\n");
+    return `Typecheck FAILED on changed TS files — fix before ending the turn:\n${tail}`;
+}
+// The single decision point. `ranTypecheck` is false when the gate short-circuited
+// (mode off, no TS project, no changed TS file, no runnable typecheck, or the run
+// timed out) — all of which allow. A conclusive non-zero rc maps to the mode.
+export function decideTypecheckAction(input) {
+    if (input.mode === "off")
+        return "allow";
+    if (!input.ranTypecheck)
+        return "allow";
+    if (input.rc === 0)
+        return "allow";
+    return input.mode;
+}

package/plugins/expert.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.18.0",
+  "version": "3.20.0",
   "mode": "expert",
   "description": "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay sharp and learnings survive context resets.",
   "tools": [