continuous-improvement 3.11.0 → 3.15.0

package/lib/gateguard-state.mjs

@@ -2,20 +2,25 @@
  * Gateguard per-session state.
  *
  * State file: <sessionDir>/gateguard-session.json. sessionDir resolves to
- * GATEGUARD_SESSION_DIR (env override, used by tests) or
- * ~/.claude/instincts/<projectHash>/ in production.
+ * GATEGUARD_SESSION_DIR (env override, used by tests), or in production to
+ * ~/.claude/instincts/<projectHash>/sessions/<sessionId>/ when the hook passes
+ * the stdin session_id, falling back to ~/.claude/instincts/<projectHash>/ when
+ * no session id is available. Per-session scoping is what stops the clearance
+ * cap from bleeding across concurrent same-day sessions on a multi-Claude host.
  *
- * V1 limitations (documented for honesty, not mitigated in code):
+ * Limitations and guarantees:
  * - Honor system: clearance is granted whenever the agent sets
  *   `_gateguard_facts_presented: true` in tool_input or has a prior per-file
  *   marker. The hook cannot verify that real investigation occurred.
  * - State-file deletion: rm'ing the state file resets every gate in the
- *   session. Defensible because the session itself is the trust boundary;
- *   the cap below limits cumulative damage.
+ *   session. Defensible because the session is the trust boundary — and with
+ *   per-session scoping that boundary is now real, not just asserted.
+ * - Self-heal: loadState treats a file older than STATE_TTL_MS (or one with an
+ *   unparseable created_at) as empty, so a stale gate never needs a manual rm.
  * - Concurrency: two parallel hook invocations can race the read+write.
  *   Acceptable trade-off vs OS-specific atomic-rename complexity on Windows.
- * - Cap: MAX_CLEARED_FILES caps the number of distinct files a single
- *   session can clear, bounding stuck-loop / rogue-agent damage.
+ * - Cap: MAX_CLEARED_FILES caps the distinct files ONE session can clear,
+ *   bounding stuck-loop / rogue-agent damage without affecting other sessions.
  */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -23,14 +28,36 @@ import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 export const MAX_CLEARED_FILES = 50;
