@davesheffer/hunch 1.20.0-rc.5 → 1.20.0

package/README.md

@@ -97,6 +97,8 @@ Most memory work happens automatically after commits. These commands cover the c
 | --- | --- |
 | `hunch why <file>` | Explain why a file is built this way and what could be affected by changing it |
 | `hunch query "<question>"` | Search project memory |
+| `hunch context "<task>" --profile reviewer` | Get a bounded builder, reviewer, or architect view without changing enforcement |
+| `hunch change-id <base> [head]` | Bind a branch and its exact squash merge to the same content-based change ID |
 | `hunch check --working` | Check current changes against the decisions and rules your team trusts |
 | `hunch log` | See what Hunch remembered and undo a memory change if needed |
 | `hunch escalations` | See the rare questions that need a human answer |
@@ -169,7 +171,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.19.0
+npm i -g @davesheffer/hunch@1.20.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"
@@ -184,7 +186,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.19.0
+npm i -g @davesheffer/hunch@1.20.0
 git pull
 hunch init
 hunch doctor
@@ -232,7 +234,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.16.0`; the release receipt resolves and records the verified rollback
+`npm i -g @davesheffer/hunch@1.19.0`; 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/index.js

@@ -55,7 +55,8 @@ import { formatContext, formatStructure } from "../core/format.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, formatVerifiedEvidenceMap } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
-import { buildDeliveryEnvelope } from "../core/delivery.js";
+import { buildDeliveryEnvelope, DELIVERY_PROFILES } from "../core/delivery.js";
+import { deriveChangeIdentity } from "../core/changeIdentity.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";
@@ -3819,14 +3820,46 @@ program
         fail(`could not compile the verified evidence map: ${error.message}`);
     }
 });
+// ---- change-id (squash-stable exact delta identity) -----------------------
+program
+    .command("change-id")
+    .description("Derive an exact change identity that survives commit-message and squash metadata changes.")
+    .argument("<base>", "base commit or ref")
+    .argument("[head]", "head commit or ref", "HEAD")
+    .option("--json", "emit the complete sealed identity as JSON")
+    .action((base, head, opts) => {
+    try {
+        const identity = deriveChangeIdentity(findRoot(), base, head);
+        if (opts.json) {
+            console.log(JSON.stringify(identity, null, 2));
+        }
+        else {
+            console.log([
+                `${identity.change_id} (${identity.algorithm})`,
+                `  exact revisions: ${identity.base_revision}..${identity.head_revision}`,
+                `  exact delta: ${identity.delta_hash}`,
+                `  Git stable patch ID: ${identity.patch_id ?? "unavailable (exact Hunch identity still valid)"}`,
+                `  files: ${identity.file_count} (${identity.paths_hash})`,
+                `  sealed receipt: ${identity.content_hash}`,
+            ].join("\n"));
+        }
+    }
+    catch (error) {
+        fail(error.message);
+    }
+});
 // ---- context (surgical retrieval) -----------------------------------------
 program
     .command("context")
     .description("Assemble the minimal relevant Hunch slice for a task on a file/symbol.")
     .argument("<target>", "file path or symbol")
     .option("--budget <n>", "rough token budget", "1500")
+    .option("--profile <profile>", "delivery role: builder, reviewer, or architect", "builder")
     .option("--as-of <ref>", "time-travel: assemble the slice as it stood at a commit/tag/branch")
     .action(async (target, opts) => {
+    if (!DELIVERY_PROFILES.includes(opts.profile)) {
+        return fail(`--profile must be one of: ${DELIVERY_PROFILES.join(", ")}`);
+    }
     const { store, root } = storeFor();
     const asOf = opts.asOf ? asOfDate(opts.asOf, root) : undefined;
     if (opts.asOf && !asOf)
@@ -3861,6 +3894,7 @@ program
         components: store.recs("components"),
         decisionCorpus: store.recs("decisions"),
         historical: !!asOf,
+        profile: opts.profile,
     }));
     store.close();
 });
@@ -4464,6 +4498,7 @@ program
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
         const envelope = buildDeliveryEnvelope(ctx, {
+            profile: "builder",
             root,
             symbols: store.recs("symbols"),
             components: store.recs("components"),
@@ -4495,6 +4530,8 @@ program
             delivery_reason: item.delivery_reason,
             provenance_status: item.provenance_status,
             token_cost: item.token_cost,
+            delivery_profile: envelope.profile,
+            ranking_policy: envelope.ranking_policy,
         })));
         if (injectionMode(evt.session_id, `pre:${target}`, text) === "delta") {
             receipts("refreshed");

package/dist/core/changeIdentity.js

@@ -0,0 +1,192 @@
+/**
+ * Commit-metadata-independent identity for one exact repository change.
+ *
+ * The identity hashes Git's raw tree delta (modes, paths and blob object IDs),
+ * not a commit SHA or prose diff. A branch range and its squash commit therefore
+ * share one change ID when they produce the same exact tree transition. Unlike
+ * `git patch-id`, whitespace-only, binary and mode changes remain significant.
+ */
+import { execFileSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { compareCodeUnits } from "./canonicalOrder.js";
+export const CHANGE_IDENTITY_SCHEMA_VERSION = "hunch.change-identity/1";
+export const CHANGE_IDENTITY_ALGORITHM = "git-raw-tree-delta-sha256/1";
+const GIT_OBJECT = /^[a-f0-9]{40,64}$/;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const CHANGE_ID = /^hchg_[a-f0-9]{24}$/;
+const MAX_GIT_OUTPUT = 64 * 1024 * 1024;
+const MAX_CHANGED_FILES = 16_384;
+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 gitText(root, args, input) {
+    try {
+        return execFileSync("git", ["-C", root, ...args], {
+            encoding: "utf8",
+            env: gitEnvironment(),
+            input,
+            maxBuffer: MAX_GIT_OUTPUT,
+            stdio: [input ? "pipe" : "ignore", "pipe", "pipe"],
+            timeout: 15_000,
+        }).trim();
+    }
+    catch (error) {
+        const stderr = error.stderr?.toString("utf8").trim().replace(/[\r\n]+/g, " ");
+        throw new Error(`could not derive exact Git change identity${stderr ? `: ${stderr.slice(0, 500)}` : ""}`);
+    }
+}
+function gitBytes(root, args) {
+    try {
+        return execFileSync("git", ["-C", root, ...args], {
+            encoding: "buffer",
+            env: gitEnvironment(),
+            maxBuffer: MAX_GIT_OUTPUT,
+            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 derive exact Git change identity${stderr ? `: ${stderr.slice(0, 500)}` : ""}`);
+    }
+}
+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 patchId(root, base, head) {
+    const diff = gitBytes(root, [
+        "diff", "--binary", "--full-index", "--no-renames", "--no-ext-diff", "--no-textconv",
+        base, head, "--",
+    ]);
+    const result = spawnSync("git", ["patch-id", "--stable"], {
+        cwd: root,
+        env: gitEnvironment(),
+        input: diff,
+        encoding: "utf8",
+        maxBuffer: MAX_GIT_OUTPUT,
+        timeout: 15_000,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    if (result.error || result.status !== 0)
+        throw new Error("could not derive interoperable Git patch ID");
+    const value = result.stdout.trim().split(/\s+/)[0] ?? "";
+    if (!value)
+        return null;
+    if (!GIT_OBJECT.test(value))
+        throw new Error("Git returned an invalid patch ID");
+    return value;
+}
+/** Derive one deterministic receipt from two commit-ish references. */
+export function deriveChangeIdentity(root, baseRef, headRef = "HEAD") {
+    const baseRevision = exactCommit(root, baseRef);
+    const headRevision = exactCommit(root, headRef);
+    const baseTree = gitText(root, ["rev-parse", "--verify", `${baseRevision}^{tree}`]);
+    const headTree = gitText(root, ["rev-parse", "--verify", `${headRevision}^{tree}`]);
+    if (!GIT_OBJECT.test(baseTree) || !GIT_OBJECT.test(headTree))
+        throw new Error("Git tree identity is invalid");
+    const rawDelta = gitBytes(root, [
+        "diff-tree", "--no-commit-id", "--raw", "--full-index", "-r", "-z", "--no-renames",
+        baseRevision, headRevision, "--",
+    ]);
+    if (rawDelta.byteLength === 0)
+        throw new Error("exact Git change is empty");
+    const rawPaths = gitBytes(root, ["diff", "--name-only", "-z", "--no-renames", baseRevision, headRevision, "--"]);
+    const pathLengths = [];
+    let start = 0;
+    for (let index = 0; index < rawPaths.length; index++) {
+        if (rawPaths[index] !== 0)
+            continue;
+        pathLengths.push(index - start);
+        start = index + 1;
+    }
+    if (!rawPaths.length || rawPaths[rawPaths.length - 1] !== 0 || start !== rawPaths.length
+        || !pathLengths.length || pathLengths.length > MAX_CHANGED_FILES
+        || pathLengths.some((length) => length < 1 || length > 4_096)) {
+        throw new Error("exact Git change has an invalid or unbounded file set");
+    }
+    const deltaHash = sha256(rawDelta);
+    const changeSeed = canonical({ algorithm: CHANGE_IDENTITY_ALGORITHM, delta_hash: deltaHash });
+    const changeId = `hchg_${sha256(changeSeed).slice("sha256:".length, "sha256:".length + 24)}`;
+    const unsigned = {
+        schema: CHANGE_IDENTITY_SCHEMA_VERSION,
+        algorithm: CHANGE_IDENTITY_ALGORITHM,
+        change_id: changeId,
+        base_revision: baseRevision,
+        head_revision: headRevision,
+        base_tree: baseTree,
+        head_tree: headTree,
+        delta_hash: deltaHash,
+        patch_id: patchId(root, baseRevision, headRevision),
+        file_count: pathLengths.length,
+        paths_hash: sha256(rawPaths),
+    };
+    const identity = { ...unsigned, content_hash: sha256(canonical(unsigned)) };
+    assertChangeIdentity(identity);
+    return identity;
+}
+/** Validate an identity without trusting any caller-supplied seal. */
+export function assertChangeIdentity(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("change identity is invalid");
+    const identity = value;
+    const expectedFields = [
+        "schema", "algorithm", "change_id", "base_revision", "head_revision", "base_tree", "head_tree",
+        "delta_hash", "patch_id", "file_count", "paths_hash", "content_hash",
+    ];
+    if (Object.keys(value).sort(compareCodeUnits).join("\0") !== expectedFields.sort(compareCodeUnits).join("\0")
+        || identity.schema !== CHANGE_IDENTITY_SCHEMA_VERSION || identity.algorithm !== CHANGE_IDENTITY_ALGORITHM
+        || !CHANGE_ID.test(identity.change_id) || !GIT_OBJECT.test(identity.base_revision)
+        || !GIT_OBJECT.test(identity.head_revision) || !GIT_OBJECT.test(identity.base_tree)
+        || !GIT_OBJECT.test(identity.head_tree) || !SHA256.test(identity.delta_hash)
+        || (identity.patch_id !== null && !GIT_OBJECT.test(identity.patch_id))
+        || !Number.isSafeInteger(identity.file_count) || identity.file_count < 1 || identity.file_count > MAX_CHANGED_FILES
+        || !SHA256.test(identity.paths_hash) || !SHA256.test(identity.content_hash)) {
+        throw new Error("change identity fields are invalid");
+    }
+    const expectedChange = `hchg_${sha256(canonical({ algorithm: identity.algorithm, delta_hash: identity.delta_hash }))
+        .slice("sha256:".length, "sha256:".length + 24)}`;
+    const { content_hash: _contentHash, ...unsigned } = identity;
+    if (identity.change_id !== expectedChange || identity.content_hash !== sha256(canonical(unsigned))) {
+        throw new Error("change identity seal is invalid");
+    }
+}
+export function changesAreEquivalent(left, right) {
+    assertChangeIdentity(left);
+    assertChangeIdentity(right);
+    return left.algorithm === right.algorithm
+        && left.change_id === right.change_id
+        && left.delta_hash === right.delta_hash;
+}
+//# sourceMappingURL=changeIdentity.js.map

package/dist/core/delivery.js

@@ -14,10 +14,39 @@ import { toPosixTarget } from "./paths.js";
 import { renderGrounding } from "./topics.js";
 import { LANDSCAPE_FRAGMENT_SCHEMA_VERSION, assertLandscapeDeliveryFragment, createLandscapeDeliveryFragment, landscapeFragmentHash, } from "./landscapeDelivery.js";
 export const DELIVERY_ENVELOPE_SCHEMA_VERSION = "hunch.delivery-envelope/1";
+export const DELIVERY_PROFILE_POLICY_VERSION = "hunch.delivery-profile/1";
+export const DELIVERY_PROFILES = ["builder", "reviewer", "architect"];
 const SEVERITY = { advisory: 1, warning: 2, blocking: 3, low: 1, medium: 2, high: 3, critical: 4 };
 const MIN_ADVISORY_CONFIDENCE = 0.5;
 const MIN_UNCONDITIONED_CONFIDENCE = 0.7;
 const MAX_ACTIONABLE_HYPOTHESES = 2;
+const MAX_PROFILE_HEADLINES = 8;
+const PROFILE_BASE_SCORE = {
+    builder: {
+        constraints: 900,
+        decisions: 800,
+        bugs: 750,
+        findings: 650,
+        resources: 550,
+        relationships: 525,
+    },
+    reviewer: {
+        constraints: 800,
+        decisions: 750,
+        bugs: 900,
+        findings: 850,
+        resources: 550,
+        relationships: 525,
+    },
+    architect: {
+        constraints: 800,
+        decisions: 900,
+        bugs: 650,
+        findings: 600,
+        resources: 850,
+        relationships: 825,
+    },
+};
 const TASK_STOP_WORDS = new Set([
     "a", "an", "and", "are", "as", "at", "be", "been", "but", "by", "can", "does", "for", "from",
     "has", "have", "in", "into", "is", "it", "its", "of", "on", "or", "that", "the", "this", "to",
@@ -379,6 +408,10 @@ export function assertDeliveryEnvelope(envelope) {
     }
     if (!/^hdr_[a-f0-9]{24}$/.test(envelope.receipt_id))
         throw new Error("delivery envelope receipt id is invalid");
+    if (!DELIVERY_PROFILES.includes(envelope.profile)
+        || envelope.ranking_policy !== DELIVERY_PROFILE_POLICY_VERSION) {
+        throw new Error("delivery envelope profile policy is unsupported");
+    }
     if (!Number.isSafeInteger(envelope.budget_tokens) || envelope.budget_tokens < 0
         || !Number.isSafeInteger(envelope.used_chars) || envelope.used_chars !== charCount(envelope.text)
         || !Number.isSafeInteger(envelope.accounted_chars) || envelope.accounted_chars < envelope.used_chars) {
@@ -426,6 +459,7 @@ export function assertDeliveryEnvelope(envelope) {
 }
 /** Build the one envelope used by CLI, MCP, and the edit hook. */
 export function buildDeliveryEnvelope(ctx, options = {}) {
+    const profile = options.profile ?? "builder";
     const budget = Number.isFinite(ctx.budget_tokens) ? Math.max(0, Math.floor(ctx.budget_tokens)) : 1500;
     const cap = budget * 4;
     const reachability = options.commitReachability
@@ -439,7 +473,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         candidates.push({
             ref: { kind: "constraints", record_id: constraint.id },
             mandatory: !retired && constraint.severity === "blocking",
-            score: 900 + SEVERITY[constraint.severity] * 10 + (constraint.provenance.confidence ?? 0),
+            score: PROFILE_BASE_SCORE[profile].constraints + SEVERITY[constraint.severity] * 10 + (constraint.provenance.confidence ?? 0),
             provenance: validation.state,
             staleDetail: validation.detail,
             retiredDetail: retired ? "constraint is retired at HEAD" : undefined,
@@ -459,7 +493,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         candidates.push({
             ref: { kind: "decisions", record_id: decision.id },
             mandatory: false,
-            score: 700 + (decision.status === "accepted" ? 20 : 0) + (decision.provenance.confidence ?? 0),
+            score: PROFILE_BASE_SCORE[profile].decisions + (decision.status === "accepted" ? 20 : 0) + (decision.provenance.confidence ?? 0),
             provenance: validation.state,
             staleDetail: validation.detail,
             retiredDetail: retired ? `decision is ${decision.status} at HEAD` : undefined,
@@ -480,7 +514,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         candidates.push({
             ref: { kind: "bugs", record_id: bug.id },
             mandatory: false,
-            score: 800 + SEVERITY[bug.severity] * 10 + (bug.status === "open" || bug.status === "regressed" ? 10 : 0),
+            score: PROFILE_BASE_SCORE[profile].bugs + SEVERITY[bug.severity] * 10 + (bug.status === "open" || bug.status === "regressed" ? 10 : 0),
             provenance: validation.state,
             staleDetail: validation.detail,
             line: `${bug.id} | bug/${bug.status}/${bug.severity} | ${clipHeadline(`${bug.title} — root cause: ${bug.root_cause}`, 220)} | ${sourceTier(bug.provenance.source)}/${validation.state} | hunch_why("${bug.id}")`,
@@ -495,7 +529,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         candidates.push({
             ref: { kind: "findings", record_id: finding.id },
             mandatory: false,
-            score: 600 + SEVERITY[finding.severity] * 10,
+            score: PROFILE_BASE_SCORE[profile].findings + SEVERITY[finding.severity] * 10,
             provenance: validation.state,
             staleDetail: validation.detail,
             line: `${finding.id} | finding/${finding.triage}/${finding.severity} | ${clipHeadline(`${finding.title} — ${finding.observation}${evidence}`, 240)} | ${sourceTier(finding.provenance.source)}/${validation.state} | hunch_why("${finding.id}")`,
@@ -509,7 +543,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         candidates.push({
             ref: { kind: "resources", record_id: record.id },
             mandatory: false,
-            score: 550 - item.selectionRank,
+            score: PROFILE_BASE_SCORE[profile].resources - item.selectionRank,
             provenance: "current",
             line,
             landscapeResource: item,
@@ -527,7 +561,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         candidates.push({
             ref: { kind: "relationships", record_id: record.id },
             mandatory: false,
-            score: 525 - item.selectionRank,
+            score: PROFILE_BASE_SCORE[profile].relationships - item.selectionRank,
             provenance: "current",
             line,
             landscapeRelationship: item,
@@ -548,6 +582,8 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         const text = fitText(empty, cap);
         return finalizeDeliveryEnvelope({
             schema_version: DELIVERY_ENVELOPE_SCHEMA_VERSION,
+            profile,
+            ranking_policy: DELIVERY_PROFILE_POLICY_VERSION,
             text,
             delivered: [],
             hypotheses: [],
@@ -617,14 +653,30 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         }
         boundedEligible.push(candidate);
     }
-    const recordCandidates = boundedEligible.filter((candidate) => candidate.ref);
-    const structuralCandidates = boundedEligible.filter((candidate) => !candidate.ref);
+    const profileBoundedEligible = [];
+    let nonBlockingHeadlines = 0;
+    for (const candidate of boundedEligible) {
+        if (candidate.ref && !candidate.mandatory) {
+            if (nonBlockingHeadlines >= MAX_PROFILE_HEADLINES) {
+                omitted.push({
+                    ...candidate.ref,
+                    reason: "profile-cap",
+                    detail: `${profile} delivery is capped at ${MAX_PROFILE_HEADLINES} non-blocking headlines; use hunch_why or a narrower task to expand this record`,
+                });
+                continue;
+            }
+            nonBlockingHeadlines++;
+        }
+        profileBoundedEligible.push(candidate);
+    }
+    const recordCandidates = profileBoundedEligible.filter((candidate) => candidate.ref);
+    const structuralCandidates = profileBoundedEligible.filter((candidate) => !candidate.ref);
     const lines = [
         `# Hunch context for "${ctx.target}"`,
         "",
         query.taskPhrase
-            ? `## 🧠 Bounded memory (Invariants · max ${MAX_ACTIONABLE_HYPOTHESES} decision hypotheses · Bugs · Known findings)`
-            : "## 🧠 Ranked memory (Invariants · Decisions · Bugs · Known findings)",
+            ? `## 🧠 ${profile === "builder" ? "Bounded" : `${profile[0].toUpperCase()}${profile.slice(1)}-bounded`} memory (Invariants · max ${MAX_ACTIONABLE_HYPOTHESES} decision hypotheses · Bugs · Known findings)`
+            : `## 🧠 ${profile === "builder" ? "Ranked" : `${profile[0].toUpperCase()}${profile.slice(1)}-ranked`} memory (Invariants · Decisions · Bugs · Known findings)`,
     ];
     if (candidates.some((candidate) => candidate.abstainReason)) {
         lines.push("Evidence rule: explicit task, repro, and test evidence outranks advisory memory; weak unverified matches are withheld.");
@@ -720,6 +772,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
     const staleCount = omitted.filter((item) => item.reason === "stale-provenance" || item.reason === "retired").length;
     const budgetCount = omitted.filter((item) => item.reason === "budget").length;
     const actionabilityCount = omitted.filter((item) => item.reason === "actionability-cap").length;
+    const profileCapCount = omitted.filter((item) => item.reason === "profile-cap").length;
     const abstention = emptyAbstention();
     for (const item of omitted) {
         if (item.reason === "low-confidence" || item.reason === "insufficient-context" || item.reason === "low-relevance") {
@@ -735,6 +788,7 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         staleCount ? `${staleCount} stale/retired record(s) withheld; run hunch drift or hunch_why(id) to inspect.` : "",
         budgetCount ? `${budgetCount} lower-ranked record(s) omitted by budget; use hunch_why(id) to drill down.` : "",
         actionabilityCount ? `${actionabilityCount} additional decision hypothesis/hypotheses withheld by the actionability cap; refine the task evidence or use hunch_why(id).` : "",
+        profileCapCount ? `${profileCapCount} non-blocking record(s) withheld by the ${profile} profile cap; use hunch_why(id) or narrow the task.` : "",
         abstention.active ? `${abstention.withheld} weak prescriptive record(s) withheld by confidence/relevance abstention. ${abstention.retry_hint}` : "",
     ].filter(Boolean);
     if (notes.length) {
@@ -785,12 +839,12 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
     const landscapeOmissions = omitted
         .filter((item) => item.kind === "resources" || item.kind === "relationships")
         .flatMap((item) => {
-        if (!["budget", "stale-provenance", "endpoint-not-delivered", "landscape-cap"].includes(item.reason))
+        if (!["budget", "stale-provenance", "endpoint-not-delivered", "landscape-cap", "profile-cap"].includes(item.reason))
             return [];
         return [{
                 kind: item.kind,
                 recordId: item.record_id,
-                reason: item.reason,
+                reason: (item.reason === "profile-cap" ? "landscape-cap" : item.reason),
                 detail: item.detail,
             }];
     });
@@ -806,6 +860,8 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         : null;
     return finalizeDeliveryEnvelope({
         schema_version: DELIVERY_ENVELOPE_SCHEMA_VERSION,
+        profile,
+        ranking_policy: DELIVERY_PROFILE_POLICY_VERSION,
         text,
         delivered,
         hypotheses,

package/dist/core/outcomeExperience.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import { findingId } from "./ids.js";
 import { FindingSchema, isCredentialFreeText } from "./types.js";
+import { assertChangeIdentity, CHANGE_IDENTITY_ALGORITHM, CHANGE_IDENTITY_SCHEMA_VERSION, } from "./changeIdentity.js";
 export const USEFULNESS_OBSERVATION_SCHEMA_VERSION = "hunch.usefulness-observation/1";
 export const USEFULNESS_SIGNALS = [
     "used",
@@ -22,6 +23,27 @@ const EvidenceReferenceSchema = z.object({
     ref: z.string().min(1).max(512),
     hash: z.string().regex(SHA256),
 }).strict();
+const OutcomeChangeIdentitySchema = z.object({
+    schema: z.literal(CHANGE_IDENTITY_SCHEMA_VERSION),
+    algorithm: z.literal(CHANGE_IDENTITY_ALGORITHM),
+    change_id: z.string().regex(/^hchg_[a-f0-9]{24}$/),
+    base_revision: z.string().regex(GIT_OBJECT),
+    head_revision: z.string().regex(GIT_OBJECT),
+    base_tree: z.string().regex(GIT_OBJECT),
+    head_tree: z.string().regex(GIT_OBJECT),
+    delta_hash: z.string().regex(SHA256),
+    patch_id: z.string().regex(GIT_OBJECT).nullable(),
+    file_count: z.number().int().positive().max(16_384),
+    paths_hash: z.string().regex(SHA256),
+    content_hash: z.string().regex(SHA256),
+}).strict().superRefine((identity, ctx) => {
+    try {
+        assertChangeIdentity(identity);
+    }
+    catch (error) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: error.message });
+    }
+});
 export const UsefulnessObservationSchema = z.object({
     schema: z.literal(USEFULNESS_OBSERVATION_SCHEMA_VERSION),
     observationId: z.string().regex(OBSERVATION_ID),
@@ -46,6 +68,8 @@ export const UsefulnessObservationSchema = z.object({
         recordRevision: z.string().regex(SHA256),
         contentHash: z.string().regex(SHA256),
     }).strict(),
+    /** Optional until hosts can produce it; when present it survives squash metadata. */
+    change: OutcomeChangeIdentitySchema.optional(),
     signal: z.enum(USEFULNESS_SIGNALS),
     evidence: z.array(EvidenceReferenceSchema).max(64),
     observedAt: z.string().min(1).max(64),
@@ -146,6 +170,7 @@ function usefulnessObservationUnsigned(observation) {
         episode: { ...observation.episode },
         delivery: { ...observation.delivery },
         record: { ...observation.record },
+        ...(observation.change ? { change: { ...observation.change } } : {}),
         signal: observation.signal,
         evidence: observation.evidence.map((item) => ({ ...item })),
         observedAt: observation.observedAt,
@@ -160,6 +185,7 @@ export function createUsefulnessObservation(input) {
         episode: { ...input.episode },
         delivery: { ...input.delivery },
         record: { ...input.record },
+        ...(input.change ? { change: { ...input.change } } : {}),
         signal: input.signal,
         evidence: input.evidence.map((item) => ({ ...item })),
         observedAt: input.observedAt,
@@ -194,6 +220,7 @@ export function usefulnessObservationFinding(value) {
         `episode:${observation.episode.episodeId}@${observation.episode.episodeHash}`,
         `delivery:${observation.delivery.receiptRef}@${observation.delivery.receiptHash}`,
         `record:${observation.record.recordId}@${observation.record.recordRevision}`,
+        ...(observation.change ? [`change:${observation.change.change_id}@${observation.change.content_hash}`] : []),
         ...observation.evidence.map((item) => `${item.kind}:${item.ref}@${item.hash}`),
     ];
     return FindingSchema.parse({

package/dist/core/served.js

@@ -41,6 +41,8 @@ const RECEIPT_COLUMNS = [
     ["delivery_reason", "TEXT"],
     ["provenance_status", "TEXT"],
     ["token_cost", "INTEGER"],
+    ["delivery_profile", "TEXT"],
+    ["ranking_policy", "TEXT"],
 ];
 function columnNames(db) {
     const rows = db.prepare("PRAGMA table_info(served)").all();
@@ -89,9 +91,9 @@ export function recordServed(root, entries) {
         const db = openServedDb(root);
         try {
             const at = new Date().toISOString();
-            const insert = db.prepare("INSERT INTO served (at, session, event, kind, record_id, target, rank, delivery_reason, provenance_status, token_cost) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
+            const insert = db.prepare("INSERT INTO served (at, session, event, kind, record_id, target, rank, delivery_reason, provenance_status, token_cost, delivery_profile, ranking_policy) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)");
             for (const entry of entries) {
-                insert.run(at, entry.session_id ?? null, entry.event, entry.kind, entry.record_id, entry.target, entry.rank ?? null, entry.delivery_reason ?? null, entry.provenance_status ?? null, entry.token_cost ?? null);
+                insert.run(at, entry.session_id ?? null, entry.event, entry.kind, entry.record_id, entry.target, entry.rank ?? null, entry.delivery_reason ?? null, entry.provenance_status ?? null, entry.token_cost ?? null, entry.delivery_profile ?? null, entry.ranking_policy ?? null);
             }
         }
         finally {
@@ -117,7 +119,7 @@ export function servedSummary(root) {
            ROUND(AVG(token_cost), 2) AS average_token_cost
          FROM served GROUP BY record_id, kind ORDER BY serves DESC, refreshes DESC`).all();
             const rawRecent = db.prepare(`SELECT at, session AS session_id, event, kind, record_id, target,
-           rank, delivery_reason, provenance_status, token_cost
+           rank, delivery_reason, provenance_status, token_cost, delivery_profile, ranking_policy
          FROM served ORDER BY rowid DESC LIMIT 50`).all();
             const rows = rawRows.map((row) => ({ ...row }));
             const recent = rawRecent.map((receipt) => ({ ...receipt }));

package/dist/integrations/claudemd.js

@@ -46,7 +46,7 @@ export function renderHunchSection(store, root) {
     lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
     lines.push("");
     lines.push("**Orient (session/task start):**");
-    lines.push("- `hunch_context(target_or_task)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST.**");
+    lines.push("- `hunch_context(target)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST.**");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
     lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");
     lines.push("- `hunch_escalations()` — the decisions only the HUMAN can make (including one exact imported ADR at a time, topic conflicts, and policy calls). Normally empty; when it isn't, ASK the user inline — an entry is a question, silence is never approval. Apply an ADR answer only through `hunch_review_imported_adr` with its printed source and review hashes.");

package/dist/mcp/server.js

@@ -25,7 +25,8 @@ import { formatStructure } from "../core/format.js";
 import { diagnoseIssueCorrectionStage, formatCorrectionStageDiagnostic } from "../core/correctionStage.js";
 import { compileVerifiedEvidenceMap, EvidenceExecutionSchema, EvidenceInterventionSchema, EvidenceProbeSchema, formatVerifiedEvidenceMap, VerifiedEvidenceReceiptSchema, } from "../core/evidenceMap.js";
 import { collectCorrectionStageSources } from "../extractors/correctionSources.js";
-import { buildDeliveryEnvelope } from "../core/delivery.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 { armExecutionObligations, loadPipelineState, savePipelineState } from "../core/pipeline.js";
 import { recordServed } from "../core/served.js";
 import { EdgeSchema, ResourceSchema } from "../core/types.js";
@@ -181,6 +182,8 @@ const LANDSCAPE_FRAGMENT_SCHEMA = z.object({
  *  backward-compatible text block. */
 const DELIVERY_OUTPUT_SCHEMA = z.object({
     schema_version: z.literal("hunch.delivery-envelope/1"),
+    profile: z.enum(DELIVERY_PROFILES),
+    ranking_policy: z.literal(DELIVERY_PROFILE_POLICY_VERSION),
     receipt_id: z.string().regex(/^hdr_[a-f0-9]{24}$/),
     text: z.string(),
     delivered: z.array(z.object({
@@ -214,7 +217,7 @@ const DELIVERY_OUTPUT_SCHEMA = z.object({
     omitted: z.array(z.object({
         kind: z.enum(["constraints", "decisions", "bugs", "findings", "resources", "relationships"]),
         record_id: z.string(),
-        reason: z.enum(["budget", "stale-provenance", "retired", "actionability-cap", "endpoint-not-delivered", "landscape-cap", "low-confidence", "insufficient-context", "low-relevance"]),
+        reason: z.enum(["budget", "stale-provenance", "retired", "actionability-cap", "endpoint-not-delivered", "landscape-cap", "profile-cap", "low-confidence", "insufficient-context", "low-relevance"]),
         detail: z.string(),
     })),
     landscape: LANDSCAPE_FRAGMENT_SCHEMA.nullable(),
@@ -233,6 +236,20 @@ const DELIVERY_OUTPUT_SCHEMA = z.object({
         retry_hint: z.string().nullable(),
     }),
 });
+const CHANGE_IDENTITY_OUTPUT_SCHEMA = z.object({
+    schema: z.literal(CHANGE_IDENTITY_SCHEMA_VERSION),
+    algorithm: z.literal(CHANGE_IDENTITY_ALGORITHM),
+    change_id: z.string().regex(/^hchg_[a-f0-9]{24}$/),
+    base_revision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    head_revision: z.string().regex(/^[a-f0-9]{40,64}$/),
+    base_tree: z.string().regex(/^[a-f0-9]{40,64}$/),
+    head_tree: z.string().regex(/^[a-f0-9]{40,64}$/),
+    delta_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    patch_id: z.string().regex(/^[a-f0-9]{40,64}$/).nullable(),
+    file_count: z.number().int().positive().max(16_384),
+    paths_hash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    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. */
@@ -255,6 +272,8 @@ function deliveredContext(root, target, envelope, sessionId) {
         delivery_reason: item.delivery_reason,
         provenance_status: item.provenance_status,
         token_cost: item.token_cost,
+        delivery_profile: structuredContent.profile,
+        ranking_policy: structuredContent.ranking_policy,
     })));
     return {
         content: [{ type: "text", text: structuredContent.text }],
@@ -458,14 +477,22 @@ export function buildServerWithRootControl(initialRoot) {
     };
     const pullTeamMemory = (force = false) => {
         if (!store.privateDir)
-            return;
+            return "not_shared";
         const now = Date.now();
         if (!force && now < nextRemotePullAt)
-            return;
-        notePull(pullHunchStatus(store.privateDir, {
-            timeoutMs: 5_000,
-            remote: startupTeamRoute ?? advertisedTeamRemoteContract(root, join(store.privateDir, "..")),
-        }), Date.now());
+            return "cooldown";
+        let status;
+        try {
+            status = pullHunchStatus(store.privateDir, {
+                timeoutMs: 5_000,
+                remote: startupTeamRoute ?? advertisedTeamRemoteContract(root, join(store.privateDir, "..")),
+            });
+        }
+        catch {
+            status = "failed";
+        }
+        notePull(status, Date.now());
+        return status;
     };
     // A source stamp is acknowledged ONLY after a stable, successful rebuild. If
     // another process changes the atomic JSON tree during the rebuild, retry once;
@@ -607,10 +634,7 @@ export function buildServerWithRootControl(initialRoot) {
                 return err("The committed team memory destination is invalid or no longer matches this process. Refusing the stale graph; reconnect Hunch first.");
             }
             if (store.mode === "shared" && store.privateDir) {
-                try {
-                    pullTeamMemory();
-                }
-                catch { /* offline / lock held / invalid remote — use local */ }
+                pullTeamMemory();
                 // Recompute the full semantic + physical snapshot after the synchronous
                 // network seam. A paired team.json/origin change can occur while fetch is
                 // blocked; serving after that race would attach the old checkout to a new
@@ -786,6 +810,31 @@ export function buildServerWithRootControl(initialRoot) {
         }
         return ok(`Blast radius for "${target}":\n\n${parts.join("\n\n")}`);
     });
+    // -- hunch_change_identity (squash-stable exact delta identity) ------------
+    server.registerTool("hunch_change_identity", {
+        title: "Derive an exact squash-stable change identity",
+        description: "Content-address the exact Git tree delta between two revisions. Commit messages, authors and squash metadata do not affect the identity; whitespace, paths, modes and blob bytes do. Read-only and deterministic.",
+        inputSchema: {
+            base_ref: z.string().min(1).max(1_024).describe("Base commit or ref for the exact tree transition."),
+            head_ref: z.string().min(1).max(1_024).optional().describe("Head commit or ref (default HEAD)."),
+            cwd: cwdHintField,
+        },
+        outputSchema: CHANGE_IDENTITY_OUTPUT_SCHEMA,
+    }, async ({ base_ref, head_ref }) => {
+        try {
+            const identity = CHANGE_IDENTITY_OUTPUT_SCHEMA.parse(deriveChangeIdentity(root, base_ref, head_ref ?? "HEAD"));
+            return {
+                content: [{
+                        type: "text",
+                        text: `${identity.change_id} — ${identity.file_count} exact file delta(s), ${identity.delta_hash}; sealed ${identity.content_hash}`,
+                    }],
+                structuredContent: identity,
+            };
+        }
+        catch (error) {
+            return err(error.message);
+        }
+    });
     // -- hunch_context (surgical retrieval) -----------------------------------
     server.registerTool("hunch_context", {
         title: "Assemble the minimal relevant Hunch slice for a task",
@@ -793,10 +842,11 @@ export function buildServerWithRootControl(initialRoot) {
         inputSchema: {
             target: z.string().describe("A file path, symbol, or task phrase you're about to work on."),
             budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
+            profile: z.enum(DELIVERY_PROFILES).optional().describe("Delivery role: builder (default), reviewer, or architect. Changes non-blocking order only."),
             as_of: z.string().optional().describe("Time-travel ref (commit/tag/branch): assemble the slice as it stood then."),
         },
         outputSchema: DELIVERY_OUTPUT_SCHEMA,
-    }, async ({ target, budget_tokens, as_of }, extra) => {
+    }, async ({ target, budget_tokens, profile, as_of }, extra) => {
         const asOf = as_of ? asOfDate(as_of, root) : undefined;
         if (as_of && !asOf)
             return err(`Could not resolve as_of "${as_of}" to a commit.`);
@@ -807,6 +857,7 @@ export function buildServerWithRootControl(initialRoot) {
             components: store.recs("components"),
             decisionCorpus: store.recs("decisions"),
             historical: !!asOf,
+            profile: profile ?? "builder",
         };
         // 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
@@ -1041,11 +1092,31 @@ export function buildServerWithRootControl(initialRoot) {
     // -- hunch_current_decision (decision-grounding: current(topic)) ----------
     server.registerTool("hunch_current_decision", {
         title: "Current decision for a topic",
-        description: "Decision-grounding: return the single CURRENT (accepted, non-superseded) decision anchored to a topic — the authoritative answer a doc or diff is checked against, plus what it rejected. If a topic has NO current decision, or an unresolved collision (>1 live), it says so and injects nothing (fail-safe).",
+        description: "Decision-grounding: return the single CURRENT (accepted, non-superseded) decision anchored to a topic — the authoritative answer a doc or diff is checked against, plus what it rejected. A shared-store miss is confirmed against fresh team memory before Hunch says the topic has no current decision. If freshness is unavailable, or a topic has an unresolved collision (>1 live), it injects nothing (fail-safe).",
         inputSchema: { topic: z.string().describe("the decision anchor, e.g. 'auth-transport'") },
     }, async ({ topic }) => {
-        const decs = store.recs("decisions");
-        const live = liveForTopic(decs, topic);
+        let decs = store.recs("decisions");
+        let live = liveForTopic(decs, topic);
+        // A prior transient fetch failure may have placed ordinary tool traffic in
+        // backoff. That is acceptable for cached positive reads, but an exact topic
+        // miss is an authority claim: local absence must never be presented as team
+        // absence. Bypass the cooldown once, then reread only after a successful
+        // bounded convergence. An unavailable remote produces an explicit abstention.
+        if (live.length === 0 && store.mode === "shared" && store.privateDir) {
+            const status = pullTeamMemory(true);
+            if (status !== "updated" && status !== "current") {
+                return err(`Shared team memory refresh is ${status}; Hunch cannot confirm that topic "${topic}" has no current decision. Retry when the shared store is available.`);
+            }
+            try {
+                if (store.sourceStamp() !== indexedSourceStamp)
+                    refreshIndex();
+            }
+            catch {
+                return err(`Shared team memory refreshed, but its derived index could not be rebuilt; Hunch cannot confirm that topic "${topic}" is absent. Retry this read.`);
+            }
+            decs = store.recs("decisions");
+            live = liveForTopic(decs, topic);
+        }
         if (live.length === 0)
             return ok(`No current decision for topic "${topic}". (Un-anchored, or never captured.)`);
         if (live.length > 1) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.20.0-rc.5",
+  "version": "1.20.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

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