@davesheffer/hunch 1.20.3 → 1.21.1

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/integrations/scaffold.js

@@ -101,14 +101,25 @@ Reconcile decision-grounding drift for **$ARGUMENTS** (or the whole repo).
 3. Only if I explicitly say "the DECISION is stale, not the doc" (Heal B): run /capture to record a superseding decision, then return to step 2 — the prose re-derives from the new decision as a separate confirm.
 4. Report: healed (Heal A), superseded (Heal B), skipped. Never touch the graph except via an explicit Heal B capture.
 `;
-/** A settings.json hook entry is Hunch's if any of its commands ends with the
- *  Hunch CLI entry + the `hook` subcommand (e.g. `…/index.js hook`). Matching the
- *  command TAIL — not the absolute path — makes re-init idempotent AND survives a
- *  repo-folder rename (the path before index.js changes; the tail does not). The
- *  leading path separator (`/` or `\`) requires `index` to be a full path segment,
- *  so a foreign tool's `…/myindex.js hook` isn't mistaken for ours and clobbered. */
+/** A settings.json hook entry is Hunch's if any of its commands is either the
+ *  native/source CLI entry (`…/index.js hook`) or the exact published-package
+ *  launcher written by older Hunch versions (`npx --package=…@davesheffer/hunch…
+ *  hunch hook`). Matching both generations makes an upgrade idempotent instead
+ *  of leaving the portable old hook alongside the new native invocation. The
+ *  source form still requires `index` to be a full path segment, and the npx form
+ *  requires both the scoped package and the `hunch hook` tail, so foreign hooks
+ *  are preserved. */
 function isHunchHook(entry) {
-    return !!entry.hooks?.some((h) => typeof h.command === "string" && /[\\/]index\.(js|ts)"?\s+hook\s*$/.test(h.command));
+    return !!entry.hooks?.some((h) => {
+        if (typeof h.command !== "string")
+            return false;
+        const command = h.command;
+        const nativeOrSource = /[\\/]index\.(js|ts)"?\s+hook\s*$/.test(command);
+        const publishedNpx = /^\s*"?npx(?:\.cmd)?"?\s+/i.test(command)
+            && /--package=(?:hunch-exact@npm:)?@davesheffer\/hunch(?:@[^"\s]+)?/.test(command)
+            && /\s"?hunch"?\s+"?hook"?\s*$/.test(command);
+        return nativeOrSource || publishedNpx;
+    });
 }
 /**
  * Install the Claude Code AGENT hooks into `.claude/settings.json` so the agent

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
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.20.3",
+  "version": "1.21.1",
   "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",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.20.3",
+  "version": "1.21.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.20.3",
+      "version": "1.21.1",
       "runtimeHint": "npx",
       "packageArguments": [
         {