@davesheffer/hunch 0.5.0 → 0.9.0

package/dist/core/migrate.js

@@ -18,13 +18,47 @@ import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { writeFileAtomic } from "./io.js";
 /** The schema generation this build writes and reads. Bump on any breaking change. */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 /** A repo whose `.hunch/` predates manifests is treated as v1. Migrations are
  *  numbered from 2 (each `version` is the number it PRODUCES), so a baseline repo
  *  runs every migration with version >= 2 — never author a no-op version:1 one. */
 export const BASELINE_VERSION = 1;
 /** Ordered, ascending by `version`. Empty at v1 (baseline); future versions append. */
-export const MIGRATIONS = [];
+export const MIGRATIONS = [
+    {
+        // v2: bi-temporal valid-time on decisions + constraints (Time-Travel Memory).
+        // Backfill new fields from each record's existing date so a v1 graph migrates
+        // losslessly — no record is dropped, and `valid_from` is populated BEFORE the
+        // Zod pass. Defensive: input is untrusted JSON.
+        version: 2,
+        description: "Add valid_from/valid_to/superseded_by/retired (decisions) and status/valid_from/valid_to (constraints)",
+        up(kind, raw) {
+            if (kind === "decisions") {
+                const date = typeof raw.date === "string" ? raw.date : "";
+                if (raw.valid_from === undefined)
+                    raw.valid_from = date;
+                // Legacy superseded decisions have no recorded successor instant. Leave
+                // valid_to = null (historically in force) rather than = date: a zero-length
+                // [date,date) window matches NO as-of query and would hide the record from
+                // all time-travel. A later `supersede` sets a real valid_to when known.
+                if (raw.valid_to === undefined)
+                    raw.valid_to = null;
+                if (raw.superseded_by === undefined)
+                    raw.superseded_by = null;
+                if (raw.retired === undefined)
+                    raw.retired = { symbols: [], deps: [] };
+            }
+            else if (kind === "constraints") {
+                if (raw.status === undefined)
+                    raw.status = "active";
+                if (raw.valid_to === undefined)
+                    raw.valid_to = null;
+                // valid_from is optional on constraints; leave unset for legacy records.
+            }
+            return raw;
+        },
+    },
+];
 /** Read `.hunch/manifest.json`. A missing/corrupt manifest is treated as the
  *  BASELINE version (a pre-manifest `.hunch/`), so future builds still migrate it. */
 export function readManifest(paths) {

package/dist/core/paths.js

@@ -10,6 +10,7 @@ export function hunchPaths(root) {
         hunch,
         sqlite: join(hunch, "hunch.sqlite"),
         manifest: join(hunch, "manifest.json"),
+        config: join(hunch, "config.json"),
         dir: (kind) => join(hunch, kind),
     };
 }

package/dist/core/types.js

@@ -68,6 +68,12 @@ export const SymbolSchema = z.object({
     metrics: SymbolMetricsSchema.default({ loc: 0, churn_90d: 0, bug_count: 0, fan_in: 0, fan_out: 0 }),
     last_changed: z.string().default("").describe("commit:<sha> or ISO date"),
 });