-export function resolveSessionDir() {
+// A clearance file whose created_at is older than this self-heals to empty on
+// the next load, so a stale gate never needs a manual rm. Long enough not to
+// reset an active session mid-work; the real cross-session fix is the
+// per-session dir in resolveSessionDir below.
+export const STATE_TTL_MS = 12 * 60 * 60 * 1000; // 12h
+// The root that holds every project's gateguard + instinct state. The MCP
+// clearance route uses this to bound a caller-supplied state_path to this tree
+// so a hostile argument can't turn the clear into an arbitrary-write primitive.
+export function resolveInstinctsRoot() {
+    const home = process.env.HOME || process.env.USERPROFILE || homedir();
+    return join(home, ".claude", "instincts");
+}
+export function resolveSessionDir(sessionId) {
     const fromEnv = process.env.GATEGUARD_SESSION_DIR;
     if (fromEnv)
         return fromEnv;
-    const home = process.env.HOME || process.env.USERPROFILE || homedir();
     const projectRoot = resolveProjectRoot();
     const projectHash = createHash("sha256").update(canonicalizeProjectRoot(projectRoot)).digest("hex").slice(0, 12);
-    return join(home, ".claude", "instincts", projectHash);
+    const base = join(resolveInstinctsRoot(), projectHash);
+    const scoped = sanitizeSessionId(sessionId);
+    return scoped ? join(base, "sessions", scoped) : base;
+}
+// A session id flows into a directory name. Strip anything outside a safe
+// alphabet so a hostile or malformed id can't traverse (`../`) or break the
+// path, and cap the length. Returns "" for an absent/empty id, which the caller
+// treats as "no session" — the legacy unscoped dir, preserving back-compat.
+function sanitizeSessionId(sessionId) {
+    if (!sessionId)
+        return "";
+    return sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
 }
 function resolveProjectRoot() {
     const fromEnv = process.env.CLAUDE_PROJECT_DIR;
@@ -49,21 +76,43 @@ function resolveProjectRoot() {
     }
     return "global";
 }
+function freshState() {
+    return { created_at: new Date().toISOString(), cleared_files: {} };
+}
+// A clearance file self-heals to empty once it ages out of STATE_TTL_MS, so a
+// stale gate never needs a manual rm. An unparseable created_at fails closed
+// (treated as expired) rather than living forever as a never-resetting gate.
+function isExpired(createdAt) {
+    const created = Date.parse(createdAt);
+    if (Number.isNaN(created))
+        return true;
+    return Date.now() - created > STATE_TTL_MS;
+}
 export function loadState(sessionDir) {
     const path = join(sessionDir, "gateguard-session.json");
     if (!existsSync(path)) {
-        return { created_at: new Date().toISOString(), cleared_files: {} };
+        return freshState();
     }
     try {
         const raw = readFileSync(path, "utf8");
         const parsed = JSON.parse(raw);
+        // Absent created_at is treated as expired (fail closed), like an unparseable
+        // one — never a never-resetting gate. On expiry we persist the new epoch
+        // immediately so the cap re-applies from zero on the very next load;
+        // otherwise every load before the next clear would independently reset and a
+        // TTL-crossing session could clear well past MAX_CLEARED_FILES.
+        if (!parsed.created_at || isExpired(parsed.created_at)) {
+            const reset = freshState();
+            saveState(sessionDir, reset);
+            return reset;
+        }
         return {
-            created_at: parsed.created_at ?? new Date().toISOString(),
+            created_at: parsed.created_at,
             cleared_files: parsed.cleared_files ?? {},
         };
     }
     catch {
-        return { created_at: new Date().toISOString(), cleared_files: {} };
+        return freshState();
     }
 }
 export function saveState(sessionDir, state) {

package/lib/goal-state.mjs

@@ -19,11 +19,15 @@ const STOPWORDS = new Set([
     "make", "made", "adds", "new", "get", "got", "set", "also", "only", "each",
     "task", "goal", "plan", "work", "working", "build", "building", "code",
 ]);
-// 4 suits Latin/Cyrillic prose, but it silently drops most Korean/Thai words
-// (typically 2 chars) even though the Unicode splitter now keeps them — so the
-// goal-state half of the tokenizer fix is only partial for those scripts. A
-// script-aware floor is a logged follow-up (see CLAUDE.md Deferred).
+// 4 suits Latin/Cyrillic/Thai prose (Thai combining marks are now kept; see
+// extractKeywordsFromProse regex). Korean Hangul words are typically 2-3 chars
+// but represent full concepts, so they get a script-aware floor of 2.
 const KEYWORD_MIN_LENGTH = 4;
+function keywordMinLengthFor(word) {
+    if (/\p{Script=Hangul}/u.test(word))
+        return 2;
+    return KEYWORD_MIN_LENGTH;
+}
 const KEYWORD_CAP = 20;
 const DEFAULT_WINDOW = 30;
 const DEFAULT_THRESHOLD = 0.3;
@@ -52,16 +56,16 @@ export function getSection(markdown, heading) {
 }
 /**
  * Tokenize prose into goal keywords: lowercase, split on any non-letter /
- * non-number (Unicode-aware, so accented Latin / Cyrillic / CJK survive), drop
- * stopwords, pure-digit tokens, and tokens shorter than KEYWORD_MIN_LENGTH.
- * Deduped, capped at KEYWORD_CAP.
+ * non-number / non-mark (Unicode-aware, so accented Latin / Cyrillic / CJK /
+ * Thai survive), drop stopwords, pure-digit tokens, and tokens shorter than
+ * KEYWORD_MIN_LENGTH. Deduped, capped at KEYWORD_CAP.
  */
 export function extractKeywordsFromProse(prose) {
     const seen = new Set();
     const out = [];
-    for (const raw of prose.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    for (const raw of prose.toLowerCase().split(/[^\p{L}\p{N}\p{M}]+/u)) {
         const word = raw.trim();
-        if (word.length < KEYWORD_MIN_LENGTH)
+        if (word.length < keywordMinLengthFor(word))
             continue;
         if (/^\p{N}+$/u.test(word))
             continue;

package/lib/hook-pack-gate.mjs

@@ -0,0 +1,65 @@
+// hook-pack-gate.mts — Pure decision core for the enforcing-hook pack (v1).
+//
+// No I/O. Given a raw Bash command string, the resolved current branch, the
+// staged-file count, and the operator's mode, decide allow / warn / block.
+// The hook (src/hooks/hook-pack.mts) wires stdin + git subprocess calls around
+// these functions; keeping them pure lets the unit tests cover every branch
+// without spawning anything. Lives in lib/ so tests can import it (the
+// test-imports-only invariant forbids importing from hooks/).
+//
+// Fail-open by construction: callers pass safe defaults (null branch, 0 staged)
+// on any failure, and an unrecognized mode resolves to warn.
+export const COMMIT_FILE_LIMIT = 15;
+const ALLOW = { action: "allow", reason: "" };
+export function parseMode(raw) {
+    const v = (raw ?? "warn").trim().toLowerCase();
+    return v === "block" || v === "off" ? v : "warn";
+}
+// Match `git push` / `git commit` at the start of the command or immediately
+// after a shell separator (newline, ;, |, &). This deliberately does NOT match
+// a mention like `echo git push`, where git is an argument, not the command.
+export function classifyCommand(command) {
+    if (/(?:^|[\n;|&])\s*git\s+push\b/.test(command))
+        return "push";
+    if (/(?:^|[\n;|&])\s*git\s+commit\b/.test(command))
+        return "commit";
+    return "other";
+}
+export function isProtectedBranch(branch) {
+    return branch === "main" || branch === "master" || /^release\//.test(branch);
+}
+// Extract the explicit destination branch of a `git push`, or null when none is
+// given (the caller should then fall back to the current branch). Handles
+// `git push <remote> <branch>`, `git push -u <remote> <branch>`, and refspecs
+// like `HEAD:main` (destination after the colon).
+function parsePushTarget(command) {
+    const tokens = command.split(/\s+/).filter(Boolean);
+    const pushIdx = tokens.findIndex((t, i) => t === "push" && tokens[i - 1] === "git");
+    if (pushIdx === -1)
+        return null;
+    const operands = tokens.slice(pushIdx + 1).filter((t) => !t.startsWith("-"));
+    // operands[0] is the remote; operands[1] is the refspec. Fewer than two means
+    // no explicit branch (e.g. `git push` or `git push origin`).
+    if (operands.length < 2)
+        return null;
+    const refspec = operands[1];
+    return refspec.includes(":") ? (refspec.split(":").pop() ?? null) : refspec;
+}
+export function evaluatePush(command, currentBranch) {
+    if (/(?:^|\s)--dry-run\b/.test(command))
+        return { gated: false, branch: null };
+    const branch = parsePushTarget(command) ?? currentBranch;
+    if (!branch)
+        return { gated: false, branch: null };
+    return { gated: isProtectedBranch(branch), branch };
+}
+export function evaluateCommitSize(command, stagedCount) {
+    if (/(?:^|\s)--amend\b/.test(command))
+        return { gated: false };
+    return { gated: stagedCount > COMMIT_FILE_LIMIT };
+}
+export function decide(mode, gated, reason) {
+    if (!gated || mode === "off")
+        return ALLOW;
+    return { action: mode === "block" ? "block" : "warn", reason };
+}

package/lib/install-targets.mjs

@@ -0,0 +1,121 @@
+/**
+ * Multi-platform install targets for the 7-Laws skill.
+ *
+ * Pure planning layer — no filesystem access. The installer
+ * (src/bin/install.mts) feeds in the SKILL.md text plus a reader callback and
+ * executes the returned write plan against the project root. Keeping this
+ * pure lets the per-target contracts be unit-tested without temp dirs.
+ *
+ * v1 contract (docs/plans/2026-06-11-multi-platform-installer.md):
+ * - Non-Claude targets receive the skill text only; hooks, the MCP server,
+ *   and instinct learning stay Claude Code-only and every plan says so.
+ * - Shared files (GEMINI.md, AGENTS.md, .rules, CONVENTIONS.md,
+ *   copilot-instructions.md) are merged through a managed block so existing
+ *   user content is never clobbered and reinstalls are idempotent.
+ * - Own-file targets (cursor, windsurf) are written whole.
+ */
+export const MANAGED_BEGIN = "<!-- continuous-improvement:begin (managed block — reinstall via `npx continuous-improvement install --target <name>`; edits inside are overwritten) -->";
+export const MANAGED_END = "<!-- continuous-improvement:end -->";
+const TARGET_SPECS = {
+    gemini: { label: "Gemini CLI", mode: "managed", relPath: "GEMINI.md" },
+    codex: { label: "Codex CLI (agents.md standard)", mode: "managed", relPath: "AGENTS.md" },
+    cursor: { label: "Cursor", mode: "whole", relPath: ".cursor/rules/continuous-improvement.mdc" },
+    windsurf: { label: "Windsurf", mode: "whole", relPath: ".windsurf/rules/continuous-improvement.md" },
+    zed: { label: "Zed", mode: "managed", relPath: ".rules" },
+    aider: { label: "Aider", mode: "managed", relPath: "CONVENTIONS.md" },
+    copilot: { label: "GitHub Copilot", mode: "managed", relPath: ".github/copilot-instructions.md" },
+};
+export const TARGET_IDS = ["claude", ...Object.keys(TARGET_SPECS)];
+export function resolveTargets(csv) {
+    const targets = [];
+    const unknown = [];
+    for (const raw of csv.split(",")) {
+        const name = raw.trim().toLowerCase();
+        if (name === "")
+            continue;
+        if (!TARGET_IDS.includes(name)) {
+            if (!unknown.includes(name))
+                unknown.push(name);
+            continue;
+        }
+        if (!targets.includes(name))
+            targets.push(name);
+    }
+    return { targets, unknown };
+}
+export function stripFrontmatter(skillMd) {
+    if (!skillMd.startsWith("---\n") && !skillMd.startsWith("---\r\n"))
+        return skillMd;
+    const close = skillMd.indexOf("\n---", 3);
+    if (close === -1)
+        return skillMd;
+    const afterClose = skillMd.indexOf("\n", close + 1);
+    if (afterClose === -1)
+        return "";
+    return skillMd.slice(afterClose + 1).replace(/^\s*\n/, "");
+}
+export function mergeManagedBlock(existing, block) {
+    if (existing === null || existing.trim() === "") {
+        return `${block}\n`;
+    }
+    const beginAt = existing.indexOf(MANAGED_BEGIN);
+    const endAt = existing.indexOf(MANAGED_END);
+    if (beginAt !== -1 && endAt !== -1 && endAt > beginAt) {
+        const before = existing.slice(0, beginAt);
+        const after = existing.slice(endAt + MANAGED_END.length);
+        return `${before}${block}${after}`;
+    }
+    return `${existing.trimEnd()}\n\n${block}\n`;
+}
+function renderManagedBlock(skillMd) {
+    return `${MANAGED_BEGIN}\n${stripFrontmatter(skillMd).trim()}\n${MANAGED_END}`;
+}
+function renderCursorRule(skillMd) {
+    return [
+        "---",
+        "description: 7 Laws of AI Agent Discipline — continuous-improvement framework",
+        "alwaysApply: true",
+        "---",
+        "",
+        stripFrontmatter(skillMd).trim(),
+        "",
+    ].join("\n");
+}
+const AIDER_CONF_PATH = ".aider.conf.yml";
+const AIDER_MINIMAL_CONF = [
+    "# Written by `npx continuous-improvement install --target aider`.",
+    "# Loads the 7 Laws conventions into every Aider session.",
+    "read: [CONVENTIONS.md]",
+    "",
+].join("\n");
+export function planTargetWrites(targetId, skillMd, readExisting) {
+    if (targetId === "claude") {
+        throw new Error("claude is handled by the standard installer flow, not planTargetWrites");
+    }
+    const spec = TARGET_SPECS[targetId];
+    if (!spec) {
+        throw new Error(`Unknown install target: ${targetId}. Valid: ${TARGET_IDS.join(", ")}`);
+    }
+    const writes = [];
+    const notes = [
+        `${spec.label} gets the 7-Laws skill text only — hooks, the MCP server, and instinct learning are Claude Code-only.`,
+    ];
+    if (spec.mode === "whole") {
+        const content = targetId === "cursor" ? renderCursorRule(skillMd) : `${stripFrontmatter(skillMd).trim()}\n`;
+        writes.push({ relPath: spec.relPath, content });
+    }
+    else {
+        const block = renderManagedBlock(skillMd);
+        writes.push({ relPath: spec.relPath, content: mergeManagedBlock(readExisting(spec.relPath), block) });
+    }
+    if (targetId === "aider") {
+        const existingConf = readExisting(AIDER_CONF_PATH);
+        if (existingConf === null) {
+            writes.push({ relPath: AIDER_CONF_PATH, content: AIDER_MINIMAL_CONF });
+        }
+        else {
+            notes.push(`${AIDER_CONF_PATH} already exists — add CONVENTIONS.md to its \`read:\` list yourself (e.g. \`read: [CONVENTIONS.md]\`); the installer never rewrites an existing conf.`);
+        }
+    }
+    return { notes, writes };
+}

package/lib/plan-review-packet.mjs

@@ -0,0 +1,96 @@
+/**
+ * plan-review-packet: turn a plan doc into a commentable review packet.
+ *
+ * Pure markdown transform — no IO. Splits a `docs/plans/*.md` plan into
+ * anchored sections, extracts a TLDR, and renders a packet a reviewer can
+ * comment on inline (one `> Comment (R#):` slot per section).
+ */
+const TLDR_HEADINGS = new Set(["goal", "summary", "overview", "tldr"]);
+const HEADING_RE = /^(#{1,6})\s+(.*\S)\s*$/;
+function normalize(markdown) {
+    return markdown.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+/** Split a plan into reviewable level-2/3 sections, each with a stable [R#] anchor. */
+export function splitSections(markdown) {
+    const lines = normalize(markdown).split("\n");
+    const sections = [];
+    let current = null;
+    let counter = 0;
+    const flush = () => {
+        if (!current)
+            return;
+        counter += 1;
+        sections.push({
+            heading: current.heading,
+            level: current.level,
+            anchor: `R${counter}`,
+            body: current.body.join("\n").trim(),
+        });
+        current = null;
+    };
+    for (const line of lines) {
+        const match = HEADING_RE.exec(line);
+        const level = match ? match[1].length : 0;
+        if (level === 1) {
+            flush();
+        }
+        else if (level === 2 || level === 3) {
+            flush();
+            current = { heading: match[2].trim(), level, body: [] };
+        }
+        else if (current) {
+            current.body.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+/** First non-empty, non-heading paragraph of a block of markdown. */
+function firstParagraph(text) {
+    for (const block of text.split(/\n\s*\n/)) {
+        const kept = block
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0 && !/^#{1,6}(\s|$)/.test(l));
+        if (kept.length > 0)
+            return kept.join("\n");
+    }
+    return "";
+}
+/** Extract a one-glance TLDR: a Goal/Summary/Overview section, else the first paragraph. */
+export function extractTldr(markdown) {
+    const goal = splitSections(markdown).find((s) => TLDR_HEADINGS.has(s.heading.trim().toLowerCase()));
+    if (goal)
+        return firstParagraph(goal.body);
+    return firstParagraph(normalize(markdown));
+}
+function extractTitle(markdown) {
+    for (const line of normalize(markdown).split("\n")) {
+        const match = /^#\s+(.*\S)\s*$/.exec(line);
+        if (match)
+            return match[1].trim();
+    }
+    return "Plan Review";
+}
+/** Render a commentable review packet from a plan doc. */
+export function buildReviewPacket(markdown, options = {}) {
+    const title = extractTitle(markdown);
+    const tldr = extractTldr(markdown);
+    const sections = splitSections(markdown);
+    const out = [`# Review packet: ${title}`, ""];
+    if (options.source)
+        out.push(`Source: ${options.source}`);
+    out.push(`TLDR: ${tldr || "(none — skim the sections below)"}`, "");
+    out.push("> How to comment: reply under each `> Comment (R#):` line. The `[R#]` anchors are stable references you can cite back.", "", "---", "");
+    if (sections.length === 0) {
+        out.push("_No reviewable sections found in this plan._", "");
+        return out.join("\n");
+    }
+    for (const section of sections) {
+        out.push(`${"#".repeat(section.level)} ${section.heading} [${section.anchor}]`, "");
+        if (section.body)
+            out.push(section.body, "");
+        out.push(`> Comment (${section.anchor}):`, "");
+    }
+    return out.join("\n");
+}

package/lib/plugin-metadata.mjs

@@ -26,7 +26,7 @@ const KEYWORDS = [
     "transcript-linter",
 ];
 const CLAUDE_PLUGIN_CATEGORY = "productivity";
-const SHARED_PLUGIN_DESCRIPTION = "Stops Claude Code from skipping research, claiming 'done' without verifying, and repeating yesterday's mistakes. The 7 Laws of AI Agent Discipline — 25 bundled skills, gating hooks, the Mulahazah auto-leveling instinct engine, and a GitHub Action transcript linter.";
+const SHARED_PLUGIN_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 25 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.";
 // Four vendored upstream companions registered alongside the CI plugin.
 // Each entry points at a pinned-SHA snapshot under third-party/<name>/.
 // See third-party/MANIFEST.md for refresh recipes and per-snapshot
@@ -76,7 +76,7 @@ const THIRD_PARTY_COMPANIONS = [
     },
     {
         name: "oh-my-claudecode",
-        description: "Multi-agent orchestration system for Claude Code — 39 skills + 19 agents covering audit, plan, build, verify, ship, release, retrospective, and ops. Includes ralph (autonomous PRD loop), release, ultrawork, ultraqa, team, trace, visual-verdict, debug, deep-dive, deep-interview, autopilot, autoresearch. Vendored snapshot at third-party/oh-my-claudecode/ pinned to upstream SHA aacde3e (v4.13.6). Heavy overlap with continuous-improvement /ralph and /superpowers — pick per task.",
+        description: "Multi-agent orchestration system for Claude Code — 38 skills + 19 agents covering audit, plan, build, verify, ship, release, retrospective, and ops. Includes ralph (autonomous PRD loop), release, ultrawork, ultraqa, team, trace, visual-verdict, debug, deep-dive, deep-interview, autopilot, autoresearch. Vendored snapshot at third-party/oh-my-claudecode/ pinned to upstream SHA aacde3e (v4.13.6). Heavy overlap with continuous-improvement /ralph and /superpowers — pick per task.",
         version: "4.13.6",
         source: "./third-party/oh-my-claudecode",
         author: {
@@ -143,6 +143,10 @@ const BEGINNER_TOOL_ENTRIES = [
                     type: "string",
                     description: "A single file path to clear (alternative to file_paths)",
                 },
+                state_path: {
+                    type: "string",
+                    description: "State-file path from the GateGuard block reason (the session-scoped gateguard-session.json). Pass it verbatim so the clearance lands in the session the hook is reading; it must resolve inside ~/.claude/instincts/. Omitting it falls back to the unscoped canonical dir — safe only in legacy (no session id) contexts; when the hook is session-scoped, omitting it writes to the wrong dir and the retry will still block.",
+                },
             },
             required: [],
         },
@@ -373,15 +377,21 @@ const EXPERT_TOOL_ENTRIES = [
             required: ["id"],
         },
     },
+    {
+        name: "ci_distill_from_workflow",
+        description: "Draft a reusable instinct from the most recent completed-and-verified native Workflow run in this project's observation feed. A Workflow script is an authored recipe, so a single run whose output passed verification is enough — unlike ci_distill_candidates, which needs a pattern repeated across sessions. Writes a DRAFT to drafts/ (a skeleton you edit); it changes no behavior until promoted with ci_distill_promote. Returns a message when no verified workflow run is found.",
+        manifestWhat: "Draft a reusable instinct from a verified Workflow run",
+        inputSchema: { type: "object", properties: {}, required: [] },
+    },
 ];
 const MODE_METADATA = {
     beginner: {
-        description: "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles four discipline skills (gateguard, para-memory-files, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default.",
+        description: "Beginner mode: see what your agent learned, list its instincts, and request a session reflection. Bundles three grounding skills (gateguard, tdd-workflow, verification-loop) so research, memory, tests, and verification happen by default — every edit starts from facts, not guesses.",
         hooks: ["PreToolUse", "PostToolUse", "UserPromptSubmit"],
-        hookDescription: "Silently captures every tool call as observations and routes prompts to the matching discipline skill via the route table. Lightweight and non-blocking.",
+        hookDescription: "Silently captures every tool call as observations and routes prompts to the matching skill via the route table. Lightweight and non-blocking.",
     },
     expert: {
-        description: "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay disciplined and learnings survive context resets.",
+        description: "Expert mode: tune confidence, manage instincts, and persist plans on disk. Adds safety, token-budget, and strategic-compact skills plus the /learn-eval command so long sessions stay sharp and learnings survive context resets.",
         hooks: ["PreToolUse", "PostToolUse", "UserPromptSubmit", "SessionStart", "SessionEnd"],
         hookDescription: "Full hook suite: observation capture, lazy prompt routing, session-level instinct loading, and auto-reflection.",
     },
@@ -457,6 +467,11 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/companion-preference.mjs\"",
         timeout: 5,
     };
+    const hookPackCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-pack.mjs\"",
+        timeout: 5,
+    };
     const observeCommand = {
         type: "command",
         command: "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/observe.sh\"",
@@ -482,8 +497,13 @@ export function getPluginHooksConfig() {
         command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/route-prompt.mjs\"",
         timeout: 5,
     };
+    const recallBriefingCommand = {
+        type: "command",
+        command: "node \"${CLAUDE_PLUGIN_ROOT}/hooks/recall-briefing.mjs\"",
+        timeout: 5,
+    };
     return {
-        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, and UserPromptSubmit lazy-routing hooks for continuous-improvement.",
+        description: "Gateguard fact-forcing PreToolUse, companion-preference enforcement, observation, session lifecycle, 3-section-close discipline, goal-drift Stop gate, 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
@@ -496,9 +516,15 @@ export function getPluginHooksConfig() {
             // through with no output.
             PreToolUse: [
                 { hooks: [gateguardCommand, companionPreferenceCommand] },
+                // hook-pack gates Bash `git push` to protected branches and oversized
+                // `git commit`s. The "Bash" matcher scopes it off the hot path for all
+                // non-Bash tools, so the two-subprocess note above still holds for
+                // Edit/Read/etc. Warn-default (CLAUDE_CI_HOOKPACK_GATE) — never blocks
+                // until the operator opts in.
+                { matcher: "Bash", hooks: [hookPackCommand] },
             ],
             PostToolUse: [{ hooks: [observeCommand] }],
-            UserPromptSubmit: [{ hooks: [routePromptCommand] }],
+            UserPromptSubmit: [{ hooks: [routePromptCommand, recallBriefingCommand] }],
             SessionStart: [{ hooks: [sessionCommand] }],
             SessionEnd: [{ hooks: [sessionCommand] }],
             Stop: [{ hooks: [threeSectionCloseCommand, goalDriftStopCommand] }],

package/lib/recall-briefing.mjs

@@ -0,0 +1,57 @@
+// recall-briefing.mts — Pure decision core for the proactive recall-briefing hook.
+//
+// No I/O. Given (enabled, already-briefed, prompt, ranked recall hits), decides
+// whether to inject a one-time-per-session "you've touched related work before"
+// system-reminder and renders it. The hook (src/hooks/recall-briefing.mts) does
+// the filesystem work — read the prompt, read observations.jsonl, build the BM25
+// index (recall-index.mts), track per-session state — then calls decideBriefing.
+// Keeping the decision pure lets the unit tests cover every gate and boundary
+// (disabled / already-briefed / empty-or-short prompt / no hits / malformed
+// input) without touching the filesystem, per the repo lesson that green gates
+// do not prove boundary safety.
+//
+// This is an amplifier, not a gate: it never blocks a prompt. It only surfaces
+// prior context so the agent reuses a past fix instead of re-deriving it. It is
+// opt-in (the hook checks an env flag) and fires at most once per session.
+export const DEFAULT_MAX_HITS = 3;
+export const DEFAULT_MIN_PROMPT_LENGTH = 12;
+/** Render ranked hits as a compact UserPromptSubmit system-reminder. Pure string. */
+export function formatBriefing(hits) {
+    const lines = [
+        "<system-reminder>",
+        "Recall briefing: this project has prior sessions that touched related work. Before re-deriving a fix, consider the `ci_recall` MCP tool (or `/recall`) for full context. Most relevant past activity:",
+    ];
+    for (const h of hits) {
+        const stamp = h && h.ts ? `[${h.ts}] ` : "";
+        const tool = (h && h.tool) || "(tool?)";
+        const snippet = ((h && h.snippet) || "").replace(/\s+/g, " ").trim();
+        lines.push(`- ${stamp}${tool}: ${snippet || "(no summary)"}`);
+    }
+    lines.push("</system-reminder>");
+    return lines.join("\n");
+}
+/**
+ * Decide whether to inject a recall briefing. Fails closed: any disabling
+ * condition (opted out, already briefed, prompt below the noise floor, no hits,
+ * malformed input) returns shouldBrief=false and never throws.
+ */
+export function decideBriefing(params) {
+    const none = { shouldBrief: false, reminder: null };
+    if (!params || params.enabled !== true)
+        return none;
+    if (params.alreadyBriefed === true)
+        return none;
+    const prompt = typeof params.prompt === "string" ? params.prompt : "";
+    const minLen = typeof params.minPromptLength === "number" && params.minPromptLength >= 0
+        ? params.minPromptLength
+        : DEFAULT_MIN_PROMPT_LENGTH;
+    if (prompt.trim().length < minLen)
+        return none;
+    const maxHits = typeof params.maxHits === "number" && params.maxHits > 0
+        ? Math.floor(params.maxHits)
+        : DEFAULT_MAX_HITS;
+    const hits = Array.isArray(params.hits) ? params.hits.slice(0, maxHits) : [];
+    if (hits.length === 0)
+        return none;
+    return { shouldBrief: true, reminder: formatBriefing(hits) };
+}

package/lib/recall-index.mjs

@@ -19,10 +19,10 @@ const BM25_K1 = 1.5;
 const BM25_B = 0.75;
 const DEFAULT_K = 5;
 const SNIPPET_RADIUS = 60;
-/** Lowercase, split on any non-letter / non-number (Unicode-aware), drop stopwords and tokens shorter than TOKEN_MIN_LENGTH. */
+/** Lowercase, split on any non-letter / non-number / non-mark (Unicode-aware), drop stopwords and tokens shorter than TOKEN_MIN_LENGTH. */
 export function tokenize(text) {
     const out = [];
-    for (const raw of text.toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    for (const raw of text.toLowerCase().split(/[^\p{L}\p{N}\p{M}]+/u)) {
         if (raw.length < TOKEN_MIN_LENGTH)
             continue;
         if (STOPWORDS.has(raw))