@davesheffer/hunch 1.31.1 → 1.32.1

package/dist/core/hookObservations.js

@@ -0,0 +1,33 @@
+/** Runtime evidence that a host actually delivered a lifecycle event to Hunch's
+ * hook. Configuration proves wiring; only an observed event proves delivery.
+ * One row per (provider, normalized event), machine-local, outside the
+ * rebuildable index. Recording is best-effort: a hook must never fail on it. */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { withServedDatabase } from "./served.js";
+import { HUNCH_VERSION } from "./version.js";
+function ensureTable(db) {
+    db.exec(`CREATE TABLE IF NOT EXISTS hook_observations (
+    provider TEXT NOT NULL, event TEXT NOT NULL, at TEXT NOT NULL, version TEXT NOT NULL,
+    PRIMARY KEY (provider, event)
+  )`);
+}
+/** Never throws (con_03a0b94b2e): a missing ledger costs evidence, not the edit. */
+export function recordHookObservation(root, provider, event) {
+    try {
+        withServedDatabase(root, db => {
+            ensureTable(db);
+            db.prepare("INSERT OR REPLACE INTO hook_observations VALUES (?, ?, ?, ?)").run(provider, event, new Date().toISOString(), HUNCH_VERSION);
+        });
+    }
+    catch { /* evidence is optional; the hook response is not */ }
+}
+export function readHookObservations(root) {
+    if (!existsSync(join(root, ".hunch-cache", "served.db")))
+        return [];
+    return withServedDatabase(root, db => {
+        ensureTable(db);
+        return db.prepare("SELECT provider, event, at, version FROM hook_observations ORDER BY at DESC").all();
+    });
+}
+//# sourceMappingURL=hookObservations.js.map

package/dist/core/hookcache.d.ts

@@ -0,0 +1,10 @@
+/** Decide whether this injection should be the FULL grounding block or a delta
+ *  one-liner. Records the content hash as a side effect (so the next identical
+ *  call dedups). Never throws. */
+export declare function injectionMode(sessionId: string | undefined, key: string, content: string): "full" | "delta";
+/** Forget everything injected into a session. Compaction summarizes injected
+ *  grounding out of the agent's context while the dedup map still says
+ *  "delivered" — so on PreCompact / SessionStart[source=compact] the map must
+ *  reset, or post-compact edits get delta one-liners against grounding the
+ *  agent no longer has. Never throws (same posture as injectionMode). */
+export declare function resetSessionInjections(sessionId: string | undefined): void;

package/dist/core/hookpolicy.d.ts

