@davesheffer/hunch 1.20.2 → 1.21.0

package/dist/core/projectDnaDelta.js

@@ -0,0 +1,159 @@
+import { createHash } from "node:crypto";
+import { compareCodeUnits } from "./canonicalOrder.js";
+import { assertProjectDnaProfile } from "./projectDna.js";
+export const PROJECT_DNA_DELTA_SCHEMA_VERSION = "hunch.project-dna-delta/1";
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const DELTA_ID = /^pdnad_[a-f0-9]{24}$/;
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .filter(([, child]) => child !== undefined)
+            .sort(([left], [right]) => compareCodeUnits(left, right))
+            .map(([key, child]) => `${JSON.stringify(key)}:${canonical(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function sha256(value) {
+    return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+function evidenceSeal(trait) {
+    return sha256(canonical(trait.evidence));
+}
+function mapTraits(profile) {
+    return new Map(profile.traits.map((trait) => [trait.key, trait]));
+}
+/**
+ * Compare two already-sealed profiles without inferring causality.
+ *
+ * A delta says only that observed DNA changed between exact revisions. It does
+ * not promote the new trait, explain why the change happened, or grant policy.
+ */
+export function diffProjectDna(fromValue, toValue) {
+    assertProjectDnaProfile(fromValue);
+    assertProjectDnaProfile(toValue);
+    const from = fromValue;
+    const to = toValue;
+    if (from.repository_id !== to.repository_id) {
+        throw new Error("project DNA profiles belong to different repositories");
+    }
+    const before = mapTraits(from);
+    const after = mapTraits(to);
+    const keys = [...new Set([...before.keys(), ...after.keys()])].sort(compareCodeUnits);
+    const changes = [];
+    for (const key of keys) {
+        const left = before.get(key);
+        const right = after.get(key);
+        if (!left && right) {
+            changes.push({
+                key,
+                kind: "added",
+                before_trait_id: null,
+                after_trait_id: right.id,
+                before_confidence: null,
+                after_confidence: right.confidence,
+            });
+            continue;
+        }
+        if (left && !right) {
+            changes.push({
+                key,
+                kind: "removed",
+                before_trait_id: left.id,
+                after_trait_id: null,
+                before_confidence: left.confidence,
+                after_confidence: null,
+            });
+            continue;
+        }
+        if (!left || !right)
+            continue;
+        if (left.id !== right.id || evidenceSeal(left) !== evidenceSeal(right)) {
+            changes.push({
+                key,
+                kind: "evidence_changed",
+                before_trait_id: left.id,
+                after_trait_id: right.id,
+                before_confidence: left.confidence,
+                after_confidence: right.confidence,
+            });
+            continue;
+        }
+        if (left.confidence !== right.confidence) {
+            changes.push({
+                key,
+                kind: "confidence_changed",
+                before_trait_id: left.id,
+                after_trait_id: right.id,
+                before_confidence: left.confidence,
+                after_confidence: right.confidence,
+            });
+        }
+    }
+    const unsigned = {
+        schema: PROJECT_DNA_DELTA_SCHEMA_VERSION,
+        repository_id: from.repository_id,
+        from_profile_id: from.profile_id,
+        to_profile_id: to.profile_id,
+        from_revision: from.repository_revision,
+        to_revision: to.repository_revision,
+        changes,
+        changed: changes.length > 0,
+    };
+    const deltaId = `pdnad_${sha256(canonical(unsigned)).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...unsigned, delta_id: deltaId };
+    const delta = { ...sealed, content_hash: sha256(canonical(sealed)) };
+    assertProjectDnaDelta(delta);
+    return delta;
+}
+export function assertProjectDnaDelta(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("project DNA delta is invalid");
+    const delta = value;
+    const expectedFields = [
+        "schema", "delta_id", "repository_id", "from_profile_id", "to_profile_id", "from_revision", "to_revision", "changes", "changed", "content_hash",
+    ].sort(compareCodeUnits);
+    if (Object.keys(value).sort(compareCodeUnits).join("\0") !== expectedFields.join("\0")
+        || delta.schema !== PROJECT_DNA_DELTA_SCHEMA_VERSION || !DELTA_ID.test(delta.delta_id)
+        || !/^pdnar_[a-f0-9]{24}$/.test(delta.repository_id)
+        || !/^pdna_[a-f0-9]{24}$/.test(delta.from_profile_id) || !/^pdna_[a-f0-9]{24}$/.test(delta.to_profile_id)
+        || !/^[a-f0-9]{40,64}$/.test(delta.from_revision) || !/^[a-f0-9]{40,64}$/.test(delta.to_revision)
+        || !Array.isArray(delta.changes) || delta.changes.length > 128 || delta.changed !== (delta.changes.length > 0)
+        || !SHA256.test(delta.content_hash)) {
+        throw new Error("project DNA delta fields are invalid");
+    }
+    const seen = new Set();
+    for (const change of delta.changes) {
+        if (!change || typeof change !== "object" || Array.isArray(change))
+            throw new Error("project DNA trait change is invalid");
+        const fields = ["key", "kind", "before_trait_id", "after_trait_id", "before_confidence", "after_confidence"].sort(compareCodeUnits);
+        if (Object.keys(change).sort(compareCodeUnits).join("\0") !== fields.join("\0")
+            || !/^[a-z][a-z0-9_.-]{2,100}$/.test(change.key) || seen.has(change.key)
+            || !["added", "removed", "evidence_changed", "confidence_changed"].includes(change.kind)
+            || (change.before_trait_id !== null && !/^pdnat_[a-f0-9]{20}$/.test(change.before_trait_id))
+            || (change.after_trait_id !== null && !/^pdnat_[a-f0-9]{20}$/.test(change.after_trait_id))
+            || (change.before_confidence !== null && (!Number.isFinite(change.before_confidence) || change.before_confidence < 0 || change.before_confidence > 1))
+            || (change.after_confidence !== null && (!Number.isFinite(change.after_confidence) || change.after_confidence < 0 || change.after_confidence > 1))) {
+            throw new Error("project DNA trait change fields are invalid");
+        }
+        if ((change.kind === "added" && (change.before_trait_id !== null || change.before_confidence !== null
+            || change.after_trait_id === null || change.after_confidence === null))
+            || (change.kind === "removed" && (change.before_trait_id === null || change.before_confidence === null
+                || change.after_trait_id !== null || change.after_confidence !== null))
+            || ((change.kind === "evidence_changed" || change.kind === "confidence_changed")
+                && (change.before_trait_id === null || change.before_confidence === null
+                    || change.after_trait_id === null || change.after_confidence === null))) {
+            throw new Error("project DNA trait change transition is invalid");
+        }
+        seen.add(change.key);
+    }
+    const { content_hash: _contentHash, delta_id: _deltaId, ...base } = delta;
+    const expectedId = `pdnad_${sha256(canonical(base)).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...base, delta_id: delta.delta_id };
+    if (delta.delta_id !== expectedId || delta.content_hash !== sha256(canonical(sealed))) {
+        throw new Error("project DNA delta seal is invalid");
+    }
+}
+//# sourceMappingURL=projectDnaDelta.js.map

package/dist/extractors/git.js

@@ -2125,6 +2125,53 @@ export function firstCommitForFile(file, cwd) {
 export function lastChangeDate(file, cwd) {
     return gitSafe(["log", "-1", "--format=%aI", "--", file], cwd);
 }
+/**
+ * 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 function scopedLastChangeDates(scopes, cwd, maxChangedPaths = 4_096) {
+    const pathspecs = [...new Set(scopes)].map((scope) => {
+        const normalized = scope.replaceAll("\\", "/");
+        return /[*?[]/.test(normalized) ? `:(glob)${normalized}` : `:(literal)${normalized}`;
+    });
+    if (pathspecs.length === 0)
+        return new Map();
+    const raw = gitRawSafeIsolated([
+        "-c", "core.quotePath=false",
+        "log", "-z", "--name-only", "--format=HUNCH_DATE:%aI%x00", "--", ...pathspecs,
+    ], cwd, 64 * 1024 * 1024);
+    if (raw === null)
+        return null;
+    const out = new Map();
+    let commitDate = "";
+    for (const rawToken of raw.split("\0")) {
+        // Git inserts one presentation newline between a custom commit format and its
+        // first NUL-delimited path. Remove exactly that byte; a real leading newline in
+        // a path remains as the second byte and therefore cannot alias a normal path.
+        const token = rawToken.startsWith("\n") ? rawToken.slice(1) : rawToken;
+        if (!token)
+            continue;
+        if (token.startsWith("HUNCH_DATE:")) {
+            const candidate = token.slice("HUNCH_DATE:".length);
+            commitDate = Number.isFinite(Date.parse(candidate)) ? candidate : "";
+            continue;
+        }
+        if (!commitDate)
+            continue;
+        const previous = out.get(token);
+        if (!previous || Date.parse(commitDate) > Date.parse(previous)) {
+            out.set(token, commitDate);
+            if (out.size > maxChangedPaths)
+                return null;
+        }
+    }
+    return out;
+}
 /** 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>`).
  *

