@davesheffer/hunch 0.5.0 → 0.9.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

@@ -56,13 +56,21 @@ Either way you then type `hunch …`. From a source checkout without `npm link`,
 `node dist/cli/index.js …` (or `npm run hunch -- …` to run via tsx). The rest of this
 README uses `hunch` for brevity.
 
-### 2. (Recommended) make the `claude` CLI available
+### 2. (Recommended) make a coding-assistant CLI available
 
-Hunch's LLM synthesis is billed to your **Claude Pro/Max subscription** through the
-`claude` CLI — **never** the pay-per-token API. If `claude --version` works in your
-terminal, you get full LLM-quality capture for free. If it doesn't, Hunch still works
-using a deterministic structural heuristic (lower-confidence drafts). `hunch doctor`
-tells you which mode you're in.
+Hunch's LLM synthesis is billed to **your subscription** through a coding-assistant
+CLI — **never** a pay-per-token API key (the API key is stripped from the child env).
+Hunch auto-detects the first one present, in this order:
+
+| CLI | Subscription | Detected by |
+|---|---|---|
+| `claude` (Claude Code) | Claude Pro/Max | `claude --version` |
+| `codex` (OpenAI Codex) | ChatGPT Plus/Pro | `codex --version` |
+| `cursor-agent` (Cursor) | Cursor | `cursor-agent --version` |
+
+If none is installed, Hunch still works using a deterministic structural heuristic
+(lower-confidence drafts). `hunch doctor` tells you which mode you're in; force one
+with `HUNCH_SYNTH_PROVIDER=claude-cli|codex-cli|cursor-agent|deterministic`.
 
 ### 3. Initialize the repo you want a memory for
 
@@ -100,24 +108,47 @@ 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
+
+The Hunch MCP server is **client-agnostic** — one `.hunch/` graph powers every
+assistant. `hunch init` scaffolds each tool's MCP config + ambient grounding so
+they all consult the same memory:
+
+| Assistant | MCP config | Grounding file |
+|---|---|---|
+| Claude Code | `.mcp.json` | `CLAUDE.md` + `/hunch-*` slash commands |
+| 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` |
+| Anything else | — | `AGENTS.md` (cross-tool standard) |
+
+Each writer **merges** into existing files (other MCP servers and your own prose are
+preserved) and is idempotent. Opt out with `hunch init --no-providers`.
 
 **Through the CLI** — the same graph, from your terminal:
 
 | Command | What |
 |---|---|
-| `hunch init [--enforce]` | scaffold `.hunch/`, index, install hook + merge driver, wire up Claude Code (`--enforce` adds a pre-commit invariant guard) |
+| `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 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) |
 | `hunch record-bug --test <id> --message <m>` | capture a Bug from a failing test |
+| `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 |
@@ -125,6 +156,43 @@ The MCP tools Claude calls under the hood: `hunch_why`, `hunch_query`,
 | `hunch doctor` | environment diagnostics (git, auth mode, schema version, counts) |
 | `hunch mcp` | start the MCP server over stdio (Claude Code connects here) |
 
+## Grounding the agent automatically (firmness)
+
+Telling an assistant "consult Hunch first" in a prompt is advisory — it drifts. `hunch
+init` instead installs two **Claude Code agent hooks** (in `.claude/settings.json`) so the
+grounding is enforced by the harness, not by the model's memory:
+
+- **Before every edit** (`PreToolUse` on `Edit`/`Write`/`MultiEdit`) Hunch injects the
+  relevant slice for the file being touched — its decisions, invariants, bug history, and
+  blast radius — straight into the model's context.
+- **On every prompt** (`UserPromptSubmit`) it reminds the agent to query Hunch.
+
+How hard it pushes is one committed knob — set it once, it applies to the whole team:
+
+```bash
+hunch firmness            # print the current level
+hunch firmness strict     # change it (takes effect on the next edit; no restart)
+```
+
+| Level | Before an edit |
+|---|---|
+| `off` | nothing (hook is a no-op) |
+| `advisory` *(default)* | inject the relevant Hunch slice as context |
+| `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
+none, every level degrades to context-only. Opt out of the hooks entirely with `hunch init
+--no-agent-hooks`.
+
 ## Semantic search (optional)
 
 By default `hunch query` and the `hunch_query` MCP tool use fast keyword (FTS) search —