@@ -0,0 +1,47 @@
+/** Decision logic for the strict agent hook (`hunch hook`): does editing a file
+ *  hit a BLOCKING invariant — directly (its scope matches) or via blast radius
+ *  (a guarded dependency)? Extracted from the CLI so it is unit-testable against a
+ *  real HunchStore, and so the model-facing refusal text lives in one audited
+ *  place. Mirrors the `hunch check` direct/near logic, blocking-severity only. */
+import type { HunchStore } from "../store/hunchStore.js";
+export interface BlockingHit {
+    /** Refusal text fed back to the model as the deny reason. Deliberately states
+     *  ONLY the invariant — never how to disable the guard, so an autonomous agent
+     *  cannot be coached into lowering enforcement to get its edit through. */
+    reason: string;
+    /** Structured provenance for the catch-log (core/events.ts). `reason` alone can't
+     *  be aggregated; these carry which rule earned its keep. A constraint block sets
+     *  `constraint`; a veto block sets `decision`. IDS ONLY — never rule TEXT: the hook
+     *  writes to the PUBLIC repo's events.log but can enforce a PRIVATE overlay rule, so
+     *  the log must stay leak-safe (an opaque id resolves to text only where that record
+     *  is visible). No subject/object/assert here — a plain block has no conformance
+     *  predicate to report (dec_6253f7e6d6). */
+    event: {
+        kind: "constraint" | "veto";
+        constraint?: string;
+        decision?: string;
+    };
+}
+/** Return a BlockingHit if editing `file` (repo-relative) hits a blocking
+ *  invariant directly or through its blast radius, else null. `proposedAddedLines`
+ *  are the lines the edit would ADD: a CONTENT-MATCHED invariant (one carrying a
+ *  `match` regex) denies ONLY when those lines actually trip it — so it stays quiet
+ *  on edits that don't break the rule, instead of blocking every edit in scope
+ *  (dec_e0a36efbf5). Scope-only invariants keep the blunt scope-touch behavior. */
+export declare function blockingInScope(store: HunchStore, file: string, proposedAddedLines?: string[]): BlockingHit | null;
+/** Return a BlockingHit if the proposed added lines for `file` re-introduce an
+ *  approach an in-force decision deliberately REJECTED (a blocking veto), else null.
+ *  The deny text states ONLY the decision + receipt (what was rejected, what was
+ *  chosen) — never how to supersede or disable the guard, so an autonomous agent
+ *  cannot be coached into reversing a decision to land its edit (dec_a466655539). */
+/** Flatten the proposed-edit text from a PreToolUse `tool_input` across all three
+ *  edit tools — Edit (`new_string`), Write (`content`), MultiEdit (`edits[].new_string`)
+ *  — into candidate added lines for the Veto Guard. Empty input → []. */
+export declare function proposedEditLines(toolInput: {
+    new_string?: string;
+    content?: string;
+    edits?: Array<{
+        new_string?: string;
+    }>;
+} | undefined): string[];
+export declare function vetoInScope(store: HunchStore, file: string, proposedAddedLines: string[]): BlockingHit | null;

package/dist/core/ids.d.ts

@@ -0,0 +1,36 @@
+export declare function shortHash(input: string, len?: number): string;
+/** Full sha1 (used for signature_hash etc.). */
+export declare function sha1(input: string): string;
+/** Symbol id from file + name + kind — deterministic across re-indexes. */
+export declare function symbolId(file: string, name: string, kind: string): string;
+/** Component id from a stable name. */
+export declare function componentId(name: string): string;
+/** Edge id from its endpoints + type — deterministic, dedupes naturally. */
+export declare function edgeId(from: string, to: string, type: string): string;
+/** Stable Engineering Landscape resource identity. The kind remains visible so
+ * fragments stay useful without a lookup table; the natural key is normalized
+ * only where spelling cannot carry meaning (outer whitespace, path separators,
+ * and a trailing slash). Kind-specific discovery may apply stricter canonical
+ * rules before calling this helper. */
+export declare function resourceId(kind: string, naturalKey: string): string;
+/** Resource relationships ride the existing edge graph and therefore share its
+ * endpoint/type identity rule. Keeping one helper prevents a parallel graph from
+ * minting incompatible relationship ids. */
+export declare function resourceRelationshipId(from: string, to: string, type: string): string;
+/** Decision id. Seed with the CANONICAL full commit sha (the auto-sync and MCP
+ *  commit paths both do this, so a recorded decision upgrades the auto-draft for
+ *  the same commit), or with "manual:<title>" for an ad-hoc MCP decision. */
+export declare function decisionId(seed: string): string;
+/** Bug id seeded by symptom/test so the same failure doesn't spawn duplicates. */
+export declare function bugId(seed: string): string;
+/** Runbook id seeded by its task; trim + lowercase so re-capturing the same task
+ *  is idempotent rather than minting a duplicate. */
+export declare function runbookId(seed: string): string;
+/** Constraint id seeded by its statement. Trim + lowercase so trivial
+ *  whitespace/case variants of the same rule collapse to one id (idempotent
+ *  re-capture), instead of minting a duplicate constraint. */
+export declare function constraintId(statement: string): string;
+/** Finding id seeded by its title (trim + lowercase, same idiom as constraints):
+ *  re-recording the same observation UPDATES it (e.g. a triage change) instead of
+ *  minting a duplicate. A genuinely new observation deserves a new title. */
+export declare function findingId(title: string): string;

