npm - @davesheffer/hunch - Versions diffs - 1.20.3 → 1.21.0 - Mend

@davesheffer/hunch 1.20.3 → 1.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md +3 -3
package/dist/cli/dna.js +116 -0
package/dist/cli/index.js +111 -0
package/dist/core/projectDna.js +478 -0
package/dist/core/projectDnaDelivery.js +54 -0
package/dist/core/projectDnaDelta.js +159 -0
package/dist/mcp/server.js +161 -8
package/dist/projectDna.js +10 -0
package/package.json +9 -1
package/server.json +2 -2

package/README.md CHANGED Viewed

@@ -174,7 +174,7 @@ repository, separate from the code repository. Hunch does not host it. Create a
 that every teammate can access, install Hunch on team machines and CI, then have one maintainer run:
 ```bash
-npm i -g @davesheffer/hunch@1.20.3
+npm i -g @davesheffer/hunch@1.21.0
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -189,7 +189,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 ```bash
-npm i -g @davesheffer/hunch@1.20.3
+npm i -g @davesheffer/hunch@1.21.0
 git pull
 hunch init
 hunch doctor
@@ -237,7 +237,7 @@ but stops automatic memory commits and pushes. As a team-coordinated rollback, r
 commit to stop discovery after teammates pull the revert. Existing machines retain their ignored
 local overlay until they are deliberately disconnected; do not delete the memory repo as part of a
 rollback. For this rollout, reinstall the previous published package with
-`npm i -g @davesheffer/hunch@1.20.2`; the release receipt resolves and records the verified rollback
+`npm i -g @davesheffer/hunch@1.20.3`; the release receipt resolves and records the verified rollback
 target from the npm registry instead of trusting Git tags. Pause enforcement first as shown above,
 and keep every team client on the same release before resuming Matrix policy workflows.

