@davesheffer/hunch 1.31.1 → 1.32.0

package/dist/core/version.d.ts

@@ -0,0 +1,10 @@
+export declare const HUNCH_VERSION: string;
+/** Exact public npm package consumed by generated CI and shared MCP/provider
+ * configs. A floating package name would let one committed configuration run
+ * different Hunch semantics as npm's latest release changes. */
+export declare const HUNCH_PACKAGE_SPEC: string;
+/** npm alias used by npx launchers. Giving the fetched package a distinct local
+ * alias prevents npm exec from treating this repository (which has the same
+ * package name) as satisfying the request and then falling through to an older
+ * global `hunch` executable. */
+export declare const HUNCH_NPX_PACKAGE_SPEC: string;

package/dist/eval/guards.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Guard eval — turn "Hunch catches bad changes" into a MEASURED number.
+ *
+ * Mirrors the retrieval eval (harness.ts) but scores ENFORCEMENT: each case is a change
+ * (changed files + optional diff) with an expected verdict, run through the SAME production
+ * path the guards use — `store.buildCheckReport(...) → verdict()` — so the number reflects the
+ * real gate, not a re-implementation. The ground-truth-able metrics:
+ *   - CAUGHT:          of changes to guarded code, how many the gate surfaced (block OR warn) —
+ *                      i.e. nothing slipped silently through. (Of those, how many HARD-block a
+ *                      merge depends on firmness/freshness, reported separately.)
+ *   - FALSE-POSITIVE:  of UNRELATED changes, how many the gate flagged — lower = safer to enable.
+ */
+import type { HunchStore } from "../store/hunchStore.js";
+/** "catch" = should be surfaced (block OR warn); block/warn/pass = an exact expected verdict. */
+export type Expect = "block" | "warn" | "pass" | "catch";
+export interface GuardCase {
+    name: string;
+    files: string[];
+    diff?: string;
+    expect: Expect;
+}
+export interface GuardEvalResult {
+    total: number;
+    shouldSurface: number;
+    surfaced: number;
+    hardBlocked: number;
+    shouldPass: number;
+    falsePositives: number;
+    accuracy: number;
+    perCase: Array<{
+        name: string;
+        expect: Expect;
+        got: Expect;
+        ok: boolean;
+    }>;
+}
+/** Parse + validate a hand-authored golden set. */
+export declare function loadGuardCases(json: string): GuardCase[];
+/** Score every case through the real guard pipeline. */
+export declare function evalGuards(store: HunchStore, cases: GuardCase[]): GuardEvalResult;
+/** Scaffold a STARTER set from the live graph: every active, vouched blocking constraint →
+ *  a CATCH case (a file in its scope — a change there must not slip silently past the gate);
+ *  a few unrelated paths → PASS cases (the precision side — the gate must NOT over-flag). Both
+ *  sides are true ground truth. Hand-add regressions / near-misses for fuller coverage. */
+export declare function generateGuardCases(store: HunchStore): GuardCase[];