package/dist/core/importReview.d.ts

@@ -0,0 +1,30 @@
+import type { Decision } from "./types.js";
+export type ImportedAdrDisposition = "approve" | "decline";
+export interface ImportedAdrReview {
+    disposition: ImportedAdrDisposition;
+    sourceHash: string;
+    reviewHash: string;
+    reviewer: string | null;
+    reviewedAt: string | null;
+}
+export declare function isImportedAdrDecision(decision: Decision): boolean;
+export declare function importedAdrSourceHash(decision: Decision): string | null;
+/** Hash the complete mapped meaning, not just the ADR source bytes. This prevents
+ * a later importer/parser change from carrying old authority onto new semantics
+ * even when the Markdown file itself did not change. */
+export declare function importedAdrReviewHash(decision: Decision): string;
+export declare function importedAdrReview(decision: Decision): ImportedAdrReview | null;
+export declare function isPendingImportedAdrReview(decision: Decision): boolean;
+export declare function pendingImportedAdrReviews(decisions: readonly Decision[]): Decision[];
+/** Apply one explicit answer to one exact live imported ADR. Never changes the
+ * ADR lifecycle or content: decline means "reviewed, keep advisory", not delete. */
+export declare function applyImportedAdrReview(decision: Decision, input: {
+    disposition: ImportedAdrDisposition;
+    expectedSourceHash: string;
+    expectedReviewHash: string;
+    reviewer: string;
+    reviewedAt?: string;
+}): Decision;
+/** Carry a review across idempotent re-import only when the source bytes match.
+ * A changed hash deliberately returns the clean new import, reopening review. */
+export declare function carryImportedAdrReview(previous: Decision | null | undefined, next: Decision): Decision;

package/dist/core/io.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Write `data` to `file` via a temp file + rename, so an interrupted write can't
+ * leave the target truncated (the symbols/edges index is the worst to half-write).
+ *
+ * Durability (issue #34): the temp file is fsync'd BEFORE the rename, and the
+ * parent directory best-effort after it. A process kill was always safe (page
+ * cache preserves ordering), but on power loss / OS crash the rename's metadata
+ * could reach disk before the temp file's data blocks — leaving the target
+ * present but truncated or garbage, the exact state the atomic-write invariant
+ * (con_902759b3dc) exists to prevent.
+ *
+ * Windows caveat: renameSync can't REPLACE a file another process holds open (even
+ * for read) — it throws EPERM/EBUSY/EACCES, exactly when the MCP server is reading
+ * while a CLI writes. Retry that atomic replacement with bounded backoff. If the
+ * contention persists, fail with the old target untouched; never trade availability
+ * for a direct write that an interruption could truncate. Failed writes clean up the
+ * temporary file.
+ */
+export declare function writeFileAtomic(file: string, data: string): void;
+/** Atomically create a complete file only when no target exists. A same-dir
+ * hard link publishes the fully written temp inode with create-if-absent
+ * semantics, so concurrent lifecycle writers can never be overwritten. */
+export declare function writeFileAtomicIfAbsent(file: string, data: string): boolean;

package/dist/core/jsonc.d.ts

@@ -0,0 +1,4 @@
+/** Parse JSON with the comments and trailing commas accepted by VS Code JSONC.
+ * String-aware scanning keeps comment-looking text and commas inside strings
+ * untouched. Callers still validate the returned shape for their own contract. */
+export declare function parseJsonc(raw: string): unknown;

package/dist/core/landscapeAdoption.d.ts

