@davesheffer/hunch 1.28.0 → 1.29.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,9 @@ 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.
+
+Read [Deterministic organizational state](docs/deterministic-state.md), the [roadmap](ROADMAP.md) and the dated [competitive landscape](docs/competitive-landscape.md).
 
 ### Naming
 
@@ -216,7 +220,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 +230,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

package/dist/cli/index.js

@@ -45,15 +45,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";
@@ -282,6 +283,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.
@@ -5468,6 +5471,79 @@ program
         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) --------------------------------
 program
     .command("findings")

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/stateContract.js

@@ -113,6 +113,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,6 +234,7 @@ 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: "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);
 /** authorization-before-retrieval, checked on the way OUT as well: nothing in a read response

package/dist/core/stateRecords.js

@@ -46,7 +46,9 @@ export const ExternalRefSchema = z.object({
 }).strict();
 /** What a derived statement rests on. Exactly what a currentness check re-validates. */
 export const DependencyRefSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("record"), id: z.string().regex(TOKEN), record_hash: z.string().regex(SHA256) }).strict(),
+    /** `scope` (additive) points into ANOTHER partition — the repository decision an
+     *  organization-drawer receipt rests on. Absent, the ref is in the record's own partition. */
+    z.object({ kind: z.literal("record"), id: z.string().regex(TOKEN), record_hash: z.string().regex(SHA256), scope: ScopeSchema.optional() }).strict(),
     z.object({ kind: z.literal("external"), ref: ExternalRefSchema }).strict(),
     z.object({ kind: z.literal("schema"), name: z.string().max(256), fingerprint: z.string().regex(SHA256) }).strict(),
 ]);
@@ -66,6 +68,12 @@ export const ActionReceiptSchema = z.object({
     verified_at: z.string().regex(ISO).optional(),
     result_fingerprint: z.string().regex(SHA256).optional(),
     invalidates: z.array(z.string().max(512)).max(64).default([]),
+    /** What the action rested on (additive): the decision it implements, the change proof for
+     *  the shipped revision, the commitment or incident it answers. Same shape as a derived
+     *  statement's dependencies, so "what does this closure rest on" is one read. A record ref
+     *  in the receipt's own partition is verified by hash on write; a ref into another partition
+     *  is a pointer the reader resolves with `records`, grants first. */
+    rests_on: z.array(DependencyRefSchema).max(64).optional(),
     provenance: ProvenanceSchema,
 }).strict();
 /** committed — an obligation with a due date and an in-force window. */
