@davesheffer/hunch 0.8.0 → 0.10.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Dave Sheffer
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Dave Sheffer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -108,7 +108,9 @@ normally and Claude consults Hunch, or invoke the slash commands:
 The MCP tools Claude calls under the hood: `hunch_why`, `hunch_query`,
 `hunch_check_constraints`, `hunch_get_dependents` (blast radius), `hunch_blast_radius`
 (dependent files + near-violations a change could break indirectly), `hunch_bug_lineage`,
-`hunch_context` (surgical minimal slice for a task), `hunch_record_decision` (write-back).
+`hunch_context` (surgical minimal slice for a task), `hunch_timeline` (a target's decision
+history over time), `hunch_record_decision` (write-back). `hunch_why` and `hunch_context`
+take an optional `as_of` (commit/tag/branch) to **time-travel** the graph to a past state.
 
 ### Works with any MCP assistant
 
@@ -122,6 +124,7 @@ they all consult the same memory:
 | Cursor | `.cursor/mcp.json` | `.cursor/rules/hunch.mdc` (always-applied) |
 | VS Code (Copilot) | `.vscode/mcp.json` | `.github/copilot-instructions.md` |
 | Codex CLI | `.codex/config.toml` | `AGENTS.md` |
+| Windsurf | `.windsurf/mcp_config.json` | `.windsurf/rules/hunch.md` (always-on) |
 | Anything else | — | `AGENTS.md` (cross-tool standard) |
 
 Each writer **merges** into existing files (other MCP servers and your own prose are
@@ -131,7 +134,7 @@ preserved) and is idempotent. Opt out with `hunch init --no-providers`.
 
 | Command | What |
 |---|---|
-| `hunch init` | scaffold `.hunch/`, index, install hook + merge driver, auto-install the advisory pre-commit guard, install the **Claude Code agent hooks**, and wire up **every assistant** (Claude Code, Cursor, VS Code/Copilot, Codex, AGENTS.md). Flags: `--no-enforce`, `--enforce-strict`, `--no-providers`, `--no-agent-hooks`, `--firmness <level>` |
+| `hunch init` | scaffold `.hunch/`, index, install hook + merge driver, auto-install the advisory pre-commit guard, install the **Claude Code agent hooks**, and wire up **every assistant** (Claude Code, Cursor, VS Code/Copilot, Codex, Windsurf, AGENTS.md). Flags: `--no-enforce`, `--enforce-strict`, `--no-providers`, `--no-agent-hooks`, `--firmness <level>` |
 | `hunch index` | parse repo → symbols / edges / components (deterministic, no LLM) |
 | `hunch backfill --since 90d` | replay git history → seed decisions |
 | `hunch sync [sha]` | turn a commit into a Decision (run automatically by the hook) |
@@ -139,12 +142,14 @@ preserved) and is idempotent. Opt out with `hunch init --no-providers`.
 | `hunch record-constraint "<statement>" [--scope <globs>] [--severity advisory\|warning\|blocking] [--type …] [--rationale <t>] [--source-decision <id>]` | record an invariant the code must not break (what `hunch check` + the strict agent hook enforce) |
 | `hunch firmness [off\|advisory\|firm\|strict]` | get/set how firmly the agent hook enforces Hunch before edits (no arg prints the current level) |
 | `hunch test [cmd…]` | run the suite (default `npm test`); auto-capture failures as Bugs (suspects + recurrence→Constraints), mark passing tests' bugs fixed |
-| `hunch why <path\|symbol>` | decisions / bugs / constraints explaining a target (flags `⚠STALE`) |
+| `hunch why <path\|symbol> [--as-of <ref>]` | decisions / bugs / constraints explaining a target (flags `⚠STALE`); `--as-of` time-travels to what was believed at a commit/tag/branch |
+| `hunch timeline <path\|symbol>` | the decision history for a target — what was believed, its valid-time window, and what superseded it |
+| `hunch supersede <old> --by <new>` | mark one decision as replaced by another: closes the old one's valid-time window (invalidate, don't delete) |
 | `hunch query "<q>" [--semantic]` | full-text + graph search (`--semantic` blends in local embeddings) |
 | `hunch embed` | generate local embeddings for semantic recall (opt-in; needs `@huggingface/transformers`) |