package/dist/eval/harness.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Deterministic retrieval eval (roadmap #2). Scores `hybridSearch` against a curated
+ * golden set of "why" questions by EXACT ref match — Recall@k + MRR — with no LLM in
+ * the scoring path, so it runs as a stable, reproducible CI signal. The `graphWeight`
+ * knob lets ONE store be scored graph-OFF (0) vs graph-ON to measure the dependency-
+ * graph stream's lift — the measurement gate for the graph-RRF decision. Traversal
+ * depth is also injectable so the shipped bounded traversal can be compared directly
+ * with its 1-hop baseline on the same cases.
+ */
+import type { HunchStore } from "../store/hunchStore.js";
+import type { Embedder } from "../store/embedder.js";
+export interface EvalCase {
+    query: string;
+    expected: string[];
+    note?: string;
+}
+export interface CaseResult {
+    query: string;
+    expected: number;
+    found: number;
+    recall: number;
+    rr: number;
+}
+export interface EvalMetrics {
+    n: number;
+    k: number;
+    recallAtK: number;
+    mrr: number;
+    hitRate: number;
+    perCase: CaseResult[];
+}
+export interface EvalOpts {
+    k?: number;
+    embedder?: Embedder | null;
+    graphWeight?: number;
+    graphDepth?: number;
+    graphNodeCap?: number;
+    graphTokenCap?: number;
+    kind?: string;
+}
+/** Score a golden set: Recall@k, MRR, hit-rate. Deterministic when no embedder. */
+export declare function evaluateRetrieval(store: HunchStore, cases: EvalCase[], opts?: EvalOpts): Promise<EvalMetrics>;
+/** Compare graph-OFF vs graph-ON on the same golden set — the #1 lift measurement. */
+export declare function evaluateGraphLift(store: HunchStore, cases: EvalCase[], opts?: EvalOpts): Promise<{
+    off: EvalMetrics;
+    on: EvalMetrics;
+    recallDelta: number;
+    mrrDelta: number;
+}>;
+/** Compare the historical 1-hop graph with the shipped bounded traversal. */
+export declare function evaluateTraversalLift(store: HunchStore, cases: EvalCase[], opts?: EvalOpts): Promise<{
+    oneHop: EvalMetrics;
+    bounded: EvalMetrics;
+    recallDelta: number;
+    mrrDelta: number;
+}>;
+/** Parse + validate a golden-set JSON string (array of {query, expected[]}). */
+export declare function loadGoldenSet(raw: string): EvalCase[];

package/dist/extractors/adrImport.d.ts

@@ -0,0 +1,59 @@
+import type { Decision } from "../core/types.js";
+/** Directories probed (in order) when no explicit dir is given — adr-tools'
+ *  default (doc/adr), MADR's (docs/decisions), and the common variants. */
+export declare const ADR_DIR_CANDIDATES: readonly ["docs/adr", "docs/decisions", "doc/adr", "adr", "docs/architecture/decisions"];
+/** An ADR file is NNNN-slug.md (adr-tools / MADR convention). Templates and
+ *  indexes (adr-template.md, README.md, index.md) never match. */
+export declare const ADR_FILE_RE: RegExp;
+/** A structurally valid ADR filename can still name corpus scaffolding rather
+ * than a decision. Keep this classification separate from parse failure so the
+ * CLI can exclude templates quietly instead of falsely calling their filename
+ * malformed. */
+export declare function isAdrCorpusTemplate(relPath: string): boolean;
+/** Decision.date is required even when an ADR has no date and no Git history is
+ * available (for example, a copied corpus outside a repository). Use an honest,
+ * deterministic sentinel instead of the import clock: re-importing the same
+ * bytes must not silently make an old decision look current. */
+export declare const UNDATED_ADR_DATE = "1970-01-01T00:00:00.000Z";
+export interface AdrSource {
+    /** repo-relative posix path, e.g. docs/adr/0005-use-postgres.md */
+    relPath: string;
+    text: string;
+    /** ISO date of the source file's introduction commit, when available. */
+    sourceDate?: string | null;
+    /** Full source introduction commit, when available. */
+    sourceRevision?: string | null;
+}
+export interface ParsedAdr {
+    relPath: string;
+    number: number;
+    slug: string;
+    title: string;
+    /** raw status text as written (e.g. "Superseded by [ADR-7](...)") */
+    statusRaw: string;
+    status: "proposed" | "accepted" | "rejected" | "superseded";
+    date: string | null;
+    context: string;
+    decision: string;
+    consequences: string[];
+    consideredOptions: string[];
+    chosenOption: string | null;
+    sourceHash: string;
+    /** ADR numbers this one supersedes / is superseded by (from status text + links) */
+    supersedesNumbers: number[];
+    supersededByNumbers: number[];
+}
+export interface AdrImportResult {
+    decisions: Decision[];
+    warnings: string[];
+}
+/** Parse one ADR markdown file (MADR 3.x/4 frontmatter style or Nygard heading
+ *  style). Returns null when the filename doesn't follow NNNN-slug.md. */
+export declare function parseAdrMarkdown(text: string, relPath: string): ParsedAdr | null;
+export declare function adrDecisionId(relPath: string): string;
+/** Map a parsed corpus to Decision records. Pure: cross-links resolve by ADR
+ *  number WITHIN the given corpus only; unresolvable references become warnings,
+ *  never guessed ids. Bi-temporal closure: a superseded ADR's valid_to is its
+ *  successor's valid_from (falling back to the successor's date, then its own
+ *  date) so as-of queries see the corpus's real history. */
+export declare function mapAdrCorpus(sources: AdrSource[]): AdrImportResult;

package/dist/extractors/comments.d.ts

@@ -0,0 +1,7 @@
+export interface InlineIntent {
+    kind: "why" | "rule";
+    text: string;
+    file: string;
+    line: number;
+}
+export declare function extractInlineIntent(root: string): InlineIntent[];

package/dist/extractors/correctionSources.d.ts

@@ -0,0 +1,11 @@
+import type { ContractAxisOwnerSource } from "../core/pipeline.js";
+export interface CorrectionSourceCollection {
+    sources: ContractAxisOwnerSource[];
+    files_read: number;
+    bytes_read: number;
+    files_skipped: number;
+}
+/** Safely read a bounded working-tree TypeScript/PHP corpus. Stage-relevant paths
+ * are read first so a huge repository cannot crowd the likely correction layer
+ * out of the fixed source budget. */
+export declare function collectCorrectionStageSources(root: string, issue: string): CorrectionSourceCollection;

package/dist/extractors/diff.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Structured analysis of a git unified diff (deterministic, no LLM). Turns raw
+ * patch text into "what actually changed" — added/removed/changed symbols, new
+ * and dropped dependencies, file add/delete/rename — so the synthesis layer can
+ * write an INFORMATIVE decision even with no model available.
+ *
+ * Parsing is hunk-state-aware: file headers ("--- "/"+++ ") are only honored in
+ * the pre-hunk region, so a CONTENT line like `+++counter` (source `++counter`)
+ * is never mistaken for a header. Symbol classification is PER FILE, so moving a
+ * function between files isn't misread as a signature change.
+ */
+export interface SymbolChange {
+    name: string;
+    kind: "function" | "class" | "interface" | "trait" | "enum" | "type" | "const";
+}
+export interface RenamePair {
+    from: string;
+    to: string;
+}
+export interface DiffAnalysis {
+    filesAdded: string[];
+    filesDeleted: string[];
+    filesModified: string[];
+    filesRenamed: RenamePair[];
+    addedSymbols: SymbolChange[];
+    removedSymbols: SymbolChange[];
+    changedSymbols: SymbolChange[];
+    addedDeps: string[];
+    removedDeps: string[];
+    addedLines: number;
+    removedLines: number;
+    /** Added line bodies (the "+" content, marker stripped) per file — every file,
+     *  not just substantive ones. The text veto's symbol/pattern tiers match against
+     *  — call sites, not just declarations, which addedSymbols can't see. Keyed by
+     *  the same (new-path) key as perFile. */
+    addedLinesByFile: Map<string, string[]>;
+}
+export declare function analyzeDiff(diff: string): DiffAnalysis;
+/** A compact human-readable summary of a DiffAnalysis (used in decision text). */
+export declare function summarizeDiff(a: DiffAnalysis): string;

package/dist/extractors/git.d.ts

@@ -0,0 +1,304 @@
+export interface CommitMeta {
+    sha: string;
+    shortSha: string;
+    subject: string;
+    body: string;
+    author: string;
+    date: string;
+    files: string[];
+}
+export declare function foreignRepoEnv(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function isGitRepo(cwd: string): boolean;
+/** Canonical worktree root, or null when Git cannot positively identify one.
+ * Callers enforcing a privacy boundary must distinguish "different repo" from
+ * "malformed/unknown Git state" instead of treating both as safe. */
+export declare function gitWorktreeRoot(cwd: string): string | null;
+/** True only when `cwd` is the repository's actual worktree root. Unlike
+ * `isGitRepo`, this does not accept an ancestor repository discovered by Git's
+ * upward walk. Private overlays use this stronger boundary so a nested
+ * `.hunch-private/.hunch` can never stage or commit into the code repository. */
+export declare function isGitRepoRoot(cwd: string): boolean;
+export declare function gitNullDevice(): string;
+/** Whether two paths resolve to the same repository identity. Comparing only
+ * worktree roots is insufficient: linked worktrees have different roots but
+ * share one Git common directory and therefore one publishable history. */
+export declare function sameGitRepository(left: string, right: string): boolean;
+/** Canonical repository identity for deterministic, credential-free discovery.
+ * The returned value is an internal identity: callers exposing it must hash
+ * local `file:` identities so host paths never enter graph records. Network
+ * credentials, URL query strings and fragments are deliberately excluded. */
+export declare function canonicalRemoteRepositoryIdentity(raw: string, cwd: string): string;
+/** Resolve a user-supplied Git remote once, before handing it to commands that
+ * run from different working directories. Git otherwise gives a relative local
+ * URL a different meaning under `git clone` and `git -C <overlay> remote add`,
+ * which can turn a successful preflight into a later privacy-boundary escape. */
+export declare function canonicalRemoteUrl(raw: string, cwd: string): string;
+/** Compare two remote spellings in the contexts where Git would interpret
+ * them. This is identity comparison, not brittle string equality. */
+export declare function sameRemoteUrl(left: string, leftCwd: string, right: string, rightCwd: string): boolean;
+/** True when two worktrees can publish to the same local Git history OR name
+ * the same configured remote repository. Separate clones of one remote are a
+ * single publication boundary even though their local common dirs differ. */
+export declare function sameGitPublication(left: string, right: string): boolean;
+/** Preflight a requested overlay URL before clone/attach can mutate a remote. */
+export declare function repositoryUsesRemote(repoRoot: string, remoteUrl: string, remoteCwd?: string): boolean;
+/** The MAIN worktree's root — the stable anchor for an overlay store. A linked worktree
+ *  can be `git worktree remove`d, so anything anchored inside it (an overlay clone, an
+ *  absolute pointer target) silently dies for every OTHER worktree; the main checkout
+ *  can't be removed. Falls back to `root` when the layout isn't the standard `.git` dir
+ *  (or not a git repo), preserving today's behavior. */
+export declare function mainWorktreeRoot(root: string): string;
+/** Stable, privacy-safe repository label for artifacts that must be reusable
+ * across linked worktrees and ordinary clones. Prefer the canonical fetch
+ * remote identity: its SHA-256 digest exposes neither a private URL nor a local
+ * path, ignores mutable remote aliases, and does not depend on clone depth. If
+ * several fetch remotes exist, canonical identity ordering makes the choice
+ * deterministic without privileging a name such as `origin`.
+ *
+ * Remote-less full clones fall back to intrinsic root commits. A remote-less
+ * shallow clone cannot prove a clone-independent repository identity without
+ * fetching missing history or persisting a shared ID, so it retains the local
+ * main-worktree label (which is still stable across linked worktrees). */
+export declare function stableRepositoryName(root: string): string;
+/** Best-effort: stage ONLY the hunch dir, commit, and push the repo it lives in. Shared by
+ *  the post-commit auto-commit (CLI sync --commit), MCP private writes, and `hunch private
+ *  --sync`. HUNCH_SYNC=1 stops the created commit from re-triggering the post-commit hook
+ *  (no recursion). Stages with a pathspec scoped to `hunchDir`, so it never sweeps unrelated
+ *  working-tree changes. Never throws — a non-repo dir / offline push just no-ops.
+ *  `push: false` commits WITHOUT merging or pushing — required when hunchDir is the PUBLIC
+ *  .hunch/ inside the user's code repo: an automatic pull/push there would merge the remote
+ *  into their working branch and publish their unpushed code commits. The memory commit
+ *  simply rides the user's next push.
+ *  Returns what ACTUALLY happened, so callers never report a commit that was skipped:
+ *  "pushed" (commit created and pushed), "committed" (commit created; push not requested,
+ *  or the merge/push failed — retry rides the next flush), null (nothing committed: lock
+ *  held, backstop refusal, nothing staged, or not a repo). */
+export type GitMemoryObservation = {
+    kind: "committed";
+    commitSha: string;
+} | {
+    kind: "published";
+    commitSha: string;
+    ref: string;
+    basis: "push-status" | "remote-ref-confirmed";
+};
+export type GitMemoryObserver = (event: GitMemoryObservation) => void;
+export type HunchCommitOptions = ({
+    push: false;
+    alsoStage?: string[];
+} | {
+    push?: true;
+    protectedRepoRoot: string;
+    alsoStage?: string[];
+    remote?: HunchRemoteContract;
+}) & {
+    observe?: GitMemoryObserver;
+};
+/** A team sync never delegates destination or ref selection to ambient Git
+ * configuration. The committed team pointer supplies one fetch URL, one push
+ * URL, and one canonical branch ref; `verify` re-proves that contract at each
+ * network seam while the Hunch lock is held. */
+export interface HunchRemoteContract {
+    fetchUrl: string;
+    pushUrl: string;
+    urlCwd: string;
+    ref: string;
+    verify: () => boolean;
+}
+export declare function commitAndPushHunch(hunchDir: string, message: string, opts: HunchCommitOptions): "pushed" | "committed" | null;
+/** True when `rel` is tracked with no staged or unstaged changes (untracked counts as
+ *  dirty, so a doc the user never committed is never swept into a memory commit). */
+export declare function isGitCleanPath(root: string, rel: string): boolean;
+/** The committed (HEAD) content of a tracked file, or null when the path is
+ *  untracked/absent at HEAD or git is unavailable. Used to decide whether a
+ *  dirty grounding doc differs from HEAD ONLY inside its generated section
+ *  (the stranded-grounding heal, fnd_b269d5c422). */
+export declare function headFileContent(root: string, rel: string): string | null;
+/** Best-effort READ-side sync: merge the overlay's remote into the local branch (e.g. on MCP
+ *  server start or at a long-lived MCP request boundary) so this machine/session sees other
+ *  machines' memory. Never throws; leaves a clean tree. Serialized with the commit lock so it
+ *  can't race a concurrent flush. Returns true only when the checked-out memory HEAD moved,
+ *  allowing callers to avoid rebuilding the derived SQLite index after a no-op pull. */
+export type HunchPullStatus = "updated" | "current" | "busy" | "failed" | "unconfigured";
+export interface PullHunchOptions {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    remote?: HunchRemoteContract;
+    /** Setup-only convergence for an existing standalone memory repository. */
+    allowUnrelatedHistories?: boolean;
+}
+export declare function pullHunchStatus(hunchDir: string, opts?: PullHunchOptions): HunchPullStatus;
+export declare function pullHunch(hunchDir: string): boolean;
+/** Explicit retry path for a clean overlay that already has a local memory commit
+ *  stranded by an earlier offline/rejected push. Unlike commitAndPushHunch this
+ *  creates no commit: it only converges and publishes existing overlay history. */
+export declare function syncExistingHunch(hunchDir: string, protectedRepoRoot: string, timeoutMs?: number, remote?: HunchRemoteContract): "pushed" | "current" | "failed";
+export declare function headSha(cwd: string): string;
+/** HEAD for a repository that is not the invocation repository. Unlike
+ * headSha, this deliberately ignores code-repo GIT_DIR/GIT_INDEX_FILE state
+ * inherited from hooks. */
+export declare function isolatedHeadSha(cwd: string): string;
+/** Stop tracking `paths` in git (remove from the INDEX only — keep the working-tree
+ *  files). Used by `hunch private --migrate` to un-publish the .hunch memory tree
+ *  without deleting it locally. `--ignore-unmatch` makes an already-untracked path a
+ *  no-op rather than an error; best-effort (a non-repo dir just no-ops). */
+export declare function gitUntrackCached(cwd: string, paths: string[]): void;
+/** Resolve any commit-ish (short sha / HEAD / branch) to a canonical full sha.
+ *  Returns the input unchanged if it can't be resolved (e.g. not a git repo). */
+export declare function revParse(ref: string, cwd: string): string;
+/** Path to the hooks dir (honors core.hooksPath / worktrees). */
+export declare function hooksDir(cwd: string): string;
+export declare function gitDir(cwd: string): string;
+/** The SHARED git dir for the repo — identical across ALL linked worktrees (unlike
+ *  `gitDir`, which is per-worktree). Absolute, so callers can anchor worktree-shared
+ *  state (the private-overlay pointer) at one stable place. "" when not a git repo. */
+export declare function gitCommonDir(cwd: string): string;
+/** True when `cwd` is inside a LINKED worktree (not the main checkout): its own git
+ *  dir differs from the shared common dir. Used by `hunch doctor` and setup messaging. */
+export declare function isLinkedWorktree(cwd: string): boolean;
+/** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
+ *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */
+export declare function currentBranch(cwd: string): string;
+/** Files changed in a single commit. `--root` makes the initial commit (which
+ *  has no parent) report its files as additions instead of returning nothing. */
+export declare function commitFiles(sha: string, cwd: string): string[];
+/** Raw `git log` over `.hunch/`, paired with parseMemoryLog — the memory-move
+ *  timeline (each commit that changed the graph). Newest first; empty on any error
+ *  (no repo / no history), so the caller degrades to an empty timeline. */
+export declare function gitMemoryLog(root: string, limit?: number): string;
+/** The diff of a single commit restricted to `.hunch/` — what one memory move
+ *  actually changed, for the click-through popup. Empty on error. */
+export declare function memoryMoveDiff(sha: string, root: string): string;
+/** Push the current branch to its remote (the "approve-to-push" step — public
+ *  memory rides the repo, so this is a plain branch push). Returns true on success;
+ *  false when there is no upstream / offline / not a repo. */
+export declare function pushCurrentBranch(root: string): boolean;
+/** Revert one validated memory-only move locally (no push). Returns true on
+ * success. Unsafe targets are refused before mutation; a conflicting revert is
+ * aborted so the working tree is never left half-reverted. */
+export declare function revertMemoryMove(sha: string, root: string): boolean;
+/** Full metadata + changed files for a commit. */
+export declare function commitMeta(sha: string, cwd: string): CommitMeta | null;
+export interface CommitFileChange {
+    status: "added" | "modified" | "deleted" | "renamed" | "copied";
+    before: string | null;
+    after: string | null;
+}
+/** First-parent and exact blob seams for deterministic before/after analysis.
+ * They never check out a ref or mutate the active worktree. */
+export declare function firstParent(sha: string, cwd: string): string | null;
+export declare function fileAtRef(ref: string, file: string, cwd: string): string | null;
+/** Name-status records for one commit, rename-aware and NUL-delimited so paths
+ * with whitespace cannot corrupt the parser. */
+export declare function commitChanges(sha: string, cwd: string): CommitFileChange[];
+export interface CommitCandidate {
+    sha: string;
+    files: string[];
+}
+/** Every commit newly reachable in `oldRef..newRef` (capped to the most
+ *  recent `maxCount`), with the files each one changed (rename-aware, via
+ *  commitChanges). Used to find the commit a squash-merge produced from a
+ *  set of now-orphaned source-branch commits. */
+export declare function mergeRangeChanges(oldRef: string, newRef: string, cwd: string, maxCount?: number): CommitCandidate[];
+/** Batched existence check for many commit shas at once — one `git cat-file
+ *  --batch-check` process instead of one `rev-parse --verify` per sha. Used
+ *  by drift.ts's default commitResolvable so hunch drift/heal/doctor spawn a
+ *  single git process regardless of how many decisions carry a commit, not
+ *  one per decision. Returns the subset of `shas` that resolve to a real
+ *  commit object, or `null` if the check itself failed to run (not a git
+ *  repo, git missing, timeout) — distinct from an empty set, which means
+ *  "checked, and none of them resolve." A caller that collapsed those two
+ *  would flag every commit as unresolvable on a transient environment error
+ *  instead of failing open. */
+export declare function commitsExist(shas: readonly string[], cwd: string): Set<string> | null;
+export type CommitRepairStatus = "orphaned" | "current" | "unresolvable" | "unknown";
+/** Classifies `commit` relative to `ref` for squash-merge repair eligibility.
+ *  "orphaned" (exists in this repo, but is not an ancestor of `ref`) is the
+ *  ONLY status planCommitRepair should ever act on. "unresolvable" (the
+ *  commit doesn't exist here at all) is explicitly out of repair scope —
+ *  drift.ts's commit-unresolvable kind is what flags that case, because
+ *  there's no reliable signal left to match a replacement against. "unknown"
+ *  (the git command itself failed to run — timeout, git missing) must never
+ *  be treated as repair-eligible; collapsing "false" and "error" into one
+ *  boolean is exactly the bug this type exists to prevent. */
+export declare function commitRepairStatus(commit: string, ref: string, cwd: string): CommitRepairStatus;
+/** The unified diff for a commit, truncated to keep synthesis prompts bounded.
+ *  Machine-generated noise (see DIFF_NOISE) is excluded so the model spends its
+ *  budget on code that encodes intent, not on regenerated lockfiles/build output. */
+export declare function commitDiff(sha: string, cwd: string, maxBytes?: number): string;
+/** Number of commits touching a file in the last `days` (churn). */
+export declare function fileChurn(file: string, cwd: string, days?: number): number;
+/** The most recent commit short-sha that touched a file. */
+export declare function lastCommitForFile(file: string, cwd: string): string;
+/** Full SHA of the commit that introduced a path. Unlike lastCommitForFile this
+ * remains stable when lifecycle/proof updates later touch the same policy file. */
+export declare function firstCommitForFile(file: string, cwd: string): string;
+/** ISO author-date of the most recent commit touching a file ("" if none). */
+export declare function lastChangeDate(file: string, cwd: string): string;
+/**
+ * Newest author date for every changed path selected by a bounded set of repository-relative
+ * Hunch scopes. One Git history walk replaces the per-file process loop used by `staleness()`.
+ *
+ * The return keys are the concrete paths Git observed, not the input scopes: callers can apply
+ * Hunch's own exact/glob/directory matcher without treating Git pathspec interpretation as graph
+ * authority. A failed or oversized read returns null, so freshness stays unknown rather than
+ * partially scoring a record.
+ */
+export declare function scopedLastChangeDates(scopes: readonly string[], cwd: string, maxChangedPaths?: number): Map<string, string> | null;
+/** Batched per-file git metrics for indexing: churn (commits touching the file in
+ *  the last `days`; pass 0 to skip) and the most-recent commit (`commit:<sha>`).
+ *
+ *  Replaces the indexer's O(files) × 2 `git log` spawns — which dominate
+ *  `hunch index` wall-time on a large repo, especially on Windows where process
+ *  creation is costly — with ONE `git log` pass each. Only paths present in `want`
+ *  are returned (every requested path gets an entry, defaulting to 0 / ""). */
+export declare function fileGitMetrics(cwd: string, want: Iterable<string>, days?: number): Map<string, {
+    churn: number;
+    lastCommit: string;
+}>;
+/** Files staged for commit (for `hunch check` pre-commit enforcement).
+ *
+ *  Every path enumerator here pins `core.quotePath=false` (issue #50): with
+ *  git's default quotePath, any path holding bytes > 0x7F comes back
+ *  octal-quoted (`"src/caf\303\251.ts"`), which matches neither the store's
+ *  POSIX paths nor constraint scope globs — a blocking constraint over such a
+ *  file graded as a vacuous PASS, and its churn/last-commit metrics read zero. */
+export declare function stagedFiles(cwd: string): string[];
+/** Files changed anywhere in the working tree compared with HEAD: both staged
+ * and unstaged tracked files, plus untracked files. This powers the local,
+ * pre-commit Change Gate; it never mutates the index or asks an agent/model. */
+export declare function workingFiles(cwd: string): string[];
+/** Does a ref resolve to a commit in this repo? Lets `--base` fail LOUDLY on an
+ *  unfetched/typo'd ref instead of silently diffing against nothing (a vacuous
+ *  CI pass), since the diff helpers below swallow git errors to "". */
+export declare function revExists(ref: string, cwd: string): boolean;
+/** Files a PR/branch changes vs `base` (3-dot: changes on HEAD since the merge-base,
+ *  i.e. exactly the PR's own commits — the CI Constraint Guard's surface). */
+export declare function rangeFiles(base: string, cwd: string, head?: string): string[];
+/** Commit subjects on `head` since `base` (2-dot: commits added by the task),
+ *  oldest-first, for distilling a runbook's ordered steps (roadmap #5). */
+export declare function rangeSubjects(base: string, cwd: string, head?: string, max?: number): string[];
+/** The PR's unified diff vs `base` (3-dot), for the Regression Guard's structural
+ *  analysis. Same noise-exclusion + truncation budget as commit/staged diffs. */
+export declare function rangeDiff(base: string, cwd: string, head?: string, maxBytes?: number): string;
+/** 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 declare function stagedDiff(cwd: string, maxBytes?: number): string;
+/** Unified diff of the complete local working tree vs HEAD. Git's normal diff
+ * includes both staged and unstaged tracked edits; untracked text files are
+ * appended as synthetic additions so guards can also see their added symbols.
+ * Binary/unreadable files remain in workingFiles (scope checks still apply) but
+ * intentionally contribute no synthetic content to regression analysis. */
+export declare function workingDiff(cwd: string, maxBytes?: number): string;
+/** 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 declare function asOfDate(ref: string, cwd: string): string | undefined;
+/** Recent commits (newest-first) for backfill. */
+export declare function logSince(spec: string, cwd: string, max?: number): string[];
+/** Commits that look like bug fixes (for backfill bug seeding). */
+export declare function fixCommits(spec: string, cwd: string, max?: number): string[];
+/** All tracked files matching the given extensions. */
+export declare function trackedFiles(cwd: string, exts: string[]): string[];