continuous-improvement 3.23.0 → 3.24.0

package/lib/skill-catalog.mjs

@@ -0,0 +1,169 @@
+/**
+ * Skill -> enforcing hook filename. Explicit because hook filenames describe
+ * the event they fire on, not the skill they serve. Adding a hook without
+ * adding its row here makes the catalog under-claim, which is the safe
+ * direction.
+ */
+export const HOOK_BY_SKILL = {
+    gateguard: "gateguard.mjs",
+    "goal-monitor": "goal-drift-stop.mjs",
+    recall: "recall-briefing.mjs",
+    superpowers: "companion-preference.mjs",
+    "verification-loop": "typecheck-stop.mjs",
+    "skill-distillation": "workflow-distill.mjs",
+};
+const TIER_LABEL = {
+    core: "Core",
+    featured: "Featured",
+    "1": "Tier 1 — beginner",
+    "2": "Tier 2 — expert",
+    companion: "Always bundled",
+    unknown: "Unclassified",
+};
+const TIER_ORDER = ["core", "featured", "1", "2", "companion", "unknown"];
+const ENFORCEMENT_TITLE = {
+    hook: "Enforced at the tool boundary by a hook — it fires whether or not the model cooperates.",
+    command: "Invoked by a slash command. Runs when you ask for it.",
+    prose: "Model-side discipline only. Nothing blocks and nothing fires automatically.",
+};
+/** Lift the Law tag out of a Law-tagged description. */
+export function lawOf(description) {
+    if (!description)
+        return undefined;
+    if (/\ball\s+7\s+Laws\b/i.test(description))
+        return "all 7";
+    if (/\bLaw\s+activator\b/i.test(description))
+        return "activator";
+    const multi = description.match(/\bLaw\s*([1-7])\s*\+\s*([1-7])\b/i);
+    if (multi)
+        return `${multi[1]} + ${multi[2]}`;
+    const single = description.match(/\bLaw\s*([1-7])\b/i);
+    return single ? single[1] : undefined;
+}
+/** Resolve the enforcement surface for one skill from the shipped file set. */
+export function enforcementOf(name, commandNames) {
+    const hookFile = HOOK_BY_SKILL[name];
+    if (hookFile)
+        return { enforcement: "hook", hookFile };
+    if (commandNames.has(name))
+        return { enforcement: "command" };
+    return { enforcement: "prose" };
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** Strip the "Enforces Law N (…) of the 7 Laws…" preamble; keep what it does. */
+export function summarize(description) {
+    if (!description)
+        return "";
+    return description
+        .replace(/^Enforces\s+(all\s+7\s+Laws|Law\s*[1-7](\s*\+\s*[1-7])?)[^.]*\.\s*/i, "")
+        .replace(/^Use this skill to\s*/i, "")
+        .trim();
+}
+const STYLE = `
+:root { color-scheme: light dark; --bg:#fbfbfa; --fg:#1a1a19; --muted:#6b6b66;
+  --line:#e3e3df; --card:#fff; --hook:#0f6f4b; --hookbg:#e4f3ec;
+  --cmd:#1b4f8a; --cmdbg:#e5eefa; --prose:#8a5a12; --prosebg:#faf0dc; }
+@media (prefers-color-scheme: dark) { :root { --bg:#121211; --fg:#ececeb;
+  --muted:#9a9a94; --line:#2c2c29; --card:#1b1b1a; --hook:#6fd3a8; --hookbg:#12332a;
+  --cmd:#8fbdf0; --cmdbg:#132840; --prose:#e3b464; --prosebg:#3a2c12; } }
+:root[data-theme="dark"] { --bg:#121211; --fg:#ececeb; --muted:#9a9a94; --line:#2c2c29;
+  --card:#1b1b1a; --hook:#6fd3a8; --hookbg:#12332a; --cmd:#8fbdf0; --cmdbg:#132840;
+  --prose:#e3b464; --prosebg:#3a2c12; }
+:root[data-theme="light"] { --bg:#fbfbfa; --fg:#1a1a19; --muted:#6b6b66; --line:#e3e3df;
+  --card:#fff; --hook:#0f6f4b; --hookbg:#e4f3ec; --cmd:#1b4f8a; --cmdbg:#e5eefa;
+  --prose:#8a5a12; --prosebg:#faf0dc; }
+body { margin:0; padding:2.5rem 1.25rem 4rem; background:var(--bg); color:var(--fg);
+  font:16px/1.6 ui-sans-serif,-apple-system,"Segoe UI",Roboto,sans-serif; }
+.wrap { max-width:70rem; margin:0 auto; }
+h1 { font-size:1.75rem; margin:0 0 .35rem; letter-spacing:-.015em; }
+.sub { color:var(--muted); margin:0 0 1.25rem; max-width:52rem; }
+h2 { font-size:1rem; text-transform:uppercase; letter-spacing:.08em; color:var(--muted);
+  margin:2.5rem 0 .75rem; font-weight:600; }
+.legend { display:flex; flex-wrap:wrap; gap:1rem; margin:0 0 1rem; padding:0; list-style:none; }
+.legend li { color:var(--muted); font-size:.85rem; }
+.scroll { overflow-x:auto; border:1px solid var(--line); border-radius:.6rem; background:var(--card); }
+table { border-collapse:collapse; width:100%; min-width:44rem; }
+th, td { text-align:left; padding:.7rem .85rem; border-bottom:1px solid var(--line); vertical-align:top; }
+th { font-size:.78rem; text-transform:uppercase; letter-spacing:.06em; color:var(--muted); font-weight:600; }
+tr:last-child td { border-bottom:0; }
+td.name { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.88rem; white-space:nowrap; }
+td.law { color:var(--muted); white-space:nowrap; font-variant-numeric:tabular-nums; }
+td.what { min-width:22rem; }
+.badge { display:inline-block; padding:.12rem .5rem; border-radius:1rem; font-size:.75rem;
+  font-weight:600; white-space:nowrap; }
+.badge.hook { color:var(--hook); background:var(--hookbg); }
+.badge.command { color:var(--cmd); background:var(--cmdbg); }
+.badge.prose { color:var(--prose); background:var(--prosebg); }
+.hookfile { display:block; margin-top:.25rem; font-family:ui-monospace,monospace;
+  font-size:.72rem; color:var(--muted); }
+footer { margin-top:3rem; color:var(--muted); font-size:.85rem; max-width:52rem; }
+code { font-family:ui-monospace,monospace; font-size:.9em; }
+`;
+/**
+ * Render the full catalog page. Pure — takes the resolved skill list and
+ * returns the complete HTML document.
+ */
+export function renderSkillCatalogHtml(skills) {
+    const counts = { hook: 0, command: 0, prose: 0 };
+    for (const s of skills)
+        counts[s.enforcement]++;
+    const sections = [];
+    for (const tier of TIER_ORDER) {
+        const rows = skills.filter((s) => s.tier === tier);
+        if (rows.length === 0)
+            continue;
+        const body = rows
+            .map((s) => {
+            const badge = `<span class="badge ${s.enforcement}" title="${escapeHtml(ENFORCEMENT_TITLE[s.enforcement])}">` +
+                `${s.enforcement}</span>` +
+                (s.hookFile ? `<span class="hookfile">hooks/${escapeHtml(s.hookFile)}</span>` : "");
+            return ("        <tr>" +
+                `<td class="name">${escapeHtml(s.name)}</td>` +
+                `<td class="law">${escapeHtml(s.law ?? "—")}</td>` +
+                `<td>${badge}</td>` +
+                `<td class="what">${escapeHtml(summarize(s.description))}</td>` +
+                "</tr>");
+        })
+            .join("\n");
+        sections.push(`    <h2>${escapeHtml(TIER_LABEL[tier])} (${rows.length})</h2>\n` +
+            '    <div class="scroll">\n      <table>\n' +
+            "        <thead><tr><th>Skill</th><th>Law</th><th>Enforcement</th><th>What it does</th></tr></thead>\n" +
+            `        <tbody>\n${body}\n        </tbody>\n` +
+            "      </table>\n    </div>");
+    }
+    return [
+        "<!doctype html>",
+        '<html lang="en">',
+        "<head>",
+        '  <meta charset="utf-8">',
+        '  <meta name="viewport" content="width=device-width,initial-scale=1">',
+        `  <title>Skill catalog — continuous-improvement (${skills.length} skills)</title>`,
+        "  <!-- GENERATED by npm run build from skills/*.md frontmatter. Do not edit by hand. -->",
+        `  <style>${STYLE}  </style>`,
+        "</head>",
+        "<body>",
+        '  <div class="wrap">',
+        "    <h1>Skill catalog</h1>",
+        `    <p class="sub">${skills.length} bundled skills, generated from <code>skills/*.md</code> frontmatter. ` +
+            "The <strong>Enforcement</strong> column is the point of this page: it states what actually backs each skill, " +
+            "derived from the shipped file set rather than from the skill's own prose. " +
+            `Today ${counts.hook} are enforced by a hook, ${counts.command} by a slash command, and ${counts.prose} by model-side discipline alone.</p>`,
+        '    <ul class="legend">',
+        '      <li><span class="badge hook">hook</span> fires at the tool boundary; model cooperation not required</li>',
+        '      <li><span class="badge command">command</span> runs when you invoke it</li>',
+        '      <li><span class="badge prose">prose</span> model-side discipline only — nothing blocks</li>',
+        "    </ul>",
+        sections.join("\n"),
+        '    <footer>A skill may only claim enforcement it ships. A <span class="badge prose">prose</span> skill that describes a runtime gate is a bug — that is what retired <code>safety-guard</code> on 2026-08-07. See <code>docs/plans/2026-08-07-six-rules-context-engineering.md</code>.</footer>',
+        "  </div>",
+        "</body>",
+        "</html>",
+        "",
+    ].join("\n");
+}

package/llms.txt

@@ -1,11 +1,22 @@
 # continuous-improvement
 
-> 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 29 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.
+> 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 28 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.
 
 ## What This Is
 
 The persistent-memory and discipline layer for AI coding agents. It carries the corrections Claude has already received from one session into the next, grounds each edit in real facts before it lands, and learns from every session so its competence compounds over time — research, plan, execute one thing at a time, verify, reflect, iterate, learn — building behavioral instincts via the Mulahazah learning system, so the same correction never has to be given twice and each run starts smarter than the last. Orchestration tools run a task; this is the layer that makes the lessons survive the run.
 
+Why these seven: every red flag an agent says ("this should work", "I'll remember", "next time I'll") is a wish standing in for a check. The Laws are one old sentence turned into checks an agent can run on itself: the wise one takes account of himself and works for what comes after; the weak one follows his impulse and merely wishes (Jami` at-Tirmidhi 2459). Before saying done: did I check, or did I hope? Sources and the mapping to each Law: docs/philosophy.md.
+
+What the gate can and cannot do: hooks/gateguard.mjs denies the first Edit/Write/MultiEdit per file until a four-item fact list is presented and the printed clear command is run (honor system, 50 files per session); destructive Bash on a fixed blocklist is denied on every call with no clearance route; Bash file writes are not gated. Goal-drift warns by default (CLAUDE_GOAL_DRIFT_GATE=block to refuse), typecheck gate and recall briefing are opt-in.
+
+Smarter models do not retire this product. Planning etiquette and "remember to verify" reminders merge into the model over time. The runtime gate, this-repo memory, and proof that a change worked do not. Keep goal-driven execution plus research / verify / learn guardrails; retire scaffolding when the native harness covers it (see skills/model-forward.md).
+
+How you actually benefit:
+1. Beginner install (or `npx continuous-improvement install`) — gateguard fires on Edit/Write; no prompt prefix required.
+2. After a real session run `/seven-laws` — capture is silent; instincts form when you close the loop. `/recall` for "have I hit this before?". `/planning-with-files` writes `task_plan.md`.
+3. Expert mode for MCP tools, `/harvest`, `/distill`, and optional `CLAUDE_RECALL_BRIEFING=1`. Empty harvest/distill on day 1 means missing observation history, not a broken command.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "continuous-improvement",
-  "version": "3.23.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 29 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.",
+  "version": "3.24.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 28 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",
     "claude-code-plugin",

package/plugins/beginner.json

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

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

@@ -7,8 +7,8 @@
   "plugins": [
     {
       "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 29 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.23.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 28 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.24.0",
       "source": "./",
       "author": {
         "name": "naimkatiman"

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

@@ -1,7 +1,7 @@
 {
   "name": "continuous-improvement",
-  "version": "3.23.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 29 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.24.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 28 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",
     "url": "https://github.com/naimkatiman"

package/plugins/continuous-improvement/README.md

@@ -36,8 +36,7 @@ the trade-off is fallback quality vs dedicated-skill quality.
 - `tdd-workflow` — RED/GREEN/REFACTOR + 80% coverage gate
 - `workspace-surface-audit` — environment + capability audit
 - Tier-1/Tier-2 enforcement skills (`gateguard`, `verification-loop`,
-  `safety-guard`, `token-budget-advisor`,
-  `strategic-compact`, `wild-risa-balance`)
+  `token-budget-advisor`, `strategic-compact`, `wild-risa-balance`)
 
 **Optional companions the orchestrator routes to (install separately if
 you want the dedicated skill instead of the inline fallback):**

package/plugins/continuous-improvement/bin/mcp-server.mjs

@@ -16,12 +16,11 @@ import { homedir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
-import { createHash } from "node:crypto";
 import { PACKAGE_NAME, VERSION, getToolDefinitions, isPluginMode, } from "../lib/plugin-metadata.mjs";
 import { formatDriftReport, parseGoalFromPlan, scoreObservations, } from "../lib/goal-state.mjs";
 import { buildIndex, formatRecallHits, parseSince, query as queryRecall, } from "../lib/recall-index.mjs";
 import { draftFromCandidate, draftFromWorkflowRun, extractTrajectories, findCandidates, formatCandidates, serializeDraft, workflowRunFromObservations, } from "../lib/skill-distill.mjs";
-import { MAX_CLEARED_FILES, canonicalizeFileKey, clearFiles, resolveInstinctsRoot, resolveSessionDir, } from "../lib/gateguard-state.mjs";
+import { MAX_CLEARED_FILES, canonicalizeFileKey, clearFiles, hashProjectRoot, resolveInstinctsRoot, resolveProjectRoot, resolveSessionDir, } from "../lib/gateguard-state.mjs";
 function getHomeDir() {
     return process.env.HOME || process.env.USERPROFILE || homedir();
 }
@@ -93,14 +92,10 @@ const modeIndex = args.indexOf("--mode");
 const requestedMode = args[modeIndex + 1];
 const MODE = isPluginMode(requestedMode) ? requestedMode : "beginner";
 function getProjectHash() {
-    try {
-        const root = execSync("git rev-parse --show-toplevel 2>/dev/null", { encoding: "utf8" }).trim();
-        const hash = createHash("sha256").update(root).digest("hex").slice(0, 12);
-        return { root, hash, name: basename(root) };
-    }
-    catch {
+    const root = resolveProjectRoot();
+    if (root === "global")
         return { root: "global", hash: "global", name: "global" };
-    }
+    return { root, hash: hashProjectRoot(root), name: basename(root) };
 }
 function readInstincts(projectHash) {
     const instincts = [];

package/plugins/continuous-improvement/bin/observe.mjs

@@ -16,10 +16,10 @@
 //
 // See docs/plans/2026-05-05-node-observer-rich-schema.md for the full design.
 import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
+import { canonicalizeProjectRoot, hashProjectRoot } from "../lib/gateguard-state.mjs";
 import { parseHookPayload, summariseInput, summariseOutput } from "../lib/observe-event.mjs";
 const ROTATION_LINE_THRESHOLD = 10_000;
 const ARCHIVE_RETENTION = 10;
@@ -40,8 +40,8 @@ function runObserver() {
     const payload = parseHookPayload(raw);
     if (!payload)
         return;
-    const projectRoot = resolveProjectRoot();
-    const projectHash = createHash("sha256").update(projectRoot).digest("hex").slice(0, 12);
+    const projectRoot = canonicalizeProjectRoot(resolveProjectRoot());
+    const projectHash = hashProjectRoot(projectRoot);
     const projectName = basename(projectRoot.replace(/\.git$/, ""));
     const instinctsDir = join(getHomeDir(), ".claude", "instincts");
     const projectDir = join(instinctsDir, projectHash);

package/plugins/continuous-improvement/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/plugins/continuous-improvement/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/plugins/continuous-improvement/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/plugins/continuous-improvement/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/plugins/continuous-improvement/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/plugins/continuous-improvement/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/plugins/continuous-improvement/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