@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/extractors/repoSource.d.ts

@@ -0,0 +1,53 @@
+export type RepoScanSource = {
+    kind: "checkout";
+} | {
+    kind: "staged";
+} | {
+    kind: "working";
+} | {
+    kind: "commit";
+    ref: string;
+} | {
+    kind: "base";
+};
+export type RepoScanSourceKind = RepoScanSource["kind"];
+export interface RepoScanSourceIdentity {
+    kind: RepoScanSourceKind;
+    /** Canonical commit object used by commit/base scans. */
+    revision?: string;
+}
+export type RepoSourceIssueCode = "conflicted" | "unsafe_path" | "unsafe_mode" | "symlink" | "non_regular" | "oversized" | "invalid_encoding" | "read_failed" | "parse_failed";
+export interface RepoSourceIssue {
+    path: string;
+    code: RepoSourceIssueCode;
+    detail: string;
+}
+export interface RepoSourceRead {
+    source: string | null;
+    mode: string;
+    /** Hash of the exact bytes supplied by Git/filesystem, before UTF-8 decode. */
+    contentHash?: string;
+    /** Missing tracked working files are intentional deletions, not scan failures. */
+    absent?: boolean;
+    issue?: RepoSourceIssue;
+}
+export interface RepoSourceEntry {
+    path: string;
+    mode: string;
+    read(): RepoSourceRead;
+}
+export interface RepoSourceInventory {
+    identity: RepoScanSourceIdentity;
+    entries: RepoSourceEntry[];
+}
+export declare function isIndexedCodePath(path: string): boolean;
+export declare function repoSourceInventory(root: string, source?: RepoScanSource): RepoSourceInventory;
+/** Read a known, safe auxiliary manifest from the exact same source selection as
+ * the semantic code scan. This is intentionally path-specific rather than a
+ * second inventory: manifests inform resolution but never become code files. */
+export declare function repoAuxiliarySource(root: string, source: RepoScanSource | undefined, path: string): RepoSourceRead;
+export declare function dirtyIndexedCodePaths(root: string): string[];
+export declare function assertCleanIndexedCode(root: string): void;
+/** Auxiliary manifests can change graph resolution just like source code. A
+ * durable checkout scan must therefore prove these selected paths are clean. */
+export declare function assertCleanAuxiliarySources(root: string, paths: readonly string[]): void;

package/dist/extractors/testreport.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Parse a test run's output into pass/fail signals for the failure-learning loop
+ * (`hunch test`). Test-framework-agnostic: it recognizes both common shapes that
+ * `node:test` (this repo), mocha, ava, vitest, jest, and `prove` emit:
+ *
+ *  - TAP:  `ok 12 - name` / `not ok 3 - name`, with an optional indented YAML
+ *          diagnostic block (error + stack) under a failure.
+ *  - spec: node:test's default non-TTY reporter — `✔ name (1.2ms)` /
+ *          `✖ name (1.2ms)`, failures followed by an indented error block.
+ *          (Also accepts ✓/✗.)
+ *
+ * Design choices:
+ *  - A failure's `message` is the test name plus its indented diagnostic block —
+ *    exactly the context recordFailure() feeds the synthesizer for root-cause and
+ *    suspect ranking.
+ *  - If NEITHER shape is recognized, we return empty lists + recognized=false so
+ *    the caller falls back to a coarse "the suite failed" bug from the raw tail —
+ *    never silently reports success.
+ *  - Results are deduped by name (a spec reporter can echo a failing test in its
+ *    end-of-run recap).
+ */
+export interface TestFailure {
+    /** Stable test identifier (the description) — seeds the bug id. */
+    test: string;
+    /** Name + diagnostic block; the root-cause/suspect context for synthesis. */
+    message: string;
+}
+export interface TestReport {
+    failures: TestFailure[];
+    /** Names of tests that passed — used to mark previously-open bugs as fixed. */
+    passed: string[];
+    /** True iff at least one result line (TAP or spec) was recognized. */
+    recognized: boolean;
+}
+/** Parse TAP-or-spec text. Pure + synchronous so it's trivially unit-testable. */
+export declare function parseTestReport(output: string): TestReport;

package/dist/integrations/ciAction.d.ts

