@davesheffer/hunch 1.20.0-rc.4 → 1.20.0-rc.6

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 |

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

@@ -0,0 +1,250 @@
+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",
+    "prevented",
+    "near_miss",
+    "contradicted",
+    "stale",
+    "unused",
+    "unknown",
+];
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const GIT_OBJECT = /^[a-f0-9]{40,64}$/;
+const RECEIPT_REF = /^hunch-memory:hmctx_[a-f0-9]{32}$/;
+const OBSERVATION_ID = /^huo_[a-f0-9]{24}$/;
+const MAX_RETENTION_MS = 365 * 24 * 60 * 60 * 1_000;
+const EvidenceReferenceSchema = z.object({
+    kind: z.enum(["artifact", "event", "verification", "receipt", "observation"]),
+    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),
+    episode: z.object({
+        provider: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+        schemaVersion: z.string().min(3).max(128),
+        episodeId: z.string().min(3).max(256),
+        episodeHash: z.string().regex(SHA256),
+        terminalAt: z.string().min(1).max(64),
+        result: z.enum(["pass", "fail", "uncertain", "abandoned", "rolled_back"]),
+    }).strict(),
+    delivery: z.object({
+        receiptRef: z.string().regex(RECEIPT_REF),
+        receiptHash: z.string().regex(SHA256),
+        graphRevision: z.string().regex(GIT_OBJECT),
+        sourceRevision: z.string().regex(GIT_OBJECT),
+        sourceContentHash: z.string().regex(SHA256),
+    }).strict(),
+    record: z.object({
+        recordId: z.string().min(3).max(512),
+        recordKind: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+        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),
+    retainUntil: z.string().min(1).max(64),
+    privacy: z.object({
+        payloadMode: z.literal("references_hashes_only"),
+        rawTranscriptIncluded: z.literal(false),
+        rawProviderOutputIncluded: z.literal(false),
+    }).strict(),
+    authority: z.object({
+        behavioralEffect: z.literal("none"),
+        mayChangeRanking: z.literal(false),
+        mayPromoteKnowledge: z.literal(false),
+        mayGrantAuthority: z.literal(false),
+    }).strict(),
+    contentHash: z.string().regex(SHA256),
+}).strict().superRefine((observation, ctx) => {
+    const timestamps = [
+        ["episode", "terminalAt", observation.episode.terminalAt],
+        ["observedAt", observation.observedAt],
+        ["retainUntil", observation.retainUntil],
+    ];
+    for (const path of timestamps) {
+        const value = path.at(-1);
+        if (!Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: path.slice(0, -1), message: "usefulness timestamp is invalid" });
+        }
+    }
+    const observedAt = Date.parse(observation.observedAt);
+    const terminalAt = Date.parse(observation.episode.terminalAt);
+    const retainUntil = Date.parse(observation.retainUntil);
+    if (Number.isFinite(observedAt) && Number.isFinite(terminalAt) && observedAt < terminalAt) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["observedAt"], message: "usefulness cannot precede the terminal outcome" });
+    }
+    if (Number.isFinite(observedAt) && Number.isFinite(retainUntil)
+        && (retainUntil <= observedAt || retainUntil - observedAt > MAX_RETENTION_MS)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["retainUntil"], message: "usefulness retention is invalid" });
+    }
+    if (observation.delivery.sourceRevision !== observation.delivery.graphRevision) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["delivery", "sourceRevision"], message: "usefulness source revision is inconsistent" });
+    }
+    if (observation.signal !== "unknown" && observation.evidence.length === 0) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence"], message: "supported usefulness requires evidence" });
+    }
+    const evidenceIdentities = new Set();
+    for (const [index, evidence] of observation.evidence.entries()) {
+        const identity = `${evidence.kind}:${evidence.ref}:${evidence.hash}`;
+        if (evidenceIdentities.has(identity)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence", index], message: "usefulness evidence is duplicated" });
+        }
+        evidenceIdentities.add(identity);
+        if (!isCredentialFreeText(evidence.ref)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["evidence", index, "ref"], message: "usefulness evidence contains credential material" });
+        }
+    }
+    for (const [path, value] of [
+        [["episode", "schemaVersion"], observation.episode.schemaVersion],
+        [["episode", "episodeId"], observation.episode.episodeId],
+        [["record", "recordId"], observation.record.recordId],
+    ]) {
+        if (!isCredentialFreeText(value)) {
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [...path], message: "usefulness identity contains credential material" });
+        }
+    }
+    const unsigned = usefulnessObservationUnsigned(observation);
+    const contentHash = usefulnessHash(unsigned);
+    if (observation.contentHash !== contentHash
+        || observation.observationId !== usefulnessObservationId(observation)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: "usefulness observation seal is invalid" });
+    }
+});
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+            .map(([key, child]) => `${JSON.stringify(key)}:${canonicalJson(child)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+function usefulnessHash(value) {
+    return `sha256:${createHash("sha256").update(canonicalJson(value), "utf8").digest("hex")}`;
+}
+function usefulnessObservationId(observation) {
+    const identityHash = usefulnessHash({
+        episodeId: observation.episode.episodeId,
+        receiptRef: observation.delivery.receiptRef,
+        receiptHash: observation.delivery.receiptHash,
+        recordId: observation.record.recordId,
+    });
+    return `huo_${identityHash.slice(7, 31)}`;
+}
+function usefulnessObservationUnsigned(observation) {
+    return {
+        schema: observation.schema,
+        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,
+        retainUntil: observation.retainUntil,
+        privacy: { ...observation.privacy },
+        authority: { ...observation.authority },
+    };
+}
+export function createUsefulnessObservation(input) {
+    const unsigned = usefulnessObservationUnsigned({
+        schema: USEFULNESS_OBSERVATION_SCHEMA_VERSION,
+        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,
+        retainUntil: input.retainUntil,
+        privacy: { ...input.privacy },
+        authority: {
+            behavioralEffect: "none",
+            mayChangeRanking: false,
+            mayPromoteKnowledge: false,
+            mayGrantAuthority: false,
+        },
+    });
+    const observationId = usefulnessObservationId(unsigned);
+    return UsefulnessObservationSchema.parse({
+        ...unsigned,
+        observationId,
+        contentHash: usefulnessHash(unsigned),
+    });
+}
+export function assertUsefulnessObservation(value) {
+    UsefulnessObservationSchema.parse(value);
+}
+/** Contradiction and staleness become open advisory review work, never truth. */
+export function usefulnessObservationFinding(value) {
+    const observation = UsefulnessObservationSchema.parse(value);
+    if (observation.signal !== "contradicted" && observation.signal !== "stale")
+        return null;
+    const title = `Outcome ${observation.signal}: ${observation.record.recordId} (${observation.observationId})`;
+    const evidence = [
+        `usefulness:${observation.observationId}`,
+        `usefulness-content:${observation.contentHash}`,
+        `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({
+        id: findingId(title),
+        title,
+        observation: observation.signal === "contradicted"
+            ? `Outcome evidence may conflict with delivered Hunch record ${observation.record.recordId}; review the record and its applicability before changing trusted knowledge.`
+            : `Outcome evidence may show that delivered Hunch record ${observation.record.recordId} was stale; review currentness before changing trusted knowledge.`,
+        evidence,
+        method: null,
+        severity: observation.signal === "contradicted" ? "high" : "medium",
+        triage: "open",
+        affected_files: [],
+        affected_symbols: [observation.record.recordId],
+        violates_constraint: null,
+        spawned_decision: null,
+        observed_at: observation.observedAt,
+        resolved_commit: null,
+        provenance: {
+            source: "outcome_experience+candidate",
+            confidence: 0.75,
+            evidence,
+            last_verified: observation.observedAt,
+        },
+    });
+}
+//# sourceMappingURL=outcomeExperience.js.map

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/extractors/adrImport.js