package/dist/cli/dna.js ADDED Viewed

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { Command } from "commander";
+import { discoverProjectDna, evaluateProjectDnaMatch } from "../core/projectDna.js";
+import { diffProjectDna } from "../core/projectDnaDelta.js";
+import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
+function gitRoot() {
+    try {
+        return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 5_000,
+        }).trim();
+    }
+    catch {
+        throw new Error("Project DNA must run inside a Git repository");
+    }
+}
+function printProfile(root, revision, json) {
+    const profile = discoverProjectDna(root, revision);
+    if (json) {
+        process.stdout.write(`${JSON.stringify(profile, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`Project DNA ${profile.profile_id}\n`);
+    process.stdout.write(`revision: ${profile.repository_revision}\n`);
+    process.stdout.write(`history sample: ${profile.history_sample_count}\n`);
+    process.stdout.write(`committed convention files: ${profile.source_files.length ? profile.source_files.join(", ") : "none"}\n`);
+    if (!profile.traits.length) {
+        process.stdout.write("traits: none yet (insufficient evidence)\n");
+        return;
+    }
+    for (const trait of profile.traits) {
+        process.stdout.write(`- [${trait.category}] ${trait.claim} (${trait.confidence.toFixed(2)}; ${trait.id})\n`);
+    }
+}
+const program = new Command();
+program
+    .name("hunch-dna")
+    .description("Derive and inspect Hunch Project DNA from exact committed repository evidence.")
+    .option("--revision <ref>", "Git revision to inspect", "HEAD")
+    .option("--json", "emit the sealed machine-readable profile")
+    .action((options) => {
+    printProfile(gitRoot(), options.revision, !!options.json);
+});
+program
+    .command("match")
+    .description("Score a commit/PR/issue/message against deterministic applicable DNA traits.")
+    .requiredOption("--kind <kind>", "commit | pull_request | issue | message")
+    .requiredOption("--title <title>", "artifact title/subject")
+    .option("--body <body>", "artifact body")
+    .option("--revision <ref>", "Git revision whose DNA applies", "HEAD")
+    .option("--json", "emit the sealed match contract")
+    .action((options) => {
+    if (!(new Set(["commit", "pull_request", "issue", "message"])).has(options.kind)) {
+        throw new Error("--kind must be commit, pull_request, issue, or message");
+    }
+    const artifact = {
+        kind: options.kind,
+        title: options.title,
+        ...(options.body !== undefined ? { body: options.body } : {}),
+    };
+    const globals = program.opts();
+    const revision = options.revision ?? globals.revision ?? "HEAD";
+    const json = options.json ?? globals.json ?? false;
+    const profile = discoverProjectDna(gitRoot(), revision);
+    const match = evaluateProjectDnaMatch(profile, artifact);
+    if (json)
+        process.stdout.write(`${JSON.stringify(match, null, 2)}\n`);
+    else {
+        process.stdout.write(`Project DNA match: ${match.score === null ? "n/a" : `${match.score}%`} (${match.applicable_checks} applicable checks)\n`);
+        for (const check of match.checks.filter((item) => item.applicable)) {
+            process.stdout.write(`- ${check.passed ? "PASS" : "FAIL"} ${check.key}: ${check.detail}\n`);
+        }
+    }
+});
+program
+    .command("context")
+    .description("Render the bounded advisory DNA supplement intended for Hunch delivery/context assembly.")
+    .option("--revision <ref>", "Git revision to inspect", "HEAD")
+    .option("--traits <count>", "maximum DNA traits in the orientation slice", "8")
+    .option("--json", "emit supplement JSON")
+    .action((options) => {
+    const globals = program.opts();
+    const revision = options.revision ?? globals.revision ?? "HEAD";
+    const json = options.json ?? globals.json ?? false;
+    const cap = Number(options.traits);
+    const supplement = projectDnaDeliverySupplement(discoverProjectDna(gitRoot(), revision), cap);
+    if (json)
+        process.stdout.write(`${JSON.stringify(supplement, null, 2)}\n`);
+    else
+        process.stdout.write(`${supplement?.text ?? "No evidence-backed Project DNA traits yet."}\n`);
+});
+program
+    .command("diff")
+    .description("Compare DNA at two exact revisions; reports observation drift without inferring causality.")
+    .argument("<from>", "older Git revision")
+    .argument("<to>", "newer Git revision")
+    .option("--json", "emit the sealed delta contract")
+    .action((from, to, options) => {
+    const root = gitRoot();
+    const delta = diffProjectDna(discoverProjectDna(root, from), discoverProjectDna(root, to));
+    const json = options.json ?? program.opts().json ?? false;
+    if (json)
+        process.stdout.write(`${JSON.stringify(delta, null, 2)}\n`);
+    else {
+        process.stdout.write(`Project DNA drift ${delta.delta_id}: ${delta.changed ? `${delta.changes.length} change(s)` : "no observed change"}\n`);
+        for (const change of delta.changes)
+            process.stdout.write(`- ${change.kind}: ${change.key}\n`);
+    }
+});
+program.parseAsync().catch((error) => {
+    process.stderr.write(`hunch-dna: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=dna.js.map

package/dist/cli/index.js CHANGED Viewed

@@ -57,6 +57,9 @@ import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/e
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
 import { buildDeliveryEnvelope, DELIVERY_PROFILES } from "../core/delivery.js";
 import { deriveChangeIdentity } from "../core/changeIdentity.js";
+import { discoverProjectDna, evaluateProjectDnaMatch } from "../core/projectDna.js";
+import { diffProjectDna } from "../core/projectDnaDelta.js";
+import { projectDnaDeliverySupplement } from "../core/projectDnaDelivery.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { isHumanConfirmed } from "../core/strictgate.js";
@@ -2903,6 +2906,114 @@ landscapeCmd
     console.log(`  hunch landscape adopt --ref ${discovery.sourceRevision} --expected ${discovery.discoveryHash} --all --reviewed-by <you>${discovery.issues.length ? " --acknowledge-issues" : ""}`);
     console.log("Or pass --candidate <hash...> to adopt an explicit subset; relationships require both endpoint resources.");
 });
+// ---- dna (read-only, exact-revision repository convention profile) -------
+const dnaCmd = program
+    .command("dna")
+    .description("Inspect evidence-backed Project DNA and evaluate repository-native artifacts without writing graph authority.");
+dnaCmd
+    .command("inspect")
+    .description("Derive a deterministic Project DNA profile from one exact Git revision. This command never writes memory.")
+    .option("--ref <ref>", "Git commit/ref to inspect", "HEAD")
+    .option("--json", "emit the complete machine-readable profile")
+    .action((opts) => {
+    try {
+        const profile = discoverProjectDna(findRoot(), opts.ref);
+        if (opts.json) {
+            console.log(JSON.stringify(profile, null, 2));
+            return;
+        }
+        console.log(`Project DNA at ${profile.repository_revision}`);
+        console.log(`Profile: ${profile.profile_id} (${profile.content_hash})`);
+        console.log(`Evidence: ${profile.history_sample_count} commit subject(s), ${profile.source_files.length} convention file(s)`);
+        if (profile.source_files.length)
+            console.log(`Sources: ${profile.source_files.join(", ")}`);
+        console.log(`\nTRAITS (${profile.traits.length})`);
+        for (const trait of profile.traits) {
+            console.log(`  ${trait.id}  [${trait.category}/${trait.confidence.toFixed(3)}] ${trait.claim}`);
+            console.log(`    ${trait.evidence.map((evidence) => `${evidence.ref} @ ${evidence.revision.slice(0, 12)} (${evidence.content_hash})`).join("; ")}`);
+        }
+        console.log("\nAdvisory observation only; no trait was adopted into graph authority.");
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+});
+dnaCmd
+    .command("match")
+    .description("Explainably score a commit, PR, issue, or message against deterministic checks in an exact-revision DNA profile.")
+    .requiredOption("--kind <kind>", "artifact kind: commit, pull_request, issue, or message")
+    .requiredOption("--title <title>", "artifact title or commit subject")
+    .option("--body <body>", "artifact body (for example a PR description)")
+    .option("--ref <ref>", "Git commit/ref whose DNA should be used", "HEAD")
+    .option("--json", "emit the complete machine-readable match envelope")
+    .action((opts) => {
+    try {
+        if (!["commit", "pull_request", "issue", "message"].includes(opts.kind)) {
+            return fail("--kind must be commit, pull_request, issue, or message");
+        }
+        const profile = discoverProjectDna(findRoot(), opts.ref);
+        const match = evaluateProjectDnaMatch(profile, {
+            kind: opts.kind,
+            title: opts.title,
+            body: opts.body,
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(match, null, 2));
+            return;
+        }
+        console.log(`Project Match: ${match.score === null ? "not enough deterministic checks" : `${match.score.toFixed(1)}/100`}`);
+        console.log(`Profile: ${match.profile_id} @ ${match.repository_revision}`);
+        for (const check of match.checks.filter((candidate) => candidate.applicable)) {
+            console.log(`  ${check.passed ? "PASS" : "FAIL"}  ${check.key} — ${check.detail}`);
+        }
+        console.log("Advisory only; the score does not grant or change enforcement authority.");
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+});
+dnaCmd
+    .command("context")
+    .description("Render the bounded advisory Project DNA supplement used by normal Hunch context delivery.")
+    .option("--ref <ref>", "Git commit/ref to inspect", "HEAD")
+    .option("--traits <count>", "maximum traits in the orientation slice", "8")
+    .option("--json", "emit the complete machine-readable supplement")
+    .action((opts) => {
+    try {
+        const traitCap = Number(opts.traits);
+        const supplement = projectDnaDeliverySupplement(discoverProjectDna(findRoot(), opts.ref), traitCap);
+        if (opts.json)
+            console.log(JSON.stringify(supplement, null, 2));
+        else
+            console.log(supplement?.text ?? "No evidence-backed Project DNA traits yet.");
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+});
+dnaCmd
+    .command("diff")
+    .description("Compare two exact-revision DNA profiles without rewriting either snapshot.")
+    .argument("<from>", "older Git revision")
+    .argument("<to>", "newer Git revision")
+    .option("--json", "emit the complete sealed delta")
+    .action((from, to, opts) => {
+    try {
+        const root = findRoot();
+        const delta = diffProjectDna(discoverProjectDna(root, from), discoverProjectDna(root, to));
+        if (opts.json) {
+            console.log(JSON.stringify(delta, null, 2));
+            return;
+        }
+        console.log(`Project DNA drift ${delta.delta_id}: ${delta.changed ? `${delta.changes.length} change(s)` : "no observed change"}`);
+        for (const change of delta.changes)
+            console.log(`  ${change.kind}  ${change.key}`);
+        console.log("Observation only; no Project DNA profile or graph authority was rewritten.");
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+});
 landscapeCmd
     .command("adopt")
     .description("Human-confirm a reviewed candidate set and write only those exact records through Hunch's normal graph boundary.")

package/dist/core/projectDna.js ADDED Viewed

@@ -0,0 +1,478 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { compareCodeUnits } from "./canonicalOrder.js";
+export const PROJECT_DNA_SCHEMA_VERSION = "hunch.project-dna/1";
+export const PROJECT_DNA_MATCH_SCHEMA_VERSION = "hunch.project-dna-match/1";
+const GIT_OBJECT = /^[a-f0-9]{40,64}$/;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const PROFILE_ID = /^pdna_[a-f0-9]{24}$/;
+const REPOSITORY_ID = /^pdnar_[a-f0-9]{24}$/;
+const MATCH_ID = /^pdnam_[a-f0-9]{24}$/;
+const MAX_GIT_OUTPUT = 8 * 1024 * 1024;
+const MAX_HISTORY = 200;
+const MIN_HISTORY = 5;
+const MAX_EVIDENCE = 8;
+const MAX_TRAITS = 64;
+const MAX_FILE_BYTES = 256 * 1024;
+export const PROJECT_DNA_CATEGORIES = ["communication", "engineering", "review", "culture", "vocabulary"];
+const STOP_WORDS = new Set([
+    "a", "an", "and", "are", "as", "at", "be", "by", "for", "from", "in", "into", "is", "it", "of", "on",
+    "or", "that", "the", "this", "to", "with", "without", "add", "adds", "added", "fix", "fixes", "fixed",
+    "update", "updates", "updated", "change", "changes", "changed", "remove", "removes", "removed", "merge",
+]);
+const SOURCE_FILES = [
+    "CONTRIBUTING.md",
+    ".github/CONTRIBUTING.md",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/pull_request_template.md",
+    "PULL_REQUEST_TEMPLATE.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+];
+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 gitEnvironment() {
+    const environment = { ...process.env, GIT_NO_REPLACE_OBJECTS: "1", LC_ALL: "C", LANG: "C" };
+    for (const name of [
+        "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT",
+        "GIT_OBJECT_DIRECTORY", "GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE",
+        "GIT_INDEX_FILE", "GIT_REPLACE_REF_BASE", "GIT_PREFIX", "GIT_INTERNAL_SUPER_PREFIX",
+        "GIT_SHALLOW_FILE", "GIT_COMMON_DIR",
+    ])
+        delete environment[name];
+    for (const name of Object.keys(environment)) {
+        if (/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(name))
+            delete environment[name];
+    }
+    return environment;
+}
+function gitBytes(root, args, maxBuffer = MAX_GIT_OUTPUT) {
+    try {
+        return execFileSync("git", ["-C", root, ...args], {
+            encoding: "buffer",
+            env: gitEnvironment(),
+            maxBuffer,
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 15_000,
+        });
+    }
+    catch (error) {
+        const stderr = error.stderr?.toString("utf8").trim().replace(/[\r\n]+/g, " ");
+        throw new Error(`could not inspect repository DNA${stderr ? `: ${stderr.slice(0, 500)}` : ""}`);
+    }
+}
+function gitText(root, args) {
+    return gitBytes(root, args).toString("utf8").trim();
+}
+function exactCommit(root, ref) {
+    if (!ref.trim() || /[\0\r\n]/.test(ref) || ref.length > 1_024)
+        throw new Error("Git revision is invalid");
+    const revision = gitText(root, ["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`]);
+    if (!GIT_OBJECT.test(revision))
+        throw new Error("Git did not return an exact commit object");
+    return revision;
+}
+function committedFile(root, revision, path) {
+    const type = execFileSync("git", ["-C", root, "cat-file", "-t", `${revision}:${path}`], {
+        encoding: "utf8",
+        env: gitEnvironment(),
+        maxBuffer: 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 5_000,
+    }).trim();
+    if (type !== "blob")
+        return null;
+    const sizeText = gitText(root, ["cat-file", "-s", `${revision}:${path}`]);
+    const size = Number(sizeText);
+    if (!Number.isSafeInteger(size) || size < 0 || size > MAX_FILE_BYTES)
+        return null;
+    const bytes = gitBytes(root, ["show", `${revision}:${path}`], MAX_FILE_BYTES + 1);
+    if (bytes.byteLength !== size || bytes.includes(0))
+        return null;
+    return bytes;
+}
+function tryCommittedFile(root, revision, path) {
+    try {
+        return committedFile(root, revision, path);
+    }
+    catch {
+        return null;
+    }
+}
+function confidence(ratio, sampleCount, floor = 0.6) {
+    const boundedRatio = Math.max(0, Math.min(1, ratio));
+    const sampleFactor = Math.min(1, sampleCount / 30);
+    return Number(Math.max(floor, boundedRatio * (0.75 + 0.25 * sampleFactor)).toFixed(3));
+}
+function traitId(category, key, claim) {
+    return `pdnat_${sha256(canonical({ category, key, claim })).slice("sha256:".length, "sha256:".length + 20)}`;
+}
+function makeTrait(category, key, claim, confidenceValue, evidence) {
+    return {
+        id: traitId(category, key, claim),
+        category,
+        key,
+        claim,
+        confidence: Number(Math.max(0, Math.min(1, confidenceValue)).toFixed(3)),
+        observation_state: "observed",
+        freshness: "current",
+        contradiction: "none",
+        evidence: [...evidence].sort((left, right) => compareCodeUnits(left.ref, right.ref)).slice(0, MAX_EVIDENCE),
+    };
+}
+function historyEvidence(revision, subjects) {
+    return {
+        kind: "git-history",
+        ref: `git:subjects:${subjects.length}`,
+        revision,
+        content_hash: sha256(subjects.join("\0")),
+        sample_count: subjects.length,
+        provenance: "committed-repository",
+        visibility: "repository",
+    };
+}
+function fileEvidence(revision, path, bytes) {
+    return {
+        kind: "committed-file",
+        ref: path,
+        revision,
+        content_hash: sha256(bytes),
+        sample_count: 1,
+        provenance: "committed-repository",
+        visibility: "repository",
+    };
+}
+function repositoryId(root, revision) {
+    const roots = gitText(root, ["rev-list", "--max-parents=0", revision, "--"])
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean)
+        .sort(compareCodeUnits);
+    if (!roots.length || roots.some((value) => !GIT_OBJECT.test(value))) {
+        throw new Error("Git did not return a stable repository lineage identity");
+    }
+    return `pdnar_${sha256(canonical({ roots })).slice("sha256:".length, "sha256:".length + 24)}`;
+}
+function firstAlphabetic(value) {
+    const match = value.match(/[A-Za-z]/);
+    return match?.[0] ?? null;
+}
+function conventionalSubject(subject) {
+    return /^(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(?:\([^)\r\n]{1,80}\))?!?:\s\S/.test(subject);
+}
+function collectHistoryTraits(revision, subjects) {
+    if (subjects.length < MIN_HISTORY)
+        return [];
+    const evidence = [historyEvidence(revision, subjects)];
+    const traits = [];
+    const count = subjects.length;
+    const conventional = subjects.filter(conventionalSubject).length;
+    const noTerminalPeriod = subjects.filter((subject) => !/[.!?]$/.test(subject.trim())).length;
+    const lowercase = subjects.filter((subject) => {
+        const first = firstAlphabetic(subject.replace(/^(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(?:\([^)]+\))?!?:\s*/, ""));
+        return first !== null && first === first.toLowerCase();
+    }).length;
+    const issueRefs = subjects.filter((subject) => /(?:^|\s)#\d+\b/.test(subject)).length;
+    if (conventional / count >= 0.7) {
+        traits.push(makeTrait("communication", "commit.conventional", "Commit subjects usually use Conventional Commit prefixes.", confidence(conventional / count, count), evidence));
+    }
+    if (noTerminalPeriod / count >= 0.8) {
+        traits.push(makeTrait("communication", "subject.no_terminal_punctuation", "Change titles usually omit terminal punctuation.", confidence(noTerminalPeriod / count, count), evidence));
+    }
+    if (lowercase / count >= 0.7) {
+        traits.push(makeTrait("communication", "subject.lowercase_lead", "Change titles usually begin their descriptive phrase with lowercase wording.", confidence(lowercase / count, count), evidence));
+    }
+    if (issueRefs / count >= 0.45) {
+        traits.push(makeTrait("communication", "subject.issue_reference", "Change titles frequently reference a GitHub issue number.", confidence(issueRefs / count, count), evidence));
+    }
+    const words = new Map();
+    for (const subject of subjects) {
+        const normalized = subject
+            .replace(/^(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(?:\([^)]+\))?!?:\s*/, "")
+            .toLowerCase();
+        for (const token of normalized.match(/[a-z][a-z0-9_-]{2,30}/g) ?? []) {
+            if (STOP_WORDS.has(token) || /^\d+$/.test(token))
+                continue;
+            words.set(token, (words.get(token) ?? 0) + 1);
+        }
+    }
+    const vocabulary = [...words.entries()]
+        .filter(([, occurrences]) => occurrences >= Math.max(3, Math.ceil(count * 0.08)))
+        .sort((left, right) => right[1] - left[1] || compareCodeUnits(left[0], right[0]))
+        .slice(0, 8);
+    for (const [word, occurrences] of vocabulary) {
+        traits.push(makeTrait("vocabulary", `term.${word}`, `The repository repeatedly uses the term “${word}” in change titles.`, confidence(occurrences / count, count, 0.55), evidence));
+    }
+    return traits;
+}
+const FILE_RULES = [
+    {
+        category: "review",
+        key: "review.tests_expected",
+        claim: "Contributions are expected to include or update tests when behavior changes.",
+        pattern: /(?:must|required|please|should|ensure|include|add|write)[^\n.]{0,80}\btests?\b|\btests?\b[^\n.]{0,80}(?:must|required|should|expected)/i,
+    },
+    {
+        category: "review",
+        key: "review.focused_changes",
+        claim: "Contributions are expected to stay focused and avoid unrelated changes.",
+        pattern: /\b(?:small|focused|narrow|scoped)\b[^\n.]{0,60}\b(?:pull request|pr|change|commit)s?\b|\b(?:unrelated|drive-by)\b[^\n.]{0,60}\b(?:change|cleanup|refactor)s?\b/i,
+    },
+    {
+        category: "culture",
+        key: "culture.backward_compatibility",
+        claim: "Backward compatibility is an explicit project concern.",
+        pattern: /\bbackward(?:s)?[- ]compatib|\bbreaking change\b|\bpublic api\b[^\n.]{0,60}\bcompatib/i,
+    },
+    {
+        category: "engineering",
+        key: "engineering.documentation_expected",
+        claim: "User-visible or public-facing changes are expected to update documentation.",
+        pattern: /(?:must|required|please|should|ensure|include|update)[^\n.]{0,80}\b(?:docs?|documentation|readme|changelog)\b/i,
+    },
+    {
+        category: "communication",
+        key: "pr.explain_why",
+        claim: "Pull requests are expected to explain motivation or rationale, not only the code change.",
+        pattern: /\b(?:why|motivation|rationale|reason)\b[^\n]{0,100}\b(?:change|pull request|pr|solution|approach)\b|\bwhat and why\b/i,
+    },
+];
+function collectFileTraits(revision, files) {
+    const byKey = new Map();
+    for (const file of files) {
+        const text = file.bytes.toString("utf8");
+        for (const rule of FILE_RULES) {
+            if (!rule.pattern.test(text))
+                continue;
+            const entry = byKey.get(rule.key) ?? { rule, evidence: [] };
+            entry.evidence.push(fileEvidence(revision, file.path, file.bytes));
+            byKey.set(rule.key, entry);
+        }
+    }
+    return [...byKey.values()].map(({ rule, evidence }) => makeTrait(rule.category, rule.key, rule.claim, Math.min(0.98, 0.8 + Math.min(3, evidence.length) * 0.05), evidence));
+}
+function dedupeTraits(traits) {
+    const byKey = new Map();
+    for (const trait of traits) {
+        const existing = byKey.get(trait.key);
+        if (!existing || trait.confidence > existing.confidence)
+            byKey.set(trait.key, trait);
+    }
+    return [...byKey.values()]
+        .sort((left, right) => compareCodeUnits(`${left.category}\0${left.key}`, `${right.category}\0${right.key}`))
+        .slice(0, MAX_TRAITS);
+}
+/**
+ * Derive a deterministic repository DNA profile from one exact Git revision.
+ *
+ * This is intentionally observation, not authority: it reads bounded committed
+ * history and bounded committed convention files. It does not read the worktree,
+ * network, GitHub reviews, model output, or private user state, and it never writes
+ * into the durable Hunch graph by itself.
+ */
+export function discoverProjectDna(root, ref = "HEAD") {
+    const repositoryRevision = exactCommit(root, ref);
+    const repositoryIdentity = repositoryId(root, repositoryRevision);
+    const historyRaw = gitText(root, [
+        "log", repositoryRevision, "--no-merges", `--max-count=${MAX_HISTORY}`, "--format=%s", "--",
+    ]);
+    const subjects = historyRaw ? historyRaw.split("\n").map((value) => value.trim()).filter(Boolean) : [];
+    const files = [];
+    for (const path of SOURCE_FILES) {
+        const bytes = tryCommittedFile(root, repositoryRevision, path);
+        if (bytes)
+            files.push({ path, bytes });
+    }
+    const traits = dedupeTraits([
+        ...collectHistoryTraits(repositoryRevision, subjects),
+        ...collectFileTraits(repositoryRevision, files),
+    ]);
+    const unsigned = {
+        schema: PROJECT_DNA_SCHEMA_VERSION,
+        repository_id: repositoryIdentity,
+        repository_revision: repositoryRevision,
+        history_sample_count: subjects.length,
+        source_files: files.map((file) => file.path).sort(compareCodeUnits),
+        traits,
+    };
+    const profileId = `pdna_${sha256(canonical(unsigned)).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...unsigned, profile_id: profileId };
+    const profile = { ...sealed, content_hash: sha256(canonical(sealed)) };
+    assertProjectDnaProfile(profile);
+    return profile;
+}
+function expectedTraitFields() {
+    return ["id", "category", "key", "claim", "confidence", "observation_state", "freshness", "contradiction", "evidence"].sort(compareCodeUnits);
+}
+function assertExactFields(value, fields, label) {
+    if (Object.keys(value).sort(compareCodeUnits).join("\0") !== [...fields].sort(compareCodeUnits).join("\0")) {
+        throw new Error(`${label} fields are invalid`);
+    }
+}
+export function assertProjectDnaProfile(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("project DNA profile is invalid");
+    const profile = value;
+    assertExactFields(value, [
+        "schema", "profile_id", "repository_id", "repository_revision", "history_sample_count", "source_files", "traits", "content_hash",
+    ], "project DNA profile");
+    if (profile.schema !== PROJECT_DNA_SCHEMA_VERSION || !PROFILE_ID.test(profile.profile_id)
+        || !REPOSITORY_ID.test(profile.repository_id) || !GIT_OBJECT.test(profile.repository_revision) || !Number.isSafeInteger(profile.history_sample_count)
+        || profile.history_sample_count < 0 || profile.history_sample_count > MAX_HISTORY
+        || !Array.isArray(profile.source_files) || profile.source_files.length > SOURCE_FILES.length
+        || profile.source_files.some((path) => typeof path !== "string" || !SOURCE_FILES.includes(path))
+        || [...profile.source_files].sort(compareCodeUnits).join("\0") !== profile.source_files.join("\0")
+        || !Array.isArray(profile.traits) || profile.traits.length > MAX_TRAITS || !SHA256.test(profile.content_hash)) {
+        throw new Error("project DNA profile fields are invalid");
+    }
+    const seen = new Set();
+    for (const trait of profile.traits) {
+        if (!trait || typeof trait !== "object" || Array.isArray(trait))
+            throw new Error("project DNA trait is invalid");
+        assertExactFields(trait, expectedTraitFields(), "project DNA trait");
+        if (!/^pdnat_[a-f0-9]{20}$/.test(trait.id) || !PROJECT_DNA_CATEGORIES.includes(trait.category)
+            || !/^[a-z][a-z0-9_.-]{2,100}$/.test(trait.key) || !trait.claim.trim() || trait.claim.length > 500
+            || !Number.isFinite(trait.confidence) || trait.confidence < 0 || trait.confidence > 1
+            || trait.observation_state !== "observed" || trait.freshness !== "current" || trait.contradiction !== "none"
+            || !Array.isArray(trait.evidence) || trait.evidence.length < 1 || trait.evidence.length > MAX_EVIDENCE
+            || seen.has(trait.key)) {
+            throw new Error("project DNA trait fields are invalid");
+        }
+        seen.add(trait.key);
+        if (trait.id !== traitId(trait.category, trait.key, trait.claim))
+            throw new Error("project DNA trait identity is invalid");
+        for (const evidence of trait.evidence) {
+            if (!evidence || typeof evidence !== "object" || Array.isArray(evidence))
+                throw new Error("project DNA evidence is invalid");
+            assertExactFields(evidence, [
+                "kind", "ref", "revision", "content_hash", "sample_count", "provenance", "visibility",
+            ], "project DNA evidence");
+            if (!["git-history", "committed-file"].includes(evidence.kind) || !evidence.ref.trim() || evidence.ref.length > 512
+                || evidence.revision !== profile.repository_revision || !SHA256.test(evidence.content_hash)
+                || !Number.isSafeInteger(evidence.sample_count) || evidence.sample_count < 1 || evidence.sample_count > MAX_HISTORY
+                || evidence.provenance !== "committed-repository" || evidence.visibility !== "repository") {
+                throw new Error("project DNA evidence fields are invalid");
+            }
+        }
+    }
+    const { content_hash: _contentHash, profile_id: _profileId, ...base } = profile;
+    const expectedProfileId = `pdna_${sha256(canonical(base)).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...base, profile_id: profile.profile_id };
+    if (profile.profile_id !== expectedProfileId || profile.content_hash !== sha256(canonical(sealed))) {
+        throw new Error("project DNA profile seal is invalid");
+    }
+}
+function artifactCheck(trait, artifact) {
+    const title = artifact.title.trim();
+    const first = firstAlphabetic(title.replace(/^(?:build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(?:\([^)]+\))?!?:\s*/, ""));
+    const weight = Math.max(1, Math.round(trait.confidence * 100));
+    switch (trait.key) {
+        case "commit.conventional":
+            return artifact.kind === "commit"
+                ? { trait_id: trait.id, key: trait.key, applicable: true, passed: conventionalSubject(title), weight, detail: "Commit subject follows the repository's observed Conventional Commit pattern." }
+                : { trait_id: trait.id, key: trait.key, applicable: false, passed: null, weight, detail: "This trait applies only to commit subjects." };
+        case "subject.no_terminal_punctuation":
+            return { trait_id: trait.id, key: trait.key, applicable: true, passed: !/[.!?]$/.test(title), weight, detail: "Title omits terminal punctuation." };
+        case "subject.lowercase_lead":
+            return { trait_id: trait.id, key: trait.key, applicable: first !== null, passed: first === null ? null : first === first.toLowerCase(), weight, detail: "Descriptive title wording begins lowercase." };
+        case "subject.issue_reference":
+            return { trait_id: trait.id, key: trait.key, applicable: true, passed: /(?:^|\s)#\d+\b/.test(title), weight, detail: "Title carries an issue reference." };
+        case "pr.explain_why": {
+            const body = artifact.body?.trim() ?? "";
+            const applicable = artifact.kind === "pull_request";
+            const passed = applicable ? /\b(?:why|because|motivation|rationale|reason)\b/i.test(body) : null;
+            return { trait_id: trait.id, key: trait.key, applicable, passed, weight, detail: "PR body contains an explicit rationale signal." };
+        }
+        default:
+            return { trait_id: trait.id, key: trait.key, applicable: false, passed: null, weight, detail: "Trait is orientation-only and has no deterministic artifact check yet." };
+    }
+}
+/** Score only traits that have a deterministic check for the supplied artifact. */
+export function evaluateProjectDnaMatch(profileValue, artifact) {
+    assertProjectDnaProfile(profileValue);
+    const profile = profileValue;
+    if (!artifact || !["commit", "pull_request", "issue", "message"].includes(artifact.kind)
+        || typeof artifact.title !== "string" || artifact.title.length < 1 || artifact.title.length > 1_000
+        || (artifact.body !== undefined && (typeof artifact.body !== "string" || artifact.body.length > 20_000))) {
+        throw new Error("project DNA artifact is invalid");
+    }
+    const checks = profile.traits.map((trait) => artifactCheck(trait, artifact));
+    const applicable = checks.filter((check) => check.applicable && check.passed !== null);
+    const totalWeight = applicable.reduce((sum, check) => sum + check.weight, 0);
+    const passedWeight = applicable.reduce((sum, check) => sum + (check.passed ? check.weight : 0), 0);
+    const score = totalWeight > 0 ? Number(((passedWeight / totalWeight) * 100).toFixed(1)) : null;
+    const unsigned = {
+        schema: PROJECT_DNA_MATCH_SCHEMA_VERSION,
+        profile_id: profile.profile_id,
+        repository_id: profile.repository_id,
+        repository_revision: profile.repository_revision,
+        artifact_kind: artifact.kind,
+        score,
+        applicable_checks: applicable.length,
+        checks,
+    };
+    // The identity is derived from the public envelope, rather than from artifact
+    // bytes that are deliberately not retained. That makes a received match fully
+    // self-validating without storing PR/issue bodies in Hunch.
+    const matchId = `pdnam_${sha256(canonical(unsigned)).slice("sha256:".length, "sha256:".length + 24)}`;
+    const sealed = { ...unsigned, match_id: matchId };
+    return { ...sealed, content_hash: sha256(canonical(sealed)) };
+}
+export function assertProjectDnaMatch(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("project DNA match is invalid");
+    const match = value;
+    assertExactFields(value, [
+        "schema", "match_id", "profile_id", "repository_id", "repository_revision", "artifact_kind", "score", "applicable_checks", "checks", "content_hash",
+    ], "project DNA match");
+    if (match.schema !== PROJECT_DNA_MATCH_SCHEMA_VERSION || !MATCH_ID.test(match.match_id) || !PROFILE_ID.test(match.profile_id)
+        || !REPOSITORY_ID.test(match.repository_id) || !GIT_OBJECT.test(match.repository_revision)
+        || !["commit", "pull_request", "issue", "message"].includes(match.artifact_kind)
+        || (match.score !== null && (!Number.isFinite(match.score) || match.score < 0 || match.score > 100))
+        || !Number.isSafeInteger(match.applicable_checks) || match.applicable_checks < 0
+        || !Array.isArray(match.checks) || match.applicable_checks > match.checks.length || !SHA256.test(match.content_hash)) {
+        throw new Error("project DNA match fields are invalid");
+    }
+    const traitIds = new Set();
+    for (const check of match.checks) {
+        if (!check || typeof check !== "object" || Array.isArray(check))
+            throw new Error("project DNA match check is invalid");
+        assertExactFields(check, [
+            "trait_id", "key", "applicable", "passed", "weight", "detail",
+        ], "project DNA match check");
+        if (!/^pdnat_[a-f0-9]{20}$/.test(check.trait_id) || traitIds.has(check.trait_id)
+            || !/^[a-z][a-z0-9_.-]{2,100}$/.test(check.key)
+            || typeof check.applicable !== "boolean"
+            || !(check.passed === true || check.passed === false || check.passed === null)
+            || (check.applicable ? check.passed === null : check.passed !== null)
+            || !Number.isSafeInteger(check.weight) || check.weight < 1 || check.weight > 100
+            || typeof check.detail !== "string" || !check.detail.trim() || check.detail.length > 500) {
+            throw new Error("project DNA match check fields are invalid");
+        }
+        traitIds.add(check.trait_id);
+    }
+    const applicable = match.checks.filter((check) => check.applicable).length;
+    if (applicable !== match.applicable_checks)
+        throw new Error("project DNA match applicable count is invalid");
+    const { content_hash: _contentHash, match_id: _matchId, ...base } = match;
+    const expectedMatchId = `pdnam_${sha256(canonical(base)).slice("sha256:".length, "sha256:".length + 24)}`;
+    const unsigned = { ...base, match_id: match.match_id };
+    if (match.match_id !== expectedMatchId)
+        throw new Error("project DNA match identity is invalid");
+    if (match.content_hash !== sha256(canonical(unsigned)))
+        throw new Error("project DNA match seal is invalid");
+}
+//# sourceMappingURL=projectDna.js.map

package/dist/core/projectDnaDelivery.js ADDED Viewed

@@ -0,0 +1,54 @@
+import { compareCodeUnits } from "./canonicalOrder.js";
+import { assertProjectDnaProfile } from "./projectDna.js";
+export const PROJECT_DNA_SUPPLEMENT_KIND = "project-dna";
+const DEFAULT_TRAIT_CAP = 8;
+const MAX_TRAIT_CAP = 16;
+const CATEGORY_ORDER = {
+    communication: 0,
+    review: 1,
+    engineering: 2,
+    culture: 3,
+    vocabulary: 4,
+};
+function orderedTraits(profile) {
+    return [...profile.traits].sort((left, right) => CATEGORY_ORDER[left.category] - CATEGORY_ORDER[right.category]
+        || right.confidence - left.confidence
+        || compareCodeUnits(left.key, right.key));
+}
+/**
+ * Render Project DNA through Hunch's existing DeliverySupplement seam.
+ *
+ * The caller still owns the final hard budget via buildDeliveryEnvelope(); this
+ * function only prepares compact, evidence-identifiable orientation text. The
+ * profile ID/revision remain visible so a host can preserve provider provenance.
+ */
+export function projectDnaDeliverySupplement(profileValue, traitCap = DEFAULT_TRAIT_CAP) {
+    assertProjectDnaProfile(profileValue);
+    const profile = profileValue;
+    if (!Number.isSafeInteger(traitCap) || traitCap < 1 || traitCap > MAX_TRAIT_CAP) {
+        throw new Error(`project DNA trait cap must be an integer between 1 and ${MAX_TRAIT_CAP}`);
+    }
+    const selected = orderedTraits(profile).slice(0, traitCap);
+    if (!selected.length)
+        return null;
+    const lines = selected.map((trait) => {
+        const evidence = trait.evidence.map((item) => item.ref).slice(0, 2).join(", ");
+        return `• [${trait.category}] ${trait.claim} (${trait.confidence.toFixed(2)}; ${trait.id}; evidence: ${evidence})`;
+    });
+    const omitted = Math.max(0, profile.traits.length - selected.length);
+    const text = [
+        `PROJECT DNA — observed repository conventions (advisory, ${profile.profile_id}, revision ${profile.repository_revision})`,
+        ...lines,
+        omitted ? `• … ${omitted} lower-priority DNA trait(s) omitted from this orientation slice.` : "",
+        "Use these traits to communicate and contribute naturally. They never override Hunch decisions, constraints, policy, or current task evidence.",
+    ].filter(Boolean).join("\n");
+    return {
+        id: profile.profile_id,
+        kind: PROJECT_DNA_SUPPLEMENT_KIND,
+        text,
+        // Ranked memory and blocking invariants remain above this supplement. Hosts
+        // may lower this further, but should not raise observational DNA over authority.
+        priority: 425,
+    };
+}
+//# sourceMappingURL=projectDnaDelivery.js.map

package/dist/core/projectDnaDelta.js ADDED Viewed

@@ -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/mcp/server.js CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

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

package/server.json CHANGED Viewed

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