-| `hunch context <path\|symbol>` | minimal relevant slice for a task: invariants → decisions → bugs → blast radius |
+| `hunch context <path\|symbol> [--as-of <ref>]` | minimal relevant slice for a task: invariants → decisions → bugs → blast radius (`--as-of` time-travels) |
 | `hunch fragile` | ranked fragility report with evidence |
-| `hunch check [--staged\|--commit <sha>] [--strict] [--blast]` | guardrail: flag changes touching a do-not-break invariant **directly or via blast radius** (a guarded file that depends on what you changed); `--blast` prints the dependency fan-out |
+| `hunch check [--staged\|--commit <sha>] [--strict] [--blast]` | guardrail: flag changes touching a do-not-break invariant **directly or via blast radius** (a guarded file that depends on what you changed), **and changes that re-introduce something a decision deliberately retired** (the Regression Guard); `--blast` prints the dependency fan-out |
 | `hunch stale [--resync]` | drift: records whose files changed after last verification (`--resync` regenerates stale decisions from their commits) |
 | `hunch review [--accept <id>\|--reject <id>]` | curate: triage / promote / drop low-confidence drafts |
 | `hunch migrate` | upgrade `.hunch/` records to the current schema version |
@@ -177,6 +182,12 @@ hunch firmness strict     # change it (takes effect on the next edit; no restart
 | `firm` | advisory **+** explicitly flag invariants in the file's scope |
 | `strict` | firm **+** **deny** an edit that hits a *blocking* invariant (directly or via blast radius), feeding the invariant back as the refusal reason |
 
