@davesheffer/hunch 1.20.2 → 1.21.0

package/README.md

@@ -58,6 +58,9 @@ existing configuration.
   passes, needs attention, or should be blocked.
 - **Past bugs stay useful** — see which old incident a piece of code fixed before accidentally
   undoing it.
+- **Fresh context without lost history** — decisions whose code anchors are still current rank
+  ahead of ones whose files changed after verification; older evidence remains visible and keeps
+  its existing authority.
 - **Understands how code connects** — for TypeScript, JavaScript, Python, Go, PHP, YAML, and Helm, Hunch
   can see what calls or depends on the code you are about to change. Its memory works with any
   language.
@@ -171,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.2
+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"
@@ -186,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.2
+npm i -g @davesheffer/hunch@1.21.0
 git pull
 hunch init
 hunch doctor
@@ -234,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.0`; 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

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

@@ -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";
@@ -1292,7 +1295,7 @@ program
         const emb = await selectEmbedder();
         if (!store.semanticReady(emb)) {
             console.log("· semantic search isn't enabled yet — run `hunch embed` (using keyword search for now).\n");
-            hits = store.search(q, 12);
+            hits = store.rankedSearch(q, 12);
         }
         else {
             hits = await store.hybridSearch(q, 12, { embedder: emb });
@@ -1300,7 +1303,7 @@ program
         }
     }
     else {
-        hits = store.search(q, 12);
+        hits = store.rankedSearch(q, 12);
     }
     if (!hits.length) {
         console.log(`No matches for "${q}".`);
@@ -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.")
@@ -3904,7 +4015,7 @@ program
         !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) {
             console.log(`No file/symbol resolves for "${target}" — closest graph matches instead:\n`);
             for (const h of hits)