@@ -80,6 +88,9 @@ export const CommitmentSchema = z.object({
     status: z.enum(["open", "waiting", "done", "cancelled"]),
     source: ExternalRefSchema.optional(),
     evidence_excerpt: z.string().max(900).optional(),
+    /** The receipt that fulfilled this commitment (additive). A closure names what happened:
+     *  the binding refuses a `closed_by` that is not a succeeded/verified receipt on record. */
+    closed_by: z.string().regex(/^nrc_[a-f0-9]{24}$/).optional(),
     valid_from: z.string().regex(ISO),
     valid_to: z.string().regex(ISO).nullable().default(null),
     provenance: ProvenanceSchema,

package/dist/integrations/hooks.js

@@ -97,4 +97,45 @@ export function installPreCommitHook(root, invocation, strict = false) {
     chmodSync(hookPath, 0o755);
     return { path: hookPath, action: "appended" };
 }
+const MERGE_MARK = "# >>> hunch post-merge >>>";
+const MERGE_END = "# <<< hunch post-merge <<<";
+/** Install a post-merge hook that re-syncs the committed grounding docs when a merge
+ *  brought memory in behind them (fnd_c402046ac7). Two branches that each captured a
+ *  record regenerate the same "N+1" counts line; git merges identical lines silently
+ *  and the doc ends up one behind the store. The hook regenerates the existing docs
+ *  from the PUBLIC store right after a local merge/pull that touched .hunch/, so the
+ *  next commit carries them. Foreground (it rewrites five files), loop-guarded via
+ *  HUNCH_SYNC, and it can never fail the merge. Preserves any existing hook. */
+export function installPostMergeHook(root, invocation) {
+    const dir = hooksDir(root);
+    const abs = isAbsolute(dir) ? dir : join(root, dir);
+    mkdirSync(abs, { recursive: true });
+    const hookPath = join(abs, "post-merge");
+    const blk = [
+        MERGE_MARK,
+        'if [ -z "$HUNCH_SYNC" ]; then',
+        "  if ! git diff --quiet ORIG_HEAD HEAD -- .hunch 2>/dev/null; then",
+        `    ( HUNCH_SYNC=1 ${invocation} grounding --refresh 2>/dev/null || true )`,
+        "  fi",
+        "fi",
+        MERGE_END,
+    ].join("\n");
+    if (!existsSync(hookPath)) {
+        writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
+        chmodSync(hookPath, 0o755);
+        return { path: hookPath, action: "created" };
+    }
+    const cur = readFileSync(hookPath, "utf8");
+    if (cur.includes(MERGE_MARK)) {
+        const updated = cur.replace(new RegExp(`${escapeRe(MERGE_MARK)}[\\s\\S]*?${escapeRe(MERGE_END)}`), blk);
+        if (updated === cur)
+            return { path: hookPath, action: "unchanged" };
+        writeFileSync(hookPath, updated);
+        chmodSync(hookPath, 0o755);
+        return { path: hookPath, action: "updated" };
+    }
+    writeFileSync(hookPath, cur.endsWith("\n") ? `${cur}${blk}\n` : `${cur}\n${blk}\n`);
+    chmodSync(hookPath, 0o755);
+    return { path: hookPath, action: "appended" };
+}
 //# sourceMappingURL=hooks.js.map

package/dist/integrations/providers.js

@@ -360,6 +360,14 @@ export function regenerateGrounding(root, store) {
         writeWindsurfRule(root, store),
     ];
 }
+/** The five grounding docs, repo-relative (POSIX separators, as git prints them). */
+export const GROUNDING_DOC_PATHS = Object.freeze([
+    "CLAUDE.md",
+    "AGENTS.md",
+    ".github/copilot-instructions.md",
+    ".cursor/rules/hunch.mdc",
+    ".windsurf/rules/hunch.md",
+]);
 function groundingTargets(root, store) {
     return [
         ["CLAUDE.md", () => updateClaudeMd(root, store)],

package/dist/mcp/server.js

@@ -13,8 +13,8 @@ import { z } from "zod";
 import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
-import { StateRefusal, SubscribeResponseSchema, capabilities, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
-import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION } from "../core/stateContract.js";
+import { StateRefusal, SubscribeResponseSchema, capabilities, partitionOf, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
+import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION, stateHash } from "../core/stateContract.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId, findingId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
@@ -931,7 +931,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             return {
                 content: [{
                         type: "text",
-                        text: `${proof.proof_id} — ${proof.verdict.toUpperCase()}; ${proof.changed_file_count} exact file delta(s), ${proof.blast_radius_count} dependent path(s), ${proof.omissions.length + proof.unknowns.length} explicit gap(s); sealed ${proof.content_hash}. Evidence only; no execution or merge authority.`,
+                        text: `${proof.proof_id} — ${proof.verdict.toUpperCase()}; ${proof.changed_file_count} exact file delta(s), ${proof.blast_radius_count} dependent path(s), ${proof.omissions.length + proof.unknowns.length} explicit gap(s); sealed ${proof.content_hash}. Evidence only; no execution or merge authority.`
+                            // The chain: a `shipped` receipt rests on this proof as a credential-free pointer.
+                            + `\n\nrests_on ref (for a nuryel receipt that shipped this change): ${JSON.stringify({ kind: "external", ref: { system: "hunch", object_type: "change_proof", object_key: proof.proof_id, content_hash: proof.content_hash, observed_at: new Date().toISOString().replace(/\.\d{3}Z$/, "Z") } })}`,
                     }],
                 structuredContent: proof,
             };
@@ -1532,7 +1534,13 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
                 : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
             const dest = destinationNote(resolveDestRoot(home, store, root));
-            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${dest}${supNote}${note}${captureNote}${quality}`);
+            // The chain (nuryel.state/1): a `shipped` receipt in an organization drawer rests on
+            // this decision by id + the hash ON FILE + this repository's partition. Hand the ref
+            // over now so the agent never rests on a pre-store hash or re-derives the scope.
+            const onFile = store.getRec("decisions", id) ?? rec;
+            const restsOn = JSON.stringify({ kind: "record", id, record_hash: stateHash(onFile), scope: partitionOf(store) });
+            const chainNote = `\n\nrests_on ref (for a nuryel receipt that implements this decision): ${restsOn}`;
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${dest}${supNote}${note}${chainNote}${captureNote}${quality}`);
         }
         catch (e) {
             return err(`Failed to record decision: ${e.message}`);
@@ -1728,10 +1736,24 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 if (ref.facet === "derived")
                     return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}`;
                 if (ref.facet === "commitments")
-                    return `- ${label} commitment ${ref.id} · ${g("status")} · due ${g("due")} · owner ${g("owner")}: ${g("title")}`;
+                    return `- ${label} commitment ${ref.id} · ${g("status")} · due ${g("due")} · owner ${g("owner")}: ${g("title")}${r.closed_by ? ` · closed by ${g("closed_by")}` : ""}`;
                 if (ref.facet === "receipts") {
                     const t = (r.target ?? {});
-                    return `- ${label} receipt ${ref.id} · ${g("action_kind")} on ${String(t.system ?? "")} ${String(t.object_type ?? "")}:${String(t.object_key ?? "")} · ${g("state")} at ${g("occurred_at")} by ${g("actor")}`;
+                    // The chain: what the action rested on, one pointer per line, so a reader follows
+                    // incident → decision → change proof → closure without a second call.
+                    const rests = (Array.isArray(r.rests_on) ? r.rests_on : []);
+                    const restLines = rests.map((d) => {
+                        if (d.kind === "record") {
+                            const sc = d.scope;
+                            return `\n    rests on record ${String(d.id)}${sc ? ` in ${String(sc.kind)}/${String(sc.id)}` : ""}`;
+                        }
+                        if (d.kind === "external") {
+                            const x = (d.ref ?? {});
+                            return `\n    rests on ${String(x.system ?? "")} ${String(x.object_type ?? "")}:${String(x.object_key ?? "")}`;
+                        }
+                        return `\n    rests on ${String(d.kind)} ${String(d.name ?? "")}`;
+                    }).join("");
+                    return `- ${label} receipt ${ref.id} · ${g("action_kind")} on ${String(t.system ?? "")} ${String(t.object_type ?? "")}:${String(t.object_key ?? "")} · ${g("state")} at ${g("occurred_at")} by ${g("actor")}${restLines}`;
                 }
                 if (ref.facet === "decisions")
                     return `- ${label} decision ${ref.id} · ${g("status")}: ${g("title")}`;

package/dist/store/changeLedger.js

@@ -19,7 +19,12 @@ export const LEDGER_SCHEMA_VERSION = "nuryel.ledger/1";
 export const CHANGES_DIR = "changes";
 const IdempotencyEntrySchema = z.object({
     record_id: z.string().min(1),
+    /** Hash of the record ON FILE (what reads, events and refs see). */
     record_hash: z.string(),
+    /** Hash of the normalized payload as the writer sent it (additive). The store may enrich a
+     *  record on put (a private-mode decision gains `valid_from`), so a replay is recognized by
+     *  the payload it re-sends, while `record_hash` stays the truth a reader can verify. */
+    payload_hash: z.string().optional(),
     facet: z.string(),
     seq: z.number().int().nonnegative(),
     at: z.string(),

package/dist/store/stateBinding.js

@@ -179,8 +179,10 @@ export function readState(store, input) {
                 const scope = admit("receipts", r);
                 if (!scope)
                     continue;
-                if (r.state === "succeeded" || r.state === "verified")
+                if (r.state === "succeeded" || r.state === "verified") {
                     done.push(keep("receipts", r, scope));
+                    dependsOn.push(...(r.rests_on ?? []));
+                }
                 if (r.invalidates.includes(subject))
                     invalidatedBy.add(r.id);
             }
@@ -193,6 +195,10 @@ export function readState(store, input) {
                     continue;
                 if ((c.status === "open" || c.status === "waiting") && c.valid_to == null)
                     inForce.push(keep("commitments", c, scope));
+                // A commitment fulfilled by a receipt is part of what HAPPENED for the subject: it
+                // leaves in_force and joins done beside the receipt that closed it (the chain's last link).
+                else if (c.status === "done" && c.closed_by)
+                    done.push(keep("commitments", c, scope));
             }
         if (facets.has("derived"))
             for (const d of store.recs("derived")) {
@@ -330,6 +336,77 @@ function subjectOf(facet, record) {
         default: return undefined;
     }
 }
+/** Which facet a record id belongs to, from its prefix; `null` for a kind-qualified entity id
+ *  or an unknown shape (those are looked up across every facet). */
+function facetOfId(id) {
+    const prefix = /^([a-z]+)_/.exec(id)?.[1];
+    switch (prefix) {
+        case "dec": return "decisions";
+        case "con": return "constraints";
+        case "bug": return "bugs";
+        case "fnd": return "findings";
+        case "nrc": return "receipts";
+        case "ncm": return "commitments";
+        case "nds": return "derived";
+        case "edge": return "relationships";
+        default: return null;
+    }
+}
+/** Find a record by id in this store, with the facet it lives in. */
+function findRecord(store, id) {
+    const facets = facetOfId(id) ? [facetOfId(id)] : [...STATE_FACETS];
+    for (const facet of facets) {
+        const record = store.getRec(facet, id);
+        if (record)
+            return { facet, record };
+    }
+    return null;
+}
+/** A receipt's `rests_on` record refs: one in a partition this store holds must exist there
+ *  with the hash the writer saw (a stale hash means the decision moved — re-read); one in a
+ *  partition the store does not hold is a pointer for the reader to resolve. Grants first: a
+ *  ref into a partition the principal is not granted is refused by scope, never by content. */
+function assertRestsOn(store, principal, scope, restsOn) {
+    const repo = partitionOf(store);
+    for (const dep of restsOn) {
+        if (dep.kind !== "record")
+            continue;
+        const refScope = dep.scope ?? scope;
+        if (!granted(principal, refScope))
+            throw new StateRefusal("outside-grants", `rests_on ${dep.id} points into ${scopePath(refScope)}, which is outside the principal's grants`);
+        const found = findRecord(store, dep.id);
+        if (!found) {
+            const held = scopePath(refScope) === scopePath(scope) || scopePath(refScope) === scopePath(repo) || (store.hasPrivate && refScope.kind !== "repository");
+            if (held)
+                throw new StateRefusal("conflict", `rests_on ${dep.id} is not on record in ${scopePath(refScope)}: a receipt rests on state that exists; write or re-read it first`, { incumbent_id: dep.id, reason: "rests_on target absent" });
+            continue; // a partition this store does not hold: a pointer, resolved by the reader
+        }
+        const actualScope = recordScope(found.record, repo);
+        if (scopePath(actualScope) !== scopePath(refScope))
+            throw new StateRefusal("conflict", `rests_on ${dep.id} lives in ${scopePath(actualScope)}, not ${scopePath(refScope)}`, { incumbent_id: dep.id, reason: "rests_on scope mismatch" });
+        const actualHash = stateHash(found.record);
+        if (actualHash !== dep.record_hash)
+            throw new StateRefusal("conflict", `rests_on ${dep.id} has moved: the record on file hashes ${actualHash}, not ${dep.record_hash} — re-read it and rest on what is current`, { incumbent_id: dep.id, reason: "rests_on hash mismatch" });
+    }
+}
+/** A commitment closed by a receipt: `closed_by` must name a succeeded/verified receipt the
+ *  principal can see, and the status must be done — a closure is a fact that happened, never
+ *  an opinion. Returns the receipt id when the closure is well-formed. */
+function assertClosedBy(store, principal, commitment) {
+    if (!commitment.closed_by)
+        return null;
+    if (commitment.status !== "done")
+        throw new StateRefusal("malformed", `closed_by names a receipt but status is ${commitment.status}: a commitment closed by a receipt is done`);
+    const receipt = store.getRec("receipts", commitment.closed_by);
+    const scope = receipt ? recordScope(receipt, partitionOf(store)) : null;
+    if (!receipt || !scope || !granted(principal, scope)) {
+        throw new StateRefusal("conflict", `closed_by ${commitment.closed_by} is not a receipt on record within the principal's grants: a commitment is closed by an action that happened — write the receipt first, then close with its id`, { incumbent_id: commitment.closed_by, reason: "closed_by receipt absent" });
+    }
+    if (receipt.state !== "succeeded" && receipt.state !== "verified") {
+        throw new StateRefusal("conflict", `closed_by ${commitment.closed_by} is ${receipt.state}, not succeeded or verified: only an action that happened closes a commitment`, { incumbent_id: commitment.closed_by, reason: `closed_by receipt ${receipt.state}` });
+    }
+    return commitment.closed_by;
+}
 /** Top-level fields whose canonical hash differs between two records, sorted. */
 function differingFields(a, b) {
     const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
@@ -418,15 +495,22 @@ export function writeState(store, input, opts = {}) {
         throw new StateRefusal("unsupported", `facet ${facet} is not a store kind`);
     const record = normalizeRecord(facet, request.scope, request.record, request.principal);
     const id = record.id;
+    /** The normalized PAYLOAD hash: what idempotency recognizes on a re-send. */
     const hash = stateHash(record);
     const ledger = readLedger(hunchDir, request.scope);
     const durability = () => opts.flush?.(isPrivate, `nuryel: write ${id}`) ?? "local";
-    const result = (outcome, conflict = null, rid = id, rhash = hash) => WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: rid, record_hash: rhash, durability: durability(), outcome, conflict, record: store.getRec(facet, rid) ?? record });
+    /** The result reports the record ON FILE and its hash — the store may enrich a record on put
+     *  (a private-mode decision gains `valid_from`), and a writer that goes on to rest a receipt
+     *  on this record must hold the hash a reader will verify, never a pre-store one. */
+    const result = (outcome, conflict = null, rid = id) => {
+        const onFile = store.getRec(facet, rid) ?? record;
+        return WriteResultSchema.parse({ schema: STATE_WRITE_VERSION, record_id: rid, record_hash: stateHash(onFile), durability: durability(), outcome, conflict, record: onFile });
+    };
     // Idempotency: the same key replays the original; the same key with a different payload
     // is a refusal, never a second record.
     const seen = ledger.idempotency[request.idempotency_key];
     if (seen) {
-        if (seen.record_hash === hash && seen.record_id === id)
+        if (seen.record_id === id && (seen.record_hash === hash || seen.payload_hash === hash))
             return result("replayed");
         // Say WHAT differs and what to do: a stable key with a varying payload (a timestamp, new
         // wording) is the trap every writer falls into once; the refusal must teach the way out.
@@ -437,7 +521,7 @@ export function writeState(store, input, opts = {}) {
     }
     const existing = store.recsInHome(facet, home).find((r) => r.id === id);
     if (existing && stateHash(existing) === hash) {
-        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, facet } }, now);
+        appendChanges(hunchDir, request.scope, [], { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, payload_hash: hash, facet } }, now);
         return result("replayed");
     }
     if (existing && request.expected_version !== null) {
@@ -482,9 +566,19 @@ export function writeState(store, input, opts = {}) {
             supersedes = null; // already closed by this record: nothing to close again, no second "superseded" event
         }
     }
