@davesheffer/hunch 1.20.0-rc.6 → 1.20.1

package/README.md

@@ -171,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.1
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -186,7 +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.1
 git pull
 hunch init
 hunch doctor
@@ -234,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.20.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

@@ -83,7 +83,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 { compareCodeUnits } from "../core/canonicalOrder.js";
+import { MAX_LANDSCAPE_REFRESH_REVISIONS, planLandscapeAdoption, } from "../core/landscapeAdoption.js";
 import { discoverRepositoryLandscape } from "../extractors/landscapeDiscovery.js";
 import { checkConformance } from "../core/conformance.js";
 import { ConstitutionService, policyEvaluationEnvelope } from "../constitution/service.js";
@@ -2911,22 +2912,46 @@ landscapeCmd
     .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")
+    .option("--refresh-reviewed", "replace only byte-proven records from an older reviewed exact revision")
     .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...>");
+    if (opts.refreshReviewed && !opts.all)
+        return fail("--refresh-reviewed requires --all so the complete prior review can be proven");
     const { store, root } = storeFor();
     try {
         const discovery = discoverRepositoryLandscape(root, opts.ref);
+        const existingResources = store.recs("resources");
+        const existingRelationships = store.recs("edges");
+        const selectedHashes = new Set(opts.all
+            ? [...discovery.resources, ...discovery.relationships].map((candidate) => candidate.candidateHash)
+            : opts.candidate);
+        const selectedIds = new Set([...discovery.resources, ...discovery.relationships]
+            .filter((candidate) => selectedHashes.has(candidate.candidateHash))
+            .map((candidate) => candidate.record.id));
+        const previousRevisions = opts.refreshReviewed
+            ? [...new Set([...existingResources, ...existingRelationships]
+                    .filter((record) => selectedIds.has(record.id))
+                    .map((record) => record.currentness?.source_revision)
+                    .filter((revision) => Boolean(revision) && revision !== discovery.sourceRevision))]
+                .sort(compareCodeUnits)
+            : [];
+        if (previousRevisions.length > MAX_LANDSCAPE_REFRESH_REVISIONS) {
+            return fail(`reviewed refresh needs ${previousRevisions.length} prior revisions; the safe limit is ${MAX_LANDSCAPE_REFRESH_REVISIONS}`);
+        }
+        const previousDiscoveries = previousRevisions.map((revision) => discoverRepositoryLandscape(root, revision));
         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"),
+            existingResources,
+            existingRelationships,
+            refreshReviewed: opts.refreshReviewed,
+            previousDiscoveries,
         });
         for (const resource of plan.resourcesToWrite)
             store.putCapture("resources", resource);