package/dist/mcp/server.js

@@ -27,6 +27,9 @@ import { compileVerifiedEvidenceMap, EvidenceExecutionSchema, EvidenceInterventi
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
 import { buildDeliveryEnvelope, DELIVERY_PROFILE_POLICY_VERSION, DELIVERY_PROFILES, } from "../core/delivery.js";
 import { CHANGE_IDENTITY_ALGORITHM, CHANGE_IDENTITY_SCHEMA_VERSION, deriveChangeIdentity, } from "../core/changeIdentity.js";
+import { PROJECT_DNA_CATEGORIES, PROJECT_DNA_MATCH_SCHEMA_VERSION, PROJECT_DNA_SCHEMA_VERSION, discoverProjectDna, evaluateProjectDnaMatch, } from "../core/projectDna.js";
+import { PROJECT_DNA_DELTA_SCHEMA_VERSION, diffProjectDna } from "../core/projectDnaDelta.js";
+import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
 import { armExecutionObligations, loadPipelineState, savePipelineState } from "../core/pipeline.js";
 import { recordServed } from "../core/served.js";
 import { EdgeSchema, ResourceSchema } from "../core/types.js";
@@ -250,6 +253,73 @@ const CHANGE_IDENTITY_OUTPUT_SCHEMA = z.object({
     paths_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
     content_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
 });
+const PROJECT_DNA_EVIDENCE_SCHEMA = z.object({
+    kind: z.enum(["git-history", "committed-file"]),
+    ref: z.string(),
+    revision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    content_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    sample_count: z.number().int().positive(),
+    provenance: z.literal("committed-repository"),
+    visibility: z.literal("repository"),
+});
+const PROJECT_DNA_PROFILE_OUTPUT_SCHEMA = z.object({
+    schema: z.literal(PROJECT_DNA_SCHEMA_VERSION),
+    profile_id: z.string().regex(/^pdna_[a-f0-9]{24}$/),
+    repository_id: z.string().regex(/^pdnar_[a-f0-9]{24}$/),
+    repository_revision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    history_sample_count: z.number().int().nonnegative(),
+    source_files: z.array(z.string()),
+    traits: z.array(z.object({
+        id: z.string().regex(/^pdnat_[a-f0-9]{20}$/),
+        category: z.enum(PROJECT_DNA_CATEGORIES),
+        key: z.string(),
+        claim: z.string(),
+        confidence: z.number().min(0).max(1),
+        observation_state: z.literal("observed"),
+        freshness: z.literal("current"),
+        contradiction: z.literal("none"),
+        evidence: z.array(PROJECT_DNA_EVIDENCE_SCHEMA),
+    })),
+    content_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+});
+const PROJECT_DNA_MATCH_OUTPUT_SCHEMA = z.object({
+    schema: z.literal(PROJECT_DNA_MATCH_SCHEMA_VERSION),
+    match_id: z.string().regex(/^pdnam_[a-f0-9]{24}$/),
+    profile_id: z.string().regex(/^pdna_[a-f0-9]{24}$/),
+    repository_id: z.string().regex(/^pdnar_[a-f0-9]{24}$/),
+    repository_revision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    artifact_kind: z.enum(["commit", "pull_request", "issue", "message"]),
+    score: z.number().min(0).max(100).nullable(),
+    applicable_checks: z.number().int().nonnegative(),
+    checks: z.array(z.object({
+        trait_id: z.string().regex(/^pdnat_[a-f0-9]{20}$/),
+        key: z.string(),
+        applicable: z.boolean(),
+        passed: z.boolean().nullable(),
+        weight: z.number().int().positive(),
+        detail: z.string(),
+    })),
+    content_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+});
+const PROJECT_DNA_DELTA_OUTPUT_SCHEMA = z.object({
+    schema: z.literal(PROJECT_DNA_DELTA_SCHEMA_VERSION),
+    delta_id: z.string().regex(/^pdnad_[a-f0-9]{24}$/),
+    repository_id: z.string().regex(/^pdnar_[a-f0-9]{24}$/),
+    from_profile_id: z.string().regex(/^pdna_[a-f0-9]{24}$/),
+    to_profile_id: z.string().regex(/^pdna_[a-f0-9]{24}$/),
+    from_revision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    to_revision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    changes: z.array(z.object({
+        key: z.string(),
+        kind: z.enum(["added", "removed", "evidence_changed", "confidence_changed"]),
+        before_trait_id: z.string().regex(/^pdnat_[a-f0-9]{20}$/).nullable(),
+        after_trait_id: z.string().regex(/^pdnat_[a-f0-9]{20}$/).nullable(),
+        before_confidence: z.number().min(0).max(1).nullable(),
+        after_confidence: z.number().min(0).max(1).nullable(),
+    })),
+    changed: z.boolean(),
+    content_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+});
 /** Return the same human-readable brief older clients consume plus the exact
  *  machine-readable envelope. Receipt recording is deliberately best-effort:
  *  recordServed never throws, so telemetry can never cost a delivery. */
@@ -835,6 +905,76 @@ export function buildServerWithRootControl(initialRoot) {
             return err(error.message);
         }
     });