+    // The chain (Gate 4): a receipt names what it rested on, a closure names the receipt.
+    // Both are checked against the drawer, grants first, before anything lands.
+    if (facet === "receipts")
+        assertRestsOn(store, request.principal, request.scope, record.rests_on ?? []);
+    const closedBy = facet === "commitments" ? assertClosedBy(store, request.principal, record) : null;
     store.putCapture(facet, record, isPrivate);
+    /** What is on file now — the hash every event, ref and result carries. */
+    const onFileHash = stateHash(store.getRec(facet, id) ?? record);
     const changes = [];
-    const cause = { kind: "write", principal: request.principal.id };
+    const cause = closedBy ? { kind: "receipt", receipt_id: closedBy } : request.cause ?? { kind: "write", principal: request.principal.id };
+    // A current derived statement written back as stale is an INVALIDATION, not an update: the
+    // ledger says so, and names the external pointer that moved when the writer gives one.
+    const invalidated = facet === "derived" && !!existing && existing.state === "current" && record.state === "stale";
     const invalidates = facet === "receipts" ? record.invalidates : [];
     const subject = subjectOf(facet, record);
     if (supersedes) {
@@ -494,8 +588,8 @@ export function writeState(store, input, opts = {}) {
             changes.push({ facet, record_id: supersedes, record_hash: stateHash(old), change: "superseded", subject: subjectOf(facet, old), invalidates: [], cause });
         }
     }