@@ -0,0 +1,66 @@
+import { type Edge, type Resource } from "./types.js";
+import { type LandscapeDiscoveryResult } from "../extractors/landscapeDiscovery.js";
+export declare const LANDSCAPE_REVIEW_SCHEMA_VERSION: "hunch.landscape-review/1";
+export declare const LANDSCAPE_ADOPTION_RECEIPT_SCHEMA_VERSION: "hunch.landscape-adoption-receipt/1";
+export declare const MAX_LANDSCAPE_REFRESH_REVISIONS = 16;
+export interface LandscapeReview {
+    schema: typeof LANDSCAPE_REVIEW_SCHEMA_VERSION;
+    authority: "human_confirmed";
+    reviewId: string;
+    reviewer: string;
+    reviewedAt: string;
+    discoveryHash: string;
+    sourceRevision: string;
+    repositoryRootIdentity: string;
+    selectedCandidateHashes: string[];
+    acknowledgedIssueCodes: string[];
+}
+export interface LandscapeAdoptionReceipt {
+    schema: typeof LANDSCAPE_ADOPTION_RECEIPT_SCHEMA_VERSION;
+    authority: "human_confirmed";
+    receiptId: string;
+    review: LandscapeReview;
+    acceptedResourceIds: string[];
+    acceptedRelationshipIds: string[];
+    writtenResourceIds: string[];
+    writtenRelationshipIds: string[];
+    reusedResourceIds: string[];
+    reusedRelationshipIds: string[];
+}
+export interface LandscapeAdoptionPlan {
+    receipt: LandscapeAdoptionReceipt;
+    resourcesToWrite: Resource[];
+    relationshipsToWrite: Edge[];
+    /** Existing, byte-proven adoption records replaced by this reviewed revision. */
+    refreshedResourceIds: string[];
+    refreshedRelationshipIds: string[];
+}
+export interface PlanLandscapeAdoptionInput {
+    discovery: LandscapeDiscoveryResult;
+    expectedDiscoveryHash: string;
+    reviewer: string;
+    reviewedAt?: string;
+    /** `all` remains an explicit operator choice; otherwise every hash is named. */
+    candidateHashes: "all" | string[];
+    acknowledgeIssues?: boolean;
+    existingResources?: Resource[];
+    existingRelationships?: Edge[];
+    /**
+     * Explicitly allow a newer exact revision to replace records from a prior
+     * reviewed adoption. Every replacement still requires a matching entry in
+     * `previousDiscoveries` so the old accepted bytes can be reconstructed and
+     * verified; metadata alone never grants replacement authority.
+     */
+    refreshReviewed?: boolean;
+    previousDiscoveries?: LandscapeDiscoveryResult[];
+}
+/** Refuse a result that was changed after exact-revision discovery. */
+export declare function assertLandscapeDiscoveryIntegrity(discovery: LandscapeDiscoveryResult): void;
+/**
+ * Convert an exact candidate discovery into a prevalidated write plan.
+ *
+ * Planning has no side effects. The caller persists only `resourcesToWrite` and
+ * `relationshipsToWrite` through the ordinary Hunch capture boundary after this
+ * function has proved every selection, endpoint and existing-record conflict.
+ */
+export declare function planLandscapeAdoption(input: PlanLandscapeAdoptionInput): LandscapeAdoptionPlan;

package/dist/core/landscapeDelivery.d.ts