@@ -35,6 +35,17 @@ export const ADR_DIR_CANDIDATES = [
 /** An ADR file is NNNN-slug.md (adr-tools / MADR convention). Templates and
  *  indexes (adr-template.md, README.md, index.md) never match. */
 export const ADR_FILE_RE = /^(\d{1,5})-([a-z0-9@][a-z0-9@._-]*)\.md$/i;
+/** A structurally valid ADR filename can still name corpus scaffolding rather
+ * than a decision. Keep this classification separate from parse failure so the
+ * CLI can exclude templates quietly instead of falsely calling their filename
+ * malformed. */
+export function isAdrCorpusTemplate(relPath) {
+    const base = relPath.split("/").pop() ?? relPath;
+    const match = ADR_FILE_RE.exec(base);
+    return match !== null
+        && Number(match[1]) === 0
+        && /^(?:adr[-_.]?)?template(?:[-_.]|$)/i.test(match[2]);
+}
 /** Decision.date is required even when an ADR has no date and no Git history is
  * available (for example, a copied corpus outside a repository). Use an honest,
  * deterministic sentinel instead of the import clock: re-importing the same
@@ -180,7 +191,7 @@ export function parseAdrMarkdown(text, relPath) {
         return null;
     const number = Number(nameMatch[1]);
     const slug = nameMatch[2].toLowerCase();
-    if (number === 0 && /^(?:adr[-_.]?)?template(?:[-_.]|$)/i.test(slug))
+    if (isAdrCorpusTemplate(relPath))
         return null;
     const fmMatch = FRONTMATTER_RE.exec(text);
     const fm = fmMatch ? fmMatch[1] : "";
@@ -253,7 +264,9 @@ export function mapAdrCorpus(sources) {
     for (const src of sources) {
         const p = parseAdrMarkdown(src.text, src.relPath);
         if (!p) {
-            warnings.push(`${src.relPath}: filename does not follow NNNN-slug.md — skipped`);
+            if (!isAdrCorpusTemplate(src.relPath)) {
+                warnings.push(`${src.relPath}: filename does not follow NNNN-slug.md — skipped`);
+            }
             continue;
         }
         parsed.push(p);

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 }],
@@ -786,6 +805,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 +837,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 +852,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.20.0-rc.4",
+  "version": "1.20.0-rc.6",
   "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.4",
+  "version": "1.20.0-rc.6",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.20.0-rc.4",
+      "version": "1.20.0-rc.6",
       "runtimeHint": "npx",
       "packageArguments": [
         {