-    changes.push({ facet, record_id: id, record_hash: hash, change: existing ? "updated" : "created", subject, invalidates, cause });
-    appendChanges(hunchDir, request.scope, changes, { key: request.idempotency_key, entry: { record_id: id, record_hash: hash, facet } }, now);
+    changes.push({ facet, record_id: id, record_hash: onFileHash, change: invalidated ? "invalidated" : existing ? "updated" : "created", subject, invalidates: invalidated && subject ? [subject] : invalidates, cause });
+    appendChanges(hunchDir, request.scope, changes, { key: request.idempotency_key, entry: { record_id: id, record_hash: onFileHash, payload_hash: hash, facet } }, now);
     store.reindex();
     return result(supersedes ? "superseded" : existing ? "updated" : "created");
 }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
-  "description": "Engineering memory and a deterministic Change Gate for AI-assisted codebases: decisions, rejected approaches, constraints, and bug lineage become portable context and opt-in enforcement for every MCP assistant.",
+  "description": "Deterministic state for organizations that run many probabilistic agents: decisions, receipts, commitments, constraints and bug lineage held in git, refused when they contradict, and delivered to every MCP assistant before it answers or edits code.",
   "homepage": "https://www.hunchmemory.com",
   "repository": {
     "type": "git",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.28.0",
+      "version": "1.29.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/tooling/competitive-watch.mjs

@@ -9,6 +9,7 @@ const repos = [
   "riponcm/projectmem",
   "Cranot/roam-code",
   "blackwell-systems/knowing",
+  "markmhendrickson/neotoma",
 ];
 
 const distinctivePhrases = [