continuous-improvement 3.19.0 → 3.20.4

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.4",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/QUICKSTART.md

@@ -139,7 +139,7 @@ npx continuous-improvement install --mode expert
 npx continuous-improvement install --pack react   # optional: react | python | go | meta
 ```
 
-Preconditions: Node 18 / 20 / 22, plus bash on Windows (Git Bash or WSL — `hooks/observe.sh` is a bash script). See [README.md § Expert](README.md#expert--adds-mcp-server-observation-hooks-and-instinct-packs) for the full preconditions and troubleshooting matrix.
+Preconditions: Node 18 / 20 / 22, plus Git Bash on Windows (`hooks/observe.sh` is a Bash script). WSL Bash launched from native Windows cannot resolve the `C:/...` hook paths written by the installer. See [README.md § Expert](README.md#expert--adds-mcp-server-observation-hooks-and-instinct-packs) for the full preconditions and troubleshooting matrix.
 
 Verify with `/dashboard` — you should see instinct health and observation count.
 

package/README.md

@@ -137,7 +137,7 @@ V1 honest limitations: the runtime gate is honor-system once the agent flips `_g
 
 Pick this if you want the MCP tools (19 of them, including `ci_plan_init` / `ci_plan_status` for `task_plan.md`-style planning), the session hooks that feed Mulahazah, and starter packs.
 