@@ -0,0 +1,76 @@
+import { type Edge, type Resource } from "./types.js";
+export declare const LANDSCAPE_FRAGMENT_SCHEMA_VERSION: "hunch.landscape-fragment/1";
+export type LandscapeSelectionReason = "exact-target" | "task-match" | "orientation-root" | "graph-neighbor";
+export interface SelectedLandscapeResource {
+    record: Resource;
+    selectionReason: LandscapeSelectionReason;
+    selectionRank: number;
+}
+export interface SelectedLandscapeRelationship {
+    record: Edge;
+    selectionReason: "graph-connection";
+    selectionRank: number;
+}
+export interface LandscapeSelectionOmission {
+    kind: "resources" | "relationships";
+    recordId: string;
+    reason: "landscape-cap";
+    detail: string;
+}
+export interface ReviewedLandscapeSelection {
+    schema: typeof LANDSCAPE_FRAGMENT_SCHEMA_VERSION;
+    authority: "human_confirmed";
+    target: string;
+    resources: SelectedLandscapeResource[];
+    relationships: SelectedLandscapeRelationship[];
+    omitted: LandscapeSelectionOmission[];
+}
+export interface DeliveredLandscapeResource extends SelectedLandscapeResource {
+    rank: number;
+    deliveryReason: "ranked";
+    required: false;
+    blocking: false;
+    provenanceStatus: "current";
+    tokenCost: number;
+}
+export interface DeliveredLandscapeRelationship extends SelectedLandscapeRelationship {
+    rank: number;
+    deliveryReason: "ranked";
+    required: false;
+    blocking: false;
+    provenanceStatus: "current";
+    tokenCost: number;
+}
+export interface LandscapeFragmentOmission {
+    kind: "resources" | "relationships";
+    recordId: string;
+    reason: "budget" | "stale-provenance" | "endpoint-not-delivered" | "landscape-cap";
+    detail: string;
+}
+export interface LandscapeDeliveryFragment {
+    schema: typeof LANDSCAPE_FRAGMENT_SCHEMA_VERSION;
+    authority: "human_confirmed";
+    target: string;
+    resources: DeliveredLandscapeResource[];
+    relationships: DeliveredLandscapeRelationship[];
+    omitted: LandscapeFragmentOmission[];
+    reviewIds: string[];
+    discoveryHashes: string[];
+    sourceRevisions: string[];
+    fragmentHash: string;
+}
+export declare function landscapeFragmentHash(value: unknown): string;
+/**
+ * Select a small orientation fragment from durable graph records.
+ *
+ * Candidate/unreviewed/stale records are excluded before ranking, so neither a
+ * good lexical match nor a graph edge can accidentally upgrade their authority.
+ */
+export declare function selectReviewedLandscape(resources: readonly Resource[], relationships: readonly Edge[], target: string, maxItems?: number): ReviewedLandscapeSelection;
+export declare function createLandscapeDeliveryFragment(input: {
+    selection: ReviewedLandscapeSelection;
+    resources: DeliveredLandscapeResource[];
+    relationships: DeliveredLandscapeRelationship[];
+    omitted: LandscapeFragmentOmission[];
+}): LandscapeDeliveryFragment;
+export declare function assertLandscapeDeliveryFragment(value: LandscapeDeliveryFragment): void;

package/dist/core/memorylog.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The memory-move timeline — the data behind `hunch log` and the VS Code "Hunch
+ * Source Control" view. Every commit that touched `.hunch/` is one MOVE (a capture,
+ * adoption, supersession, or prune), classified deterministically from git's own
+ * name-status. Pure parsing — no LLM, no judgment — so the panel shows exactly what
+ * git recorded and each move maps back to a real, revertable commit.
+ *
+ * The parser is split from the git shell-out (extractors/git.gitMemoryLog) so it is
+ * unit-testable with canned `git log` output.
+ */
+export type MemoryMoveKind = "capture" | "adopt" | "supersede" | "prune" | "repair" | "edit";
+/** One commit that changed the memory graph, ready to render as a timeline entry. */
+export interface MemoryMove {
+    sha: string;
+    shortSha: string;
+    /** committer date, ISO 8601. */
+    date: string;
+    subject: string;
+    kind: MemoryMoveKind;
+    /** decision ids (dec_*) this move touched — for the click-through popup. */
+    decisionIds: string[];
+    /** other record ids touched (bugs/constraints/components/policies). */
+    otherIds: string[];
+    added: number;
+    modified: number;
+    deleted: number;
+    /** the `.hunch/` files this commit changed. */
+    files: string[];
+}
+/** The record-header separator we ask `git log --format` to emit, so header lines
+ *  are unambiguous against the name-status lines that follow each commit. */
+export declare const MEMLOG_HEADER = "@@@";
+/** The `--format` string that pairs with {@link parseMemoryLog}. */
+export declare const MEMLOG_FORMAT = "@@@%H\t%h\t%cI\t%s";
+/** Parse `git log <MEMLOG_FORMAT> --name-status -- .hunch/` output into classified
+ *  moves, newest first (git's order). */
+export declare function parseMemoryLog(raw: string): MemoryMove[];