@@ -272,5 +340,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

@@ -15,6 +15,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
+import { relative } from "node:path";
 import { Command } from "commander";
 import { hunchPaths, findRoot } from "../core/paths.js";
 import { HunchStore } from "../store/hunchStore.js";
@@ -23,12 +24,17 @@ 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";
-import { writeMcpJson, writeSlashCommands } from "../integrations/scaffold.js";
+import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
+import { scaffoldProviders } from "../integrations/providers.js";
 import { formatContext } from "../core/format.js";
+import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
+import { blockingInScope } from "../core/hookpolicy.js";
+import { constraintId } from "../core/ids.js";
 import { readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
 import { mergeHunchJson } from "../store/merge.js";
 import { planCompaction } from "../store/compact.js";
@@ -49,7 +55,15 @@ program
     .option("--no-index", "skip the initial repo index")
     .option("--no-enforce", "do not install the advisory pre-commit constraint guard")
     .option("--enforce-strict", "make the pre-commit guard FAIL the commit on a blocking invariant (direct or near)")
+    .option("--no-providers", "skip scaffolding non-Claude assistant configs (Cursor / VS Code / Codex / AGENTS.md)")
+    .option("--no-agent-hooks", "skip installing the Claude Code agent hooks (.claude/settings.json)")
+    .option("--firmness <level>", "agent-hook firmness: off | advisory | firm | strict")
     .action((opts) => {
+    // Validate --firmness up front, before any side effects (indexing, git hooks,
+    // .mcp.json) or opening the store — a bad value must not leave a half-init.
+    if (opts.firmness !== undefined && !isFirmness(opts.firmness)) {
+        return fail(`--firmness must be one of: ${FIRMNESS_LEVELS.join(", ")}`);
+    }
     const root = findRoot();
     const paths = hunchPaths(root);
     const store = new HunchStore(paths);
@@ -88,6 +102,26 @@ program
     console.log(`  ✓ wrote ${cmds.length} slash commands (/hunch-why, /hunch-fix, /hunch-fragile)`);
     const cmd = updateClaudeMd(root, store);
     console.log(`  ✓ updated ${rel(root, cmd)} with ambient Hunch context`);
+    // Firmness: stamp .hunch/config.json (default advisory) so `hunch hook` reads a
+    // level even before the user runs `hunch firmness` (--firmness validated above).
+    const firmness = writeConfig(paths, opts.firmness ? { firmness: opts.firmness } : {}).firmness;
+    // Agent hooks: ground the assistant in Hunch automatically (PreToolUse injects
+    // context before edits; UserPromptSubmit reminds). Reads firmness at run time.
+    if (opts.agentHooks !== false) {
+        const a = installClaudeHooks(root, `${inv.shell} hook`);
+        console.log(`  ✓ Claude Code agent hooks ${a.action} (firmness: ${firmness} — change with \`hunch firmness <level>\`)`);
+    }
+    // Multi-assistant compatibility: the MCP server is client-agnostic, so wire up
+    // Cursor / VS Code (Copilot) / Codex / AGENTS.md to the same .hunch/ graph.
+    if (opts.providers !== false) {
+        const ps = scaffoldProviders(root, inv.mcp, store);
+        const ok = ps.filter((p) => !p.error);
+        const total = ok.reduce((a, p) => a + p.files.length, 0);
+        console.log(`  ✓ wrote ${total} multi-assistant config file(s) → ${ok.map((p) => p.assistant).join(", ")}`);
+        for (const p of ps)
+            if (p.error)
+                console.log(`  ⚠ skipped ${p.assistant}: ${p.error}`);
+    }
     store.close();
     console.log("\nNext: make a commit (the hook captures a decision), then ask Claude Code \"why is X built this way?\"");
     console.log("Cold start? Seed from history:  hunch backfill --since 90d");
@@ -260,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)
@@ -324,6 +362,44 @@ program
         console.log(`  ↳ promoted constraint ${r.constraint.id} [${r.constraint.severity}]: ${r.constraint.statement}`);
     store.close();
 });
