@davesheffer/hunch 1.19.0 → 1.20.0-rc.2

package/README.md

@@ -1,49 +1,33 @@
 # Hunch
 
-## Your repo remembers why.
+## Give your AI coding assistant the missing story behind your code.
 
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
 [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
 
-For the precise rules your team explicitly trusts and proves, Hunch gives a concrete guarantee:
-**your agents do not re-make a decided decision or re-introduce a fixed bug without a deterministic
-violation being surfaced.** The mechanism is an engineering-memory and architectural-conformance
-layer — the decisions, constraints, rejected approaches, and bug history behind your code, delivered
-as evidence before an assistant changes anything, with the result checked deterministically after.
+Git remembers what changed. Chat history disappears. A future Claude, Cursor, Codex, or Copilot
+session can read your code, but it usually does not know why your team chose this design, which
+alternative failed, or which old bug a strange-looking line prevents.
 
-Memory starts **advisory**. Nothing blocks until you explicitly trust a precise rule and choose
-strict enforcement.
+**Hunch is project memory for the AI coding tools you already use.** It saves decisions, bug fixes,
+rejected approaches, and important rules. Before an assistant changes code, Hunch brings back the
+relevant reasons. After the change, it can check whether the work conflicts with a rule your team
+explicitly trusts.
 
-**Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
-then a deterministic check of the change against the rules your team has explicitly trusted.
+### A simple example
 
-> **New in v1.19.0:** correction search now keeps the flat top five but adds
-> transfer-tested semantic declaration families and an efficiency-tested progressive queue.
-> Evidence receipts are read-only annotations: they never reorder candidates or claim an exact
-> owner. Install the stable release with `npm i -g @davesheffer/hunch`.
+Your team once moved login sessions to the server so stolen tokens could be disabled immediately.
+Months later, an AI assistant sees the extra code and proposes a “simpler” token-only design. Hunch
+shows the assistant why the server-side design exists and which security bug it prevents—before the
+edit happens.
 
-The measured improvement is deliberately scoped to fresh, preregistered transfer cases:
+That means less time repeating old explanations, fewer old mistakes returning, and the same project
+context across every coding assistant.
 
-| Measure | Flat/baseline | v1.19 bounded view | Change |
-| --- | ---: | ---: | ---: |
-| Changed declaration found | 3/12 (25%) | 6/12 (50%) | +25 percentage points |
-| Correct file found | 8/12 (66.7%) | 10/12 (83.3%) | +16.6 percentage points |
-| Declarations inspected for the same five hits | 18.9 average | 11 average | 41.9% less |
-
-These are bounded diagnostic and inspection results, not a claim that Hunch is universally twice as
-accurate. Failed evidence and causal rerankers remain disabled; the receipts annotate the shortlist
-without changing its order or asserting an exact owner.
-
-> **New in v1.18.0:** YAML and Helm now enter the same dependency graph as application code.
-> Anchors and aliases become reference edges; chart-scoped `define`, `include`, and `template`
-> relationships survive pre-render syntax without weakening fail-closed handling for ordinary
-> invalid YAML.
-
-Read the [v1.18 release story](https://hunch-pi.vercel.app/blog/post?slug=configuration-joins-the-graph)
-for the graph semantics, chart boundaries, honest limits, and Oliver Sampson's contribution.
-
-See the public [roadmap](ROADMAP.md) for what is next and what is deliberately out of scope.
+Hunch is **not another AI model** and it does not replace your coding assistant. It is the memory and
+safety layer behind it. Memory is advisory by default; nothing blocks work unless you deliberately
+turn on strict checks for a precise rule.
 
 ## Start in five minutes
 
@@ -56,44 +40,76 @@ hunch init
 hunch backfill --since 90d   # optional: seed memory from recent history
 ```
 
-Reload your coding assistant, then ask:
+Reload your coding assistant, then ask a normal question:
 
 > Why is this built this way?
 
-`hunch init` indexes the repo, installs the local memory hooks, and connects supported assistants
-to the same graph. It merges into existing configuration instead of replacing it.
+Hunch answers from your project's saved history and shows where the answer came from. `hunch init`
+indexes the repo, installs local hooks, and connects supported assistants without replacing their
+existing configuration.
 
 ## What Hunch gives you
 
-- **Durable context** — decisions and corrections survive the chat session that produced them.
-- **One memory for every assistant** — Claude Code, Cursor, Copilot, Windsurf, Antigravity, Codex,
-  and any MCP client see the same evidence.
-- **Change receipts** — review a working tree, commit, or branch against recorded intent and get a
-  cited PASS / WARN / BLOCK result.
-- **Bug lineage** — understand which old incident a line fixed before accidentally undoing it.
-- **Code awareness** — TypeScript, JavaScript, Python, Go, YAML, and chart-scoped Helm templates
-  feed dependency, blast-radius, and redundancy checks. The reasoning layer works with any language.
-- **ADR interop** — `hunch import-adr` populates the graph from an existing MADR/Nygard corpus;
-  `hunch export-adr` projects it back as standard MADR any ADR reader understands, and the
-  projection then tracks the graph automatically and reports its own drift.
+- **A memory that outlives chat** — decisions and corrections are still available next week, next
+  year, and in a different assistant.
+- **One shared story** — Claude Code, Cursor, Copilot, Windsurf, Antigravity, Codex, and any MCP
+  client get the same project context.
+- **Warnings with reasons** — review a change against trusted project rules and see exactly why it
+  passes, needs attention, or should be blocked.
+- **Past bugs stay useful** — see which old incident a piece of code fixed before accidentally
+  undoing it.
+- **Understands how code connects** — for TypeScript, JavaScript, Python, Go, YAML, and Helm, Hunch
+  can see what calls or depends on the code you are about to change. Its memory works with any
+  language.
+- **Works with existing decision documents** — import your architecture decision records into
+  Hunch, or export Hunch decisions back to a standard format other tools can read.
 
 The source of truth is readable JSON in `.hunch/`. A local SQLite index makes retrieval fast but
 is always rebuildable.
 
-## Day-to-day
+## What improved in v1.19
+
+Hunch now gives developers a better, shorter list of code to inspect when they describe a problem.
+In a 12-problem test on unfamiliar code, it found the changed piece of code in 6 cases instead of 3
+and found the correct file in 10 cases instead of 8. In a separate test, it kept the same five
+successful finds while reducing the average number of named code items to inspect—such as functions
+or classes—from 18.9 to 11.
+
+| What the test measured | Before | v1.19 | Result |
+| --- | ---: | ---: | ---: |
+| Problems where Hunch found the changed code | 3/12 | 6/12 | 2× as many in this test |
+| Problems where Hunch found the correct file | 8/12 | 10/12 | 2 more correct files |
+| Pieces of code inspected for the same five finds | 18.9 average | 11 average | 41.9% less to inspect |
+
+These are small, controlled tests—not a promise that Hunch is twice as accurate everywhere. Hunch
+also refuses to pretend it knows the exact fix when the evidence only shows where to investigate.
+The detailed receipts live in [`bench/external/results`](bench/external/results).
+
+See the public [roadmap](ROADMAP.md) for what is next and what is deliberately out of scope.
+
+## Common tasks
 
 Most memory work happens automatically after commits. These commands cover the common manual paths:
 
 | Command | Use it for |
 | --- | --- |
-| `hunch why <file>` | Decisions, bugs, constraints, and blast radius behind a file |
+| `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 check --working` | Review all current changes against recorded intent |
-| `hunch shortlist --issue "..."` | Experimental flat shortlist plus a progressive, file-anchored semantic inspection plan; add `--evidence receipt.json` for read-only evidence annotations |
-| `hunch evidence-map receipt.json` | Compile observed probe/execution receipts without guessing an exact owner |
-| `hunch log` | See the memory timeline and its reversible moves |
-| `hunch escalations` | See the rare decisions only a human can make |
-| `hunch doctor` | Diagnose setup, provider, index, or private-overlay problems |
+| `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 |
+| `hunch doctor` | Diagnose setup problems |
+
+<details>
+<summary><strong>Advanced: problem shortlisting and evidence receipts</strong></summary>
+
+These tools help researchers and maintainers investigate where a described behavior may live. They
+show uncertainty instead of claiming to know the exact fix.
+
+| Command | Use it for |
+| --- | --- |
+| `hunch shortlist --issue "..."` | Build a bounded list of files and named code items to inspect |
+| `hunch evidence-map receipt.json` | Add observed execution evidence without guessing the exact owner |
 
 `hunch evidence-map` accepts a bounded JSON receipt containing a red target, a distinct green
 control, optional execution counts, and optional intervention outcomes. It reports target-only and
@@ -133,6 +149,8 @@ one-hop relationship expansion added none, and evidence/causal rerankers also fa
 transfer gates. The receipts remain in `bench/external/results`; rejected mechanisms cannot silently
 change the production ordering.
 
+</details>
+
 Corrections can become scoped rules, but captured memory cannot hard-block on its own. Enforcement is
 deterministic and opt-in:
 
@@ -141,12 +159,11 @@ hunch firmness strict
 hunch check --staged --strict
 ```
 
-## Share one living team memory
+## Share the same memory with your team
 
-Matrix mode keeps the team's decisions, corrections, constraints, and proofs in one dedicated Git
-repository, separate from the code repository. Hunch does not host that repository: create a private
-Git repo that every teammate can access, install the Matrix release on team machines and CI, then
-have one maintainer run:
+For a team, Hunch can keep everyone’s decisions, corrections, and rules in one private Git
+repository, separate from the code repository. Hunch does not host it. Create a private repository
+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

package/dist/cli/index.js

@@ -81,6 +81,8 @@ import { pendingEscalations, policyEscalations } from "../core/escalations.js";
 import { premiseEscalations } from "../core/premises.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
 import { compareCandidates } from "../core/compare.js";
+import { planLandscapeAdoption } from "../core/landscapeAdoption.js";
+import { discoverRepositoryLandscape } from "../extractors/landscapeDiscovery.js";
 import { checkConformance } from "../core/conformance.js";
 import { ConstitutionService, policyEvaluationEnvelope } from "../constitution/service.js";
 import { sourceGraphSnapshot } from "../constitution/evaluator.js";
@@ -2853,6 +2855,87 @@ for (const command of ["status", "report"]) {
         }
     });
 }
+// ---- landscape (review + explicitly adopt exact repository candidates) ---
+const landscapeCmd = program
+    .command("landscape")
+    .description("Review exact-revision Engineering Landscape candidates and explicitly adopt them into the graph.");
+landscapeCmd
+    .command("review")
+    .description("Discover a read-only, hash-bound candidate set. This command never writes graph authority.")
+    .option("--ref <ref>", "Git commit/ref to inspect", "HEAD")
+    .option("--json", "emit the complete machine-readable discovery envelope")
+    .action((opts) => {
+    const root = findRoot();
+    const discovery = discoverRepositoryLandscape(root, opts.ref);
+    if (opts.json) {
+        console.log(JSON.stringify(discovery, null, 2));
+        return;
+    }
+    console.log(`Landscape candidates at ${discovery.sourceRevision}`);
+    console.log(`Discovery: ${discovery.discoveryHash}`);
+    console.log(`Repository identity: ${discovery.repositoryRootIdentity}\n`);
+    console.log(`RESOURCES (${discovery.resources.length})`);
+    for (const candidate of discovery.resources) {
+        console.log(`  ${candidate.candidateHash}  ${candidate.record.id}  ${candidate.record.name}`);
+    }
+    console.log(`\nRELATIONSHIPS (${discovery.relationships.length})`);
+    for (const candidate of discovery.relationships) {
+        console.log(`  ${candidate.candidateHash}  ${candidate.record.from} --${candidate.record.type}--> ${candidate.record.to}`);
+    }
+    if (discovery.issues.length) {
+        console.log(`\nISSUES (${discovery.issues.length})`);
+        for (const issue of discovery.issues) {
+            console.log(`  ${issue.code}  ${issue.sourcePath}${issue.sourceField ? `#${issue.sourceField}` : ""} — ${issue.detail}`);
+        }
+    }
+    console.log("\nNothing was written. Review the candidates, then adopt all of them with:");
+    console.log(`  hunch landscape adopt --ref ${discovery.sourceRevision} --expected ${discovery.discoveryHash} --all --reviewed-by <you>${discovery.issues.length ? " --acknowledge-issues" : ""}`);
+    console.log("Or pass --candidate <hash...> to adopt an explicit subset; relationships require both endpoint resources.");
+});
+landscapeCmd
+    .command("adopt")
+    .description("Human-confirm a reviewed candidate set and write only those exact records through Hunch's normal graph boundary.")
+    .option("--ref <ref>", "exact Git commit/ref that was reviewed", "HEAD")
+    .requiredOption("--expected <hash>", "discovery hash printed by landscape review")
+    .requiredOption("--reviewed-by <label>", "credential-free operator/reviewer label")
+    .option("--all", "adopt every candidate in the reviewed discovery")
+    .option("--candidate <hashes...>", "adopt only these candidate hashes")
+    .option("--acknowledge-issues", "confirm that the printed discovery issues were reviewed")
+    .action((opts) => {
+    if (opts.all && opts.candidate?.length)
+        return fail("choose either --all or --candidate, not both");
+    if (!opts.all && !opts.candidate?.length)
+        return fail("choose --all or name reviewed hashes with --candidate <hashes...>");
+    const { store, root } = storeFor();
+    try {
+        const discovery = discoverRepositoryLandscape(root, opts.ref);
+        const plan = planLandscapeAdoption({
+            discovery,
+            expectedDiscoveryHash: opts.expected,
+            reviewer: opts.reviewedBy,
+            candidateHashes: opts.all ? "all" : opts.candidate,
+            acknowledgeIssues: opts.acknowledgeIssues,
+            existingResources: store.recs("resources"),
+            existingRelationships: store.recs("edges"),
+        });
+        for (const resource of plan.resourcesToWrite)
+            store.putCapture("resources", resource);
+        for (const relationship of plan.relationshipsToWrite)
+            store.putCapture("edges", relationship);
+        store.reindex();
+        if (plan.resourcesToWrite.length || plan.relationshipsToWrite.length) {
+            pumpMemoryHome(store, root, store.captureHome(false), "hunch: adopt reviewed Engineering Landscape candidates");
+        }
+        console.log(JSON.stringify(plan.receipt, null, 2));
+        console.log(`✓ accepted ${plan.receipt.acceptedResourceIds.length} resource(s) and ${plan.receipt.acceptedRelationshipIds.length} relationship(s); wrote ${plan.resourcesToWrite.length + plan.relationshipsToWrite.length}, reused ${plan.receipt.reusedResourceIds.length + plan.receipt.reusedRelationshipIds.length}.`);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- compare (rank N candidate solutions by architectural fit) ------------
 program
     .command("compare")
@@ -3720,7 +3803,13 @@ program
     // used to come back empty while the graph held the answer one FTS query away —
     // the task-shaped entry point must not whiff on task-shaped input. Fall back to
     // search so the caller always leaves with the closest graph matches.
-    const empty = !ctx.constraints.length && !ctx.decisions.length && !ctx.bugs.length && !ctx.blast_radius.length;
+    const empty = !ctx.constraints.length &&
+        !ctx.decisions.length &&
+        !ctx.bugs.length &&
+        !ctx.blast_radius.length &&
+        !ctx.findings.length &&
+        !ctx.landscape?.resources.length &&
+        !ctx.landscape?.relationships.length;
     if (empty && !asOf) {
         const hits = store.search(target, 8);
         if (hits.length) {
@@ -4325,7 +4414,15 @@ program
         // from this file. No diff exists yet, so this is context — "don't re-add X" —
         // not a block; the commit-time `hunch check` does the actual gating.
         const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
-        const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length || ctx.findings.length || retired.length || docGround;
+        const hasContent = ctx.constraints.length ||
+            ctx.decisions.length ||
+            ctx.bugs.length ||
+            ctx.blast_radius.length ||
+            ctx.findings.length ||
+            ctx.landscape?.resources.length ||
+            ctx.landscape?.relationships.length ||
+            retired.length ||
+            docGround;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
         const envelope = buildDeliveryEnvelope(ctx, {

package/dist/core/delivery.js

@@ -12,6 +12,8 @@ import { isAbsolute, join } from "node:path";
 import { pathMatchesGlob, pathsRelated } from "./glob.js";
 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";
 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;
@@ -361,6 +363,67 @@ function charCount(text) {
 function estimatedTokens(text) {
     return Math.max(1, Math.ceil(charCount(text) / 4));
 }
+function finalizeDeliveryEnvelope(unsigned) {
+    const digest = landscapeFragmentHash(unsigned);
+    const envelope = {
+        ...unsigned,
+        receipt_id: `hdr_${digest.slice("sha256:".length, "sha256:".length + 24)}`,
+    };
+    assertDeliveryEnvelope(envelope);
+    return envelope;
+}
+/** Validate the public receipt without trusting a caller-supplied identity. */
+export function assertDeliveryEnvelope(envelope) {
+    if (envelope.schema_version !== DELIVERY_ENVELOPE_SCHEMA_VERSION) {
+        throw new Error("delivery envelope schema is unsupported");
+    }
+    if (!/^hdr_[a-f0-9]{24}$/.test(envelope.receipt_id))
+        throw new Error("delivery envelope receipt id is invalid");
+    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) {
+        throw new Error("delivery envelope budget accounting is invalid");
+    }
+    if (!envelope.blocking_overflow && envelope.accounted_chars > envelope.budget_tokens * 4) {
+        throw new Error("delivery envelope exceeds its hard caller budget");
+    }
+    if (envelope.landscape)
+        assertLandscapeDeliveryFragment(envelope.landscape);
+    const landscapeReceipts = new Map((envelope.landscape
+        ? [...envelope.landscape.resources, ...envelope.landscape.relationships]
+        : []).map((item) => [`${item.record.schema === "hunch.resource/1" ? "resources" : "relationships"}:${item.record.id}`, item]));
+    const deliveredLandscape = envelope.delivered.filter((item) => item.kind === "resources" || item.kind === "relationships");
+    if (deliveredLandscape.length !== landscapeReceipts.size) {
+        throw new Error("delivery envelope landscape receipts do not match delivered records");
+    }
+    const deliveredLandscapeKeys = new Set();
+    for (const receipt of deliveredLandscape) {
+        const key = `${receipt.kind}:${receipt.record_id}`;
+        const nested = landscapeReceipts.get(key);
+        if (!nested || deliveredLandscapeKeys.has(key)
+            || nested.rank !== receipt.rank || nested.tokenCost !== receipt.token_cost
+            || nested.deliveryReason !== receipt.delivery_reason
+            || nested.provenanceStatus !== receipt.provenance_status) {
+            throw new Error("delivery envelope landscape receipt is inconsistent");
+        }
+        deliveredLandscapeKeys.add(key);
+    }
+    if (deliveredLandscapeKeys.size !== landscapeReceipts.size) {
+        throw new Error("delivery envelope landscape receipts are not one-to-one");
+    }
+    const deliveredRecordChars = envelope.landscape
+        ? [...envelope.landscape.resources, ...envelope.landscape.relationships]
+            .reduce((sum, item) => sum + charCount(JSON.stringify(item.record)), 0)
+        : 0;
+    if (envelope.accounted_chars < envelope.used_chars + deliveredRecordChars) {
+        throw new Error("delivery envelope undercounts its structured landscape records");
+    }
+    const { receipt_id: _receiptId, ...unsigned } = envelope;
+    const expected = landscapeFragmentHash(unsigned);
+    if (envelope.receipt_id !== `hdr_${expected.slice("sha256:".length, "sha256:".length + 24)}`) {
+        throw new Error("delivery envelope receipt does not match its content");
+    }
+}
 /** Build the one envelope used by CLI, MCP, and the edit hook. */
 export function buildDeliveryEnvelope(ctx, options = {}) {
     const budget = Number.isFinite(ctx.budget_tokens) ? Math.max(0, Math.floor(ctx.budget_tokens)) : 1500;
@@ -438,19 +501,73 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
             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}")`,
         });
     }