package/dist/core/migrate.d.ts

@@ -0,0 +1,28 @@
+import type { EntityKind } from "./types.js";
+import type { HunchPaths } from "./paths.js";
+/** The schema generation this build writes and reads. Bump on any breaking change. */
+export declare const SCHEMA_VERSION = 3;
+/** A repo whose `.hunch/` predates manifests is treated as v1. Migrations are
+ *  numbered from 2 (each `version` is the number it PRODUCES), so a baseline repo
+ *  runs every migration with version >= 2 — never author a no-op version:1 one. */
+export declare const BASELINE_VERSION = 1;
+export interface Migration {
+    /** The version this migration PRODUCES (i.e. it upgrades version-1 → `version`). */
+    version: number;
+    description: string;
+    /** Transform one raw record (untrusted JSON) of `kind` to the next shape. */
+    up(kind: EntityKind, raw: Record<string, unknown>): Record<string, unknown>;
+}
+/** Ordered, ascending by `version`. Empty at v1 (baseline); future versions append. */
+export declare const MIGRATIONS: Migration[];
+export interface Manifest {
+    schema_version: number;
+}
+/** Read `.hunch/manifest.json`. A missing/corrupt manifest is treated as the
+ *  BASELINE version (a pre-manifest `.hunch/`), so future builds still migrate it. */
+export declare function readManifest(paths: HunchPaths): Manifest;
+/** Write `.hunch/manifest.json` at `version` (default: the current SCHEMA_VERSION). */
+export declare function writeManifest(paths: HunchPaths, version?: number): void;
+/** Apply every migration in (fromVersion, toVersion] to a single raw record. Skips
+ *  non-object input untouched (the loader's Zod pass will reject it). */
+export declare function migrateRaw(kind: EntityKind, raw: unknown, fromVersion: number, migrations?: Migration[], toVersion?: number): unknown;