+// ---- record-constraint (human-authored invariant) -------------------------
+program
+    .command("record-constraint")
+    .description("Record an invariant the codebase must not break — what `hunch check` and the strict agent hook enforce.")
+    .argument("<statement>", 'the invariant, e.g. "vectors are derived, never the source of truth"')
+    .option("--scope <globs>", "comma-separated path/glob(s) it applies to (e.g. src/store/**)", "")
+    .option("--severity <s>", "advisory | warning | blocking", "warning")
+    .option("--type <t>", "security | performance | correctness | architecture | compliance", "correctness")
+    .option("--rationale <text>", "why it must hold", "")
+    .option("--source-decision <id>", "decision id this derives from")
+    .option("--enforcement <e>", "advisory_v1 | ci | manual", "advisory_v1")
+    .action((statement, opts) => {
+    const SEV = ["advisory", "warning", "blocking"];
+    if (!SEV.includes(opts.severity))
+        return fail(`--severity must be one of: ${SEV.join(", ")}`);
+    const { store, root } = storeFor();
+    store.json.ensureDirs();
+    const scope = opts.scope.split(",").map((s) => s.trim()).filter(Boolean);
+    const c = store.json.put("constraints", {
+        id: constraintId(statement),
+        type: opts.type,
+        statement,
+        scope,
+        severity: opts.severity,
+        enforcement: opts.enforcement,
+        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();
+    updateClaudeMd(root, store);
+    console.log(`✓ recorded ${c.severity} constraint ${c.id}: "${c.statement}" (scope: ${scope.join(", ") || "repo"})`);
+    store.close();
+});
 // ---- test (failure-learning loop) -----------------------------------------
 program
     .command("test")
@@ -470,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) {
@@ -479,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;
     }
@@ -501,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 {
@@ -516,12 +609,149 @@ 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) ------------------------------
+program
+    .command("firmness")
+    .description("Get or set how firmly the Claude Code agent hook enforces Hunch before edits.")
+    .argument("[level]", "off | advisory | firm | strict (omit to print the current level)")
+    .action((level) => {
+    const paths = hunchPaths(findRoot());
+    if (!level) {
+        console.log(`firmness: ${readConfig(paths).firmness}`);
+        console.log(`levels:   ${FIRMNESS_LEVELS.join(" | ")}  (set with: hunch firmness <level>)`);
+        return;
+    }
+    if (!isFirmness(level)) {
+        return fail(`firmness must be one of: ${FIRMNESS_LEVELS.join(", ")}`);
+    }
+    const next = writeConfig(paths, { firmness: level }).firmness;
+    console.log(`✓ firmness set to ${next} (takes effect on the next edit — no Claude Code restart needed).`);
+});
+// ---- hook (Claude Code agent-hook handler) --------------------------------
+program
+    .command("hook")
+    .description("Claude Code hook handler: inject relevant Hunch context before edits (and, at strict firmness, deny edits that hit a blocking invariant). Reads the hook event JSON on stdin.")
+    .action(async () => {
+    // A hook MUST NEVER break the agent: on ANY error or unrecognized input we
+    // emit nothing and exit 0 (the action defers to Claude Code's normal flow).
+    let store = null;
+    try {
+        const evt = JSON.parse(await readStdin());
+        const root = findRoot();
+        const paths = hunchPaths(root);
+        const firmness = readConfig(paths).firmness;
+        if (firmness === "off")
+            return;
+        if (evt.hook_event_name === "UserPromptSubmit") {
+            emitContext("UserPromptSubmit", HOOK_REMINDER);
+            return;
+        }
+        if (evt.hook_event_name !== "PreToolUse")
+            return;
+        const abs = evt.tool_input?.file_path;
+        if (!abs)
+            return;
+        const target = toRepoRel(root, abs);
+        // Outside the repo (".." prefix) or on another drive (absolute, e.g. "D:/…")
+        // → nothing for Hunch to say.
+        if (!target || target.startsWith("..") || /^[a-zA-Z]:/.test(target))
+            return;
+        store = new HunchStore(paths);
+        // strict: refuse an edit that hits a BLOCKING invariant (direct OR via blast
+        // radius), feeding the invariant statement back as the refusal reason. Reindex
+        // first so the blast radius reflects uncommitted edges — strict opts into the
+        // cost for correctness. Advisory/firm skip it: the hook fires on every edit,
+        // and decisions/constraints don't change between commits, so the committed
+        // index is good enough for grounding.
+        if (firmness === "strict") {
+            store.reindex();
+            const deny = blockingInScope(store, target);
+            if (deny) {
+                emitDeny(deny.reason);
+                return;
+            }
+        }
+        // advisory / firm / strict(non-blocking): inject the relevant Hunch slice.
+        const ctx = store.assembleContext(target);
+        // 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();
+        if (firmness !== "advisory" && ctx.constraints.length) {
+            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 {
+        // swallow — never block an edit on a hook failure
+    }
+    finally {
+        store?.close();
+    }
+});
 // ---- review (curate loop) -------------------------------------------------
 program
     .command("review")
@@ -676,16 +906,22 @@ program
     console.log(`schema:     v${onDisk} (hunch v${SCHEMA_VERSION})${schemaNote}`);
     const provider = await selectProvider();
     console.log(`synthesis:  ${provider.name}`);
-    // Synthesis is billed to the user's Claude SUBSCRIPTION via the `claude` CLI,
-    // never the pay-per-token API. Surface whatever stands between here and that.
-    if (provider.name === "claude-cli") {
-        const hadKey = !!(process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN);
-        console.log(`            ↳ LLM synthesis billed to your Claude subscription` +
-            (hadKey ? ` (ANTHROPIC_API_KEY in env is stripped — never billed to the API)` : ``));
+    // Synthesis is billed to the user's SUBSCRIPTION via a coding-assistant CLI,
+    // never a pay-per-token API key. Surface which one — or what's missing.
+    const SUB = {
+        "claude-cli": { label: "Claude subscription (claude CLI)", strip: "ANTHROPIC_API_KEY" },
+        "codex-cli": { label: "ChatGPT subscription (codex CLI)", strip: "OPENAI_API_KEY" },
+        "cursor-agent": { label: "Cursor subscription (cursor-agent CLI)" },
+    };
+    const sub = SUB[provider.name];
+    if (sub) {
+        const hadKey = sub.strip && !!process.env[sub.strip];
+        console.log(`            ↳ LLM synthesis billed to your ${sub.label}` +
+            (hadKey ? ` (${sub.strip} in env is stripped — never billed to the API)` : ``));
     }
-    else if (provider.name === "deterministic") {
-        console.log(dim(`            ↳ no \`claude\` CLI — synthesis uses the offline heuristic (advisory, low-confidence)`));
-        console.log(dim(`              for full synthesis: install Claude Code + \`claude /login\`, or set CLAUDE_CODE_OAUTH_TOKEN (\`claude setup-token\`) for CI`));
+    else {
+        console.log(dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence)`));
+        console.log(dim(`              for full synthesis install one: Claude Code (\`claude /login\`), Codex (\`codex login\`), or Cursor (\`cursor-agent login\`)`));
     }
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
@@ -712,6 +948,37 @@ function fail(msg) {
     console.error(`error: ${msg}`);
     process.exitCode = 1;
 }
+// --- agent-hook helpers (used by `hunch hook`) -----------------------------
+const HOOK_REMINDER = "Hunch (engineering memory) is available for this repo. Before editing, call " +
+    "hunch_check_constraints(scope) for do-not-break invariants and hunch_why(target) " +
+    "for the rationale; use hunch_get_dependents for blast radius and hunch_bug_lineage " +
+    "for prior root causes. After a non-trivial choice, record it with hunch_record_decision.";
+/** Read all of stdin (the hook event JSON). A TTY (no piped input) resolves to ""
+ *  so an accidental interactive `hunch hook` exits cleanly instead of hanging. */
+function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY)
+            return resolve("");
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => (data += c));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+    });
+}
+/** Absolute edit path → repo-relative, forward-slash (constraint scopes are
+ *  forward-slash globs even on Windows). */
+function toRepoRel(root, abs) {
+    return relative(root, abs).split("\\").join("/");
+}
+function emitContext(event, text) {
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } }));
+}
+function emitDeny(reason) {
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason },
+    }));
+}
 program.parseAsync().catch((e) => {
     try {
         openStore?.close();

package/dist/core/config.js

@@ -0,0 +1,35 @@
+/** Hunch user config (`.hunch/config.json`) — runtime knobs that are NOT schema
+ *  state (the on-disk schema version lives in manifest.json). Committed alongside
+ *  the graph, so a whole team shares the same settings — e.g. how firmly the
+ *  Claude Code agent hook enforces engineering memory before an edit. */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+export const FIRMNESS_LEVELS = ["off", "advisory", "firm", "strict"];
+export const DEFAULT_FIRMNESS = "advisory";
+function defaults() {
+    return { firmness: DEFAULT_FIRMNESS };
+}
+export function isFirmness(v) {
+    return typeof v === "string" && FIRMNESS_LEVELS.includes(v);
+}
+/** Read `.hunch/config.json`. A missing/unparseable file, or an unknown firmness
+ *  value, falls back to defaults — the hook must NEVER crash an edit over config. */
+export function readConfig(paths) {
+    if (!existsSync(paths.config))
+        return defaults();
+    try {
+        const raw = JSON.parse(readFileSync(paths.config, "utf8"));
+        return { firmness: isFirmness(raw.firmness) ? raw.firmness : DEFAULT_FIRMNESS };
+    }
+    catch {
+        return defaults();
+    }
+}
+/** Write `.hunch/config.json`, merging `patch` over the current on-disk config. */
+export function writeConfig(paths, patch) {
+    const next = { ...readConfig(paths), ...patch };
+    mkdirSync(dirname(paths.config), { recursive: true });
+    writeFileSync(paths.config, JSON.stringify(next, null, 2) + "\n");
+    return next;
+}
+//# sourceMappingURL=config.js.map

package/dist/core/hookpolicy.js

@@ -0,0 +1,22 @@
+/** Return a BlockingHit if editing `file` (repo-relative) hits a blocking
+ *  invariant directly or through its blast radius, else null. */
+export function blockingInScope(store, file) {
+    for (const c of store.checkConstraints(file)) {
+        if (c.severity === "blocking") {
+            return {
+                reason: `Hunch: editing ${file} would touch a BLOCKING invariant — "${c.statement}" (${c.id}). Do not proceed unless this change is meant to modify that invariant; otherwise preserve it.`,
+            };
+        }
+    }
+    for (const b of store.blastRadiusFiles(file)) {
+        for (const c of store.checkConstraints(b.file)) {
+            if (c.severity === "blocking") {
+                return {
+                    reason: `Hunch: ${file} is in the blast radius of a BLOCKING invariant — "${c.statement}" (${c.id}; via ${b.file}, ${b.via} depth ${b.depth}). Verify the invariant still holds before editing.`,
+                };
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=hookpolicy.js.map