+    for (const item of ctx.landscape?.resources ?? []) {
+        const record = item.record;
+        const reviewId = String(record.metadata.landscape_review_id);
+        const revision = record.currentness.source_revision ?? "unknown";
+        const line = `${record.id} | resource/${record.kind}/${record.lifecycle} | ${clipHeadline(record.name, 160)} | ${item.selectionReason} | current@${revision} | review ${reviewId}`;
+        candidates.push({
+            ref: { kind: "resources", record_id: record.id },
+            mandatory: false,
+            score: 550 - item.selectionRank,
+            provenance: "current",
+            line,
+            landscapeResource: item,
+            // The structured record is part of what an MCP caller receives. Charge
+            // it conservatively instead of pretending only the duplicate headline
+            // consumes the caller's context budget.
+            accountedChars: charCount(line) + charCount(JSON.stringify(record)) + 240,
+        });
+    }
+    for (const item of ctx.landscape?.relationships ?? []) {
+        const record = item.record;
+        const reviewId = String(record.metadata.landscape_review_id);
+        const revision = record.currentness?.source_revision ?? "unknown";
+        const line = `${record.id} | relationship/${record.type} | ${record.from} -> ${record.to} | graph-connection | current@${revision} | review ${reviewId}`;
+        candidates.push({
+            ref: { kind: "relationships", record_id: record.id },
+            mandatory: false,
+            score: 525 - item.selectionRank,
+            provenance: "current",
+            line,
+            landscapeRelationship: item,
+            accountedChars: charCount(line) + charCount(JSON.stringify(record)) + 240,
+        });
+    }
     for (const dependent of ctx.blast_radius) {
         candidates.push({ mandatory: false, score: 400 - dependent.depth, provenance: "current", line: `graph | blast/d${dependent.depth} | ${clipHeadline(dependent.via, 220)}` });
     }
     if (ctx.components.length) {
         candidates.push({ mandatory: false, score: 300, provenance: "current", line: `graph | components | ${clipHeadline(ctx.components.map((component) => component.name).join(", "), 240)}` });
     }