+/** The structural delta a decision's commit DELETED — the evidence the Regression
+ *  Guard matches a later diff against ("you're re-adding what dec_X removed"). */
+export const RetiredSignalSchema = z.object({
+    symbols: z.array(z.string()).default([]).describe("symbol names this decision removed"),
+    deps: z.array(z.string()).default([]).describe("external deps this decision dropped"),
+});
 /** ADR-style decision record, auto-drafted and human-confirmable. */
 export const DecisionSchema = z.object({
     id: z.string().describe("dec_*"),
@@ -80,8 +86,17 @@ export const DecisionSchema = z.object({
     related_components: z.array(z.string()).default([]),
     related_files: z.array(z.string()).default([]),
     supersedes: z.string().nullable().default(null),
+    superseded_by: z.string().nullable().default(null).describe("the decision that closed this one's window"),
     caused_by_bug: z.string().nullable().default(null),
     commit: z.string().nullable().default(null),
+    // Bi-temporal VALID-TIME window, git-anchored. `valid_from` is when the decision
+    // took effect (its commit date); `valid_to` is when a superseding decision closed
+    // it (null = still in force). Enables "what did we believe as of commit X?".
+    // Optional so legacy/hand-built records still validate (the migration backfills
+    // from `date`, and the capture paths always set it); undefined = always-started.
+    valid_from: z.string().optional().describe("ISO instant the decision took effect (commit date)"),
+    valid_to: z.string().nullable().default(null).describe("ISO instant it was superseded (null = in force)"),
+    retired: RetiredSignalSchema.default({ symbols: [], deps: [] }),
     provenance: ProvenanceSchema,
     date: z.string(),
 });
@@ -120,6 +135,12 @@ export const ConstraintSchema = z.object({
     rationale: z.string().default(""),
     source_decision: z.string().nullable().default(null),
     violations: z.array(z.string()).default([]),
+    // Bi-temporal VALID-TIME: a constraint can be RETIRED without deletion, so
+    // "what invariants were in force as of commit X?" stays answerable. `valid_to`
+    // null = still active. A retired constraint is excluded from enforcement at HEAD.
+    status: z.enum(["active", "retired"]).default("active"),
+    valid_from: z.string().optional().describe("ISO instant the invariant took effect"),
+    valid_to: z.string().nullable().default(null).describe("ISO instant it was retired (null = active)"),
     provenance: ProvenanceSchema,
 });
 /** The six entity collections, keyed by their on-disk directory name. */

package/dist/extractors/git.js

@@ -105,6 +105,22 @@ export function stagedFiles(cwd) {
     const out = gitSafe(["diff", "--cached", "--name-only", "--diff-filter=ACMR"], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
+/** Unified diff of the staged changes (for the Regression Guard's structural
+ *  analysis). Excludes machine-generated noise and truncates at the SAME budget as
+ *  commitDiff, so the staged and `--commit` guard paths can't diverge on big diffs. */
+export function stagedDiff(cwd, maxBytes = 60_000) {
+    const out = gitSafe(["diff", "--cached", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
+    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+}
+/** Resolve a time-travel ref (commit / tag / branch / HEAD~n) to the ISO author-
+ *  date of that commit — the instant valid-time windows are filtered against.
+ *  Undefined if it can't be resolved (not a git repo, or an unknown ref). Single
+ *  source for the CLI and MCP as-of paths so they can't drift. */
+export function asOfDate(ref, cwd) {
+    if (!isGitRepo(cwd))
+        return undefined;
+    return commitMeta(revParse(ref, cwd), cwd)?.date || undefined;
+}
 /** Translate a backfill window spec into git-log window args.
  *   "90d" / bare "90" -> last 90 days   |   "40c" -> last 40 commits
  *   anything else      -> passed to --since as an approxidate/date string. */

package/dist/extractors/parse.js

@@ -26,19 +26,19 @@ const BUILTIN_METHODS = new Set([
     "log", "error", "warn", "info", "debug",
 ]);
 /** Tree-sitter query capturing every construct we care about in one pass. */
-const QUERY_SRC = `
-  (function_declaration name: (identifier) @fn.name) @fn.def
-  (generator_function_declaration name: (identifier) @fn.name) @fn.def
-  (method_definition name: (property_identifier) @method.name) @method.def
-  (class_declaration name: (type_identifier) @class.name) @class.def
-  (interface_declaration name: (type_identifier) @iface.name) @iface.def
-  (type_alias_declaration name: (type_identifier) @type.name) @type.def
-  (variable_declarator
-     name: (identifier) @arrow.name
-     value: [(arrow_function) (function_expression)]) @arrow.def
-  (import_statement source: (string) @import.src)
-  (call_expression function: (identifier) @call.id)
-  (call_expression function: (member_expression property: (property_identifier) @call.member))
+const QUERY_SRC = `
+  (function_declaration name: (identifier) @fn.name) @fn.def
+  (generator_function_declaration name: (identifier) @fn.name) @fn.def
+  (method_definition name: (property_identifier) @method.name) @method.def
+  (class_declaration name: (type_identifier) @class.name) @class.def
+  (interface_declaration name: (type_identifier) @iface.name) @iface.def
+  (type_alias_declaration name: (type_identifier) @type.name) @type.def
+  (variable_declarator
+     name: (identifier) @arrow.name
+     value: [(arrow_function) (function_expression)]) @arrow.def
+  (import_statement source: (string) @import.src)
+  (call_expression function: (identifier) @call.id)
+  (call_expression function: (member_expression property: (property_identifier) @call.member))
 `;
 const cache = new Map();
 function bundleFor(lang, key) {

package/dist/integrations/claudemd.js

@@ -3,8 +3,8 @@
  * context loaded every session for free"). We own ONLY the region between the
  * HUNCH markers — any user-authored content outside it is preserved verbatim.
  */
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
 const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
 const END = "<!-- HUNCH:END -->";
 export function renderHunchSection(store) {
@@ -45,20 +45,18 @@ export function renderHunchSection(store) {
     lines.push(END);
     return lines.join("\n");
 }
-/** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
-export function updateClaudeMd(root, store) {
-    const file = join(root, "CLAUDE.md");
-    const section = renderHunchSection(store);
+/** Insert/replace the marker-delimited HUNCH section in a markdown doc, preserving
+ *  all user-authored content outside the markers. Shared by CLAUDE.md, AGENTS.md,
+ *  and .github/copilot-instructions.md so every assistant gets the same grounding. */
+export function upsertSection(file, section, fallbackTitle) {
     let content = existsSync(file) ? readFileSync(file, "utf8") : "";
     const iStart = content.indexOf(START);
     const iEnd = content.indexOf(END);
     if (iStart >= 0 && iEnd > iStart) {
-        // clean both-marker case: replace in place, preserving surrounding content
         content = content.slice(0, iStart) + section + content.slice(iEnd + END.length);
     }
     else if (iStart >= 0 || iEnd >= 0) {
-        // partial/corrupt markers (only one survived, or out of order): strip every
-        // stray marker line, then append ONE clean section — never duplicate.
+        // partial/corrupt markers: strip stray marker lines, then append ONE clean section.
         const body = content.split("\n").filter((l) => !l.includes(START) && !l.includes(END)).join("\n").trimEnd();
         content = body ? `${body}\n\n${section}\n` : `${section}\n`;
     }
@@ -66,11 +64,16 @@ export function updateClaudeMd(root, store) {
         content = `${content.trimEnd()}\n\n${section}\n`;
     }
     else {
-        content = `# ${root.split("/").pop()}\n\n${section}\n`;
+        content = `${fallbackTitle}\n\n${section}\n`;
     }
+    mkdirSync(dirname(file), { recursive: true }); // e.g. .github/ for copilot-instructions
     writeFileSync(file, content);
     return file;
 }
+/** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
+export function updateClaudeMd(root, store) {
+    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store), `# ${root.split("/").pop()}`);
+}
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;
 }

package/dist/integrations/providers.js

@@ -0,0 +1,229 @@
+/**
+ * Multi-assistant compatibility (DESIGN §7, extended). The Hunch MCP server is
+ * client-agnostic — any MCP-capable assistant can call the `hunch_*` tools. The
+ * only per-tool difference is HOW each one is told to launch the server and where
+ * its ambient grounding lives. This module scaffolds those surfaces for the major
+ * assistants so the same `.hunch/` graph powers all of them:
+ *
+ *   Assistant   | MCP config              | root key       | grounding file
+ *   ------------|-------------------------|----------------|---------------------------------
+ *   Claude Code | .mcp.json               | mcpServers     | CLAUDE.md            (scaffold.ts)
+ *   Cursor      | .cursor/mcp.json        | mcpServers     | .cursor/rules/hunch.mdc
+ *   VS Code     | .vscode/mcp.json        | servers (+type)| .github/copilot-instructions.md
+ *   Codex CLI   | .codex/config.toml      | [mcp_servers.*]| AGENTS.md
+ *   (any other) | —                       | —              | AGENTS.md (cross-tool standard)
+ *
+ * Every writer MERGES into existing files (preserving other servers / user prose)
+ * and is idempotent, so re-running `hunch init` is safe.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { renderHunchSection, upsertSection } from "./claudemd.js";
+/** Strip // line and block comments + trailing commas (JSONC → JSON). String-aware
+ *  (double-quoted, with escapes) so a // inside a value isn't mangled. VS Code's
+ *  .vscode/mcp.json is JSONC, so we must tolerate comments. */
+function stripJsonc(s) {
+    let out = "";
+    let inStr = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        const n = s[i + 1];
+        if (inStr) {
+            out += c;
+            if (c === "\\") {
+                out += n ?? "";
+                i++;
+                continue;
+            }
+            if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"') {
+            inStr = true;
+            out += c;
+            continue;
+        }
+        if (c === "/" && n === "/") {
+            while (i < s.length && s[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (c === "/" && n === "*") {
+            i += 2;
+            while (i < s.length && !(s[i] === "*" && s[i + 1] === "/"))
+                i++;
+            i++;
+            continue;
+        }
+        out += c;
+    }
+    return dropTrailingCommas(out);
+}
+/** Remove trailing commas (`,` before `}`/`]`) — string-aware, so a comma inside
+ *  a string value (e.g. "a,]") is never touched. A blanket regex would corrupt it
+ *  (the same trap test/migrate.test.ts guards against). Runs on comment-free text,
+ *  so lookahead need only skip whitespace. */
+function dropTrailingCommas(s) {
+    let out = "";
+    let inStr = false;
+    let esc = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (inStr) {
+            out += c;
+            if (esc)
+                esc = false;
+            else if (c === "\\")
+                esc = true;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"') {
+            inStr = true;
+            out += c;
+            continue;
+        }
+        if (c === ",") {
+            let j = i + 1;
+            while (j < s.length && /\s/.test(s[j]))
+                j++;
+            if (s[j] === "}" || s[j] === "]")
+                continue; // trailing comma → drop
+        }
+        out += c;
+    }
+    return out;
+}
+/** Read a JSON/JSONC object. Returns {} only for an ABSENT or empty file. A
+ *  non-empty file we cannot parse THROWS — overwriting it would silently wipe the
+ *  user's other MCP servers. */
+function readJsonObj(file) {
+    if (!existsSync(file))
+        return {};
+    const raw = readFileSync(file, "utf8");
+    if (!raw.trim())
+        return {};
+    try {
+        const v = JSON.parse(stripJsonc(raw));
+        if (v && typeof v === "object" && !Array.isArray(v))
+            return v;
+        throw new Error("not a JSON object");
+    }
+    catch (e) {
+        throw new Error(`refusing to overwrite ${file}: could not parse it (${e.message}). Fix or remove it, then re-run.`);
+    }
+}
+/** Render a string as a TOML value: a literal '…' when safe (no escaping needed —
+ *  ideal for Windows backslash paths), else a basic "…" with escapes. */
+function tomlStr(s) {
+    // TOML literal '…' needs no escaping (ideal for Windows backslash paths) but
+    // can't contain a quote or newline; otherwise a basic "…" with escapes.
+    if (!/['\r\n]/.test(s))
+        return `'${s}'`;
+    const esc = s
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+    return `"${esc}"`;
+}
+function writeJson(file, obj) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(obj, null, 2) + "\n");
+    return file;
+}
+/** Cursor: .cursor/mcp.json — same `mcpServers` shape as Claude Desktop/Code. */
+export function writeCursorMcp(root, inv) {
+    const file = join(root, ".cursor", "mcp.json");
+    const json = readJsonObj(file);
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
+/** VS Code (Copilot agent mode): .vscode/mcp.json — root key is `servers`, and
+ *  each stdio entry carries an explicit `type: "stdio"` (VS Code's schema). */
+export function writeVscodeMcp(root, inv) {
+    const file = join(root, ".vscode", "mcp.json");
+    const json = readJsonObj(file);
+    json.servers = json.servers ?? {};
+    json.servers.hunch = { type: "stdio", command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
+const TOML_START = "# >>> hunch mcp (managed) >>>";
+const TOML_END = "# <<< hunch mcp <<<";
+/** Codex CLI: .codex/config.toml — `[mcp_servers.hunch]` stdio entry. We own only
+ *  a marker-delimited block; any other TOML the user has is preserved. Paths use
+ *  TOML single-quote LITERAL strings so Windows backslashes need no escaping. */
+export function writeCodexConfig(root, inv) {
+    const file = join(root, ".codex", "config.toml");
+    const argsToml = [...inv.args, "mcp"].map(tomlStr).join(", ");
+    const block = [
+        TOML_START,
+        "[mcp_servers.hunch]",
+        `command = ${tomlStr(inv.command)}`,
+        `args = [${argsToml}]`,
+        TOML_END,
+    ].join("\n");
+    // Strip any prior managed block first, so `base` is the user's own TOML.
+    const content = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const i = content.indexOf(TOML_START);
+    const j = content.indexOf(TOML_END);
+    let base;
+    if (i >= 0 && j > i)
+        base = content.slice(0, i) + content.slice(j + TOML_END.length);
+    else if (i >= 0 || j >= 0)
+        base = content.split("\n").filter((l) => !l.includes(TOML_START) && !l.includes(TOML_END)).join("\n");
+    else
+        base = content;
+    // A user-authored [mcp_servers.hunch] outside our block would make TWO tables of
+    // the same name → TOML duplicate-table error. Refuse rather than corrupt it.
+    if (/^\s*\[mcp_servers\.hunch\]/m.test(base)) {
+        throw new Error(`refusing to edit ${file}: it already defines [mcp_servers.hunch] outside Hunch's managed block. Remove it, then re-run.`);
+    }
+    base = base.trimEnd();
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, base ? `${base}\n\n${block}\n` : `${block}\n`);
+    return file;
+}
+/** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
+ *  set of assistants read it). Marker-delimited so user prose is preserved. */
+export function writeAgentsMd(root, store) {
+    return upsertSection(join(root, "AGENTS.md"), renderHunchSection(store), "# AGENTS.md");
+}
+/** GitHub Copilot custom instructions (VS Code / github.com). Same grounding. */
+export function writeCopilotInstructions(root, store) {
+    return upsertSection(join(root, ".github", "copilot-instructions.md"), renderHunchSection(store), "# Copilot instructions");
+}
+/** Cursor project rule (.mdc = frontmatter + body). `alwaysApply` keeps the Hunch
+ *  grounding in context for every request. Fully managed by Hunch (overwritten). */
+export function writeCursorRule(root, store) {
+    const file = join(root, ".cursor", "rules", "hunch.mdc");
+    const body = `---\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\nalwaysApply: true\n---\n\n${renderHunchSection(store)}\n`;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, body);
+    return file;
+}
+/** Scaffold MCP config + grounding for all supported assistants. Returns a
+ *  per-assistant summary for `hunch init` to print. Each assistant is isolated:
+ *  a writer that refuses to clobber a malformed file degrades to a warning rather
+ *  than aborting the rest. Claude Code is handled separately by scaffold.ts. */
+export function scaffoldProviders(root, inv, store) {
+    const tasks = [
+        ["Cursor", () => [writeCursorMcp(root, inv), writeCursorRule(root, store)]],
+        ["VS Code (Copilot)", () => [writeVscodeMcp(root, inv), writeCopilotInstructions(root, store)]],
+        ["Codex CLI", () => [writeCodexConfig(root, inv)]],
+        ["Any (AGENTS.md)", () => [writeAgentsMd(root, store)]],
+    ];
+    return tasks.map(([assistant, run]) => {
+        try {
+            return { assistant, files: run() };
+        }
+        catch (e) {
+            return { assistant, files: [], error: e.message };
+        }
+    });
+}
+//# sourceMappingURL=providers.js.map

package/dist/integrations/scaffold.js

@@ -4,7 +4,7 @@
  *   - .claude/commands/* → user-triggered slash commands for the §5 workflows
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
 /** Merge a `hunch` server entry into .mcp.json, preserving other servers. */
 export function writeMcpJson(root, inv) {
     const file = join(root, ".mcp.json");
@@ -55,6 +55,62 @@ then produce a **fragility report with evidence**: the specific files/functions,
 the bug history behind them, their churn and fan-in, and any missing guards.
 Avoid generic advice — every claim must cite a Hunch record or metric.
 `;
+/** A settings.json hook entry is Hunch's if any of its commands ends with the
+ *  Hunch CLI entry + the `hook` subcommand (e.g. `…/index.js hook`). Matching the
+ *  command TAIL — not the absolute path — makes re-init idempotent AND survives a
+ *  repo-folder rename (the path before index.js changes; the tail does not). The
+ *  leading path separator (`/` or `\`) requires `index` to be a full path segment,
+ *  so a foreign tool's `…/myindex.js hook` isn't mistaken for ours and clobbered. */
+function isHunchHook(entry) {
+    return !!entry.hooks?.some((h) => typeof h.command === "string" && /[\\/]index\.(js|ts)"?\s+hook\s*$/.test(h.command));
+}
+/**
+ * Install the Claude Code AGENT hooks into `.claude/settings.json` so the agent
+ * is grounded in Hunch automatically (not by remembering to call the tools):
+ *   - PreToolUse (Edit|Write|MultiEdit) → inject the relevant Hunch slice before
+ *     an edit, and (at strict firmness) deny edits that hit a blocking invariant.
+ *   - UserPromptSubmit → remind the agent to consult Hunch.
+ * Both invoke `hunch hook`, which reads the firmness level from .hunch/config.json
+ * at run time — so changing firmness needs no settings.json edit. We own only our
+ * entries (matched by isHunchHook): other hooks and settings are preserved, and a
+ * non-empty file we cannot parse THROWS rather than clobbering the user's config.
+ */
+export function installClaudeHooks(root, hookCmd) {
+    const file = join(root, ".claude", "settings.json");
+    const existed = existsSync(file);
+    let json = {};
+    let before = "";
+    if (existed) {
+        before = readFileSync(file, "utf8");
+        if (before.trim()) {
+            try {
+                const v = JSON.parse(before);
+                if (!v || typeof v !== "object" || Array.isArray(v))
+                    throw new Error("not a JSON object");
+                json = v;
+            }
+            catch (e) {
+                throw new Error(`refusing to overwrite ${file}: could not parse it (${e.message}). Fix or remove it, then re-run.`);
+            }
+        }
+    }
+    json.hooks = json.hooks ?? {};
+    const keep = (arr) => (Array.isArray(arr) ? arr.filter((e) => !isHunchHook(e)) : []);
+    json.hooks.PreToolUse = [
+        ...keep(json.hooks.PreToolUse),
+        { matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: hookCmd }] },
+    ];
+    json.hooks.UserPromptSubmit = [
+        ...keep(json.hooks.UserPromptSubmit),
+        { hooks: [{ type: "command", command: hookCmd }] },
+    ];
+    const next = JSON.stringify(json, null, 2) + "\n";
+    if (existed && before === next)
+        return { path: file, action: "unchanged" };
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, next);
+    return { path: file, action: existed ? "updated" : "created" };
+}
 export function writeSlashCommands(root) {
     const dir = join(root, ".claude", "commands");
     mkdirSync(dir, { recursive: true });

package/dist/mcp/server.js

@@ -13,7 +13,7 @@ import { hunchPaths, findRoot } from "../core/paths.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId } from "../core/ids.js";
-import { revParse } from "../extractors/git.js";
+import { revParse, asOfDate } from "../extractors/git.js";
 import { formatContext } from "../core/format.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
@@ -76,10 +76,16 @@ export function buildServer(root) {
     // -- hunch_why ------------------------------------------------------------
     server.registerTool("hunch_why", {
         title: "Explain why a file/symbol is the way it is",
-        description: "Return the decisions, bugs, and constraints that explain a file path or symbol — the 'why' and the 'what must not break', with evidence.",
-        inputSchema: { target: z.string().describe("A file path (e.g. src/auth/session.ts) or symbol name.") },
-    }, async ({ target }) => {
-        const w = store.why(target);
+        description: "Return the decisions, bugs, and constraints that explain a file path or symbol — the 'why' and the 'what must not break', with evidence. Pass `as_of` (a commit/tag/branch) to time-travel: see what was believed at that point in history.",
+        inputSchema: {
+            target: z.string().describe("A file path (e.g. src/auth/session.ts) or symbol name."),
+            as_of: z.string().optional().describe("Time-travel ref: a commit sha, tag, or branch (e.g. v0.7.0). Omit for the current view."),
+        },
+    }, async ({ target, as_of }) => {
+        const asOf = as_of ? asOfDate(as_of, root) : undefined;
+        if (as_of && !asOf)
+            return err(`Could not resolve as_of "${as_of}" to a commit.`);
+        const w = store.why(target, { asOf });
         // Highest-signal first, then cap: invariants by severity, decisions by
         // confidence, bugs by severity — so a hot file's trim drops the tail, not
         // the records that matter most.
@@ -185,9 +191,30 @@ export function buildServer(root) {
         inputSchema: {
             target: z.string().describe("A file path or symbol you're about to edit."),
             budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
+            as_of: z.string().optional().describe("Time-travel ref (commit/tag/branch): assemble the slice as it stood then."),
         },
-    }, async ({ target, budget_tokens }) => {
-        return ok(formatContext(store.assembleContext(target, budget_tokens ?? 1500)));
+    }, async ({ target, budget_tokens, as_of }) => {
+        const asOf = as_of ? asOfDate(as_of, root) : undefined;
+        if (as_of && !asOf)
+            return err(`Could not resolve as_of "${as_of}" to a commit.`);
+        return ok(formatContext(store.assembleContext(target, budget_tokens ?? 1500, { asOf })));
+    });
+    // -- hunch_timeline (decision history) ------------------------------------
+    server.registerTool("hunch_timeline", {
+        title: "The decision history for a file/symbol",
+        description: "Time-travel: the decisions touching a file/symbol over time — what was believed, its valid-time window, and what superseded it. Use to understand how (and why) the design changed, and to avoid re-introducing a deliberately-retired approach.",
+        inputSchema: { target: z.string().describe("A file path or symbol name.") },
+    }, async ({ target }) => {
+        const tl = store.timeline(target);
+        if (!tl.length)
+            return ok(`No decision history for "${target}" yet.`);
+        const lines = tl.map((d) => {
+            const from = (d.valid_from ?? d.date).slice(0, 10);
+            const window = d.valid_to ? `${from} → ${d.valid_to.slice(0, 10)}` : `${from} → now`;
+            const sup = d.superseded_by ? ` (superseded by ${d.superseded_by})` : "";
+            return `  • ${d.id} [${d.status}] (${window})${sup}\n      ${d.title}`;
+        });
+        return ok(`Decision timeline for "${target}" (newest first):\n${lines.join("\n")}`);
     });
     // -- hunch_record_decision (write-back) -----------------------------------
     server.registerTool("hunch_record_decision", {
@@ -204,6 +231,7 @@ export function buildServer(root) {
                 related_components: z.array(z.string()).optional(),
                 status: z.enum(["proposed", "accepted", "rejected", "superseded"]).optional(),
                 commit: z.string().optional(),
+                supersedes: z.string().optional().describe("id of a decision this one replaces — closes its valid-time window (invalidate, don't delete)"),
             }),
         },
     }, async ({ decision }) => {
@@ -223,6 +251,7 @@ export function buildServer(root) {
             const source = existing && existing.provenance.source.includes("llm_draft")
                 ? "llm_draft+human_confirmed"
                 : "human_confirmed";
+            const now = new Date().toISOString();
             const rec = {
                 id,
                 title: decision.title,
@@ -233,16 +262,24 @@ export function buildServer(root) {
                 alternatives_rejected: decision.alternatives_rejected ?? [],
                 related_components: decision.related_components ?? existing?.related_components ?? [],
                 related_files: decision.related_files ?? existing?.related_files ?? [],
-                supersedes: existing?.supersedes ?? null,
+                supersedes: decision.supersedes ?? existing?.supersedes ?? null,
+                superseded_by: existing?.superseded_by ?? null,
                 caused_by_bug: existing?.caused_by_bug ?? null,
                 commit: decision.commit ?? existing?.commit ?? null,
+                valid_from: existing?.valid_from ?? now,
+                valid_to: existing?.valid_to ?? null,
+                retired: existing?.retired ?? { symbols: [], deps: [] },
                 provenance: { source, confidence: 0.95, evidence: decision.related_files ?? existing?.provenance.evidence ?? [] },
-                date: new Date().toISOString(),
+                date: now,
             };
             store.json.put("decisions", rec);
+            // Invalidate, don't delete: closing the superseded decision's valid-time
+            // window (+ a supersedes edge) preserves the why-it-changed trail.
+            const superseded = decision.supersedes ? store.supersede(decision.supersedes, rec) : null;
             store.reindex();
+            const supNote = superseded ? ` Superseded ${superseded.id} (window closed at ${rec.valid_from}).` : "";
             const note = decision.commit && !fullSha ? ` (note: commit "${decision.commit}" could not be resolved — recorded as a standalone decision, not linked to a commit)` : "";
-            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${note}`);
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${supNote}${note}`);
         }
         catch (e) {
             return err(`Failed to record decision: ${e.message}`);