+    // -- hunch_project_dna ----------------------------------------------------
+    server.registerTool("hunch_project_dna", {
+        title: "Inspect this repository's evidence-backed Project DNA",
+        description: "Derive a bounded, deterministic profile of how this repository communicates, reviews, and builds from one exact committed revision. Read-only: observations remain advisory and are never adopted into graph authority automatically.",
+        inputSchema: {
+            ref: z.string().min(1).max(1_024).optional().describe("Git commit/ref to inspect (default HEAD)."),
+            cwd: cwdHintField,
+        },
+        outputSchema: PROJECT_DNA_PROFILE_OUTPUT_SCHEMA,
+    }, async ({ ref }) => {
+        try {
+            const profile = PROJECT_DNA_PROFILE_OUTPUT_SCHEMA.parse(discoverProjectDna(root, ref ?? "HEAD"));
+            const headline = `${profile.profile_id} at ${profile.repository_revision}: ${profile.traits.length} evidence-backed trait(s) from ${profile.history_sample_count} commit subject(s) and ${profile.source_files.length} convention file(s). Advisory observation only.`;
+            return { content: [{ type: "text", text: headline }], structuredContent: profile };
+        }
+        catch (error) {
+            return err(error.message);
+        }
+    });
+    // -- hunch_project_match --------------------------------------------------
+    server.registerTool("hunch_project_match", {
+        title: "Evaluate whether an artifact matches this repository's Project DNA",
+        description: "Explainably score a commit subject, PR, issue, or message using only deterministic checks supported by an exact-revision Project DNA profile. Advisory: never changes policy or enforcement authority.",
+        inputSchema: {
+            kind: z.enum(["commit", "pull_request", "issue", "message"]),
+            title: z.string().min(1).max(1_000),
+            body: z.string().max(20_000).optional(),
+            ref: z.string().min(1).max(1_024).optional().describe("Git commit/ref whose DNA should be used (default HEAD)."),
+            cwd: cwdHintField,
+        },
+        outputSchema: PROJECT_DNA_MATCH_OUTPUT_SCHEMA,
+    }, async ({ kind, title, body, ref }) => {
+        try {
+            const profile = discoverProjectDna(root, ref ?? "HEAD");
+            const match = PROJECT_DNA_MATCH_OUTPUT_SCHEMA.parse(evaluateProjectDnaMatch(profile, { kind, title, body }));
+            const failed = match.checks.filter((check) => check.applicable && !check.passed).map((check) => check.key);
+            const headline = match.score === null
+                ? `${match.match_id}: no deterministic DNA checks apply to this artifact.`
+                : `${match.match_id}: Project Match ${match.score.toFixed(1)}/100 across ${match.applicable_checks} check(s)${failed.length ? `; mismatches: ${failed.join(", ")}` : ""}. Advisory only.`;
+            return { content: [{ type: "text", text: headline }], structuredContent: match };
+        }
+        catch (error) {
+            return err(error.message);
+        }
+    });
+    // -- hunch_project_dna_delta ---------------------------------------------
+    server.registerTool("hunch_project_dna_delta", {
+        title: "Compare Project DNA across two exact repository revisions",
+        description: "Return a sealed, explainable delta between two immutable Project DNA profiles. Read-only: reports observation drift and never rewrites history or graph authority.",
+        inputSchema: {
+            from_ref: z.string().min(1).max(1_024).describe("Older Git commit/ref."),
+            to_ref: z.string().min(1).max(1_024).describe("Newer Git commit/ref."),
+            cwd: cwdHintField,
+        },
+        outputSchema: PROJECT_DNA_DELTA_OUTPUT_SCHEMA,
+    }, async ({ from_ref, to_ref }) => {
+        try {
+            const delta = PROJECT_DNA_DELTA_OUTPUT_SCHEMA.parse(diffProjectDna(discoverProjectDna(root, from_ref), discoverProjectDna(root, to_ref)));
+            return {
+                content: [{
+                        type: "text",
+                        text: `${delta.delta_id}: ${delta.changed ? `${delta.changes.length} observed DNA change(s)` : "no observed DNA change"} from ${delta.from_revision} to ${delta.to_revision}. Advisory only.`,
+                    }],
+                structuredContent: delta,
+            };
+        }
+        catch (error) {
+            return err(error.message);
+        }
+    });
     // -- hunch_context (surgical retrieval) -----------------------------------
     server.registerTool("hunch_context", {
         title: "Assemble the minimal relevant Hunch slice for a task",
@@ -851,6 +991,15 @@ export function buildServerWithRootControl(initialRoot) {
         if (as_of && !asOf)
             return err(`Could not resolve as_of "${as_of}" to a commit.`);
         const ctx = store.assembleContext(target, budget_tokens ?? 1500, { asOf });
+        let dnaSupplement = null;
+        try {
+            dnaSupplement = projectDnaDeliverySupplement(discoverProjectDna(root, as_of ?? "HEAD"));
+        }
+        catch {
+            // Context retrieval must keep its existing graceful behavior when the
+            // Git checkout cannot provide DNA; the dedicated DNA tool reports the
+            // exact derivation error when a caller needs diagnostics.
+        }
         const options = {
             root,
             symbols: store.recs("symbols"),
@@ -858,6 +1007,7 @@ export function buildServerWithRootControl(initialRoot) {
             decisionCorpus: store.recs("decisions"),
             historical: !!asOf,
             profile: profile ?? "builder",
+            supplements: dnaSupplement ? [dnaSupplement] : [],
         };
         // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
         // used to return an empty brief while the graph held the answer — fall back to
@@ -870,7 +1020,7 @@ export function buildServerWithRootControl(initialRoot) {
             !ctx.landscape?.resources.length &&
             !ctx.landscape?.relationships.length;
         if (empty && !asOf) {
-            const hits = store.search(target, 8);
+            const hits = store.rankedSearch(target, 8);
             if (hits.length) {
                 const resolved = hits.map((hit) => ({ hit, record: store.resolve(hit.ref)?.record }));
                 const fallback = {
@@ -882,14 +1032,17 @@ export function buildServerWithRootControl(initialRoot) {
                 };
                 const envelope = buildDeliveryEnvelope(fallback, {
                     ...options,
-                    supplements: hits
-                        .filter((hit) => !["constraints", "decisions", "bugs", "findings"].includes(hit.kind))
-                        .map((hit, index) => ({
-                        id: hit.ref,
-                        kind: `search-${hit.kind}`,
-                        text: `${hit.ref} — ${hit.title}: ${hit.snippet}`,
-                        priority: 100 - index,
-                    })),
+                    supplements: [
+                        ...(dnaSupplement ? [dnaSupplement] : []),
+                        ...hits
+                            .filter((hit) => !["constraints", "decisions", "bugs", "findings"].includes(hit.kind))
+                            .map((hit, index) => ({
+                            id: hit.ref,
+                            kind: `search-${hit.kind}`,
+                            text: `${hit.ref} — ${hit.title}: ${hit.snippet}`,
+                            priority: 100 - index,
+                        })),
+                    ],
                 });
                 return deliveredContext(root, target, envelope, extra.sessionId);
             }

package/dist/projectDna.js

@@ -0,0 +1,10 @@
+/**
+ * Stable public programmatic surface for the Project DNA Engine.
+ *
+ * Keep transport/orchestration consumers on this barrel so internal core file
+ * layout can evolve without changing the published contract entry point.
+ */
+export { PROJECT_DNA_CATEGORIES, PROJECT_DNA_MATCH_SCHEMA_VERSION, PROJECT_DNA_SCHEMA_VERSION, assertProjectDnaMatch, assertProjectDnaProfile, discoverProjectDna, evaluateProjectDnaMatch, } from "./core/projectDna.js";
+export { PROJECT_DNA_DELTA_SCHEMA_VERSION, assertProjectDnaDelta, diffProjectDna, } from "./core/projectDnaDelta.js";
+export { PROJECT_DNA_SUPPLEMENT_KIND, projectDnaDeliverySupplement, } from "./core/projectDnaDelivery.js";
+//# sourceMappingURL=projectDna.js.map

package/dist/store/hunchStore.js

@@ -18,7 +18,7 @@ import { openDb, withTx } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
-import { gitCommonDir, gitWorktreeRoot, sameGitPublication } from "../extractors/git.js";
+import { gitCommonDir, gitWorktreeRoot, isolatedHeadSha, sameGitPublication, scopedLastChangeDates, } from "../extractors/git.js";
 import { pathMatchesGlob, pathsRelated } from "../core/glob.js";
 import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
@@ -85,6 +85,11 @@ export class HunchStore {
      *  equal to a committed file (dec_d7bad4ccb7). */
     suppressPrivate = false;
     _db = null;
+    /** HEAD-keyed, process-local ranking evidence. It never changes record authority or storage. */
+    decisionFreshnessRoot = "";
+    decisionFreshnessHead = "";
+    decisionFreshnessScopes = new Set();
+    decisionFreshnessChanges = new Map();
     constructor(paths) {
         this.paths = paths;
         this.json = new JsonStore(paths);
@@ -621,7 +626,8 @@ export class HunchStore {
     /** Post-fusion rerank by graph PRIORS (dec_25e277f479): relevance ordering, not
      *  just reachability. Trust weight w = liveness × provenance × recency: liveness 0.6
      *  for superseded/retired/rejected, provenance 1.0 / 0.85 / 0.75 for
-     *  human_confirmed / llm_draft / extracted-inferred, recency 0.7 + 0.3·½^(age/90d).
+     *  human_confirmed / llm_draft / extracted-inferred, recency 0.7 + 0.3·½^(age/90d),
+     *  and proven anchored-file staleness 0.8. Every factor is ranking-only.
      *  Runbook trigger phrases matching the query boost ×1.5 (exact intent beats
      *  keyword luck). Structural refs (symbols/components/edges) stay neutral.
      *
@@ -643,7 +649,7 @@ export class HunchStore {
      *  a stale or low-provenance record visibly dims, an exact runbook-trigger match
      *  visibly promotes, and neither can leapfrog the whole pool. Same measurement
      *  after: 0% evicted from fused ranks 0–8. Deterministic; ties keep fused order. */
-    rerankByPriors(hits, limit, query) {
+    rerankByPriors(hits, limit, query, freshnessRoot = this.paths.root) {
         if (!hits.length)
             return hits; // a SINGLE hit still runs — topic-chain promotion must fire for the lone stale match
         const now = Date.now();
@@ -672,6 +678,10 @@ export class HunchStore {
                 pos: i + 0.5,
             });
         }
+        const decisionsById = new Map(this.recs("decisions").map((decision) => [decision.id, decision]));
+        const staleDecisionIds = this.staleDecisionIds(pool.filter(({ h }) => h.kind === "decisions")
+            .map(({ h }) => decisionsById.get(h.ref))
+            .filter((decision) => !!decision), freshnessRoot);
         const scored = pool.map(({ h, pos }) => {
             const m = this.priorMeta(h.ref, h.kind);
             let w = 1;
@@ -694,6 +704,10 @@ export class HunchStore {
                     if (Number.isFinite(ageDays))
                         w *= 0.7 + 0.3 * Math.pow(0.5, ageDays / 90);
                 }
+                // File-change staleness is a bounded relevance signal only. It cannot retire,
+                // withhold, supersede, or weaken a decision's enforcement authority.
+                if (h.kind === "decisions" && staleDecisionIds.has(h.ref))
+                    w *= STALE_DECISION_PRIOR_WEIGHT;
                 if (q && m.triggers?.some((tr) => q.includes(tr) || tr.includes(q)))
                     w *= 1.5;
             }
@@ -708,6 +722,77 @@ export class HunchStore {
         scored.sort((a, b) => a.pos - b.pos);
         return scored.slice(0, limit).map((x) => x.h);
     }
+    /**
+     * Score only freshness that the existing graph clocks can prove: an anchored path changed after
+     * `provenance.last_verified`. One bounded Git pass fills a HEAD-keyed cache for newly encountered
+     * scopes; repeated MCP/CLI queries perform no history walk until HEAD changes.
+     */
+    staleDecisionIds(decisions, freshnessRoot) {
+        const root = resolve(freshnessRoot);
+        const head = isolatedHeadSha(root);
+        if (!head)
+            return new Set();
+        if (root !== this.decisionFreshnessRoot || head !== this.decisionFreshnessHead) {
+            this.decisionFreshnessRoot = root;
+            this.decisionFreshnessHead = head;
+            this.decisionFreshnessScopes.clear();
+            this.decisionFreshnessChanges.clear();
+        }
+        const eligible = new Map();
+        let scopeCount = 0;
+        for (const decision of decisions) {
+            const verifiedAt = Date.parse(decision.provenance.last_verified ?? "");
+            if (!Number.isFinite(verifiedAt))
+                continue;
+            const scopes = [...new Set(decision.related_files.map(safeFreshnessScope).filter(Boolean))];
+            if (scopes.length === 0 || scopeCount + scopes.length > DECISION_FRESHNESS_SCOPE_QUERY_CAP)
+                continue;
+            scopeCount += scopes.length;
+            eligible.set(decision.id, { verifiedAt, scopes });
+        }
+        let missing = [...new Set([...eligible.values()].flatMap((candidate) => candidate.scopes))]
+            .filter((scope) => !this.decisionFreshnessScopes.has(scope));
+        if (missing.length) {
+            if (this.decisionFreshnessScopes.size + missing.length > DECISION_FRESHNESS_SCOPE_CACHE_CAP) {
+                this.decisionFreshnessScopes.clear();
+                this.decisionFreshnessChanges.clear();
+                missing = [...new Set([...eligible.values()].flatMap((candidate) => candidate.scopes))];
+            }
+            const observed = scopedLastChangeDates(missing, root, DECISION_FRESHNESS_PATH_CACHE_CAP);
+            if (observed) {
+                if (this.decisionFreshnessChanges.size + observed.size > DECISION_FRESHNESS_PATH_CACHE_CAP) {
+                    this.decisionFreshnessScopes.clear();
+                    this.decisionFreshnessChanges.clear();
+                }
+                else {
+                    missing.forEach((scope) => this.decisionFreshnessScopes.add(scope));
+                    observed.forEach((date, path) => {
+                        const previous = this.decisionFreshnessChanges.get(path);
+                        if (!previous || Date.parse(date) > Date.parse(previous))
+                            this.decisionFreshnessChanges.set(path, date);
+                    });
+                }
+            }
+        }
+        const stale = new Set();
+        for (const [decisionId, candidate] of eligible) {
+            if (candidate.scopes.some((scope) => !this.decisionFreshnessScopes.has(scope)))
+                continue;
+            for (const [changedPath, changedAt] of this.decisionFreshnessChanges) {
+                if (Date.parse(changedAt) <= candidate.verifiedAt)
+                    continue;
+                if (candidate.scopes.some((scope) => freshnessScopeMatches(changedPath, scope))) {
+                    stale.add(decisionId);
+                    break;
+                }
+            }
+        }
+        return stale;
+    }
+    /** Fast relevance ranking for task-phrase context fallback: FTS + bounded graph priors, no model. */
+    rankedSearch(query, limit = 12, opts = {}) {
+        return this.rerankByPriors(this.search(query, Math.max(limit, 24)), limit, query, opts.freshnessRoot ?? this.paths.root);
+    }
     /** The prior-bearing metadata for a hit: liveness, provenance, effective date,
      *  and (runbooks) trigger phrases. null = structural ref, neutral prior. */
     priorMeta(ref, kind) {
@@ -779,9 +864,9 @@ export class HunchStore {
             tokenCap: boundedWhole(opts.graphTokenCap, GRAPH_TOKEN_CAP, GRAPH_TOKEN_HARD_MAX),
         }, gw);
         if (!sem.length && !graph.length)
-            return this.rerankByPriors(fts, limit, query);
+            return this.rerankByPriors(fts, limit, query, opts.freshnessRoot ?? this.paths.root);
         // Fuse with headroom so the prior rerank can promote from below the cut line.
-        return this.rerankByPriors(this.rrfFuse(fts, sem, graph, Math.max(limit, 24), gw), limit, query);
+        return this.rerankByPriors(this.rrfFuse(fts, sem, graph, Math.max(limit, 24), gw), limit, query, opts.freshnessRoot ?? this.paths.root);
     }
     /** Runbook-scoped retrieval (roadmap #5): the same FTS+graph(+semantic) fusion,
      *  restricted to the `runbooks` kind — so a "what's the procedure for X" query
@@ -1777,6 +1862,11 @@ const GRAPH_TOKEN_CAP = boundedWhole(numEnv("HUNCH_GRAPH_TOKEN_CAP", 2_000), 2_0
  *  rerankByPriors for the measurement that fixed it at 4. */
 const PRIOR_SHIFT_SCALE = numEnv("HUNCH_PRIOR_SHIFT_SCALE", 12);
 const MAX_PRIOR_SHIFT = numEnv("HUNCH_MAX_PRIOR_SHIFT", 4);
+/** A stale anchored decision stays visible and authoritative; it moves down by at most the shared prior clamp. */
+const STALE_DECISION_PRIOR_WEIGHT = Math.min(1, numEnv("HUNCH_STALE_DECISION_PRIOR_WEIGHT", 0.8));
+const DECISION_FRESHNESS_SCOPE_QUERY_CAP = 256;
+const DECISION_FRESHNESS_SCOPE_CACHE_CAP = 512;
+const DECISION_FRESHNESS_PATH_CACHE_CAP = 4_096;
 /** Memory-record prior: a "why" question is answered by RECORDED INTENT (decisions,
  *  constraints, bugs, runbooks, policies), not by the code symbols that merely share
  *  its vocabulary. Symbols carry a neutral prior (priorMeta -> null), so on a graph
@@ -1789,6 +1879,23 @@ const MAX_PRIOR_SHIFT = numEnv("HUNCH_MAX_PRIOR_SHIFT", 4);
  *  0.402 -> 0.575. Set HUNCH_MEMORY_PRIOR_SHIFT=0 to disable. */
 const MEMORY_PRIOR_SHIFT = numEnv("HUNCH_MEMORY_PRIOR_SHIFT", 12);
 const MEMORY_KINDS = new Set(["decisions", "constraints", "bugs", "runbooks", "policies"]);
+function safeFreshnessScope(value) {
+    const normalized = toPosixTarget(value.trim());
+    if (!normalized || normalized.length > 1_024 || normalized.includes("\0")
+        || isAbsolute(normalized) || /^[a-zA-Z]:/.test(normalized)
+        || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")
+        || normalized.startsWith("private:"))
+        return null;
+    return normalized.replace(/^\.\//, "");
+}
+function freshnessScopeMatches(path, scope) {
+    try {
+        return pathsRelated(path, scope) || pathMatchesGlob(path, scope);
+    }
+    catch {
+        return false;
+    }
+}
 function numEnv(name, dflt) {
     const v = Number(process.env[name]);
     // >= 0, not > 0: zero is the documented kill-switch (HUNCH_RRF_W_*=0 disables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.20.2",
+  "version": "1.21.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -17,6 +17,14 @@
   "bin": {
     "hunch": "dist/cli/index.js"
   },
+  "exports": {
+    "./project-dna": {
+      "types": "./dist/projectDna.d.ts",
+      "default": "./dist/projectDna.js"
+    },
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist/**/*.js",
     "server.json",