-Preconditions: Node 18 / 20 / 22, plus bash on Windows (Git Bash or WSL — `hooks/observe.sh` is a bash script and silently no-ops without it). **`jq` is no longer required**: as of v3.6.0, `observe.sh` prefers the Node observer (`bin/observe.mjs`) which writes the rich event schema natively without external dependencies. The bash thin-schema path is kept as a two-phase shim, so legacy installs that have not re-run `npx continuous-improvement install` since v3.5.x will still degrade silently without `jq` (`winget install jqlang.jq` on Windows, `brew install jq` on macOS, `apt install jq` on Debian/Ubuntu) — re-running the installer is the cleaner fix and removes the dependency entirely. See [CHANGELOG.md](CHANGELOG.md) `[3.6.0]` for the migration details.
+Preconditions: Node 18 / 20 / 22, plus Git Bash on Windows (`hooks/observe.sh` is a Bash script). WSL Bash launched from native Windows cannot resolve the `C:/...` hook paths written by the installer. **`jq` is no longer required**: as of v3.6.0, `observe.sh` prefers the Node observer (`bin/observe.mjs`) which writes the rich event schema natively without external dependencies. The bash thin-schema path is kept as a two-phase shim, so legacy installs that have not re-run `npx continuous-improvement install` since v3.5.x will still degrade silently without `jq` (`winget install jqlang.jq` on Windows, `brew install jq` on macOS, `apt install jq` on Debian/Ubuntu) — re-running the installer is the cleaner fix and removes the dependency entirely. See [CHANGELOG.md](CHANGELOG.md) `[3.6.0]` for the migration details.
 
 ```bash
 npx continuous-improvement install --mode expert
@@ -158,7 +158,7 @@ Three failures account for nearly every install support thread. Try them in orde
 | Symptom | Real cause | Fix |
 |---|---|---|
 | `/discipline` says "command not recognized" right after `/plugin install` | Slash commands load on session start; the marketplace did pick the plugin up | Quit and reopen Claude Code, then run `/discipline` again |
-| Expert mode hooks never fire on Windows | `observe.sh` is bash; PowerShell silently no-ops on it | Install Git Bash (or WSL) and re-run `npx continuous-improvement install --mode expert` |
+| Expert mode hooks never fire on Windows | WSL Bash cannot resolve the native `C:/...` hook paths | Install Git Bash, ensure its `bin` directory precedes `C:\Windows\System32` on PATH, then re-run `npx continuous-improvement install --mode expert` |
 | `/plugin marketplace add ...` returned nothing visible | Marketplace add was silent; the plugin is not yet selected | Run `/plugin install continuous-improvement@continuous-improvement` to select and activate it |
 
 If none of those apply, paste the output of `npx continuous-improvement install` into a GitHub issue — that surface logs every step.
@@ -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/check-landing-version.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { argv, cwd } from "node:process";
+import { fileURLToPath } from "node:url";
+const VERSION_RE = "([0-9]+\\.[0-9]+\\.[0-9]+)";
+function firstMatch(content, pattern) {
+    return pattern.exec(content)?.[1] ?? null;
+}
+export function checkLandingVersion(repoRoot) {
+    const packagePath = resolve(repoRoot, "package.json");
+    const landingPath = resolve(repoRoot, "docs", "landing", "index.html");
+    const packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+    const packageVersion = typeof packageJson.version === "string" ? packageJson.version : "";
+    const landing = readFileSync(landingPath, "utf8");
+    const markers = {
+        badge: firstMatch(landing, new RegExp(`<span\\b[^>]*class=["'][^"']*\\bver\\b[^"']*["'][^>]*>\\s*v${VERSION_RE}\\s*</span>`, "i")),
+        hero: firstMatch(landing, new RegExp(`<span\\b[^>]*class=["'][^"']*\\bkicker\\b[^"']*["'][^>]*>[\\s\\S]*?\\bREV\\s+${VERSION_RE}[\\s\\S]*?</span>`, "i")),
+        current: firstMatch(landing, new RegExp(`<span\\b[^>]*class=["'][^"']*\\bv\\b[^"']*["'][^>]*>\\s*v${VERSION_RE}\\s*</span>\\s*<span\\b[^>]*class=["'][^"']*\\bk\\b[^"']*["'][^>]*>\\s*Current rev\\s*</span>`, "i")),
+        footer: firstMatch(landing, new RegExp(`<span\\b[^>]*class=["'][^"']*\\bfoot-doc\\b[^"']*["'][^>]*>[\\s\\S]*?\\bREV\\s+${VERSION_RE}[\\s\\S]*?</span>`, "i")),
+    };
+    const errors = [];
+    if (!/^[0-9]+\.[0-9]+\.[0-9]+$/.test(packageVersion)) {
+        errors.push(`package.json has an invalid version: ${packageVersion || "<missing>"}`);
+    }
+    const missing = Object.entries(markers)
+        .filter(([, version]) => version === null)
+        .map(([name]) => name);
+    if (missing.length > 0) {
+        errors.push(`landing release marker(s) missing: ${missing.join(", ")}`);
+    }
+    const landingVersions = [...new Set(Object.values(markers).filter((value) => value !== null))];
+    if (landingVersions.length > 1) {
+        errors.push(`landing release markers are mixed: ${landingVersions.join(", ")}`);
+    }
+    for (const [name, version] of Object.entries(markers)) {
+        if (version !== null && version !== packageVersion) {
+            errors.push(`${name} marker is ${version}; package.json is ${packageVersion}`);
+        }
+    }
+    return { ok: errors.length === 0, packageVersion, markers, errors };
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    try {
+        const result = checkLandingVersion(repoRoot);
+        if (result.ok) {
+            console.log(`OK landing-version: all 4 markers match package.json ${result.packageVersion}.`);
+            return;
+        }
+        console.error(`FAIL landing-version: ${result.errors.join("; ")}`);
+        process.exitCode = 1;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`FAIL landing-version: ${message}`);
+        process.exitCode = 1;
+    }
+}
+const entryPath = argv[1] ? resolve(argv[1]) : "";
+if (entryPath === fileURLToPath(import.meta.url)) {
+    main();
+}

package/bin/check-scripts-citation-drift.mjs

@@ -11,7 +11,7 @@
  * Three sides of the contract are enforced as one invariant:
  *
  *   Side A — every file in scripts/ (excluding README.md) must appear in the
- *            Inventory table's Script column.
+ *            Inventory table, and every inventoried helper must exist on disk.
  *   Side B — for every Inventory row, every `skills/<name>.md` token in the
  *            Cited by cell must reference a file whose body contains the
  *            literal substring `scripts/<script-filename>` for at least one
