continuous-improvement 3.19.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.19.0",
+      "version": "3.20.0",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/README.md

@@ -177,6 +177,7 @@ The framework has documented operator-level modes that change hook behavior with
 | `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

@@ -157,6 +157,7 @@ async function writePluginBundle() {
         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/lib/plugin-metadata.mjs

@@ -505,6 +505,11 @@ export function getPluginHooksConfig() {
         // 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\"",
@@ -516,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, opt-in typecheck Stop gate, 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
@@ -540,7 +545,7 @@ export function getPluginHooksConfig() {
             UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
-            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand, typecheckStopCommand] }],
+            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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.19.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.19.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.19.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.19.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, opt-in typecheck Stop gate, 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": [
       {
@@ -98,6 +98,11 @@
             "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/lib/plugin-metadata.mjs

@@ -505,6 +505,11 @@ export function getPluginHooksConfig() {
         // 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\"",
@@ -516,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, opt-in typecheck Stop gate, 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
@@ -540,7 +545,7 @@ export function getPluginHooksConfig() {
             UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
-            Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand, workflowDistillCommand, typecheckStopCommand] }],
+            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/expert.json

@@ -1,6 +1,6 @@
 {
   "name": "continuous-improvement",
-  "version": "3.19.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": [