package/dist/core/outcomeExperience.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { type Finding } from "./types.js";
+export declare const USEFULNESS_OBSERVATION_SCHEMA_VERSION: "hunch.usefulness-observation/1";
+export declare const USEFULNESS_SIGNALS: readonly ["used", "prevented", "near_miss", "contradicted", "stale", "unused", "unknown"];
+export declare const UsefulnessObservationSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"hunch.usefulness-observation/1">;
+    observationId: z.ZodString;
+    episode: z.ZodObject<{
+        provider: z.ZodString;
+        schemaVersion: z.ZodString;
+        episodeId: z.ZodString;
+        episodeHash: z.ZodString;
+        terminalAt: z.ZodString;
+        result: z.ZodEnum<{
+            fail: "fail";
+            pass: "pass";
+            uncertain: "uncertain";
+            abandoned: "abandoned";
+            rolled_back: "rolled_back";
+        }>;
+    }, z.core.$strict>;
+    delivery: z.ZodObject<{
+        receiptRef: z.ZodString;
+        receiptHash: z.ZodString;
+        graphRevision: z.ZodString;
+        sourceRevision: z.ZodString;
+        sourceContentHash: z.ZodString;
+    }, z.core.$strict>;
+    record: z.ZodObject<{
+        recordId: z.ZodString;
+        recordKind: z.ZodString;
+        recordRevision: z.ZodString;
+        contentHash: z.ZodString;
+    }, z.core.$strict>;
+    change: z.ZodOptional<z.ZodObject<{
+        schema: z.ZodLiteral<"hunch.change-identity/1">;
+        algorithm: z.ZodLiteral<"git-raw-tree-delta-sha256/1">;
+        change_id: z.ZodString;
+        base_revision: z.ZodString;
+        head_revision: z.ZodString;
+        base_tree: z.ZodString;
+        head_tree: z.ZodString;
+        delta_hash: z.ZodString;
+        patch_id: z.ZodNullable<z.ZodString>;
+        file_count: z.ZodNumber;
+        paths_hash: z.ZodString;
+        content_hash: z.ZodString;
+    }, z.core.$strict>>;
+    signal: z.ZodEnum<{
+        unknown: "unknown";
+        stale: "stale";
+        used: "used";
+        prevented: "prevented";
+        near_miss: "near_miss";
+        contradicted: "contradicted";
+        unused: "unused";
+    }>;
+    evidence: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            observation: "observation";
+            artifact: "artifact";
+            receipt: "receipt";
+            event: "event";
+            verification: "verification";
+        }>;
+        ref: z.ZodString;
+        hash: z.ZodString;
+    }, z.core.$strict>>;
+    observedAt: z.ZodString;
+    retainUntil: z.ZodString;
+    privacy: z.ZodObject<{
+        payloadMode: z.ZodLiteral<"references_hashes_only">;
+        rawTranscriptIncluded: z.ZodLiteral<false>;
+        rawProviderOutputIncluded: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+    authority: z.ZodObject<{
+        behavioralEffect: z.ZodLiteral<"none">;
+        mayChangeRanking: z.ZodLiteral<false>;
+        mayPromoteKnowledge: z.ZodLiteral<false>;
+        mayGrantAuthority: z.ZodLiteral<false>;
+    }, z.core.$strict>;
+    contentHash: z.ZodString;
+}, z.core.$strict>;
+export type UsefulnessObservation = z.infer<typeof UsefulnessObservationSchema>;
+export type CreateUsefulnessObservationInput = Omit<UsefulnessObservation, "schema" | "observationId" | "authority" | "contentHash">;
+export declare function createUsefulnessObservation(input: CreateUsefulnessObservationInput): UsefulnessObservation;
+export declare function assertUsefulnessObservation(value: unknown): asserts value is UsefulnessObservation;
+/** Contradiction and staleness become open advisory review work, never truth. */
+export declare function usefulnessObservationFinding(value: unknown): Finding | null;

package/dist/core/overlaySafety.d.ts

@@ -0,0 +1,24 @@
+/** Validate the materialized overlay without following links. Git's metadata is
+ * deliberately skipped, but its own directory must still be contained under the
+ * canonical overlay root. Every remotely controlled entry must be an ordinary
+ * file or real directory whose canonical path stays inside that root. */
+export declare function safeOverlayTree(root: string): boolean;
+/** Validate `git ls-tree -r -t -z <exact-oid>` output before checkout. A Git
+ * remote can encode symlinks (120000) and gitlinks (160000); accepting only
+ * ordinary blobs and trees makes the fetched object graph safe to materialize.
+ * The explicit Hunch topology rules keep canonical record directories and
+ * capability/config paths from changing shape on a later pull. */
+export declare function safeOverlayGitTreeListing(listing: string): boolean;
+/** A dedicated Hunch overlay needs exactly one attribute capability: selecting
+ * the locally installed `merge=hunch` JSON merge driver, plus Hunch's exact
+ * `.hunch/manifest.json merge=text` override (the manifest has no record id and
+ * must use Git's built-in text merge), and the five exact generated-doc rules
+ * installed with the grounding merge driver. Reject every other token/pattern pair,
+ * including byte-transforming built-ins such as `ident` and
+ * `working-tree-encoding`, rather than maintaining a command-key blacklist.
+ * Blank lines and comments remain harmless. */
+export declare function hunchAttributesAreSafe(content: string): boolean;
+/** Validate every committed .gitattributes blob in an already-safe ls-tree
+ * listing. Blob loading is injected so clone and later-pull seams share one
+ * parser without either trusting worktree bytes before materialization. */
+export declare function hunchTreeAttributesAreSafe(listing: string, readBlob: (oid: string) => string | null): boolean;