@@ -85,30 +85,67 @@ function listSkillFiles(repoRoot) {
     const dir = join(repoRoot, SKILLS_DIR);
     if (!existsSync(dir) || !statSync(dir).isDirectory())
         return [];
-    return readdirSync(dir)
-        .filter((entry) => entry.endsWith(".md"))
-        .map((entry) => `${SKILLS_DIR}/${entry}`)
-        .sort();
+    const skills = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name.endsWith(".md")) {
+            skills.push(`${SKILLS_DIR}/${entry.name}`);
+            continue;
+        }
+        if (entry.isDirectory() &&
+            existsSync(join(dir, entry.name, "SKILL.md"))) {
+            skills.push(`${SKILLS_DIR}/${entry.name}.md`);
+        }
+    }
+    return skills.sort();
+}
+function resolveSkillFile(repoRoot, skillPath) {
+    const flatPath = join(repoRoot, skillPath);
+    if (existsSync(flatPath))
+        return flatPath;
+    const bundledSkill = /^skills\/([^/]+)\.md$/.exec(skillPath);
+    if (bundledSkill?.[1]) {
+        return join(repoRoot, SKILLS_DIR, bundledSkill[1], "SKILL.md");
+    }
+    return flatPath;
 }
 function toPosix(relPath) {
     return relPath.split(sep).join(posix.sep);
 }
 export function checkRepo(repoRoot) {
+    const structure = [];
     const sideA = [];
     const sideB = [];
     const sideC = [];
-    const scriptFiles = listScriptFiles(repoRoot);
+    const scriptsPath = join(repoRoot, SCRIPTS_DIR);
     const readmePath = join(repoRoot, SCRIPTS_README);
-    const readmeContent = existsSync(readmePath) ? readFileSync(readmePath, "utf8") : "";
+    const scriptsDirectoryExists = existsSync(scriptsPath) && statSync(scriptsPath).isDirectory();
+    const readmeExists = scriptsDirectoryExists && existsSync(readmePath);
+    const readmeContent = readmeExists ? readFileSync(readmePath, "utf8") : "";
     const rows = parseInventoryTable(readmeContent);
+    if (!scriptsDirectoryExists) {
+        structure.push("scripts/ directory is missing");
+    }
+    else if (!readmeExists) {
+        structure.push("scripts/README.md inventory is missing");
+    }
+    else if (rows.length === 0) {
+        structure.push("scripts/README.md inventory has no rows");
+    }
+    const scriptFiles = listScriptFiles(repoRoot);
     const inventoryScripts = new Set();
     for (const row of rows) {
         for (const s of row.scripts)
             inventoryScripts.add(s);
     }
+    const scriptFileSet = new Set(scriptFiles);
     for (const file of scriptFiles) {
         if (!inventoryScripts.has(file)) {
-            sideA.push(file);
+            sideA.push(`${file} — file is missing from the inventory`);
+        }
+    }
+    for (const inventoryScript of inventoryScripts) {
+        if (!scriptFileSet.has(inventoryScript)) {
+            sideA.push(`${inventoryScript} — inventoried helper file is missing`);
         }
     }
     let citationCount = 0;
@@ -122,7 +159,7 @@ export function checkRepo(repoRoot) {
     for (const row of rows) {
         for (const skillPath of row.skills) {
             citationCount += 1;
-            const fullSkill = join(repoRoot, skillPath);
+            const fullSkill = resolveSkillFile(repoRoot, skillPath);
             let skillBody = "";
             try {
                 skillBody = readFileSync(fullSkill, "utf8");
@@ -142,7 +179,7 @@ export function checkRepo(repoRoot) {
     for (const skillPath of skillFiles) {
         let body = "";
         try {
-            body = readFileSync(join(repoRoot, skillPath), "utf8");
+            body = readFileSync(resolveSkillFile(repoRoot, skillPath), "utf8");
         }
         catch {
             continue;
@@ -160,6 +197,7 @@ export function checkRepo(repoRoot) {
         }
     }
     return {
+        structure,
         sideA,
         sideB,
         sideC,
@@ -170,15 +208,25 @@ export function checkRepo(repoRoot) {
 function main() {
     const repoRoot = argv[2] ?? cwd();
     const result = checkRepo(repoRoot);
-    const totalViolations = result.sideA.length + result.sideB.length + result.sideC.length;
+    const totalViolations = result.structure.length +
+        result.sideA.length +
+        result.sideB.length +
+        result.sideC.length;
     if (totalViolations === 0) {
         console.log(`OK scripts-citation-drift: ${result.scriptCount} script(s), ${result.citationCount} skill citation(s), all three sides reconciled.`);
         exit(0);
     }
     console.error(`FAIL scripts-citation-drift: ${totalViolations} drift(s) across the inventory-citation contract.`);
+    if (result.structure.length > 0) {
+        console.error("");
+        console.error("Contract structure:");
+        for (const v of result.structure) {
+            console.error(`  ${toPosix(v)}`);
+        }
+    }
     if (result.sideA.length > 0) {
         console.error("");
-        console.error("Side A — script files missing from scripts/README.md inventory table:");
+        console.error("Side A — scripts/ files and inventory rows do not match:");
         for (const v of result.sideA) {
             console.error(`  ${toPosix(v)}`);
         }
@@ -198,7 +246,7 @@ function main() {
         }
     }
     console.error("");
-    console.error("Fix: update scripts/README.md inventory (Side A/C) or correct the skill citation (Side B).");
+    console.error("Fix: restore scripts/ and its inventory, update Side A/C, or correct the Side B skill citation.");
     exit(1);
 }
 const scriptPathFromArgv = argv[1];

package/bin/generate-plugin-manifests.mjs

@@ -82,6 +82,7 @@ async function writePluginBundleReadme() {
         "- `commands/`",
         "- `agents/` — `code-reviewer`, `security-auditor`, `test-engineer` personas (auto-discovered Claude Code subagents; pattern from addy/agent-skills)",
         "- `hooks/`",
+        "- `scripts/`",
         "- `bin/mcp-server.mjs`",
         "- `bin/observe.mjs`",
         "- `bin/backfill.mjs`",
@@ -140,6 +141,7 @@ async function writePluginBundle() {
         copyDirectory(join(REPO_ROOT, "commands"), join(PLUGIN_BUNDLE_DIR, "commands")),
         copyDirectory(join(REPO_ROOT, "agents"), join(PLUGIN_BUNDLE_DIR, "agents")),
         copyDirectory(join(REPO_ROOT, "hooks"), join(PLUGIN_BUNDLE_DIR, "hooks")),
+        copyDirectory(join(REPO_ROOT, "scripts"), join(PLUGIN_BUNDLE_DIR, "scripts")),
         copyDirectory(join(REPO_ROOT, "instinct-packs"), join(PLUGIN_BUNDLE_DIR, "instinct-packs")),
         copyDirectory(join(REPO_ROOT, "templates", "planning-with-files"), join(PLUGIN_BUNDLE_DIR, "templates", "planning-with-files")),
         copyFileTo(join(REPO_ROOT, "bin", "mcp-server.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "mcp-server.mjs")),
@@ -157,6 +159,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/bin/install.mjs

@@ -10,7 +10,7 @@
  *   npx continuous-improvement install --uninstall    # remove everything
  */
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
-import { execSync } from "node:child_process";
+import { execFileSync as runFileSync, execSync } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -84,20 +84,25 @@ function readJsonFile(filePath) {
         return null;
     }
 }
-// The observation hooks (hooks/observe.sh, hooks/session.sh) are bash scripts.
-// On Windows without Git Bash / WSL the hook commands written into settings.json
-// silently no-op, so the user finishes install thinking observation capture is
-// live when it never fires. Refuse the install with one actionable line instead.
-function assertBashAvailableOnWindows() {
+// The observation hooks are Bash scripts, and the native Windows settings use
+// forward-slash drive paths such as C:/Users/... . Git Bash resolves that form;
+// WSL's C:\Windows\System32\bash.exe does not. Probe the real packaged hook path
+// instead of accepting any executable that happens to answer `bash --version`.
+function assertBashCanReadHookOnWindows() {
     if (process.platform !== "win32")
         return;
+    const hookSource = toBashPath(join(REPO_ROOT, "hooks", "observe.sh"));
     try {
-        execSync("bash --version", { stdio: "ignore" });
+        runFileSync("bash", ["-c", 'test -r "$CONTINUOUS_IMPROVEMENT_HOOK_SOURCE"'], {
+            env: { ...process.env, CONTINUOUS_IMPROVEMENT_HOOK_SOURCE: hookSource },
+            stdio: "ignore",
+        });
     }
     catch {
-        console.error("  ✗ Install refused: the observation hooks (hooks/observe.sh, hooks/session.sh) " +
-            "are bash scripts, but `bash --version` is not on PATH. Install Git Bash or WSL, " +
-            "reopen your shell, and re-run — see README → Troubleshooting install.");
+        console.error(`  ✗ Install refused: Bash on PATH cannot read the Windows hook path ${hookSource}. ` +
+            "Install Git Bash and ensure its bin directory comes before " +
+            "C:\\Windows\\System32 on PATH, then reopen your shell and re-run. " +
+            "See README > Troubleshooting install.");
         process.exit(1);
     }
 }
@@ -612,6 +617,10 @@ function installNonClaudeTargets(targetIds) {
     for (const note of notes)
         console.log(`  ℹ ${note}`);
 }
+// A mixed target install can write non-Claude rule files below. Validate the
+// Claude hook runtime first so an incompatible Bash cannot leave a partial install.
+if (requestedTargets.includes("claude"))
+    assertBashCanReadHookOnWindows();
 const nonClaudeTargets = requestedTargets.filter((targetId) => targetId !== "claude");
 if (nonClaudeTargets.length > 0) {
     console.log("\ncontinuous-improvement multi-platform install\n");
@@ -625,7 +634,6 @@ console.log(`
 continuous-improvement (mode: ${INSTALL_MODE})
 Research → Plan → Execute → Verify → Reflect → Learn → Iterate
 `);
-assertBashAvailableOnWindows();
 warnOnMarketplaceCollision();
 console.log("Installing to Claude Code...\n");
 const installed = installSkill() ? 1 : 0;

package/commands/verify-install.md

@@ -41,7 +41,7 @@ The observation hook appends one row per tool call to
 
 - If it exists and has at least one row — capture is recording. Record `observe: ✓`.
 - If it is missing or empty — record `observe: ✗ (observation hook not recording —
-  on Windows confirm Git Bash / WSL is installed, then re-run the installer)`.
+  on Windows confirm Git Bash is installed before WSL Bash on PATH, then re-run the installer)`.
 
 ## Report
 

package/hooks/gateguard.mjs

@@ -210,6 +210,16 @@ function buildMutatingFileReason(toolName, filePaths, stateFilePath) {
         "  `_gateguard_facts_presented: true`; Claude Code's strict schema rejects that, so use A or B.)",
     ].join("\n");
 }
+function isGitBraceSelector(value) {
+    const selector = value.trim();
+    if (/^(?:u|upstream|push|-?\d+)$/i.test(selector))
+        return true;
+    if (/^(?:now|today|yesterday|tomorrow|noon|midnight|tea)$/i.test(selector))
+        return true;
+    if (/^\d{4}-\d{1,2}-\d{1,2}(?:[ T].*)?$/.test(selector))
+        return true;
+    return !selector.startsWith("#") && /(?:^|[.\s])ago$/i.test(selector);
+}
 function findUnquotedBraceRef(command) {
     let quote = null;
     for (let i = 0; i < command.length; i++) {
@@ -224,17 +234,26 @@ function findUnquotedBraceRef(command) {
             continue;
         }
         if (ch === "@" && command[i + 1] === "{") {
+            const braceEnd = command.indexOf("}", i + 2);
+            if (braceEnd === -1)
+                continue;
+            const selector = command.slice(i + 2, braceEnd);
+            // Deny only recognized Git selector grammar. PowerShell hashtables can
+            // contain comments, quoted braces, or arbitrary key expressions.
+            if (!isGitBraceSelector(selector)) {
+                i = braceEnd;
+                continue;
+            }
             // Expand to the whitespace-delimited word that carries this @{ ref, then
             // single-quote that whole word in the suggested fix.
             let wordStart = i;
             while (wordStart > 0 && !/\s/.test(command[wordStart - 1]))
                 wordStart--;
-            let wordEnd = i;
+            let wordEnd = braceEnd + 1;
             while (wordEnd < command.length && !/\s/.test(command[wordEnd]))
                 wordEnd++;
             const word = command.slice(wordStart, wordEnd);
-            const braceEnd = command.indexOf("}", i);
-            const ref = braceEnd === -1 ? command.slice(i, wordEnd) : command.slice(i, braceEnd + 1);
+            const ref = command.slice(i, braceEnd + 1);
             const fixed = `${command.slice(0, wordStart)}'${word}'${command.slice(wordEnd)}`;
             return { ref, fixed };
         }

package/hooks/query-cost-nudge.mjs

@@ -0,0 +1,114 @@
+#!/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"])),
+        ...parseChangedFiles(run(["ls-files", "--others", "--exclude-standard"])),
+    ];
+}
+// 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

@@ -51,7 +51,8 @@ function collectChangedFiles(root) {
     };
     const unstaged = run(["diff", "--name-only", "--diff-filter=ACMR"]);
     const staged = run(["diff", "--cached", "--name-only", "--diff-filter=ACMR"]);
-    return [...parseChangedFiles(unstaged), ...parseChangedFiles(staged)];
+    const untracked = run(["ls-files", "--others", "--exclude-standard"]);
+    return [...parseChangedFiles(unstaged), ...parseChangedFiles(staged), ...parseChangedFiles(untracked)];
 }
 function hasNpmTypecheckScript(root) {
     try {

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