continuous-improvement 3.23.0 → 3.24.0

package/bin/reconcile-instinct-hashes.mjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Merge instinct buckets that are the same project under different path
+ * spellings (C:/ vs c:/ vs C:\). observe/gateguard now hash the canonical
+ * root; this CLI copies history into that hash and leaves an alias marker
+ * on the old dir. Idempotent. Never deletes a directory.
+ *
+ * Usage:
+ *   node bin/reconcile-instinct-hashes.mjs --dry-run
+ *   node bin/reconcile-instinct-hashes.mjs --apply
+ *   node bin/reconcile-instinct-hashes.mjs --apply --only 3ef4426c6e15 --only 137f2f54ec70
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, exit } from "node:process";
+import { canonicalizeProjectRoot, hashProjectRoot, resolveInstinctsRoot } from "../lib/gateguard-state.mjs";
+function countJsonl(path) {
+    if (!existsSync(path))
+        return 0;
+    return readFileSync(path, "utf8").split(/\n/).filter((line) => line.trim() !== "").length;
+}
+function isoNow() {
+    return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+export function discoverGroups(instinctsRoot) {
+    const groups = new Map();
+    let entries;
+    try {
+        entries = readdirSync(instinctsRoot);
+    }
+    catch {
+        return [];
+    }
+    for (const name of entries) {
+        if (name === "global")
+            continue;
+        const dir = join(instinctsRoot, name);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (existsSync(join(dir, "alias.json")) && !existsSync(join(dir, "observations.jsonl"))) {
+            continue;
+        }
+        const projectPath = join(dir, "project.json");
+        if (!existsSync(projectPath))
+            continue;
+        let project;
+        try {
+            project = JSON.parse(readFileSync(projectPath, "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (!project.root)
+            continue;
+        const canonicalRoot = canonicalizeProjectRoot(project.root);
+        const canonicalHash = hashProjectRoot(canonicalRoot);
+        const bucket = {
+            hash: name,
+            root: project.root,
+            name: project.name ?? name,
+            rows: countJsonl(join(dir, "observations.jsonl")),
+        };
+        const existing = groups.get(canonicalHash);
+        if (existing) {
+            existing.members.push(bucket);
+        }
+        else {
+            groups.set(canonicalHash, {
+                canonicalHash,
+                canonicalRoot,
+                name: project.name ?? name,
+                members: [bucket],
+            });
+        }
+    }
+    return [...groups.values()].filter((group) => group.members.some((member) => member.hash !== group.canonicalHash && member.rows > 0));
+}
+function parseTs(line) {
+    try {
+        const parsed = JSON.parse(line);
+        const value = Date.parse(parsed.ts ?? "");
+        return Number.isFinite(value) ? value : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+export function mergeJsonl(sources) {
+    const rows = [];
+    const seen = new Set();
+    for (const file of sources) {
+        if (!existsSync(file))
+            continue;
+        for (const line of readFileSync(file, "utf8").split(/\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed || seen.has(trimmed))
+                continue;
+            seen.add(trimmed);
+            rows.push(trimmed);
+        }
+    }
+    rows.sort((a, b) => parseTs(a) - parseTs(b) || a.localeCompare(b));
+    return rows.length === 0 ? "" : `${rows.join("\n")}\n`;
+}
+export function selectGroups(groups, only) {
+    if (only.length === 0)
+        return groups;
+    const wanted = new Set(only);
+    return groups.filter((group) => wanted.has(group.canonicalHash) || group.members.some((member) => wanted.has(member.hash)));
+}
+export function applyGroup(instinctsRoot, group) {
+    const destDir = join(instinctsRoot, group.canonicalHash);
+    mkdirSync(destDir, { recursive: true });
+    const destObs = join(destDir, "observations.jsonl");
+    const sources = group.members
+        .map((member) => join(instinctsRoot, member.hash, "observations.jsonl"))
+        .filter((path) => existsSync(path));
+    const merged = mergeJsonl(sources);
+    writeFileSync(destObs, merged, "utf8");
+    let createdAt = isoNow();
+    const destProject = join(destDir, "project.json");
+    if (existsSync(destProject)) {
+        try {
+            const existing = JSON.parse(readFileSync(destProject, "utf8"));
+            if (existing.created_at)
+                createdAt = existing.created_at;
+        }
+        catch {
+            // rewrite below
+        }
+    }
+    writeFileSync(destProject, `${JSON.stringify({
+        id: group.canonicalHash,
+        name: group.name,
+        root: group.canonicalRoot,
+        created_at: createdAt,
+    })}\n`, "utf8");
+    const aliases = [];
+    for (const member of group.members) {
+        if (member.hash === group.canonicalHash)
+            continue;
+        const srcDir = join(instinctsRoot, member.hash);
+        try {
+            for (const file of readdirSync(srcDir)) {
+                if (!file.endsWith(".yaml"))
+                    continue;
+                const dest = join(destDir, file);
+                if (!existsSync(dest))
+                    copyFileSync(join(srcDir, file), dest);
+            }
+        }
+        catch {
+            // missing dir is non-fatal
+        }
+        const srcObs = join(srcDir, "observations.jsonl");
+        if (existsSync(srcObs)) {
+            renameSync(srcObs, join(srcDir, `observations.migrated-to-${group.canonicalHash}.jsonl`));
+        }
+        writeFileSync(join(srcDir, "alias.json"), `${JSON.stringify({
+            canonical: group.canonicalHash,
+            canonical_root: group.canonicalRoot,
+            migrated_at: isoNow(),
+            rows: member.rows,
+        })}\n`, "utf8");
+        aliases.push(member.hash);
+    }
+    const copiedRows = merged === "" ? 0 : merged.trim().split("\n").length;
+    return { copiedRows, aliases };
+}
+function printPlan(groups) {
+    if (groups.length === 0) {
+        console.log("No alias observation buckets to merge.");
+        return;
+    }
+    console.log(`Alias groups: ${groups.length}`);
+    for (const group of groups) {
+        console.log(`  ${group.name} → ${group.canonicalHash} (${group.canonicalRoot})`);
+        for (const member of group.members) {
+            const mark = member.hash === group.canonicalHash ? "canonical" : "alias";
+            console.log(`    ${member.hash}  ${member.rows} rows  ${mark}  root=${member.root}`);
+        }
+    }
+}
+function parseOnly(args) {
+    const only = [];
+    for (let i = 0; i < args.length; i += 1) {
+        if (args[i] === "--only" && args[i + 1]) {
+            only.push(args[i + 1]);
+            i += 1;
+        }
+    }
+    return only;
+}
+function main() {
+    const args = argv.slice(2);
+    const apply = args.includes("--apply");
+    const dryRun = args.includes("--dry-run") || !apply;
+    const instinctsRoot = resolveInstinctsRoot();
+    const groups = selectGroups(discoverGroups(instinctsRoot), parseOnly(args));
+    printPlan(groups);
+    if (dryRun) {
+        if (groups.length > 0)
+            console.log("\nRe-run with --apply to merge.");
+        return;
+    }
+    for (const group of groups) {
+        const result = applyGroup(instinctsRoot, group);
+        console.log(`merged ${result.copiedRows} rows into ${group.canonicalHash}; aliases ${result.aliases.join(",") || "(none)"}`);
+    }
+}
+const invokedDirectly = argv[1]?.endsWith("reconcile-instinct-hashes.mjs");
+if (invokedDirectly) {
+    try {
+        main();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(message);
+        exit(1);
+    }
+}

package/commands/discipline.md

@@ -19,6 +19,8 @@ Print this card and check yourself against each law.
 | 6 | **Iterate One Change** | Am I changing one thing at a time? | "And also..." |
 | 7 | **Learn From Every Session** | Did I capture this as an instinct? | "Next time I'll..." |
 
+Read the seven as three moments around every act. **Before** (Laws 1, 2): set the terms. **During** (Laws 3, 6): watch yourself. **After** (Laws 4, 5, 7): settle the account and carry it forward. Every check is an audit you run on yourself; every red flag is you hoping instead. The sentence this comes from, and its sources: `docs/philosophy.md`.
+
 ## Operator Stakes
 
 The Laws above are the *how*. These five principles are the *why*: code ships from your account, the incident lands on your pager, the bill hits your budget. Each one pairs with the Law that prevents it from going wrong.
@@ -31,7 +33,7 @@ The Laws above are the *how*. These five principles are the *why*: code ships fr
 | 4 | **Problem framing** | Builds the websocket chat the ticket asked for | Finds out users wanted faster support replies, not chat | 1 |
 | 5 | **Constraints management** | Calls the $0.02/image model on every upload | Does the math, adds client-side validation + caching + cheaper triage model | 2 |
 
-Code is a liability, not an asset. Speed without these five turns into someone else's incident at 3am — except the someone is you.
+Code is a liability, not an asset. Speed without these five turns into someone else's incident at 3am — except the someone is you. The other half of the why is not fear: the session ends and the context is gone, so the only work that survives is what you verified and wrote down for the one who comes after, whether that is tomorrow's session or the engineer who inherits the repo.
 
 ## Goal-Driven Execution maps onto the Laws
 
@@ -61,5 +63,6 @@ Before saying "Done", verify ALL:
 - [ ] I checked the **actual** result (not assumed)
 - [ ] Build passes
 - [ ] I can explain the change in one sentence
+- [ ] For each item above I checked, not hoped
 
-If you're skipping a step, that's the step you need most.
+If you're skipping a step, that's the step you need most. The step you skip is the one you are hoping through.

package/commands/reconcile.md

@@ -95,7 +95,7 @@ git branch -d <type>/<slug>            # delete the merged feature branch (safe
 ## Pairs with
 
 - **`reconcile`** skill — the discipline this command runs.
-- **`gateguard`** / **`safety-guard`** — runtime + destructive-op guardrails.
+- **`gateguard`** — the runtime gate for mutating tool calls and destructive shell.
 - **`recall`** — recall whether the same git op failed here before.
 - **`audit`** — the loop that often produces the fix `/reconcile` then ships.
 - **`/ship`** — the TDD-gated single-defect variant; `commit-commands:commit-push-pr` is the external-plugin equivalent of the commit → PR tail.

package/commands/superpowers.md

@@ -13,7 +13,7 @@ The 7 Laws define *what* discipline must be applied. `/superpowers` decides *whi
 
 | Source | Where it lives | Examples of what it routes to |
 |---|---|---|
-| `continuous-improvement` (this plugin) | bundled — always present | `gateguard` (Law 1), `tdd-workflow` (Law 3+4), `verification-loop` (Law 4), `wild-risa-balance` (Law 2), `safety-guard` (Law 3), `proceed-with-the-recommendation` (all 7), `ralph` (Law 6), `workspace-surface-audit` (Law 1) |
+| `continuous-improvement` (this plugin) | bundled — always present | `gateguard` (Law 1), `tdd-workflow` (Law 3+4), `verification-loop` (Law 4), `wild-risa-balance` (Law 2), `proceed-with-the-recommendation` (all 7), `ralph` (Law 6), `workspace-surface-audit` (Law 1) |
 | `obra/superpowers` (Jesse Vincent) | vendored at `third-party/superpowers/`, pinned SHA `f2cbfbe` (v5.1.0) | `superpowers:brainstorming`, `:writing-plans`, `:executing-plans`, `:test-driven-development`, `:systematic-debugging`, `:requesting-code-review`, `:receiving-code-review`, `:verification-before-completion`, `:dispatching-parallel-agents`, `:using-git-worktrees`, `:finishing-a-development-branch`, `:subagent-driven-development`, `:writing-skills`, `:using-superpowers` |
 | `addyosmani/agent-skills` | vendored at `third-party/addy-agent-skills/`, pinned SHA `742dca5` (v1.0.0) | `spec-driven-development`, `source-driven-development`, `context-engineering`, `idea-refine`, `incremental-implementation`, `code-review-and-quality`, `code-simplification`, `security-and-hardening`, `debugging-and-error-recovery`, `performance-optimization`, `api-and-interface-design`, `frontend-ui-engineering`, `browser-testing-with-devtools`, `ci-cd-and-automation`, `deprecation-and-migration`, `documentation-and-adrs`, `git-workflow-and-versioning`, `planning-and-task-breakdown`, `shipping-and-launch` |
 | `ruflo-swarm` (ruvnet) | vendored at `third-party/ruflo-swarm/`, pinned SHA `addb5cd` (v0.2.0) | `swarm-init`, `monitor-stream`; `swarm_*` and `agent_*` MCP tools; `/swarm`, `/watch` |

package/commands/verify-install.md

@@ -29,9 +29,14 @@ with the text `probe`) **without presenting any research first**.
 
 - If the hook **blocks** the write with a fact-list reason — the runtime layer is
   wired. Record `gateguard: ✓`. Do not retry the write; the block is the pass.
-- If the write **goes through** with no pause — the hook did not load. Record
-  `gateguard: ✗ (hooks/gateguard.mjs not wired — see README → Troubleshooting install)`.
-  Delete the probe file if it was created.
+- If the write **goes through** with no pause — either the hook did not load, or
+  `CI_GATEGUARD_EXCLUDE` is set to a fragment that matches the probe path (a
+  catch-all such as `/` or `.` matches every path and switches the file gate off;
+  the hook prints a one-line stderr notice when an exclusion fires). Run
+  `echo "$CI_GATEGUARD_EXCLUDE"` first. If it is empty, record
+  `gateguard: ✗ (hooks/gateguard.mjs not wired — see README → Troubleshooting install)`;
+  if it is set, record `gateguard: ✗ (excluded by CI_GATEGUARD_EXCLUDE=<value>; unset it or
+  narrow the fragment)`. Delete the probe file if it was created.
 
 ## Check 3 — observation capture recording
 

package/hooks/companion-preference.mjs

@@ -30,10 +30,10 @@
  * suite or a follow-up audit walks the table against this map.
  */
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 const OVERRIDES = {
     "tdd-workflow": {
         companion: "superpowers:test-driven-development",
@@ -125,10 +125,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function telemetryPath(home) {
-    const hash = createHash("sha256")
-        .update(resolveProjectRoot())
-        .digest("hex")
-        .slice(0, 12);
+    const hash = hashProjectRoot(resolveProjectRoot());
     return join(home, ".claude", "instincts", hash, "companion-preference.jsonl");
 }
 /**

package/hooks/config-guard.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Runtime PreToolUse config-guard hook.
+ *
+ * Stdin  : JSON { tool_name, tool_input }
+ * Stdout : empty on allow / warn (warn prints to stderr); on block, the
+ *          documented PreToolUse shape:
+ *          { hookSpecificOutput: { hookEventName: "PreToolUse",
+ *            permissionDecision: "deny", permissionDecisionReason } }
+ * Exit   : 0 always (decision is in stdout; fail-open on any error).
+ *
+ * Guards the files that wire the guardrails: `.claude/settings*.json`,
+ * `.mcp.json`, `hooks.json`, `.claude/hooks/`, `.claude/plugins/`,
+ * `.claude-plugin/`, and the `claude plugin|mcp|config` CLI forms that edit
+ * them. Pure logic in ../lib/config-guard-gate.mjs.
+ *
+ * Mode via CI_CONFIG_GUARD: "warn" (default) | "block" | "off".
+ *   warn  : print a one-line notice to stderr; never blocks.
+ *   block : emit the PreToolUse deny shape.
+ *   off   : no-op.
+ * One-call bypass: CI_CONFIG_GUARD_ALLOW=true allows the call and says so.
+ *
+ * Registered with a tool matcher (Bash|Edit|MultiEdit|Write|NotebookEdit) so
+ * read-only tools never spawn it. No network. No git. Fail-open.
+ */
+import { readFileSync } from "node:fs";
+import { classifyMutation, decide, parseMode } from "../lib/config-guard-gate.mjs";
+function readStdinSync() {
+    try {
+        return readFileSync(0, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function buildReason(toolName, hit, mode) {
+    const what = hit.via === "claude-cli"
+        ? `\`${hit.target}\` edits the plugin / MCP / settings configuration`
+        : `${toolName} would modify ${hit.target} (matches "${hit.pattern}")`;
+    return [
+        `config-guard: ${what}, one of the files that wires the guardrails (settings, MCP config, hooks, installed plugins).`,
+        "If this is intended, rerun this one call with CI_CONFIG_GUARD_ALLOW=true, or set CI_CONFIG_GUARD=off for the session.",
+        mode === "block"
+            ? "You are seeing a deny because CI_CONFIG_GUARD=block; the default is warn."
+            : "This is a warning (CI_CONFIG_GUARD=warn, the default); set CI_CONFIG_GUARD=block to deny instead.",
+    ].join("\n");
+}
+function main() {
+    const mode = parseMode(process.env.CI_CONFIG_GUARD);
+    if (mode === "off")
+        return;
+    const payload = safeJsonParse(readStdinSync());
+    if (!payload || typeof payload !== "object")
+        return;
+    const obj = payload;
+    const toolName = typeof obj.tool_name === "string" ? obj.tool_name : "";
+    const toolInput = obj.tool_input && typeof obj.tool_input === "object" ? obj.tool_input : {};
+    const hit = classifyMutation(toolName, toolInput);
+    if (!hit)
+        return;
+    if (String(process.env.CI_CONFIG_GUARD_ALLOW ?? "").trim().toLowerCase() === "true") {
+        process.stderr.write(`[continuous-improvement] config-guard: CI_CONFIG_GUARD_ALLOW=true let ${toolName} touch ${hit.target} on this call.\n`);
+        return;
+    }
+    const decision = decide(mode, true, buildReason(toolName, hit, mode));
+    if (decision.action === "block") {
+        process.stdout.write(`${JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: decision.reason,
+            },
+        })}\n`);
+        return;
+    }
+    if (decision.action === "warn") {
+        process.stderr.write(`[continuous-improvement] ${decision.reason.split("\n")[0]}\n`);
+    }
+}
+try {
+    main();
+}
+catch {
+    // fail-open: never block a session on a hook error
+}
+process.exit(0);

package/hooks/gateguard.mjs

@@ -35,6 +35,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { classifyDestructiveBash } from "../lib/destructive-bash.mjs";
 import { MAX_CLEARED_FILES, canonicalizeFileKey, canonicalizeProjectRoot, isCapReached, isFileCleared, loadState, markFileCleared, resolveProjectRoot, resolveSessionDir, saveState, } from "../lib/gateguard-state.mjs";
 const TOOL_ROUTE = {
     Read: "allow",
@@ -48,42 +49,14 @@ const TOOL_ROUTE = {
     NotebookEdit: "mutating-file",
     Bash: "allow",
 };
-const DESTRUCTIVE_PATTERNS = [
-    "rm -rf",
-    "rm -fr",
-    "git reset --hard",
-    "git push --force",
-    "git push -f",
-    "--force-with-lease",
-    "git branch -D",
-    "drop table",
-    "drop database",
-    "drop schema",
-    "truncate ",
-    "mkfs",
-    "dd if=",
-    "format ",
-    "rmdir /s",
-    "del /f /q",
-    "del /q /f",
-    "Remove-Item -Recurse",
-    "Remove-Item -Force",
-];
-// Flags whose VALUE is human prose (a commit message, a PR body) or a filename —
-// never a command to execute. Their contents must not trip the destructive scan:
-// `git commit -m "drop the stale format helper"` and `gh pr create --body "…"`
-// were stranding finished work on their own wording. `-c` is deliberately
-// EXCLUDED — `bash -c "rm -rf /"` carries a real command and must still gate.
-const MESSAGE_FLAG_RE = /(^|\s)(-m|--message|-F|--file|--body|--body-file|--title|--notes|-C|--reuse-message)(=|\s+)('[^']*'|"[^"]*"|\S+)/g;
-// Blank the value of every message/body flag so only executable command syntax
-// remains for the destructive-pattern scan. The flag itself is preserved so a
-// flag like `-F` never accidentally merges with its neighbours.
-function stripMessageArgs(command) {
-    return command.replace(MESSAGE_FLAG_RE, (_match, lead, flag) => `${lead}${flag} `);
-}
+// The destructive-Bash classifier lives in lib/destructive-bash.mjs: structured
+// rules (flag order and spelling do not matter: `rm -r -f`, `git clean -fdx`,
+// `git checkout -- .`, `git restore .`, `find -delete`, `git push +ref`,
+// `git stash drop`) plus the original substring list as the fallback. The
+// message-flag carve-out (`git commit -m "…"`) lives there too. Each rule has
+// a stable id the deny reason prints, so a block is explainable.
 function isDestructiveBash(command) {
-    const lower = stripMessageArgs(command).toLowerCase();
-    return DESTRUCTIVE_PATTERNS.some((p) => lower.includes(p.toLowerCase()));
+    return classifyDestructiveBash(command).destructive;
 }
 function classifyTool(toolName, toolInput) {
     const route = TOOL_ROUTE[toolName] ?? "allow";
@@ -119,12 +92,34 @@ const EXCLUDE_FRAGMENTS = String(process.env.CI_GATEGUARD_EXCLUDE ?? "")
     .split(",")
     .map((fragment) => fragment.trim().replace(/\\/g, "/").toLowerCase())
     .filter((fragment) => fragment !== "");
-function isExcludedPath(filePath) {
+function matchedExcludeFragment(filePath) {
     if (EXCLUDE_FRAGMENTS.length === 0 || typeof filePath !== "string" || filePath === "") {
-        return false;
+        return null;
     }
     const normalized = filePath.replace(/\\/g, "/").toLowerCase();
-    return EXCLUDE_FRAGMENTS.some((fragment) => normalized.includes(fragment));
+    return EXCLUDE_FRAGMENTS.find((fragment) => normalized.includes(fragment)) ?? null;
+}
+function isExcludedPath(filePath) {
+    return matchedExcludeFragment(filePath) !== null;
+}
+// A fragment every path contains ("/", ".", any single character) is not an
+// exclusion, it is an off switch for the whole file gate. It is still honoured —
+// the operator set it — but silently honouring it is how a host ends up with the
+// headline feature off and nobody noticing (this repo's own author's shell had
+// CI_GATEGUARD_EXCLUDE="/,." for weeks). So every exclusion prints one stderr
+// line, and a catch-all says plainly that the gate is off. stderr never changes
+// the decision: allow stays empty stdout + exit 0.
+function isCatchAllFragment(fragment) {
+    return fragment.length <= 1 || fragment === "./" || fragment === "..";
+}
+function buildExcludeNotice(paths, fragment) {
+    const shown = paths.map((p) => p.replace(/\\/g, "/")).join(", ");
+    if (isCatchAllFragment(fragment)) {
+        return (`[continuous-improvement] gateguard: CI_GATEGUARD_EXCLUDE fragment "${fragment}" matches every path, ` +
+            `so the file gate is off for this session (skipped ${shown}). ` +
+            "Narrow it to a directory, e.g. CI_GATEGUARD_EXCLUDE=docs/wiki, to get the gate back.");
+    }
+    return `[continuous-improvement] gateguard: skipped by CI_GATEGUARD_EXCLUDE (fragment "${fragment}" matched ${shown}).`;
 }
 // --- Target lock (opt-in) --------------------------------------------------
 // A fact-list can't catch a wrong-repo / wrong-worktree write — you can present
@@ -271,6 +266,7 @@ function buildBraceRefReason(hit) {
     ].join("\n");
 }
 function buildDestructiveBashReason(command) {
+    const rule = classifyDestructiveBash(command).rule ?? "unknown";
     return [
         `Destructive command requested: ${command}`,
         "",
@@ -278,6 +274,7 @@ function buildDestructiveBashReason(command) {
         "  2. Write a one-line rollback procedure",
         "  3. Quote the user's current instruction verbatim",
         "",
+        `Matched rule: ${rule}`,
         "Destructive Bash gates EVERY call — clearance is not cached.",
     ].join("\n");
 }
@@ -354,7 +351,10 @@ function main() {
     const allTargetPaths = extractFilePaths(toolInput);
     const filePaths = allTargetPaths.filter((path) => !isExcludedPath(path));
     if (allTargetPaths.length > 0 && filePaths.length === 0) {
-        emitAllow(); // every target is under a CI_GATEGUARD_EXCLUDE path; skip the gate
+        // Every target is under a CI_GATEGUARD_EXCLUDE path; skip the gate, but say so.
+        const fragment = matchedExcludeFragment(allTargetPaths[0]) ?? EXCLUDE_FRAGMENTS[0];
+        process.stderr.write(`${buildExcludeNotice(allTargetPaths, fragment)}\n`);
+        emitAllow();
         return;
     }
     // Target lock runs before the fact gate and independent of clearance: a

package/hooks/goal-drift-stop.mjs

@@ -17,10 +17,10 @@
 // construction: any error / missing goal / unreadable observations exits 0 and
 // never blocks. No network. 5s hook budget.
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { evaluateGoalDrift } from "../lib/goal-drift-gate.mjs";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
 function readStdinSync() {
     try {
@@ -62,7 +62,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function projectHash(root) {
-    return createHash("sha256").update(root).digest("hex").slice(0, 12);
+    return hashProjectRoot(root);
 }
 function readGoalMarkdown(projectRoot, instinctsProjectDir) {
     const candidates = [join(projectRoot, "task_plan.md"), join(instinctsProjectDir, "goal.md")];

package/hooks/query-cost-nudge.mjs

@@ -16,7 +16,7 @@
  * the DB files stay dirty. Never blocks; fail-open on any error.
  */
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -71,7 +71,7 @@ function markerKey(sessionId) {
     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);
+    const hash = hashProjectRoot(projectRoot);
     return join(home, ".claude", "instincts", hash, "query-cost-nudge", `${markerKey(sessionId)}.nudged`);
 }
 function main() {

package/hooks/recall-briefing.mjs

@@ -23,13 +23,13 @@
  * ~/.claude/instincts/<project-hash>/recall-briefing-session.json records which
  * session_ids have been briefed so each session is briefed at most once.
  */
-import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { buildIndex, query } from "../lib/recall-index.mjs";
 import { DEFAULT_MAX_HITS, decideBriefing } from "../lib/recall-briefing.mjs";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 const ENABLED_VALUES = new Set(["1", "on", "true", "yes"]);
 const MAX_BRIEFED_KEYS = 1000;
 function isEnabled() {
@@ -65,7 +65,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function instinctsDir(home) {
-    const hash = createHash("sha256").update(resolveProjectRoot()).digest("hex").slice(0, 12);
+    const hash = hashProjectRoot(resolveProjectRoot());
     return join(home, ".claude", "instincts", hash);
 }
 function readObservations(dir) {

package/hooks/route-prompt.mjs

@@ -30,12 +30,12 @@
  *   }
  * Rows are evaluated in order; first match wins.
  */
-import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 function readStdin() {
     try {
         return readFileSync(0, "utf8");
@@ -65,10 +65,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function telemetryPath(home) {
-    const hash = createHash("sha256")
-        .update(resolveProjectRoot())
-        .digest("hex")
-        .slice(0, 12);
+    const hash = hashProjectRoot(resolveProjectRoot());
     return join(home, ".claude", "instincts", hash, "route-prompt.jsonl");
 }
 function writeTelemetry(home, event) {

package/hooks/session.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
 function read(path) {
     try {
@@ -62,7 +62,7 @@ function main() {
     if (!home)
         return;
     const instinctsRoot = join(home, ".claude", "instincts");
-    const hash = createHash("sha256").update(projectRoot()).digest("hex").slice(0, 12);
+    const hash = hashProjectRoot(projectRoot());
     const projectDir = join(instinctsRoot, hash);
     const files = [...yamlFiles(projectDir), ...yamlFiles(join(instinctsRoot, "global"))];
     const observations = read(join(projectDir, "observations.jsonl")).split(/\r?\n/).filter(Boolean).length;

package/hooks/workflow-distill.mjs

@@ -24,9 +24,9 @@
 // name + verify command, so a run is nudged at most once. Fail-open by
 // construction: any error exits 0 and never blocks. No network. 5s hook budget.
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { resolveHomeDir } from "../lib/resolve-home-dir.mjs";
 import { workflowRunFromObservations } from "../lib/skill-distill.mjs";
 function safeJsonParse(text) {
@@ -60,7 +60,7 @@ function resolveProjectRoot() {
     return "global";
 }
 function projectHash(root) {
-    return createHash("sha256").update(root).digest("hex").slice(0, 12);
+    return hashProjectRoot(root);
 }
 function readObservations(instinctsProjectDir) {
     const file = join(instinctsProjectDir, "observations.jsonl");