@davesheffer/hunch 1.28.0 → 1.30.0

package/README.md

@@ -1,25 +1,27 @@
 # Hunch
 
-## Your repo remembers why — and teaches every coding agent how the project works.
+## Agents are probabilistic. Organizations need deterministic state. Hunch is the state layer between them.
 
 [![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)
 
-Every new AI coding session can read your code. It cannot automatically see why your team chose this design, which alternative already failed, what an odd-looking line protects, or how this repository expects work to be explained and reviewed.
+Every employee is getting an agent. Each one reads the code, the CRM, the mail thread, the chat, and forms its own opinion about what was decided, what was done and what is still owed. Two agents, two slightly different realities. Neither is wrong. Both are guesses, made fresh, from raw material.
 
-That is how settled decisions get reopened, fixed bugs return, and technically plausible changes arrive feeling foreign to the project.
+An organization cannot run on guesses. It runs on state: this was decided, this rule is in force, this action happened and was verified, this promise is due Thursday, this summary is current and rests on these sources. Hunch holds that state in git, refuses it when it contradicts, and delivers it to Claude, Codex, Cursor, Copilot, Windsurf, Antigravity and any other MCP client before the agent answers or edits.
 
-**Hunch is evidence-backed deterministic project intelligence for the AI coding tools you already use.** It gives Claude, Codex, Cursor, Copilot, Windsurf, Antigravity and other MCP clients the same durable understanding of your codebase:
+**Hunch started as engineering memory for coding agents** and still is: why the code is shaped this way, which alternative already failed, what an odd-looking line protects, what depends on the code about to change, and which trusted decisions, fixes and architectural boundaries a change must preserve. The same graph now holds organizational state for operations agents too (see [Deterministic organizational state](#deterministic-organizational-state)).
 
-- why the code is shaped this way;
-- how the repository communicates, reviews and builds;
-- what depends on the code about to change; and
-- which trusted decisions, fixes and architectural boundaries the result must preserve.
+## Why Hunch, not another memory layer
 
-For precise rules your team has explicitly trusted, the promise is **Never Twice**: an agent may propose a different direction, but it cannot quietly re-make a decided decision or re-introduce a fixed failure without Hunch surfacing the conflict and its evidence.
+Memory optimizes recall. State optimizes refusal. Hunch competes for the deterministic state layer from the organizational side, and every point below is a property you can verify in this repository rather than a claim:
 
-Memory starts advisory. Nothing blocks until a human deliberately trusts a precise rule and opts into strict enforcement.
+- **Git is the source of truth.** Every fact is a JSON file under `.hunch/`, every change a commit: diffable, PR-reviewable, revertable, mergeable, never locked in a vendor database. SQLite is only a derived index.
+- **Refusal, not convergence.** One live decision per topic. A second contradicting record is refused at write time with the incumbent named, and a supersede target must still be open. Diverging writes are not merged later.
+- **Organization drawers with a key per agent.** Repository, user, team and organization partitions; the bearer key resolves the principal and decides visibility before anything is looked up.
+- **Receipts and commitments are facts.** What was actually done in an external system, verified or not, and who owes what by when, readable by any agent with the key.
+- **Never Twice.** A human correction becomes an enforced rule, not a one-session memory. Nothing blocks until a human deliberately trusts a precise rule and opts into strict enforcement.
+- **The code spoke.** Decisions, constraints and bug lineage are checked against the code deterministically, with no model in the block path. No state-layer peer has it.
 
 ## Start in five minutes
 
@@ -144,19 +146,19 @@ hunch check --staged --strict
 
 Captured memory cannot silently hard-block on its own.
 
-## Deterministic organizational state — next product direction
+## Deterministic organizational state
 
-Repository memory solves one version of a larger problem.
+Repository memory solves one version of a larger problem, and since 1.25.0 Hunch ships the larger one.
 
 As organizations give every employee an agent that can work across CRM, email, messaging, repositories and other tools, the agents become probabilistic writers/readers of the same organization. If each one independently reconstructs what was decided, what was already done or what is still owed, the organization gets multiple conflicting realities.
 
-The active roadmap asks whether Hunch can become the deterministic state layer between those agents and the organization:
+Hunch is the deterministic state layer between those agents and the organization:
 
 > **Agents are probabilistic. Organizations need deterministic state. Hunch is the state layer between them.**
 
 The target is **one product, one authorized state graph and one versioned state contract** across repository, user, team and organization scopes.
 
-Planned state includes:
+The state it holds:
 
 - decisions currently in force;
 - verified action receipts / what was done;
@@ -203,7 +205,15 @@ user:david --root <dir> --principal sofia@david` declares a partition and mints
 client is `import { createStateClient } from "@davesheffer/hunch/state"`. This folds the separate
 Hunch Memory service into Hunch.
 
-Read [Deterministic organizational state](docs/deterministic-state.md) and the [roadmap](ROADMAP.md).
+As of 1.27.0 a fourth verb, `records`, lists a subject's records for the first writers, and the per-scope ledger compacts and merges across clones. As of 1.28.0 reads are a union across writers, a supersede target must still be open (two racing writers can no longer leave two current records), state records are searchable and delivered by subject, and subjects are keyed by the external record rather than by the agent. Proven on an emulated organization: three agents over ten clinics and a generated year of mail, chat and CRM, one organization drawer, 96 cited summaries, 24 verified receipts, 24 commitments, zero contradictions.
+
+<<<<<<< HEAD
+As of 1.30.0 subject identity is by external reference: one active entity per external record per partition, a subject written as an entity's external key refused with the entity id named, reads resolving one explicit hop — so two agents over one CRM record land on one subject. Replay determinism is a check, not a claim: `hunch serve replay --partition <kind:id>` (or `--root <dir>`) folds a partition's ledger into the state it implies and compares it hash for hash to the records on file, exits 1 on any divergence, and runs on every agent-farm run; and a human correction outranks later agent writes — a record a human confirmed is never overwritten or superseded by an agent or service principal (replay, stale-with-cause and closure by receipt are the only agent moves, each keeping the human's provenance).
+=======
+As of 1.30.0 replay determinism is a check, not a claim: `hunch serve replay --partition <kind:id>` (or `--root <dir>`) folds a partition's ledger into the state it implies and compares it hash for hash to the records on file, exits 1 on any divergence, runs inside `hunch drift` when the partition has a ledger, and runs on every agent-farm run; and a human correction outranks later agent writes — a record a human confirmed is never overwritten or superseded by an agent or service principal (replay, stale-with-cause and closure by receipt are the only agent moves, each keeping the human's provenance).
+>>>>>>> feat/replay-determinism
+
+Read [Deterministic organizational state](docs/deterministic-state.md), the [roadmap](ROADMAP.md) and the dated [competitive landscape](docs/competitive-landscape.md).
 
 ### Naming
 
@@ -216,7 +226,7 @@ The current release can keep a team's **repository-scoped** memory in a dedicate
 Today Hunch does not host that shared Git repository; teammates/CI use normal Git access and one maintainer connects it:
 
 ```bash
-npm i -g @davesheffer/hunch@1.23.3
+npm i -g @davesheffer/hunch@1.28.0
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -226,7 +236,7 @@ git push
 Teammates then install the same version and run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.23.3
+npm i -g @davesheffer/hunch@1.28.0
 git pull
 hunch init
 hunch doctor
@@ -264,9 +274,11 @@ See the [changelog](CHANGELOG.md) for release detail and the [roadmap](ROADMAP.m
 
 - [Full documentation](https://www.hunchmemory.com/docs)
 - [Copy-paste cookbook](https://www.hunchmemory.com/cookbook)
+- [Turn PR review threads into scoped review rules](docs/review-memory.md)
 - [Deterministic organizational state](docs/deterministic-state.md)
 - [Project DNA](docs/project-dna.md)
 - [Native change proof](docs/change-proof.md)
+- [The autonomy ladder](docs/autonomy-ladder.md)
 - [Engineering Landscape Graph](docs/engineering-landscape.md)
 - [Hunch roadmap](ROADMAP.md)
 - [VS Code extension](vscode-extension/README.md)

package/dist/cli/index.js

@@ -27,6 +27,7 @@ import { HUNCH_VERSION } from "../core/version.js";
 import { registerIntegrationCommands } from "./integrations.js";
 import { registerServeCommands } from "./serve.js";
 import { registerUpdateCommand } from "./update.js";
+import { registerReviewMemoryCommands } from "./reviewMemory.js";
 import { inspectIntegrations, formatIntegrationHealth, integrationHealthFails, integrationSessionWarning } from "../integrations/health.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { JsonStore } from "../store/jsonStore.js";
@@ -45,15 +46,16 @@ import { deriveForbids, effectiveForbids } from "../core/constraintmatch.js";
 import { extractInlineIntent } from "../extractors/comments.js";
 import { renderText, renderMarkdown, renderSarif, renderImpact, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, isReviewDraft, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
-import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
+import { installPostCommitHook, installPreCommitHook, installPostMergeHook } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
 import { flushCapture, flushMemoryHome, flushMemoryHomes, pinSharedRemote, sharedRemoteFor } from "../integrations/sync.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS } from "../integrations/gitignore.js";
 import { writeCiWorkflow } from "../integrations/ciAction.js";
-import { updateClaudeMd } from "../integrations/claudemd.js";
+import { updateClaudeMd, renderHunchSection } from "../integrations/claudemd.js";
+import { classifyGroundingBlock, describeGroundingFreshness } from "../core/groundingLag.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
-import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refreshCommittableGrounding } from "../integrations/providers.js";
+import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding, refreshCommittableGrounding, GROUNDING_DOC_PATHS } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 import { formatContext, formatSearchHit, formatStructure } from "../core/format.js";
 import { isStateKind, renderStateLine, stateSupplements } from "../core/stateDelivery.js";
@@ -107,6 +109,10 @@ import { draftTripwires, knownRepoDeps } from "../synthesis/tripwires.js";
 import { constraintId } from "../core/ids.js";
 import { readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
 import { mergeHunchJson } from "../store/merge.js";
+import { ledgerFile } from "../store/changeLedger.js";
+import { verifyReplay } from "../store/replay.js";
+import { partitionOf, stateHomeFor } from "../store/stateBinding.js";
+import { scopePath } from "../core/stateContract.js";
 import { movePublicMemoryToPrivate } from "../store/privateMigrate.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { planCompaction } from "../store/compact.js";
@@ -117,6 +123,28 @@ program.name("hunch").description("Hunch — engineering memory and a determinis
 registerIntegrationCommands(program);
 registerServeCommands(program);
 registerUpdateCommand(program);
+registerReviewMemoryCommands(program, (records, repository, privateOnly) => {
+    const { store, root } = storeFor();
+    if (!repositoryUsesRemote(root, `https://github.com/${repository}.git`)) {
+        throw new Error("review packet repository does not match this checkout's remotes");
+    }
+    const home = store.captureHome(privateOnly);
+    // Preflight the whole batch. A repeated import must never revive a retired rule,
+    // replace a countersigned constraint, or change its scope/evidence silently.
+    for (const record of records) {
+        if (!existsSync(join(root, record.scope[0])))
+            throw new Error(`review scope ${record.scope[0]} no longer exists; review the current code before capturing this rule`);
+        const existing = store.recs("constraints").find(r => r.id === record.id);
+        if (existing)
+            throw new Error(`constraint ${record.id} already exists; use the existing correction review flow to change it`);
+    }
+    for (const record of records)
+        store.putCapture("constraints", record, privateOnly);
+    store.reindex();
+    if (home === "public" && !store.autoCommit)
+        refreshExistingGrounding(root, store);
+    pumpMemoryHome(store, root, home, `hunch: capture ${records.length} sourced review rule(s)`);
+});
 let openStore = null;
 function openTeamStore(root, opts = {}) {
     // A committed team.json is an explicit declaration that this checkout belongs
@@ -282,6 +310,8 @@ program
         console.log(`  ✓ post-commit hook ${h.action} (learning loop)${syncToOverlay ? " — syncs to the shared overlay" : ""}${opts.autoCommit ? " — auto-commit on" : ""}`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
+        const pm = installPostMergeHook(root, inv.shell);
+        console.log(`  ✓ post-merge hook ${pm.action} (re-syncs grounding docs after a merge that brought memory in)`);
         // Auto-install the pre-commit guard by default (advisory: flags invariants
         // touched directly OR via blast radius, never blocks). Opt out with
         // --no-enforce; --enforce-strict makes blocking near/direct hits fail the commit.
@@ -466,7 +496,7 @@ program
         pumpMemoryHome(store, root, home, `hunch: backfill ${written} decision(s)`);
     // Honest tally of where the tokens went: trivial commits are seeded by the
     // free deterministic heuristic, only substantive ones spend the LLM.
-    console.log(`Done: ${written} decision(s) seeded (${llm} via LLM, ${heuristic} heuristic), ${skipped} skipped (trivial/non-code/already-captured).`);
+    console.log(`Done: ${written} decision(s) seeded (${llm} via LLM, ${heuristic} heuristic), ${skipped} skipped (trivial/not substantive/already-captured).`);
     store.close();
 });
 // ---- sync (post-commit hook) ----------------------------------------------
@@ -5445,27 +5475,110 @@ program
 // ---- drift (doc≠graph detector; advisory + CI-gateable) -------------------
 program
     .command("drift")
-    .description("Detect memory drift: dead refs, dangling supersedes, stale 'proposed' docs, doc≠graph anchor-stale (a file still anchored to a superseded decision), and markdown sections whose <!-- hunch:topic … dec_id --> pin points at a superseded or missing decision (AGENTS.md/CLAUDE.md as a drift surface). Exits non-zero on any anchor-stale drift or topic collision — the doc≠graph gate.")
+    .description("Detect memory drift: dead refs, dangling supersedes, stale 'proposed' docs, doc≠graph anchor-stale (a file still anchored to a superseded decision), markdown sections whose <!-- hunch:topic … dec_id --> pin points at a superseded or missing decision (AGENTS.md/CLAUDE.md as a drift surface), and ledger≠records replay divergence when this partition has a change ledger. Exits non-zero on any anchor-stale drift, topic collision or replay divergence — the doc≠graph and ledger≠records gate.")
     .action(() => {
     const { store, root } = storeFor();
     try {
         const { findings } = computeDrift(store, root);
         const collisions = topicCollisions(store.recs("decisions"));
-        if (!findings.length && collisions.size === 0) {
-            console.log("✓ No drift — memory is in sync with the code/docs.");
+        // ledger≠records: when the partition this store IS has a change ledger, its records must be
+        // exactly what the ledger implies (nuryel.replay/1). No ledger, nothing to check.
+        const own = partitionOf(store);
+        const replay = existsSync(ledgerFile(stateHomeFor(store, own).hunchDir, own)) ? verifyReplay(store, own) : null;
+        const replayFailing = replay ? replay.divergences.filter((d) => d.kind !== "legacy-drift") : [];
+        const replayCount = replay && !replay.ok ? Math.max(1, replayFailing.length) : 0;
+        if (!findings.length && collisions.size === 0 && !replayCount) {
+            console.log(`✓ No drift — memory is in sync with the code/docs.${replay ? ` Replay OK: ${scopePath(own)} ledger head ${replay.ledger.head_seq}, ${replay.records.verified + replay.records.verified_by_idempotency} record(s) verified.` : ""}`);
             return;
         }
         for (const f of findings.slice(0, 50))
             console.log(`· [${f.kind}] ${f.id} — ${f.detail}`);
         for (const [topic, decs] of collisions)
             console.log(`· [topic-collision] "${topic}" has ${decs.length} live decisions: ${decs.map((d) => d.id).join(", ")} — run \`hunch reconcile-topics\``);
+        for (const d of replay?.divergences ?? [])
+            console.log(`· [replay-${d.kind}] ${d.record_id} — ${d.detail}`);
+        if (replayCount && !replayFailing.length)
+            console.log(`· [replay-fingerprint] ${scopePath(own)}: ledger fold ${replay.replay_hash} ≠ stored ${replay.stored_hash}`);
         const anchor = findings.filter((f) => f.kind === "anchor-stale" || f.kind === "doc-anchor-stale").length;
-        console.log(`\n${findings.length} finding(s)${anchor ? `, ${anchor} doc≠graph (anchor-stale)` : ""}${collisions.size ? `, ${collisions.size} topic-collision(s)` : ""}.`);
-        if (anchor || collisions.size)
+        console.log(`\n${findings.length + replayCount} finding(s)${anchor ? `, ${anchor} doc≠graph (anchor-stale)` : ""}${collisions.size ? `, ${collisions.size} topic-collision(s)` : ""}${replayCount ? `, ${replayCount} ledger≠records (replay: hunch serve replay --root .)` : ""}.`);
+        if (anchor || collisions.size || replayCount)
+            process.exitCode = 1;
+    }
+    finally {
+        store.close();
+    }
+});
+// ---- grounding (the committed grounding docs vs the PUBLIC graph) -------------
+const GROUNDING_START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
+const GROUNDING_END = "<!-- HUNCH:END -->";
+function groundingBlockContent(text) {
+    const i = text.indexOf(GROUNDING_START);
+    const j = text.indexOf(GROUNDING_END);
+    if (i === -1 || j === -1 || j < i)
+        return null;
+    return text.slice(i + GROUNDING_START.length, j).trim();
+}
+program
+    .command("grounding")
+    .description("Check the committed grounding docs (CLAUDE.md, AGENTS.md, copilot-instructions, hunch.mdc, hunch.md) against what the PUBLIC graph generates — direction-aware: counts that merely LAG a merge are reported, counts AHEAD of the store (a record never committed) or divergent prose fail. --refresh regenerates every existing doc from the public store (never the overlay union, never a doc the project lacks). Exits 1 on ahead/diverged unless refreshed.")
+    .option("--refresh", "regenerate the existing grounding docs from the public store (what the post-merge hook and the release remedy run)")
+    .option("--json", "machine-readable verdicts")
+    .option("--quiet", "print nothing on success")
+    .action((opts) => {
+    const root = findRoot();
+    // PUBLIC-ONLY by construction, exactly as the release gate and the freshness test
+    // read it: HUNCH_PRIVATE_DIR at an empty overlay beats .hunch/local.json and the
+    // shared pointer, so a dev machine with an overlay attached can never write union
+    // counts into a committed public doc.
+    const emptyPrivate = mkdtempSync(join(tmpdir(), "hunch-grounding-public-"));
+    const prior = process.env.HUNCH_PRIVATE_DIR;
+    process.env.HUNCH_PRIVATE_DIR = emptyPrivate;
+    const store = new HunchStore(hunchPaths(root));
+    try {
+        const rendered = renderHunchSection(store, root);
+        const generated = groundingBlockContent(rendered) ?? rendered.trim();
+        const verdicts = GROUNDING_DOC_PATHS.map((rel) => {
+            const file = join(root, ...rel.split("/"));
+            if (!existsSync(file))
+                return { doc: rel, verdict: { kind: "absent" } };
+            const committed = groundingBlockContent(readFileSync(file, "utf8"));
+            if (committed === null)
+                return { doc: rel, verdict: { kind: "diverged", reason: "no managed HUNCH block" } };
+            return { doc: rel, verdict: classifyGroundingBlock(committed, generated) };
+        });
+        const refreshed = opts.refresh ? refreshExistingGrounding(root, store) : [];
+        const failing = verdicts.filter((v) => v.verdict.kind === "ahead" || v.verdict.kind === "diverged");
+        const lagging = verdicts.filter((v) => v.verdict.kind === "lagging");
+        if (opts.json) {
+            console.log(JSON.stringify({ docs: verdicts, refreshed, ok: opts.refresh ? true : failing.length === 0 }, null, 2));
+        }
+        else if (opts.refresh) {
+            if (!opts.quiet)
+                console.log(refreshed.length ? `grounding refreshed: ${refreshed.join(", ")}` : "grounding already fresh — nothing to regenerate");
+        }
+        else {
+            for (const v of verdicts) {
+                if (v.verdict.kind === "absent")
+                    continue;
+                if (v.verdict.kind === "fresh" && opts.quiet)
+                    continue;
+                console.log(`${v.verdict.kind === "fresh" ? "✓" : v.verdict.kind === "lagging" ? "·" : "✗"} ${describeGroundingFreshness(v.doc, v.verdict)}`);
+            }
+            if (!opts.quiet && !failing.length) {
+                console.log(lagging.length
+                    ? `\n${lagging.length} doc(s) lag a merge — transient; the next capture commit or \`hunch grounding --refresh\` heals it.`
+                    : "✓ grounding docs are fresh.");
+            }
+        }
+        if (!opts.refresh && failing.length)
             process.exitCode = 1;
     }
     finally {
         store.close();
+        process.env.HUNCH_PRIVATE_DIR = prior;
+        if (prior === undefined)
+            delete process.env.HUNCH_PRIVATE_DIR;
+        rmSync(emptyPrivate, { recursive: true, force: true });
     }
 });
 // ---- findings (the open-observations ledger) --------------------------------

package/dist/cli/reviewMemory.js

@@ -0,0 +1,32 @@
+import { readFileSync, statSync } from "node:fs";
+import { prepareReviewMemory, compileReviewRules, validateReviewPacket } from "../core/reviewMemory.js";
+function readJson(file) {
+    if (statSync(file).size > 16 * 1024 * 1024)
+        throw new Error("review input exceeds 16 MiB");
+    return JSON.parse(readFileSync(file, "utf8"));
+}
+export function registerReviewMemoryCommands(program, capture) {
+    const command = program.command("review-memory").description("Turn sourced PR review threads into scoped review rules");
+    command.command("prepare").requiredOption("--from <file>", "GitHub REST review comments JSON")
+        .requiredOption("--repository <owner/repo>", "repository that owns every comment")
+        .description("Print a deterministic evidence packet; no rules are activated")
+        .action((opts) => {
+        console.log(JSON.stringify(prepareReviewMemory(opts.repository, readJson(opts.from)), null, 2));
+    });
+    command.command("capture").requiredOption("--from <file>", "prepared evidence packet")
+        .requiredOption("--rules <file>", "explicit selections: candidate_id, evidence_hash, rule, check")
+        .option("--apply", "persist the previewed rules as advisory constraints")
+        .option("--private", "keep rules and source links in the configured private overlay")
+        .option("--public", "allow rules and source links into repository-visible memory")
+        .description("Preview selected rules; --apply records them without blocking authority")
+        .action((opts) => {
+        if (opts.apply && !!opts.private === !!opts.public)
+            throw new Error("--apply requires exactly one of --private or --public");
+        const packet = validateReviewPacket(readJson(opts.from));
+        const records = compileReviewRules(packet, readJson(opts.rules), new Date().toISOString());
+        if (opts.apply)
+            capture(records, packet.repository, !!opts.private);
+        console.log(JSON.stringify({ applied: !!opts.apply, authority: "advisory", rules: records }, null, 2));
+    });
+}
+//# sourceMappingURL=reviewMemory.js.map

package/dist/cli/serve.js

@@ -2,6 +2,10 @@ import { resolve } from "node:path";
 import { createServeApp } from "../serve/app.js";
 import { initServeConfig, partitionFor, readServeConfig } from "../serve/config.js";
 import { compactLedger } from "../store/changeLedger.js";
+import { HunchStore } from "../store/hunchStore.js";
+import { hunchPaths } from "../core/paths.js";
+import { partitionOf } from "../store/stateBinding.js";
+import { formatReplayReport, verifyReplay } from "../store/replay.js";
 import { join } from "node:path";
 import { ScopeSchema, scopePath } from "../core/stateContract.js";
 import { HUNCH_VERSION } from "../core/version.js";
@@ -55,6 +59,46 @@ export function registerServeCommands(program) {
         }
         console.log(result.dropped ? `${scopePath(scope)}: dropped ${result.dropped} event(s); floor ${result.floor_seq}, head ${result.head_seq}` : `${scopePath(scope)}: nothing to compact (${result.head_seq - result.floor_seq} events retained)`);
     });
+    serve.command("replay")
+        .description("Replay determinism check: fold a partition's change ledger into the state it implies and compare it, hash for hash, to the records on file. Exits 1 on any divergence — wire into CI.")
+        .option("--partition <kind:id>", "the served partition to verify (from --config); omit with --root")
+        .option("--root <dir>", "verify the partition a directory IS (its .hunch/partition.json, or the repository) without a serve config")
+        .option("--json", "machine-readable report (nuryel.replay/1)")
+        .action((opts) => {
+        let root;
+        let scope;
+        if (opts.root) {
+            root = resolve(opts.root);
+            const probe = new HunchStore(hunchPaths(root));
+            try {
+                scope = opts.partition ? parseScopeArg(opts.partition) : partitionOf(probe);
+            }
+            finally {
+                probe.close();
+            }
+        }
+        else {
+            if (!opts.partition)
+                throw new Error("pass --partition kind:id (with a serve config) or --root <dir>");
+            const parent = serve.opts();
+            const config = readServeConfig(resolve(parent.config ?? DEFAULT_CONFIG));
+            scope = parseScopeArg(opts.partition);
+            const partition = partitionFor(config, scope);
+            if (!partition)
+                throw new Error(`this config does not serve ${scopePath(scope)}`);
+            root = partition.root;
+        }
+        const store = new HunchStore(hunchPaths(root));
+        try {
+            const report = verifyReplay(store, scope);
+            console.log(opts.json ? JSON.stringify(report) : formatReplayReport(report));
+            if (!report.ok)
+                process.exitCode = 1;
+        }
+        finally {
+            store.close();
+        }
+    });
     serve.command("init")
         .description("Declare a partition directory and mint a principal token (printed once; only its hash is stored)")
         .requiredOption("--partition <kind:id>", "the scope this directory IS, e.g. user:david or organization:acme")

package/dist/core/groundingLag.js

@@ -0,0 +1,82 @@
+/**
+ * Grounding-block freshness classification (fnd_c402046ac7).
+ *
+ * The committed grounding docs (CLAUDE.md, AGENTS.md, copilot-instructions,
+ * hunch.mdc, hunch.md) carry a managed block whose first sentence states the
+ * public store's RECORD COUNTS. Those counts are a pure function of .hunch/*.json,
+ * so two branches that each capture one decision both regenerate the very same
+ * "N+1 decisions" line. Git merges identical lines silently, the merged store holds
+ * N+2, and the committed doc is one behind — with no conflict, no hook (the merge
+ * happened on the forge) and no human error. Every release-gate red of that class
+ * (PR #128, #135, v1.26.2's first run) was this lag.
+ *
+ * The lag is transient and self-healing: the next capture commit folds the
+ * regenerated docs in (refreshCommittableGrounding), and the release gate's
+ * repository-index stage regenerates them in the worktree and already treats the
+ * dirt as memory churn. What must STILL fail is a doc that is genuinely wrong:
+ *
+ *   - prose in the block differs (a hand edit, a stale renderer, a template change);
+ *   - an append-only count is AHEAD of the store: the doc counted a record the
+ *     repository does not carry — the never-committed Video component of
+ *     fnd_6391b4242f, the only defect the counts ever caught.
+ *
+ * So the rule is direction-aware and deterministic: decisions, bugs, constraints,
+ * components and policies only accrue, so a doc may lag behind them (merge) but never
+ * run ahead (missing record). Open findings move both ways (a finding resolved on one
+ * branch, a finding recorded on another), so a differing findings count alone is lag.
+ */
+const COUNTS_RE = /\*\*(\d+) decisions?, (\d+) bugs?, (\d+) constraints?, (\d+) components?, (\d+) polic(?:y|ies)(?:, (\d+) open findings?)?\*\*/;
+/** Record kinds whose committed count may only ever lag behind the store. */
+export const APPEND_ONLY_COUNT_KINDS = ["decisions", "bugs", "constraints", "components", "policies"];
+export function parseGroundingCounts(block) {
+    const m = COUNTS_RE.exec(block);
+    if (!m)
+        return null;
+    return {
+        match: m[0],
+        counts: {
+            decisions: Number(m[1]),
+            bugs: Number(m[2]),
+            constraints: Number(m[3]),
+            components: Number(m[4]),
+            policies: Number(m[5]),
+            findings: m[6] === undefined ? 0 : Number(m[6]),
+        },
+    };
+}
+/** Classify a committed managed block against the one the graph generates NOW.
+ *  Both inputs are block CONTENT (markers stripped, trimmed). */
+export function classifyGroundingBlock(committed, generated) {
+    if (committed === generated)
+        return { kind: "fresh" };
+    const c = parseGroundingCounts(committed);
+    const g = parseGroundingCounts(generated);
+    if (!c)
+        return { kind: "diverged", reason: "the committed block carries no record-counts sentence" };
+    if (!g)
+        return { kind: "diverged", reason: "the generated block carries no record-counts sentence" };
+    const withoutCounts = (text, match) => text.replace(match, "<counts>");
+    if (withoutCounts(committed, c.match) !== withoutCounts(generated, g.match)) {
+        return { kind: "diverged", reason: "the block differs outside the record-counts sentence" };
+    }
+    const ahead = APPEND_ONLY_COUNT_KINDS.filter((k) => c.counts[k] > g.counts[k]);
+    if (ahead.length)
+        return { kind: "ahead", committed: c.counts, generated: g.counts, ahead };
+    const behind = Object.keys(g.counts).filter((k) => c.counts[k] !== g.counts[k]);
+    return { kind: "lagging", committed: c.counts, generated: g.counts, behind };
+}
+/** One human line per verdict — shared by the freshness test and `hunch grounding`. */
+export function describeGroundingFreshness(doc, verdict) {
+    const delta = (a, b, kinds) => kinds.map((k) => `${k} ${a[k]} → ${b[k]}`).join(", ");
+    switch (verdict.kind) {
+        case "fresh":
+            return `${doc}: fresh`;
+        case "lagging":
+            return `${doc}: counts lag the store (${delta(verdict.committed, verdict.generated, verdict.behind)}) — records merged in behind the doc; heals on the next capture or \`hunch grounding --refresh\``;
+        case "ahead":
+            return `${doc}: counts run AHEAD of the store (${delta(verdict.committed, verdict.generated, verdict.ahead)}) — the doc counted a record this repository does not carry; commit the missing .hunch/ record or regenerate`;
+        case "diverged":
+            return `${doc}: stale — ${verdict.reason}; regenerate with \`hunch grounding --refresh\` and commit`;
+    }
+}
+//# sourceMappingURL=groundingLag.js.map

package/dist/core/reviewMemory.js

@@ -0,0 +1,100 @@
+/** Review text is evidence, never executable instructions or policy authority. */
+import { z } from "zod";
+import { canonicalHash } from "../constitution/canonical.js";
+import { buildCorrectionConstraint } from "./correction.js";
+const repositorySchema = z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/);
+const pathSchema = z.string().min(1).max(500).refine(p => !p.startsWith("/") && !/[\\:*?\[\]{}\x00-\x1f]/.test(p)
+    && p.split("/").every(part => part !== ".." && part !== "." && part !== ""), "expected a literal repository-relative file");
+const commentSchema = z.object({
+    id: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    body: z.string().trim().min(1).max(32000),
+    path: pathSchema,
+    html_url: z.string().url(),
+    commit_id: z.string().regex(/^[a-f0-9]{40,64}$/),
+    created_at: z.string().datetime({ offset: true }),
+    updated_at: z.string().datetime({ offset: true }),
+    in_reply_to_id: z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional(),
+    user: z.object({ login: z.string().min(1).max(100), type: z.enum(["User", "Bot"]) }),
+});
+/** Accept GitHub REST review-comment exports, including gh --paginate --slurp pages. */
+export function prepareReviewMemory(repository, input) {
+    repositorySchema.parse(repository);
+    if (!Array.isArray(input))
+        throw new Error("expected a GitHub review-comment array");
+    const comments = z.array(commentSchema).max(10000).parse(input.flat());
+    const unique = new Map();
+    for (const comment of comments) {
+        const url = new URL(comment.html_url);
+        if (url.origin !== "https://github.com" || url.username || url.password || url.search
+            || !new RegExp(`^/${repository.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/pull/[1-9][0-9]*$`, "i").test(url.pathname)
+            || url.hash !== `#discussion_r${comment.id}`)
+            throw new Error(`comment ${comment.id} does not belong to ${repository}`);
+        const previous = unique.get(comment.id);
+        if (previous && canonicalHash(previous) !== canonicalHash(comment))
+            throw new Error(`conflicting versions of comment ${comment.id}`);
+        unique.set(comment.id, comment);
+    }
+    const groups = new Map();
+    let excluded = 0;
+    for (const comment of unique.values()) {
+        if (comment.user.type === "Bot") {
+            excluded++;
+            continue;
+        }
+        const rootId = comment.in_reply_to_id ?? comment.id;
+        const group = groups.get(rootId) ?? [];
+        group.push(comment);
+        groups.set(rootId, group);
+    }
+    const candidates = [];
+    for (const [rootId, group] of groups) {
+        // Do not misrepresent a reply as the original request when an export is partial.
+        const root = group.find(comment => comment.id === rootId && !comment.in_reply_to_id);
+        if (!root)
+            throw new Error(`missing human root comment ${rootId}; export the complete thread`);
+        if (group.some(comment => comment.path !== root.path || new URL(comment.html_url).pathname !== new URL(root.html_url).pathname)) {
+            throw new Error(`inconsistent thread ${rootId}`);
+        }
+        group.sort((a, b) => a.id - b.id);
+        const evidenceHash = canonicalHash({ repository: repository.toLowerCase(), comments: group });
+        candidates.push({ id: `review_${rootId}`, evidence_hash: evidenceHash, file: root.path, comments: group });
+    }
+    candidates.sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    return { schema: "hunch.review-memory/1", repository: repository.toLowerCase(), authority: "none", candidates, excluded_bots: excluded };
+}
+export function validateReviewPacket(input) {
+    const packet = z.object({
+        schema: z.literal("hunch.review-memory/1"), repository: repositorySchema,
+        authority: z.literal("none"), excluded_bots: z.number().int().nonnegative(),
+        candidates: z.array(z.object({ id: z.string(), evidence_hash: z.string(), file: pathSchema, comments: z.array(commentSchema).min(1) }).strict()).max(10000),
+    }).strict().parse(input);
+    const rebuilt = prepareReviewMemory(packet.repository, packet.candidates.flatMap(c => c.comments));
+    if (canonicalHash(rebuilt.candidates) !== canonicalHash(packet.candidates))
+        throw new Error("review packet evidence hash or membership changed; prepare it again");
+    return packet;
+}
+/** A separate, explicit selection supplies the actual rule and how to check it. */
+export function compileReviewRules(packetInput, selections, now) {
+    const packet = validateReviewPacket(packetInput);
+    const rules = z.array(z.object({
+        candidate_id: z.string(), evidence_hash: z.string(),
+        rule: z.string().trim().min(10).max(2000),
+        check: z.string().trim().min(10).max(4000),
+    }).strict()).min(1).max(100).parse(selections);
+    const results = rules.map(selection => {
+        const candidate = packet.candidates.find(c => c.id === selection.candidate_id);
+        if (!candidate || candidate.evidence_hash !== selection.evidence_hash)
+            throw new Error(`stale or missing review selection ${selection.candidate_id}`);
+        const record = buildCorrectionConstraint({ rule: selection.rule, scope_hint_file: candidate.file,
+            severity: "warning", vouched: false, rationale: `Review check: ${selection.check}` }, now);
+        // Prose cannot silently create a regex/import matcher or earn a human signature.
+        record.forbids = null;
+        record.provenance.evidence = [packet.repository, candidate.id, candidate.evidence_hash,
+            ...candidate.comments.flatMap(c => [c.html_url, `git:${c.commit_id}`])];
+        return record;
+    });
+    if (new Set(results.map(r => r.id)).size !== results.length)
+        throw new Error("duplicate rule statements; select one thread per rule");
+    return results;
+}
+//# sourceMappingURL=reviewMemory.js.map

package/dist/core/stateContract.js

@@ -28,6 +28,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import { compareCodeUnits } from "./canonicalOrder.js";
 import { DELIVERY_PROFILES } from "./delivery.js";
+import { isHumanConfirmed as sourceIsHumanConfirmed } from "./strictgate.js";
 import { ScopeSchema, scopePath, DependencyRefSchema, ExternalRefSchema, RECEIPT_SCHEMA_VERSION, COMMITMENT_SCHEMA_VERSION, DERIVED_SCHEMA_VERSION, ENTITY_SCHEMA_VERSION, RELATIONSHIP_SCHEMA_VERSION, } from "./stateRecords.js";
 export * from "./stateRecords.js";
 export const STATE_CONTRACT_VERSION = "nuryel.state/1";
@@ -113,6 +114,10 @@ export const WriteRequestSchema = z.object({
     idempotency_key: z.string().min(8).max(256),
     expected_version: z.union([z.string().max(256), z.number().int().nonnegative()]).nullable().default(null),
     supersedes: z.string().max(2048).optional(),
+    /** Why this write happened, when it is not the writer's own doing (additive): an external
+     *  source moved. A derived record written back as `stale` with this cause emits an
+     *  `invalidated` change naming the pointer — the `changed` facet, finally written by someone. */
+    cause: z.object({ kind: z.literal("external"), ref: ExternalRefSchema }).strict().optional(),
 }).strict();
 export const DURABILITY = ["pushed", "committed", "local"];
 export const WriteResultSchema = z.object({
@@ -230,8 +235,17 @@ export const STATE_INVARIANTS = [
     { id: "one-live-decision-per-topic", statement: "A second live decision on a topic is refused with the incumbent named; supersession is explicit." },
     { id: "external-truth-stays-external", statement: "External systems remain authoritative for their own content; Nuryel holds credential-free pointers, versions and hashes, never mirrored bodies." },
     { id: "derived-state-carries-dependencies", statement: "A derived statement without dependencies cannot be invalidated and is therefore not state." },
+    { id: "one-entity-per-external-ref", statement: "One external record is one entity in a partition: a second active entity carrying an external key an incumbent already carries is refused with the incumbent named, and a subject written as that record's external key is refused with the entity's id named. Identity is explicit refs, never similarity; merge is explicit — a retired entity names the survivor in `merged_into`, the ledger holds the `retired` event, nothing under the old id is rewritten and reads resolve to the survivor — and split is the explicit reverse; never a silent rewrite." },
+    { id: "human-correction-outranks-agent-writes", statement: "A record a human confirmed is never overwritten or superseded by an agent or service principal: the agent may replay it, write derived state back stale with the external cause that moved, or close a commitment with a receipt on record. Changing what the human said takes a human." },
+    { id: "derived-state-writer-owns-currentness", statement: "No source writes the drawer. The writer of a derived statement owns keeping its dependencies true: re-validate them on a schedule or on a source event, and write the statement back stale with the moved pointer as cause when one no longer holds. An agent that will not do this must not write derived state." },
 ];
 const grantKey = (scope) => scopePath(scope);
+/** The memory supply chain's top tier: a record whose provenance a human signed. Same tier rule
+ *  as the strict gate's (strictgate.isHumanConfirmed), applied to a record instead of a source. */
+export function isHumanConfirmed(record) {
+    const source = record?.provenance?.source;
+    return typeof source === "string" && sourceIsHumanConfirmed(source);
+}
 /** authorization-before-retrieval, checked on the way OUT as well: nothing in a read response
  *  may sit outside the principal's grants. Bindings must also filter on the way in. */
 export function assertReadWithinGrants(principal, response) {