@@ -2937,7 +2962,8 @@ landscapeCmd
             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}.`);
+        const refreshed = plan.refreshedResourceIds.length + plan.refreshedRelationshipIds.length;
+        console.log(`✓ accepted ${plan.receipt.acceptedResourceIds.length} resource(s) and ${plan.receipt.acceptedRelationshipIds.length} relationship(s); wrote ${plan.resourcesToWrite.length + plan.relationshipsToWrite.length} (${refreshed} refreshed), reused ${plan.receipt.reusedResourceIds.length + plan.receipt.reusedRelationshipIds.length}.`);
     }
     catch (error) {
         fail(error instanceof Error ? error.message : String(error));

package/dist/core/landscapeAdoption.js

@@ -5,6 +5,7 @@ export const LANDSCAPE_REVIEW_SCHEMA_VERSION = "hunch.landscape-review/1";
 export const LANDSCAPE_ADOPTION_RECEIPT_SCHEMA_VERSION = "hunch.landscape-adoption-receipt/1";
 const SHA256 = /^sha256:[a-f0-9]{64}$/;
 const MAX_SELECTIONS = 4_096;
+export const MAX_LANDSCAPE_REFRESH_REVISIONS = 16;
 function sortedUnique(values, label) {
     if (values.length > MAX_SELECTIONS)
         throw new Error(`landscape ${label} exceeds the bounded selection limit`);
@@ -168,6 +169,71 @@ function sameAcceptedCandidate(record, candidate, discoveryHash) {
     // when the entire reviewed record still equals the candidate-derived value.
     return landscapeContentHash(record) === landscapeContentHash(expected);
 }
+function previousDiscoveriesForRefresh(input) {
+    const previous = input.previousDiscoveries ?? [];
+    if (!input.refreshReviewed) {
+        if (previous.length > 0)
+            throw new Error("landscape previous discoveries require explicit reviewed refresh authority");
+        return new Map();
+    }
+    if (input.candidateHashes !== "all") {
+        throw new Error("landscape reviewed refresh requires the complete candidate set (--all)");
+    }
+    if (previous.length > MAX_LANDSCAPE_REFRESH_REVISIONS) {
+        throw new Error(`landscape reviewed refresh exceeds the bounded prior-revision proof limit (${MAX_LANDSCAPE_REFRESH_REVISIONS})`);
+    }
+    const byRevision = new Map();
+    for (const discovery of previous) {
+        assertLandscapeDiscoveryIntegrity(discovery);
+        if (discovery.repositoryRootIdentity !== input.discovery.repositoryRootIdentity) {
+            throw new Error("landscape reviewed refresh prior discovery belongs to a different repository");
+        }
+        if (discovery.sourceRevision === input.discovery.sourceRevision) {
+            throw new Error("landscape reviewed refresh requires an older exact discovery revision");
+        }
+        if (byRevision.has(discovery.sourceRevision)) {
+            throw new Error(`landscape reviewed refresh contains duplicate prior revision: ${discovery.sourceRevision}`);
+        }
+        byRevision.set(discovery.sourceRevision, discovery);
+    }
+    return byRevision;
+}
+function isProvenPreviousAdoption(record, previousDiscoveries) {
+    const sourceRevision = record.currentness?.source_revision;
+    if (!sourceRevision)
+        return false;
+    const previous = previousDiscoveries.get(sourceRevision);
+    if (!previous)
+        return false;
+    const candidates = record.schema === "hunch.resource/1"
+        ? previous.resources
+        : previous.relationships;
+    const candidate = candidates.find((value) => value.record.id === record.id);
+    if (!candidate || !sameAcceptedCandidate(record, candidate, previous.discoveryHash))
+        return false;
+    const reviewer = record.metadata.landscape_reviewed_by;
+    const reviewedAt = record.metadata.landscape_reviewed_at;
+    const reviewId = record.metadata.landscape_review_id;
+    if (typeof reviewer !== "string" || typeof reviewedAt !== "string" || typeof reviewId !== "string")
+        return false;
+    try {
+        const allCandidateHashes = [...previous.resources, ...previous.relationships]
+            .map((value) => value.candidateHash)
+            .sort(compareCodeUnits);
+        const reconstructed = reviewFor({
+            discovery: previous,
+            expectedDiscoveryHash: previous.discoveryHash,
+            reviewer,
+            reviewedAt,
+            candidateHashes: "all",
+            acknowledgeIssues: previous.issues.length > 0,
+        }, allCandidateHashes);
+        return reconstructed.reviewId === reviewId;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Convert an exact candidate discovery into a prevalidated write plan.
  *
@@ -208,6 +274,7 @@ export function planLandscapeAdoption(input) {
         }
     }
     const review = reviewFor(input, selectedCandidateHashes);
+    const previousDiscoveries = previousDiscoveriesForRefresh(input);
     const existingResources = new Map();
     for (const value of input.existingResources ?? []) {
         const record = ResourceSchema.parse(value);
@@ -226,13 +293,21 @@ export function planLandscapeAdoption(input) {
     const relationshipsToWrite = [];
     const reusedResourceIds = [];
     const reusedRelationshipIds = [];
+    const refreshedResourceIds = [];
+    const refreshedRelationshipIds = [];
     for (const candidate of selectedResources) {
         const existing = existingResources.get(candidate.record.id);
         if (existing) {
-            if (!sameAcceptedCandidate(existing, candidate, input.discovery.discoveryHash)) {
+            if (sameAcceptedCandidate(existing, candidate, input.discovery.discoveryHash)) {
+                reusedResourceIds.push(existing.id);
+            }
+            else if (input.refreshReviewed && isProvenPreviousAdoption(existing, previousDiscoveries)) {
+                resourcesToWrite.push(acceptedResource(candidate, input.discovery.discoveryHash, review));
+                refreshedResourceIds.push(existing.id);
+            }
+            else {
                 throw new Error(`landscape resource ${candidate.record.id} already exists with different reviewed content`);
             }
-            reusedResourceIds.push(existing.id);
         }
         else {
             resourcesToWrite.push(acceptedResource(candidate, input.discovery.discoveryHash, review));
@@ -241,10 +316,16 @@ export function planLandscapeAdoption(input) {
     for (const candidate of selectedRelationships) {
         const existing = existingRelationships.get(candidate.record.id);
         if (existing) {
-            if (!sameAcceptedCandidate(existing, candidate, input.discovery.discoveryHash)) {
+            if (sameAcceptedCandidate(existing, candidate, input.discovery.discoveryHash)) {
+                reusedRelationshipIds.push(existing.id);
+            }
+            else if (input.refreshReviewed && isProvenPreviousAdoption(existing, previousDiscoveries)) {
+                relationshipsToWrite.push(acceptedRelationship(candidate, input.discovery.discoveryHash, review));
+                refreshedRelationshipIds.push(existing.id);
+            }
+            else {
                 throw new Error(`landscape relationship ${candidate.record.id} already exists with different reviewed content`);
             }
-            reusedRelationshipIds.push(existing.id);
         }
         else {
             relationshipsToWrite.push(acceptedRelationship(candidate, input.discovery.discoveryHash, review));
@@ -266,6 +347,8 @@ export function planLandscapeAdoption(input) {
         receipt: { ...receiptUnsigned, receiptId },
         resourcesToWrite,
         relationshipsToWrite,
+        refreshedResourceIds: refreshedResourceIds.sort(compareCodeUnits),
+        refreshedRelationshipIds: refreshedRelationshipIds.sort(compareCodeUnits),
     };
 }
 //# sourceMappingURL=landscapeAdoption.js.map

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

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