@davesheffer/hunch 1.20.0 → 1.20.2

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.20.0
+npm i -g @davesheffer/hunch@1.20.2
 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.20.0
+npm i -g @davesheffer/hunch@1.20.2
 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.19.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/extractors/git.js

@@ -592,12 +592,27 @@ export function commitAndPushHunch(hunchDir, message, opts) {
         else {
             run(["add", "--", "."]);
         }
-        // SAFETY BACKSTOP (critical — bug_overlay_clobber): a memory sync is PURELY ADDITIVE small
-        // JSON. If the staged set contains a DELETION, rename, or any non-.json file, hunchDir is NOT
-        // a clean overlay store — most dangerously, the overlay was never its own git repo so `git -C`
-        // walked UP to the PROJECT repo. Committing/pushing there would overwrite/delete the user's
-        // code (we shipped exactly this). Refuse hard: unstage and bail without committing or pushing.
-        const staged = stagedMemoryPaths(hunchDir, env);
+        // Snapshot replacement can remove stale per-record JSON. Only a push-capable
+        // private/shared store may stage those deletions: the publication boundary
+        // above has already proved that it is a standalone repository distinct from
+        // the protected code repository. `-u` is still scoped to this exact Hunch
+        // subtree, and the staged-set guard below admits only contained JSON deletes.
+        // Public stores retain the older no-deletion rule because they live inside
+        // the user's code repository.
+        if (opts.push !== false && !run([
+            "-c", `core.attributesFile=${gitNullDevice()}`,
+            "-c", "core.autocrlf=false",
+            "add", "-u", "--", ".",
+        ])) {
+            run(["reset", "-q", "--", "."]);
+            return null;
+        }
+        // SAFETY BACKSTOP (critical — bug_overlay_clobber): only contained JSON
+        // memory bytes may be committed. Renames, copies, type changes, local.json,
+        // derived artifacts and every path outside this exact Hunch subtree remain
+        // fail-closed. A deletion is admitted only for the already-proven standalone
+        // private/shared repository above; it can never delete protected source.
+        const staged = stagedMemoryPaths(hunchDir, env, opts.push !== false);
         if (staged === null) {
             try {
                 execFileSync("git", ["-C", hunchDir, "reset", "-q", "--", "."], { stdio: "ignore", env });
@@ -608,7 +623,7 @@ export function commitAndPushHunch(hunchDir, message, opts) {
             // stays on disk and the next flush's `git add .` sweeps it up. The overlay path
             // stays loud: there it signals the escaped-to-project-repo misconfiguration.
             if (opts.push !== false) {
-                console.error(`hunch: refusing to auto-commit memory at "${hunchDir}" — the staged change includes deletions or non-memory files, so this is not a clean overlay repo. Nothing was committed or pushed. (Use \`hunch shared --repo <url>\` so the overlay is its OWN git repo.)`);
+                console.error(`hunch: refusing to auto-commit memory at "${hunchDir}" — the staged change includes an unsafe deletion or non-memory file, so this is not a clean overlay repo. Nothing was committed or pushed. (Use \`hunch shared --repo <url>\` so the overlay is its OWN git repo.)`);
             }
             return null;
         }
@@ -744,7 +759,7 @@ export function headFileContent(root, rel) {
         return null;
     }
 }
-function stagedMemoryPaths(hunchDir, env) {
+function stagedMemoryPaths(hunchDir, env, allowMemoryDeletions = false) {
     let out = "";
     let prefix = "";
     try {
@@ -755,8 +770,11 @@ function stagedMemoryPaths(hunchDir, env) {
     }
     if (!prefix)
         return null; // a Hunch layout is a scoped subdirectory, never the whole repository
+    // Snapshot ID churn is semantically one delete plus one add. Disable Git's
+    // heuristic rename presentation so the exact paths remain independently
+    // auditable against the contained-memory rules below.
     try {
-        out = execFileSync("git", ["-C", hunchDir, "diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-status"], { encoding: "utf8", env });
+        out = execFileSync("git", ["-C", hunchDir, "diff", "--cached", "--no-ext-diff", "--no-textconv", "--no-renames", "--name-status"], { encoding: "utf8", env });
     }
     catch {
         return null;
@@ -772,8 +790,8 @@ function stagedMemoryPaths(hunchDir, env) {
         const path = (parts[parts.length - 1] ?? "").trim();
         if (path.includes(".hunch-commit.lock"))
             continue; // transient lock dir, never a record
-        if (!/^[AM]$/.test(status))
-            return null; // only Add / Modify — any D/R/C/T → not a memory sync
+        if (!/^[AMD]$/.test(status) || (status === "D" && !allowMemoryDeletions))
+            return null;
         const normalizedPath = path.replace(/\\/g, "/");
         if (!normalizedPath.startsWith(prefix))
             return null; // never bless another staged JSON file

package/package.json

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