@@ -0,0 +1,8 @@
+export declare function ciWorkflowYaml(): string;
+export interface CiResult {
+    path: string;
+    action: "created" | "exists";
+}
+/** Write .github/workflows/hunch-guard.yml. Never overwrites an existing file
+ *  (respects user edits) — reports "exists" instead. */
+export declare function writeCiWorkflow(root: string): CiResult;

package/dist/integrations/claudeConfig.d.ts

@@ -0,0 +1,44 @@
+/** Absolute path to Claude Code's per-user config (`~/.claude.json`). */
+export declare function claudeConfigPath(): string;
+export interface HealedGroup {
+    /** The normalized real path the casing variants collapse to. */
+    realPath: string;
+    /** The raw project keys that differ only by drive-letter case. */
+    casings: string[];
+    /** The union of MCP server names now mirrored across every casing. */
+    servers: string[];
+}
+export interface HealResult {
+    platform: NodeJS.Platform;
+    /** False on non-Windows (the bug can't occur there) — the heal is a no-op. */
+    applicable: boolean;
+    file: string;
+    /** Path to the timestamped backup, set only when a write happened. */
+    backup?: string;
+    /** Whether the file was modified. */
+    changed: boolean;
+    /** The case-split groups that were merged (empty when nothing to heal). */
+    groups: HealedGroup[];
+}
+export interface HealOptions {
+    /** Defaults to `claudeConfigPath()`. */
+    file?: string;
+    /** Defaults to `process.platform`; pass "win32" to exercise the heal in tests. */
+    platform?: NodeJS.Platform;
+}
+/**
+ * Scan `~/.claude.json` for project keys that collapse to the same real directory
+ * but differ by drive-letter case, and HEAL each split by computing the UNION of
+ * its casings' MCP config and MIRRORING that union back into EVERY casing.
+ *
+ * Why mirror (not merge-into-one-canonical-and-delete-the-rest): we cannot predict
+ * which casing a given Claude Code session will resolve its cwd to. If we collapsed
+ * to a single canonical key, a session that lands on a deleted casing would get a
+ * fresh empty block → hunch missing again. Mirroring the union guarantees that
+ * whichever casing wins, the server is there — and it deletes nothing Claude made.
+ *
+ * Safety: no-op on non-Windows; backs up the file (timestamped copy) BEFORE any
+ * write; merges only (never clobbers other servers/keys); and THROWS rather than
+ * overwrite a non-empty file it cannot parse (mirrors readJsonObj in providers.ts).
+ */
+export declare function healClaudeConfigCaseSplit(opts?: HealOptions): HealResult;

package/dist/integrations/claudemd.d.ts