+Before an edit, the hook also grounds the agent in anything an in-force decision
+**deliberately retired** from that file ("don't re-introduce `login` here — dec_017 removed
+it"). The actual gate is at commit time: `hunch check` runs the **Regression Guard** over
+the staged diff and, under `--strict`, fails the commit when a change re-adds a retired
+symbol/dependency tied to a blocking invariant (otherwise it warns).
+
 The hook never breaks your flow: any error or unrecognized input emits nothing and exits
 0, and it stays silent on files Hunch hasn't learned yet. `strict` only bites once you have
 **blocking** constraints recorded (`hunch record-constraint … --severity blocking`) — with
@@ -330,5 +341,5 @@ npm test            # node:test suite (store, graph, parse, indexer, synthesis,
 npm run hunch -- why src/store/hunchStore.ts   # run the CLI from source via tsx, no build
 ```
 
-See [DESIGN.md](DESIGN.md) for the full spec. Deferred by design: embeddings / vector
-search, PR/CI webhooks, a web dashboard, and multi-repo support.
+See [DESIGN.md](DESIGN.md) for the full spec. Deferred by design: PR/CI webhooks, a
+web dashboard, and multi-repo support.

package/dist/cli/index.js

@@ -24,7 +24,8 @@ import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { selectProvider } from "../synthesis/provider.js";
-import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff } from "../extractors/git.js";
+import { analyzeDiff } from "../extractors/diff.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { updateClaudeMd } from "../integrations/claudemd.js";
@@ -293,12 +294,16 @@ program
     .command("why")
     .description("Explain why a file/symbol is the way it is (decisions, bugs, constraints).")
     .argument("<target>", "file path or symbol name")
-    .action((target) => {
+    .option("--as-of <ref>", "time-travel: what was believed as of a commit/tag/branch (e.g. v0.7.0, HEAD~5)")
+    .action((target, opts) => {
     const { store, root } = storeFor();
-    const w = store.why(target);
+    const asOf = opts.asOf ? asOfDate(opts.asOf, root) : undefined;
+    if (opts.asOf && !asOf)
+        return fail(`could not resolve --as-of "${opts.asOf}" to a commit (need a git repo and a valid ref)`);
+    const w = store.why(target, { asOf });
     const staleIds = new Set(store.staleness((f) => lastChangeDate(f, root)).map((s) => s.id));
     const drift = (id) => (staleIds.has(id) ? " ⚠STALE" : "");
-    console.log(`Why "${target}":\n`);
+    console.log(asOf ? `Why "${target}" (as of ${opts.asOf} — ${asOf.slice(0, 10)}):\n` : `Why "${target}":\n`);
     if (w.decisions.length) {
         console.log("DECISIONS:");
         for (const d of w.decisions)
@@ -385,6 +390,9 @@ program
         rationale: opts.rationale,
         source_decision: opts.sourceDecision ?? null,
         violations: [],
+        status: "active",
+        valid_from: new Date().toISOString(),
+        valid_to: null,
         provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: new Date().toISOString() },
     });
     store.reindex();
@@ -538,6 +546,13 @@ program
             }
         }
     }
+    // 3) REGRESSION — does the diff RE-ADD something an in-force decision removed?
+    //    (e.g. re-introducing a symbol/dep that was deliberately deleted). Warn
+    //    always; only a blocking-linked resurrection fails the commit under strict.
+    const diff = opts.commit ? commitDiff(opts.commit, root) : stagedDiff(root);
+    const an = analyzeDiff(diff);
+    const regHits = store.regressionHits({ symbols: an.addedSymbols.map((s) => s.name), deps: an.addedDeps }, files);
+    const regBlocking = regHits.filter((h) => h.blocking).length;
     if (opts.blast) {
         console.log(`Blast radius of ${files.length} changed file(s):`);
         for (const f of files) {
@@ -547,8 +562,8 @@ program
         }
         console.log("");
     }
-    if (!direct.size && !near.size) {
-        console.log(`✓ ${files.length} changed file(s) touch no recorded invariants (directly or via blast radius).`);
+    if (!direct.size && !near.size && !regHits.length) {
+        console.log(`✓ ${files.length} changed file(s) touch no recorded invariants (directly or via blast radius) and re-introduce nothing deliberately retired.`);
         store.close();
         return;
     }
@@ -569,8 +584,18 @@ program
             console.log(`  ${mark(c.severity)} [${c.severity}] ${c.statement}\n      ${c.id}\n      ${via.slice(0, 4).join("\n      ")}${via.length > 4 ? `\n      …+${via.length - 4} more path(s)` : ""}`);
         }
     }
-    if (opts.strict && blocking) {
-        console.log(`\n✗ ${blocking} blocking invariant(s) in scope (direct or near) — review before committing.`);
+    if (regHits.length) {
+        console.log(`${direct.size || near.size ? "\n" : ""}Re-introduces ${regHits.length} deliberately-retired item(s):\n`);
+        for (const h of regHits) {
+            console.log(`  ${h.blocking ? "⛔" : "⚠"} re-adds ${h.kind} \`${h.name}\` — ${h.decision} removed it${h.blocking ? " (blocking-linked)" : ""}\n      “${h.title}”\n      ${h.reason}`);
+        }
+    }
+    if (opts.strict && (blocking || regBlocking)) {
+        const reasons = [
+            blocking ? `${blocking} blocking invariant(s) in scope` : "",
+            regBlocking ? `${regBlocking} blocking-linked regression(s)` : "",
+        ].filter(Boolean).join(" + ");
+        console.log(`\n✗ ${reasons} — review before committing.`);
         process.exitCode = 1;
     }
     else {
@@ -584,10 +609,58 @@ program
     .description("Assemble the minimal relevant Hunch slice for a task on a file/symbol.")
     .argument("<target>", "file path or symbol")
     .option("--budget <n>", "rough token budget", "1500")
+    .option("--as-of <ref>", "time-travel: assemble the slice as it stood at a commit/tag/branch")
     .action((target, opts) => {
-    const { store } = storeFor();
+    const { store, root } = storeFor();
+    const asOf = opts.asOf ? asOfDate(opts.asOf, root) : undefined;
+    if (opts.asOf && !asOf)
+        return fail(`could not resolve --as-of "${opts.asOf}" to a commit`);
     store.reindex(); // reflect any out-of-band JSON edits before assembling
-    process.stdout.write(formatContext(store.assembleContext(target, Number(opts.budget))));
+    process.stdout.write(formatContext(store.assembleContext(target, Number(opts.budget), { asOf })));
+    store.close();
+});
+// ---- timeline -------------------------------------------------------------
+program
+    .command("timeline")
+    .description("Time-travel: the decision history for a file/symbol — what was believed, and when/why it changed.")
+    .argument("<target>", "file path or symbol name")
+    .action((target) => {
+    const { store } = storeFor();
+    const tl = store.timeline(target);
+    if (!tl.length) {
+        console.log(`No decision history for "${target}" yet.`);
+    }
+    else {
+        console.log(`Decision timeline for "${target}" (newest first):\n`);
+        for (const d of tl) {
+            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}` : "";
+            console.log(`  • ${d.id} [${d.status}] (${window})${sup}\n      ${d.title}`);
+        }
+    }
+    store.close();
+});
+// ---- supersede ------------------------------------------------------------
+program
+    .command("supersede")
+    .description("Mark one decision as replaced by another: closes the old one's valid-time window (invalidate, don't delete).")
+    .argument("<old>", "decision id being replaced")
+    .requiredOption("--by <new>", "decision id that supersedes it")
+    .action((oldId, opts) => {
+    const { store } = storeFor();
+    const by = store.json.get("decisions", opts.by);
+    if (!by) {
+        store.close();
+        return fail(`--by decision "${opts.by}" not found`);
+    }
+    const closed = store.supersede(oldId, by);
+    if (!closed) {
+        store.close();
+        return fail(`decision "${oldId}" not found (or same as --by)`);
+    }
+    store.reindex();
+    console.log(`✓ ${oldId} superseded by ${opts.by} — window closed at ${closed.valid_to?.slice(0, 10)}.`);
     store.close();
 });
 // ---- firmness (agent-hook enforcement level) ------------------------------
@@ -654,7 +727,11 @@ program
         }
         // advisory / firm / strict(non-blocking): inject the relevant Hunch slice.
         const ctx = store.assembleContext(target);
-        const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length;
+        // Regression Guard (edit-time grounding): what an in-force decision retired
+        // from this file. No diff exists yet, so this is context — "don't re-add X" —
+        // not a block; the commit-time `hunch check` does the actual gating.
+        const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
+        const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length || retired.length;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
         let text = formatContext(ctx).trim();
@@ -662,6 +739,10 @@ program
             const names = ctx.constraints.map((c) => `[${c.severity}] ${c.statement}`).join("; ");
             text += `\n\n⚠ This file is in scope of ${ctx.constraints.length} invariant(s): ${names}. Preserve them.`;
         }
+        if (retired.length) {
+            const items = retired.map((r) => `${[...r.symbols, ...r.deps].join(", ")} (${r.decision})`).join("; ");
+            text += `\n\n⚠ Deliberately RETIRED from this file — do not re-introduce without cause: ${items}.`;
+        }
         emitContext("PreToolUse", text);
     }
     catch {

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/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/providers.js

@@ -11,6 +11,7 @@
  *   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
+ *   Windsurf    | .windsurf/mcp_config.json| mcpServers    | .windsurf/rules/hunch.md
  *   (any other) | —                       | —              | AGENTS.md (cross-tool standard)
  *
  * Every writer MERGES into existing files (preserving other servers / user prose)
@@ -206,6 +207,25 @@ export function writeCursorRule(root, store) {
     writeFileSync(file, body);
     return file;
 }
+/** Windsurf (Cascade): .windsurf/mcp_config.json — same `mcpServers` shape as
+ *  Cursor. Repo-local (committed, shared via git) to match Hunch's other configs,
+ *  rather than the global ~/.codeium/windsurf path. Merges; refuses to clobber. */
+export function writeWindsurfMcp(root, inv) {
+    const file = join(root, ".windsurf", "mcp_config.json");
+    const json = readJsonObj(file);
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
+/** Windsurf project rule (.windsurf/rules/hunch.md). `trigger: always_on` keeps the
+ *  Hunch grounding in Cascade's context for every request. Fully managed (overwritten). */
+export function writeWindsurfRule(root, store) {
+    const file = join(root, ".windsurf", "rules", "hunch.md");
+    const body = `---\ntrigger: always_on\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\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
@@ -215,6 +235,7 @@ export function scaffoldProviders(root, inv, store) {
         ["Cursor", () => [writeCursorMcp(root, inv), writeCursorRule(root, store)]],
         ["VS Code (Copilot)", () => [writeVscodeMcp(root, inv), writeCopilotInstructions(root, store)]],
         ["Codex CLI", () => [writeCodexConfig(root, inv)]],
+        ["Windsurf", () => [writeWindsurfMcp(root, inv), writeWindsurfRule(root, store)]],
         ["Any (AGENTS.md)", () => [writeAgentsMd(root, store)]],
     ];
     return tasks.map(([assistant, run]) => {

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}`);

package/dist/store/hunchStore.js

@@ -4,6 +4,7 @@ import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { pathMatchesGlob } from "../core/glob.js";
+import { edgeId } from "../core/ids.js";
 export class HunchStore {
     paths;
     json;
@@ -273,13 +274,17 @@ export class HunchStore {
         return [...acc.values()].sort((a, b) => b.score - a.score).slice(0, limit).map((e) => ({ ...e.hit, score: e.score }));
     }
     /** All decisions/bugs/constraints/symbols/components touching a file path or
-     *  symbol name (hunch_why). */
-    why(target) {
+     *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
+     *  return only decisions/constraints whose valid-time window contained that
+     *  instant — "what did we believe as of commit X?". Omit `asOf` for the full,
+     *  history-inclusive view (backward-compatible default). */
+    why(target, opts = {}) {
         const decisions = this.json.loadAll("decisions");
         const bugs = this.json.loadAll("bugs");
         const constraints = this.json.loadAll("constraints");
         const symbols = this.json.loadAll("symbols");
         const components = this.json.loadAll("components");
+        const asOf = opts.asOf;
         const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || s.file.endsWith(target));
         const symIds = new Set(matchedSymbols.map((s) => s.id));
         const fileSet = new Set(matchedSymbols.map((s) => s.file));
@@ -287,9 +292,11 @@ export class HunchStore {
         const fileMatch = (files) => files.some((f) => f === target || (isPath && (f.endsWith(target) || target.endsWith(f))) || fileSet.has(f));
         return {
             target,
-            decisions: decisions.filter((d) => fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths)))),
+            decisions: decisions.filter((d) => (fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths))))
+                && inWindow(d.valid_from, d.valid_to, asOf)),
             bugs: bugs.filter((b) => fileMatch(b.affected_files) || b.affected_symbols.some((s) => symIds.has(s))),
-            constraints: constraints.filter((c) => c.scope.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))),
+            constraints: constraints.filter((c) => c.scope.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))
+                && inWindow(c.valid_from, c.valid_to, asOf)),
             symbols: matchedSymbols,
             components: components.filter((c) => c.paths.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))),
         };
@@ -357,13 +364,114 @@ export class HunchStore {
         }
         return [...out.values()].sort((a, b) => a.depth - b.depth || a.file.localeCompare(b.file));
     }
-    /** Constraints whose scope glob matches a path/glob (hunch_check_constraints). */
-    checkConstraints(scope) {
+    /** Constraints whose scope glob matches a path/glob (hunch_check_constraints).
+     *  By default only ACTIVE invariants are returned — a retired constraint is no
+     *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at
+     *  that instant (time-travel: "what must I not have broken as of commit X?"). */
+    checkConstraints(scope, opts = {}) {
         const all = this.json.loadAll("constraints");
+        const asOf = opts.asOf;
         return all
             .filter((c) => c.scope.some((g) => pathMatchesGlob(scope, g) || pathMatchesGlob(g, scope) || g === scope))
+            .filter((c) => (asOf ? inWindow(c.valid_from, c.valid_to, asOf) : c.status !== "retired"))
             .sort((a, b) => sev(b.severity) - sev(a.severity));
     }
+    /** Time-travel: the decision history for a target — every decision touching it,
+     *  newest-first, with its valid-time window and supersession links. Answers
+     *  "what did we believe, and when/why did it change?" (hunch_timeline). */
+    timeline(target) {
+        return this.why(target).decisions.sort((a, b) => (b.valid_from ?? b.date).localeCompare(a.valid_from ?? a.date));
+    }
+    /** Invalidate, don't delete (Zep edge-invalidation): close `oldId`'s valid-time
+     *  window at the superseding decision's `valid_from`, mark it superseded + linked,
+     *  and write a `supersedes` edge. Returns the updated old decision, or null if it
+     *  doesn't exist. All writes are atomic via json.put (con_902759b3dc). */
+    supersede(oldId, by) {
+        const old = this.json.get("decisions", oldId);
+        if (!old || old.id === by.id)
+            return null;
+        const closed = {
+            ...old,
+            status: "superseded",
+            superseded_by: by.id,
+            valid_to: old.valid_to ?? by.valid_from ?? null,
+        };
+        this.json.put("decisions", closed);
+        const edge = {
+            id: edgeId(by.id, oldId, "supersedes"),
+            from: by.id,
+            to: oldId,
+            type: "supersedes",
+            reason: `${by.id} supersedes ${oldId}`,
+            strength: 1,
+            provenance: { source: "derived", confidence: 1, evidence: [by.id, oldId] },
+        };
+        this.json.put("edges", edge);
+        return closed;
+    }
+    /** Regression Guard: detect a change RE-INTRODUCING something an in-force
+     *  decision deliberately removed. Matches the added symbols/deps of a diff
+     *  against the `retired` signal of decisions concerning the touched files. A hit
+     *  is `blocking` when the retiring decision is tied to an ACTIVE blocking
+     *  constraint (via source_decision) — that's the only case the strict guard
+     *  fails the commit on; everything else is an advisory warning. */
+    regressionHits(added, files) {
+        const addedSyms = new Set(added.symbols);
+        const addedDeps = new Set(added.deps);
+        if (!addedSyms.size && !addedDeps.size)
+            return [];
+        const fileRelevant = (related) => related.some((f) => files.some((x) => pathRelated(x, f)));
+        const decisions = this.json.loadAll("decisions");
+        // decisions tied to an active blocking constraint via source_decision
+        const blockingDec = new Set(this.json.loadAll("constraints")
+            .filter((c) => c.severity === "blocking" && c.status !== "retired" && c.source_decision)
+            .map((c) => c.source_decision));
+        const out = [];
+        const seen = new Set(); // dedup by kind+name: report each resurrected item once
+        const add = (d, kind, name) => {
+            const key = `${kind}:${name}`;
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            out.push({ decision: d.id, title: d.title, kind, name, blocking: blockingDec.has(d.id), reason: d.decision || d.title });
+        };
+        // Blocking-linked decisions first, so a deduped hit keeps the higher-severity
+        // attribution (the strict guard fails on `blocking`).
+        const ordered = [...decisions].sort((a, b) => Number(blockingDec.has(b.id)) - Number(blockingDec.has(a.id)));
+        for (const d of ordered) {
+            // Only IN-FORCE decisions: re-adding what an OUTDATED (superseded) decision
+            // removed is not a regression against the current design.
+            if (d.superseded_by || d.status === "superseded")
+                continue;
+            if (!d.retired.symbols.length && !d.retired.deps.length)
+                continue;
+            if (!fileRelevant(d.related_files))
+                continue;
+            for (const s of d.retired.symbols)
+                if (addedSyms.has(s))
+                    add(d, "symbol", s);
+            for (const dep of d.retired.deps)
+                if (addedDeps.has(dep))
+                    add(d, "dep", dep);
+        }
+        return out;
+    }
+    /** The symbols/deps an in-force decision deliberately RETIRED from a file — the
+     *  agent-hook grounding ("don't re-add X here; dec_Y removed it"). No diff is
+     *  available at edit time, so this surfaces the risk as context, not a block. */
+    retiredForFile(file) {
+        const out = [];
+        for (const d of this.json.loadAll("decisions")) {
+            if (d.superseded_by || d.status === "superseded")
+                continue;
+            if (!d.retired.symbols.length && !d.retired.deps.length)
+                continue;
+            if (!d.related_files.some((f) => pathRelated(f, file)))
+                continue;
+            out.push({ decision: d.id, title: d.title, symbols: d.retired.symbols, deps: d.retired.deps });
+        }
+        return out;
+    }
     /** Bugs matching a symptom (FTS over bugs) or a symbol, with lineage (hunch_bug_lineage). */
     bugLineage(symptomOrSymbol) {
         const bugs = this.json.loadAll("bugs");
@@ -450,8 +558,8 @@ export class HunchStore {
     /** The Context Assembler (DESIGN §2.1/§6): the MINIMAL relevant Hunch slice for
      *  a task on `target`, ordered by what matters most — invariants first, then the
      *  why, then blast radius and bug history — trimmed to a rough token budget. */
-    assembleContext(target, budget = 1500) {
-        const w = this.why(target);
+    assembleContext(target, budget = 1500, opts = {}) {
+        const w = this.why(target, opts);
         const symIds = w.symbols.map((s) => s.id);
         const blast = new Map();
         for (const id of symIds) {
@@ -477,6 +585,25 @@ export class HunchStore {
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;
 }
+/** Is a valid-time window open at `asOf`? `valid_from` undefined = always-started
+ *  (legacy records). `valid_to` null = still in force. `asOf` undefined disables
+ *  filtering (the history-inclusive default). Half-open [from, to) so a record and
+ *  the one that supersedes it never both match at the supersession instant. */
+/** Do two repo paths refer to the same file? Exact match, or one is a trailing
+ *  path-SEGMENT suffix of the other (e.g. "x.ts" vs "src/x.ts") — anchored at a
+ *  "/" boundary so "re.ts" never matches "store.ts" (the bare-endsWith hazard). */
+function pathRelated(a, b) {
+    return a === b || a.endsWith("/" + b) || b.endsWith("/" + a);
+}
+function inWindow(valid_from, valid_to, asOf) {
+    if (!asOf)
+        return true;
+    if (valid_from && valid_from > asOf)
+        return false;
+    if (valid_to != null && asOf >= valid_to)
+        return false;
+    return true;
+}
 function round(n) {
     return Math.round(n * 100) / 100;
 }

package/dist/synthesis/synthesize.js

@@ -93,8 +93,17 @@ export async function syncCommit(store, root, sha, opts = {}) {
         related_components: relatedComponents,
         related_files: codeFiles,
         supersedes: existing?.supersedes ?? null,
+        superseded_by: existing?.superseded_by ?? null,
         caused_by_bug: existing?.caused_by_bug ?? null,
         commit: meta.shortSha,
+        // Valid-time window is git-anchored: the decision takes effect at its commit
+        // date and stays in force until a later decision supersedes it (preserve any
+        // window an earlier sync/supersession already set on this same commit's record).
+        valid_from: existing?.valid_from ?? meta.date,
+        valid_to: existing?.valid_to ?? null,
+        // What this commit DELETED — the Regression Guard later matches a re-adding
+        // diff against this (recompute from the fresh analysis, even on --force).
+        retired: { symbols: analysis.removedSymbols.map((s) => s.name), deps: analysis.removedDeps },
         provenance: {
             source: draft.source,
             confidence: draft.confidence,
@@ -227,6 +236,9 @@ function promoteConstraint(store, bug) {
         rationale: `Derived from ${bug.id}: ${bug.root_cause || bug.symptom}`,
         source_decision: null,
         violations: [],
+        status: "active",
+        valid_from: new Date().toISOString(),
+        valid_to: null,
         provenance: { source: "derived", confidence: Math.min(0.9, bug.provenance.confidence + 0.2), evidence: [`bug:${bug.id}`] },
     };
     return store.json.put("constraints", con);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "license": "MIT",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",