package/dist/core/overlaySafety.js

@@ -129,7 +129,8 @@ export function safeOverlayGitTreeListing(listing) {
 /** A dedicated Hunch overlay needs exactly one attribute capability: selecting
  * the locally installed `merge=hunch` JSON merge driver, plus Hunch's exact
  * `.hunch/manifest.json merge=text` override (the manifest has no record id and
- * must use Git's built-in text merge). Reject every other token/pattern pair,
+ * must use Git's built-in text merge), and the five exact generated-doc rules
+ * installed with the grounding merge driver. Reject every other token/pattern pair,
  * including byte-transforming built-ins such as `ident` and
  * `working-tree-encoding`, rather than maintaining a command-key blacklist.
  * Blank lines and comments remain harmless. */
@@ -144,6 +145,11 @@ export function hunchAttributesAreSafe(content) {
         const attributes = fields.slice(1);
         if (attributes.every((attribute) => attribute === "merge=hunch"))
             continue;
+        // These exact document paths are the only grounding-driver routes installed
+        // by Hunch. Never accept a wildcard or allow it to target JSON memory.
+        if (["CLAUDE.md", "AGENTS.md", ".github/copilot-instructions.md", ".cursor/rules/hunch.mdc", ".windsurf/rules/hunch.md"].includes(fields[0])
+            && attributes.every((attribute) => attribute === "merge=hunch-grounding"))
+            continue;
         if (fields[0] === ".hunch/manifest.json"
             && attributes.every((attribute) => attribute === "merge=text"))
             continue;

package/dist/core/paths.d.ts

@@ -0,0 +1,31 @@
+export declare const HUNCH_DIR = ".hunch";
+/** Canonicalize a free-form path/target to repo-relative POSIX form. Hunch stores
+ *  every path with forward slashes (git emits "/" on all OSes), so any user- or
+ *  agent-supplied target must be normalized before comparison — otherwise a
+ *  Windows caller passing `src\auth\session.ts` never matches the stored
+ *  `src/auth/session.ts`. Safe on symbol names too: they contain no backslashes. */
+export declare function toPosixTarget(target: string): string;
+export interface HunchPaths {
+    /** Repo root (where .hunch/ lives). */
+    root: string;
+    hunch: string;
+    sqlite: string;
+    /** `.hunch/manifest.json` — records the on-disk schema version. */
+    manifest: string;
+    /** `.hunch/config.json` — user runtime config (firmness, etc.). */
+    config: string;
+    dir(kind: string): string;
+}
+export declare function hunchPaths(root: string): HunchPaths;
+/** Build paths for a hunch-layout directory given DIRECTLY — i.e. `hunchDir` IS
+ *  the dir holding the kind subdirs (decisions/, bugs/, …). Used for an external
+ *  PRIVATE overlay store (HUNCH_PRIVATE_DIR), which lives in a separate repo the
+ *  user controls rather than under the current repo's `.hunch/`. */
+export declare function hunchPathsForDir(hunchDir: string): HunchPaths;
+/** Walk up from `start` to the nearest dir containing a .hunch/ dir OR a .git
+ *  (repo boundary), else `start`. Lets `hunch` run from subdirs. A `.git`
+ *  WITHOUT `.hunch` stops the walk: an ancestor `.hunch` above the repo
+ *  boundary belongs to some other scope (e.g. a stray ~/.hunch) and must never
+ *  hijack a fresh repo — init would scaffold, index, and scan OUTSIDE the repo. */
+export declare function isDir(path: string): boolean;
+export declare function findRoot(start?: string): string;