@@ -0,0 +1,13 @@
+import type { HunchStore } from "../store/hunchStore.js";
+/** Remove the managed HUNCH section (markers inclusive), leaving only the
+ *  user-authored surroundings. Lets a caller decide whether two versions of a
+ *  doc differ ONLY in generated content (the stranded-grounding heal,
+ *  fnd_b269d5c422): equal outside the block ⇒ regenerating cannot lose prose. */
+export declare function stripManagedSection(text: string): string;
+export declare function renderHunchSection(store: HunchStore, root?: string): string;
+/** 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 declare function upsertSection(file: string, section: string, fallbackTitle: string): string;
+/** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
+export declare function updateClaudeMd(root: string, store: HunchStore): string;

package/dist/integrations/claudemd.js

@@ -8,6 +8,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { basename, join, dirname } from "node:path";
 import { wikiSummary } from "../wiki/wiki.js";
 import { PolicyRepository } from "../constitution/repository.js";
+import { renderCountsMatch } from "../core/groundingLag.js";
 const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
 const END = "<!-- HUNCH:END -->";
 /** Remove the managed HUNCH section (markers inclusive), leaving only the
@@ -41,13 +42,14 @@ export function renderHunchSection(store, root) {
     lines.push("");
     lines.push("This repo has **Hunch** — a curated graph of *why* the code is the way it is " +
         "(decisions, bug history, invariants). It currently holds " +
-        `**${counts.decisions} decisions, ${counts.bugs} bugs, ${counts.constraints} constraints, ${counts.components} components, ${counts.policies} policies${counts.findings ? `, ${counts.findings} open findings` : ""}**.`);
+        `${renderCountsMatch(counts)}.`);
     lines.push("");
     lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
     lines.push("");
     lines.push("**Orient (session/task start):**");
+    lines.push("- For a new user task, call `hunch_task(action: \"start\", title: <short task title>)` once and retain its `task_id`. If a native prompt hook already supplied a task ID, reuse its exact start arguments instead of creating another task; each new native prompt has its own ID. Otherwise reuse the ID for follow-up work on the same task; never borrow another task's ID. This is task bookkeeping; `hunch_context` remains the first memory lookup. If reporting fails, continue the work and disclose the gap.");
     lines.push("- When the user asks to **update Hunch**, run `hunch update` from this repository root. It updates to the latest release and repairs all configured harness pins. Use `hunch update --global` to also update a global CLI alongside a repository dependency; reconnect active MCP sessions afterward.");
-    lines.push("- `hunch_context(target)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST.**");
+    lines.push("- `hunch_context(target, task_id)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST** for memory. Include the current task ID on each context call so its contribution is inspectable.");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
     lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");
     lines.push("- `hunch_escalations()` — the decisions only the HUMAN can make (including one exact imported ADR at a time, topic conflicts, and policy calls). Normally empty; when it isn't, ASK the user inline — an entry is a question, silence is never approval. Apply an ADR answer only through `hunch_review_imported_adr` with its printed source and review hashes.");
@@ -69,6 +71,13 @@ export function renderHunchSection(store, root) {
     lines.push("- `hunch_policy_evaluate(policy_id?, active_only?)` / `hunch_policy_plan(policy_id)` / `hunch_policy_card(policy_id)` / `hunch_policy_proof(policy_id)` — evaluate canonical policy, inspect the planned corpus, review the evidence/uncertainty card, and inspect raw replay receipts; only an explicit human activation grants authority.");
     lines.push("- `hunch_pr_impact(base?)` / `hunch_merge_verdict(...)` — a change's memory surface; would it re-open a closed bug?");
     lines.push("");
+    lines.push("**Before the final response — make Hunch's contribution visible:**");
+    lines.push("- When running a relevant check, use the exact verification_argv launcher returned by hunch_task start, followed by the check command and its arguments, from this worktree. It runs `hunch task verify <task_id> -- <command> [arguments]` using the same installation as MCP, avoiding stale global binaries. This retains the actual exit result and source snapshot; raw output is not stored. Do not rerun an expensive check solely for reporting; missing evidence stays unverified.");
+    lines.push("- Include the current task_id when calling hunch_record_decision, hunch_record_correction, or hunch_record_finding. The save path records its actual memory home and verifies exact Git revisions when committing or pushing; never infer publication from a successful capture alone.");
+    lines.push("- Before claiming an application, call `hunch_report(task_id)` and copy the exact occurrence_id, record_id and content_hash from application_references, adding an action you actually took. Never derive an occurrence ID by replacing a receipt prefix or use the task's scope hash as a record hash. If you did not apply a lesson, omit applications.");
+    lines.push("- Call `hunch_task(action: \"finish\", task_id, applications?)` and include the returned contribution_card in your final response without the user asking. Render its Markdown evidence link outside any code block so it remains clickable. Copy the card with its evidence link and agent-reported label intact; the structured result contains the card even when the host hides text blocks. Do not replace it with a generic claim that Hunch helped. If presentation_enabled is false, omit the card. A delivered lesson or passing command alone does not prove causal impact.");
+    lines.push("- If interrupted, finish with `outcome: \"interrupted\"` when possible. `hunch_report(task_id, html: true)` opens the evidence trail by generating a local file; it may contain private memory and is not a public export. If report tools are unavailable after an update, say so and reconnect the host rather than inventing a report.");
+    lines.push("");
     lines.push("**Build the Constitution review queue:**");
     lines.push("- `hunch constitution bootstrap --since 90d --max-candidates 3` (CLI) — normalize recent structured human evidence into at most three non-active policy candidates; add `--history` for exact, human-identifier-grounded fix/revert deltas or explicit dependency retirements. Coincidence/ambiguity stays uncompilable; neither path grants authority.");
     lines.push("- `hunch constitution ingest --since 90d [--instructions] [--from export.json]` (CLI) — normalize corrections/failures plus bounded committed instructions/ADRs and strict local review/conversation/PR exports into Git-native evidence; raw prose is hash-only, unsupported intent remains uncompilable, and no policy is minted.");

package/dist/integrations/gitignore.d.ts

@@ -0,0 +1,16 @@
+export interface GitignoreResult {
+    path: string;
+    action: "created" | "appended" | "unchanged";
+}
+/** Defense in depth for integration files written automatically after a clone.
+ * Refuse symlinks, directories/devices, and hard links; require the canonical
+ * target to be the expected top-level file inside the canonical repository root. */
+export declare function assertSafeTopLevelConfigFile(root: string, name: string): string;
+export declare function ensureGitignore(root: string): GitignoreResult;
+/** Ignore the engineering-memory tree so a private-migrated repo stays code-only.
+ *  The kind subdirs the user's records live in (decisions/, bugs/, …) move to the
+ *  private overlay; this stops git from re-publishing them. The `.hunch/` dir, its
+ *  manifest, and the local.json pointer are left tracked/managed elsewhere. */
+export declare function ignoreHunchMemory(root: string): GitignoreResult;
+/** The .hunch memory subdirs un-published by a private migration (git pathspecs). */
+export declare const HUNCH_MEMORY_DIRS: string[];