-    const hasAnything = candidates.length > 0 || (options.supplements?.length ?? 0) > 0;
+    const hasAnything = candidates.length > 0
+        || (ctx.landscape?.omitted.length ?? 0) > 0
+        || (options.supplements?.length ?? 0) > 0;
     if (!hasAnything) {
         const empty = `# Hunch context for "${ctx.target}"\n\n(No recorded constraints/decisions/bugs for this target yet — Hunch is still learning it.)\n`;
         const text = fitText(empty, cap);
-        return { text, delivered: [], hypotheses: [], obligations: [], supplements: [], omitted: [], budget_tokens: budget, used_chars: charCount(text), blocking_overflow: false, abstention: emptyAbstention() };
+        return finalizeDeliveryEnvelope({
+            schema_version: DELIVERY_ENVELOPE_SCHEMA_VERSION,
+            text,
+            delivered: [],
+            hypotheses: [],
+            obligations: [],
+            supplements: [],
+            omitted: [],
+            landscape: null,
+            budget_tokens: budget,
+            used_chars: charCount(text),
+            accounted_chars: charCount(text),
+            blocking_overflow: false,
+            abstention: emptyAbstention(),
+        });
     }
-    const omitted = [];
+    const omitted = (ctx.landscape?.omitted ?? []).map((item) => ({
+        kind: item.kind,
+        record_id: item.recordId,
+        reason: item.reason,
+        detail: item.detail,
+    }));
     const eligible = [];
     for (const candidate of candidates) {
         if (candidate.retiredDetail && candidate.ref) {
@@ -515,28 +632,48 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
     if (query.taskPhrase) {
         lines.push("Diagnostic loop: before editing, call hunch_context again with the first concrete failing assertion, stack frame, expected behavior, and API/code path you observe.");
     }
-    let text = `${lines.join("\n")}\n`;
+    if ((ctx.landscape?.resources.length ?? 0) + (ctx.landscape?.relationships.length ?? 0) > 0) {
+        lines.push(`Landscape: only current human-reviewed ${LANDSCAPE_FRAGMENT_SCHEMA_VERSION} records may share this envelope and budget.`);
+    }
+    let text = fitText(`${lines.join("\n")}\n`, cap);
+    let accountedChars = charCount(text);
     const delivered = [];
     const hypotheses = [];
     const obligations = [];
     const supplements = [];
     let blockingOverflow = false;
+    const deliveredLandscapeResourceIds = new Set();
     for (const [index, candidate] of recordCandidates.entries()) {
         const next = `- ${candidate.line}\n`;
-        if (charCount(text) + charCount(next) <= cap || candidate.mandatory) {
+        if (candidate.landscapeRelationship) {
+            const relationship = candidate.landscapeRelationship.record;
+            if (!deliveredLandscapeResourceIds.has(relationship.from) || !deliveredLandscapeResourceIds.has(relationship.to)) {
+                omitted.push({
+                    ...candidate.ref,
+                    reason: "endpoint-not-delivered",
+                    detail: "reviewed relationship was withheld because both endpoint resources were not delivered in this budget",
+                });
+                continue;
+            }
+        }
+        const chargedChars = candidate.accountedChars ?? charCount(next);
+        if (accountedChars + chargedChars <= cap || candidate.mandatory) {
             text += next;
+            accountedChars += chargedChars;
             delivered.push({
                 ...candidate.ref,
                 rank: index + 1,
                 delivery_reason: candidate.mandatory ? "blocking-reserved" : "ranked",
                 provenance_status: candidate.provenance,
-                token_cost: estimatedTokens(next),
+                token_cost: Math.max(1, Math.ceil(chargedChars / 4)),
             });
+            if (candidate.landscapeResource)
+                deliveredLandscapeResourceIds.add(candidate.landscapeResource.record.id);
             if (candidate.hypothesis) {
                 hypotheses.push({ ...candidate.hypothesis, rank: index + 1 });
                 obligations.push(...candidate.hypothesis.obligations);
             }
-            if (charCount(text) > cap && candidate.mandatory)
+            if (accountedChars > cap && candidate.mandatory)
                 blockingOverflow = true;
         }
         else if (candidate.ref) {
@@ -564,8 +701,9 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
         if (abstainedMemory && delivered.length === 0 && supplement.kind.startsWith("search-")) {
             supplements.push({ id: supplement.id, kind: supplement.kind, delivered: false, reason: "abstained", rank: index + 1, token_cost: tokenCost });
         }
-        else if (charCount(text) + charCount(next) <= cap) {
+        else if (accountedChars + charCount(next) <= cap) {
             text += next;
+            accountedChars += charCount(next);
             supplements.push({ id: supplement.id, kind: supplement.kind, delivered: true, reason: "supplemental", rank: index + 1, token_cost: tokenCost });
         }
         else {
@@ -574,8 +712,10 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
     }
     for (const candidate of structuralCandidates) {
         const next = `- ${candidate.line}\n`;
-        if (charCount(text) + charCount(next) <= cap)
+        if (accountedChars + charCount(next) <= cap) {
             text += next;
+            accountedChars += charCount(next);
+        }
     }
     const staleCount = omitted.filter((item) => item.reason === "stale-provenance" || item.reason === "retired").length;
     const budgetCount = omitted.filter((item) => item.reason === "budget").length;
@@ -599,25 +739,85 @@ export function buildDeliveryEnvelope(ctx, options = {}) {
     ].filter(Boolean);
     if (notes.length) {
         const footer = `… ${notes.join(" ")}\n`;
-        if (charCount(text) + charCount(footer) <= cap)
+        if (accountedChars + charCount(footer) <= cap) {
             text += footer;
+            accountedChars += charCount(footer);
+        }
     }
-    if (!text.endsWith("\n") && charCount(text) < cap)
+    if (!text.endsWith("\n") && accountedChars < cap) {
         text += "\n";
+        accountedChars += 1;
+    }
     if (!blockingOverflow)
         text = fitText(text, cap);
     omitted.sort((left, right) => left.record_id.localeCompare(right.record_id) || left.reason.localeCompare(right.reason));
-    return {
+    const deliveredById = new Map(delivered.map((item) => [`${item.kind}:${item.record_id}`, item]));
+    const landscapeResources = (ctx.landscape?.resources ?? [])
+        .flatMap((selection) => {
+        const receipt = deliveredById.get(`resources:${selection.record.id}`);
+        if (!receipt)
+            return [];
+        return [{
+                ...selection,
+                rank: receipt.rank,
+                deliveryReason: "ranked",
+                required: false,
+                blocking: false,
+                provenanceStatus: "current",
+                tokenCost: receipt.token_cost,
+            }];
+    });
+    const landscapeRelationships = (ctx.landscape?.relationships ?? [])
+        .flatMap((selection) => {
+        const receipt = deliveredById.get(`relationships:${selection.record.id}`);
+        if (!receipt)
+            return [];
+        return [{
+                ...selection,
+                rank: receipt.rank,
+                deliveryReason: "ranked",
+                required: false,
+                blocking: false,
+                provenanceStatus: "current",
+                tokenCost: receipt.token_cost,
+            }];
+    });
+    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))
+            return [];
+        return [{
+                kind: item.kind,
+                recordId: item.record_id,
+                reason: item.reason,
+                detail: item.detail,
+            }];
+    });
+    const landscape = ctx.landscape && (landscapeResources.length > 0
+        || landscapeRelationships.length > 0
+        || landscapeOmissions.length > 0)
+        ? createLandscapeDeliveryFragment({
+            selection: ctx.landscape,
+            resources: landscapeResources,
+            relationships: landscapeRelationships,
+            omitted: landscapeOmissions,
+        })
+        : null;
+    return finalizeDeliveryEnvelope({
+        schema_version: DELIVERY_ENVELOPE_SCHEMA_VERSION,
         text,
         delivered,
         hypotheses,
         obligations,
         supplements,
         omitted,
+        landscape,
         budget_tokens: budget,
         used_chars: charCount(text),
+        accounted_chars: accountedChars,
         blocking_overflow: blockingOverflow,
         abstention,
-    };
+    });
 }
 //# sourceMappingURL=delivery.js.map