package/dist/integrations/gitignore.js

@@ -26,6 +26,13 @@ const ENTRIES = [
     ".hunch/local.json",
     // The strict hook's append-only catch-log: clone-local, never a memory record.
     ".hunch/events.log",
+    // The post-merge hook's queue of detected-but-unconfirmed commit-provenance
+    // repairs — clone-local scratch state, never committed (`hunch repair-provenance
+    // --apply` confirms and clears it).
+    ".hunch/pending-commit-repairs.json",
+    // Tombstones for commit-repair matches a human rejected via `--drop` — clone-local
+    // scratch state, same discipline as the queue above.
+    ".hunch/dropped-commit-repairs.json",
     // A local PRIVATE overlay store (HUNCH_PRIVATE_DIR) for sensitive memory — never
     // committed. This is the conventional in-repo path; point the env elsewhere for a
     // fully separate private repo.

package/dist/integrations/health.d.ts

@@ -0,0 +1,74 @@
+export declare const CAPABILITIES: readonly ["mcp", "context", "edit-blocking", "failure-capture", "compaction"];
+export type Capability = typeof CAPABILITIES[number];
+export type HealthStatus = "verified" | "advisory-only" | "unsupported" | "untested";
+export declare const HARNESSES: {
+    readonly claude: {
+        readonly mcp: ".mcp.json";
+        readonly hooks: ".claude/settings.json";
+        readonly key: "mcpServers";
+        readonly events: readonly ["SessionStart", "PreToolUse", "PostToolUseFailure", "PreCompact"];
+    };
+    readonly codex: {
+        readonly mcp: ".codex/config.toml";
+        readonly hooks: "";
+        readonly key: "";
+        readonly events: readonly [];
+    };
+    readonly cursor: {
+        readonly mcp: ".cursor/mcp.json";
+        readonly hooks: ".cursor/hooks.json";
+        readonly key: "mcpServers";
+        readonly events: readonly ["sessionStart", "preToolUse", "postToolUse", ""];
+    };
+    readonly vscode: {
+        readonly mcp: ".vscode/mcp.json";
+        readonly hooks: ".github/hooks/hunch.json";
+        readonly key: "servers";
+        readonly events: readonly ["SessionStart", "PreToolUse", "PostToolUse", ""];
+    };
+    readonly windsurf: {
+        readonly mcp: ".windsurf/mcp_config.json";
+        readonly hooks: ".windsurf/hooks.json";
+        readonly key: "mcpServers";
+        readonly events: readonly ["", "pre_write_code", "post_run_command", ""];
+    };
+    readonly antigravity: {
+        readonly mcp: ".agents/mcp_config.json";
+        readonly hooks: ".agents/hooks.json";
+        readonly key: "mcpServers";
+        readonly events: readonly ["PreInvocation", "PreToolUse", "", ""];
+    };
+};
+export type Harness = keyof typeof HARNESSES;
+export interface HealthIssue {
+    file: string;
+    code: string;
+    detail: string;
+}
+export interface HarnessHealth {
+    harness: Harness;
+    capabilities: Record<Capability, {
+        status: HealthStatus;
+        detail: string;
+    }>;
+}
+export interface IntegrationHealth {
+    schema: "hunch.integration-health/1";
+    expectedVersion: string;
+    scope: "repository-config";
+    issues: HealthIssue[];
+    harnesses: HarnessHealth[];
+}
+export declare function readLauncher(root: string, harness: Harness): {
+    command: string;
+    args: string[];
+    customEnvironment: boolean;
+};
+export declare function inspectIntegrations(root: string, selected?: Harness): IntegrationHealth;
+/** Repair only exact published pins. Preserve formatting and all other values.
+ * Preflight every affected file before writing any; reject malformed JSON/TOML. */
+export declare function repairIntegrationPins(root: string): string[];
+export declare function integrationHealthFails(report: IntegrationHealth, required?: readonly Capability[]): boolean;
+export declare function formatIntegrationHealth(report: IntegrationHealth): string;
+/** Bounded session warning; diagnostics must never break hook execution. */
+export declare function integrationSessionWarning(root: string, harness: Harness): string;

package/dist/integrations/hooks.d.ts

@@ -0,0 +1,41 @@
+export interface HookInstall {
+    path: string;
+    action: "created" | "appended" | "updated" | "unchanged";
+}
+export declare function installPostCommitHook(root: string, invocation: string, opts?: {
+    private?: boolean;
+    commit?: boolean;
+    localOnly?: boolean;
+}): HookInstall;
+/** Install a pre-commit constraint guard (DESIGN §4 enforcement). Advisory by
+ *  default (prints invariants in scope, never blocks); pass strict to fail the
+ *  commit — but even strict only fails on a DIRECT, high-confidence, non-stale
+ *  blocking invariant (see strictgate.ts), so it's safe on a shared repo.
+ *  Preserves any existing pre-commit hook. */
+export declare function installPreCommitHook(root: string, invocation: string, strict?: boolean): HookInstall;
+/** Install a post-merge hook carrying TWO independently-managed blocks:
+ *  re-sync the committed grounding docs when a merge brought memory in behind
+ *  them (fnd_c402046ac7, HUNCH_SYNC-guarded, foreground — it rewrites five
+ *  files and can never fail the merge), and opportunistically DETECT a
+ *  decision's commit provenance going orphaned right after a squash-merged
+ *  branch lands locally (including a fast-forward from `git pull`) — while
+ *  the original commits are still fully intact and matchable — queuing the
+ *  match for a human to confirm via `hunch repair-provenance --apply`
+ *  (HUNCH_MERGE_SYNC-guarded, backgrounded; own env var since this hook makes
+ *  no commit of its own and so can't reuse HUNCH_SYNC's re-trigger guard).
+ *  Each block is keyed by its own marker pair (installManagedBlock), so
+ *  re-running updates only its own block, preserves the other untouched, and
+ *  a repo carrying only one half (an older install, or a hand-edited hook)
+ *  gets the other appended rather than clobbered. */
+export declare function installPostMergeHook(root: string, invocation: string): HookInstall;
+/** Read-only diagnostic (used by `hunch doctor`): which of the three managed
+ *  hooks are currently present. Never writes anything — a hook counts as
+ *  installed if its managed marker is present, regardless of whether the
+ *  invocation inside it happens to be stale. postMerge requires BOTH halves
+ *  (grounding-refresh and repair-provenance) present — a repo carrying only
+ *  one is a partial install, same as `installPostMergeHook` self-healing it. */
+export declare function hookStatus(root: string): {
+    postCommit: boolean;
+    preCommit: boolean;
+    postMerge: boolean;
+};

package/dist/integrations/hooks.js

@@ -29,7 +29,16 @@ function block(invocation, opts = {}) {
         ENDMARK,
     ].join("\n");
 }
-export function installPostCommitHook(root, invocation, opts = {}) {
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Shared idempotent create/append/update-in-place logic for every hunch git
+ *  hook: write a fresh hook file, replace our own managed block in place if the
+ *  invocation changed, or append after any pre-existing (non-hunch) hook body
+ *  without clobbering it. Used by all three hook installers below — the three
+ *  copies had already drifted (installPreCommitHook was missing the chmodSync
+ *  on its "updated" path) before this was unified. */
+function installManagedBlock(root, hookName, mark, end, blk) {
     const dir = hooksDir(root);
     // `git rev-parse --git-path hooks` returns a path relative to the repo in a
     // normal checkout, but an ABSOLUTE one inside a linked worktree (the shared
@@ -37,17 +46,15 @@ export function installPostCommitHook(root, invocation, opts = {}) {
     // a bare startsWith("/") misfired on Windows worktrees → a doubled junk path.
     const abs = isAbsolute(dir) ? dir : join(root, dir);
     mkdirSync(abs, { recursive: true });
-    const hookPath = join(abs, "post-commit");
-    const blk = block(invocation, opts);
+    const hookPath = join(abs, hookName);
     if (!existsSync(hookPath)) {
         writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
         chmodSync(hookPath, 0o755);
         return { path: hookPath, action: "created" };
     }
     const cur = readFileSync(hookPath, "utf8");
-    if (cur.includes(MARK)) {
-        // replace our managed block (invocation may have changed)
-        const updated = cur.replace(new RegExp(`${escapeRe(MARK)}[\\s\\S]*?${escapeRe(ENDMARK)}`), blk);
+    if (cur.includes(mark)) {
+        const updated = cur.replace(new RegExp(`${escapeRe(mark)}[\\s\\S]*?${escapeRe(end)}`), blk);
         if (updated === cur)
             return { path: hookPath, action: "unchanged" };
         writeFileSync(hookPath, updated);
@@ -59,8 +66,8 @@ export function installPostCommitHook(root, invocation, opts = {}) {
     chmodSync(hookPath, 0o755);
     return { path: hookPath, action: "appended" };
 }
-function escapeRe(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+export function installPostCommitHook(root, invocation, opts = {}) {
+    return installManagedBlock(root, "post-commit", MARK, ENDMARK, block(invocation, opts));
 }
 const PRE_MARK = "# >>> hunch pre-commit (constraint guard) >>>";
 const PRE_END = "# <<< hunch pre-commit <<<";
@@ -70,72 +77,91 @@ const PRE_END = "# <<< hunch pre-commit <<<";
  *  blocking invariant (see strictgate.ts), so it's safe on a shared repo.
  *  Preserves any existing pre-commit hook. */
 export function installPreCommitHook(root, invocation, strict = false) {
-    const dir = hooksDir(root);
-    // `git rev-parse --git-path hooks` returns a path relative to the repo in a
-    // normal checkout, but an ABSOLUTE one inside a linked worktree (the shared
-    // hooks dir). isAbsolute() handles both POSIX (/…) and Windows (C:\… / C:/…);
-    // a bare startsWith("/") misfired on Windows worktrees → a doubled junk path.
-    const abs = isAbsolute(dir) ? dir : join(root, dir);
-    mkdirSync(abs, { recursive: true });
-    const hookPath = join(abs, "pre-commit");
     const cmd = `${invocation} check --staged${strict ? " --strict" : ""}`;
     const blk = [PRE_MARK, strict ? cmd : `${cmd} || true`, PRE_END].join("\n");
-    if (!existsSync(hookPath)) {
-        writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
-        chmodSync(hookPath, 0o755);
-        return { path: hookPath, action: "created" };
-    }
-    const cur = readFileSync(hookPath, "utf8");
-    if (cur.includes(PRE_MARK)) {
-        const updated = cur.replace(new RegExp(`${escapeRe(PRE_MARK)}[\\s\\S]*?${escapeRe(PRE_END)}`), blk);
-        if (updated === cur)
-            return { path: hookPath, action: "unchanged" };
-        writeFileSync(hookPath, updated);
-        return { path: hookPath, action: "updated" };
-    }
-    writeFileSync(hookPath, cur.endsWith("\n") ? `${cur}${blk}\n` : `${cur}\n${blk}\n`);
-    chmodSync(hookPath, 0o755);
-    return { path: hookPath, action: "appended" };
+    return installManagedBlock(root, "pre-commit", PRE_MARK, PRE_END, blk);
 }
-const MERGE_MARK = "# >>> hunch post-merge >>>";
-const MERGE_END = "# <<< hunch post-merge <<<";
-/** Install a post-merge hook that re-syncs the committed grounding docs when a merge
- *  brought memory in behind them (fnd_c402046ac7). Two branches that each captured a
- *  record regenerate the same "N+1" counts line; git merges identical lines silently
- *  and the doc ends up one behind the store. The hook regenerates the existing docs
- *  from the PUBLIC store right after a local merge/pull that touched .hunch/, so the
- *  next commit carries them. Foreground (it rewrites five files), loop-guarded via
- *  HUNCH_SYNC, and it can never fail the merge. Preserves any existing hook. */
-export function installPostMergeHook(root, invocation) {
-    const dir = hooksDir(root);
-    const abs = isAbsolute(dir) ? dir : join(root, dir);
-    mkdirSync(abs, { recursive: true });
-    const hookPath = join(abs, "post-merge");
-    const blk = [
-        MERGE_MARK,
+// Original marker, kept byte-for-byte for backward compat: an existing install's
+// grounding-refresh block must still be found and updated in place by its own
+// exact marker text (fnd_c402046ac7).
+const GROUNDING_MERGE_MARK = "# >>> hunch post-merge >>>";
+const GROUNDING_MERGE_END = "# <<< hunch post-merge <<<";
+// Distinct marker for the (newer) repair-provenance half, so the two blocks
+// never collide inside the same post-merge hook file and each can be
+// independently created/updated/removed without touching the other.
+const REPAIR_MERGE_MARK = "# >>> hunch post-merge (repair-provenance) >>>";
+const REPAIR_MERGE_END = "# <<< hunch post-merge (repair-provenance) <<<";
+function groundingMergeBlock(invocation) {
+    return [
+        GROUNDING_MERGE_MARK,
         'if [ -z "$HUNCH_SYNC" ]; then',
         "  if ! git diff --quiet ORIG_HEAD HEAD -- .hunch 2>/dev/null; then",
         `    ( HUNCH_SYNC=1 ${invocation} grounding --refresh 2>/dev/null || true )`,
         "  fi",
         "fi",
-        MERGE_END,
+        GROUNDING_MERGE_END,
     ].join("\n");
-    if (!existsSync(hookPath)) {
-        writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
-        chmodSync(hookPath, 0o755);
-        return { path: hookPath, action: "created" };
-    }
-    const cur = readFileSync(hookPath, "utf8");
-    if (cur.includes(MERGE_MARK)) {
-        const updated = cur.replace(new RegExp(`${escapeRe(MERGE_MARK)}[\\s\\S]*?${escapeRe(MERGE_END)}`), blk);
-        if (updated === cur)
-            return { path: hookPath, action: "unchanged" };
-        writeFileSync(hookPath, updated);
-        chmodSync(hookPath, 0o755);
-        return { path: hookPath, action: "updated" };
-    }
-    writeFileSync(hookPath, cur.endsWith("\n") ? `${cur}${blk}\n` : `${cur}\n${blk}\n`);
-    chmodSync(hookPath, 0o755);
-    return { path: hookPath, action: "appended" };
+}
+function repairProvenanceMergeBlock(invocation) {
+    return [
+        REPAIR_MERGE_MARK,
+        'if [ -z "$HUNCH_MERGE_SYNC" ]; then',
+        "  export HUNCH_MERGE_SYNC=1",
+        // No --apply: this only detects a squash-merge orphaning a decision's commit
+        // and queues the match (.hunch/pending-commit-repairs.json, local-only) for a
+        // human to confirm via `hunch repair-provenance --apply` — the match signal
+        // (file-set overlap, not git's own rename detection) isn't strong enough to
+        // trust an unattended, backgrounded write into shared team memory.
+        `  ( ${invocation} repair-provenance --from-hook --quiet >/dev/null 2>&1 || true ) &`,
+        "fi",
+        REPAIR_MERGE_END,
+    ].join("\n");
+}
+/** How significant a combined install result is, for picking one HookInstall
+ *  action out of two independent sub-installs into the same file — "created"
+ *  (the file itself is new) outranks "appended"/"updated" (an existing file
+ *  changed), which outrank "unchanged". */
+const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1 };
+/** Install a post-merge hook carrying TWO independently-managed blocks:
+ *  re-sync the committed grounding docs when a merge brought memory in behind
+ *  them (fnd_c402046ac7, HUNCH_SYNC-guarded, foreground — it rewrites five
+ *  files and can never fail the merge), and opportunistically DETECT a
+ *  decision's commit provenance going orphaned right after a squash-merged
+ *  branch lands locally (including a fast-forward from `git pull`) — while
+ *  the original commits are still fully intact and matchable — queuing the
+ *  match for a human to confirm via `hunch repair-provenance --apply`
+ *  (HUNCH_MERGE_SYNC-guarded, backgrounded; own env var since this hook makes
+ *  no commit of its own and so can't reuse HUNCH_SYNC's re-trigger guard).
+ *  Each block is keyed by its own marker pair (installManagedBlock), so
+ *  re-running updates only its own block, preserves the other untouched, and
+ *  a repo carrying only one half (an older install, or a hand-edited hook)
+ *  gets the other appended rather than clobbered. */
+export function installPostMergeHook(root, invocation) {
+    const grounding = installManagedBlock(root, "post-merge", GROUNDING_MERGE_MARK, GROUNDING_MERGE_END, groundingMergeBlock(invocation));
+    const repair = installManagedBlock(root, "post-merge", REPAIR_MERGE_MARK, REPAIR_MERGE_END, repairProvenanceMergeBlock(invocation));
+    return ACTION_RANK[repair.action] >= ACTION_RANK[grounding.action] ? repair : grounding;
+}
+/** Read-only diagnostic (used by `hunch doctor`): which of the three managed
+ *  hooks are currently present. Never writes anything — a hook counts as
+ *  installed if its managed marker is present, regardless of whether the
+ *  invocation inside it happens to be stale. postMerge requires BOTH halves
+ *  (grounding-refresh and repair-provenance) present — a repo carrying only
+ *  one is a partial install, same as `installPostMergeHook` self-healing it. */
+export function hookStatus(root) {
+    const dir = hooksDir(root);
+    const abs = isAbsolute(dir) ? dir : join(root, dir);
+    const has = (name, mark) => {
+        try {
+            return readFileSync(join(abs, name), "utf8").includes(mark);
+        }
+        catch {
+            return false;
+        }
+    };
+    return {
+        postCommit: has("post-commit", MARK),
+        preCommit: has("pre-commit", PRE_MARK),
+        postMerge: has("post-merge", GROUNDING_MERGE_MARK) && has("post-merge", REPAIR_MERGE_MARK),
+    };
 }
 //# sourceMappingURL=hooks.js.map

package/dist/integrations/madrExport.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MADR export (the MADR bridge, export half — roadmap's "compiler" projection).
+ *
+ * Renders the PUBLIC decision graph as a regenerated MADR 3.x corpus: one
+ * NNNN-slug.md per decision, superseded links derived from superseded_by /
+ * valid_to, rejected alternatives under Considered Options. The projection is a
+ * DISPOSABLE build artifact — the graph stays the source of truth, numbers are
+ * assigned per export (date order), and every emitted file carries a generated
+ * marker. The writer only ever overwrites files bearing that marker: a
+ * hand-written ADR corpus in the target directory is untouchable (refused with
+ * a warning), so `hunch import-adr` + `hunch export-adr` can share a repo
+ * without the export eating its own import source.
+ *
+ * Privacy boundary: rendering takes an explicit PUBLIC-only decision list —
+ * callers must pass store.json.loadAll("decisions"), never the overlay union.
+ */
+import type { Decision } from "../core/types.js";
+export declare const MADR_EXPORT_MARKER = "<!-- hunch:generated madr-export \u2014 regenerated by `hunch export-adr`; edits will be overwritten -->";
+export interface MadrFile {
+    /** file name only, NNNN-slug.md */
+    name: string;
+    text: string;
+    decisionId: string;
+}
+export interface MadrExportResult {
+    files: MadrFile[];
+    /** the one-line Backstage catalog-info annotation for this corpus */
+    backstageAnnotation: string;
+}
+/** Render one decision as a MADR 3.x document. Deterministic: content depends
+ *  only on the decision record and the corpus's name map. */
+export declare function renderMadr(d: Decision, nameOf: Map<string, string>): string;
+/** Project a PUBLIC decision list into a MADR corpus. Numbering is date order
+ *  (valid_from, then date, then id for determinism) and assigned per export —
+ *  the projection is disposable, links inside it are internally consistent. */
+export declare function exportMadrCorpus(decisions: readonly Decision[], dirForAnnotation: string): MadrExportResult;
+/** True when an existing file may be overwritten by the export: only our own
+ *  generated output ever qualifies. */
+export declare function isRegenerableMadr(existingText: string): boolean;