@davesheffer/hunch 1.28.0 → 1.30.0

package/dist/core/stateRecords.js

@@ -44,9 +44,29 @@ export const ExternalRefSchema = z.object({
     observed_at: z.string().regex(ISO),
     locator: credentialFree("external locator").optional(),
 }).strict();
+/** The external system's own key, canonicalized so two writers that copied it from the same
+ *  system agree byte for byte: Unicode NFC, trimmed, internal whitespace collapsed. Case is
+ *  preserved — the key belongs to the external system, and folding it could merge two of its
+ *  records. No other guessing: identity here is explicit refs, never similarity. */
+export function canonicalObjectKey(key) {
+    return key.normalize("NFC").trim().replace(/\s+/g, " ");
+}
+/** The identity of an external record across writers: system, type and canonical key. Two
+ *  entities in one partition that carry the same external key are the same thing. */
+export function externalKey(ref) {
+    return `${ref.system}/${ref.object_type}/${canonicalObjectKey(ref.object_key)}`;
+}
+/** The subject an external record is known by, the convention the read verb already uses for
+ *  receipts (`event:26904`): the object type and the canonical key. When an entity in the
+ *  partition carries the ref, that entity's id is the subject and this form resolves to it. */
+export function subjectOfRef(ref) {
+    return `${ref.object_type}:${canonicalObjectKey(ref.object_key)}`;
+}
 /** 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 +86,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 +106,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,
@@ -113,10 +142,22 @@ export const ExternalEntitySchema = z.object({
     refs: z.array(ExternalRefSchema).min(1).max(64),
     attributes: z.record(z.string().max(128), AttributeValue).default({}),
     lifecycle: z.enum(["active", "deprecated", "retired"]).default("active"),
+    /** Audited merge (additive): this entity was folded into another. Set only on a retired
+     *  entity; the survivor must be an active entity on record. Nothing under the retired id is
+     *  rewritten — reads resolve the old id and its keys to the survivor, and the ledger holds
+     *  the `retired` event with its provenance. A split is the explicit reverse: retire or
+     *  re-key the survivor, then write the entity active again without `merged_into`. */
+    merged_into: z.string().min(3).max(2048).optional(),
     provenance: ProvenanceSchema,
     created_at: z.string().regex(ISO),
     updated_at: z.string().regex(ISO),
 }).strict().superRefine((entity, ctx) => {
+    if (entity.merged_into !== undefined) {
+        if (entity.lifecycle !== "retired")
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["merged_into"], message: "a merged entity is retired; the survivor stays active" });
+        if (entity.merged_into === entity.id)
+            ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["merged_into"], message: "an entity cannot merge into itself" });
+    }
     const prefix = `${entity.kind}:`;
     const key = entity.id.startsWith(prefix) ? entity.id.slice(prefix.length) : "";
     if (!key.trim() || entity.id !== resourceId(entity.kind, key)) {

package/dist/extractors/diff.js

@@ -26,7 +26,7 @@ const DECL_PATTERNS = [
     // `class Foo(Bar):` header too, and — since declOf() returns on the first match —
     // always wins for Python class lines before any Python-specific pattern would run.
 ];
-import { languageFor } from "./languages.js";
+import { languageFor, isSubstantive } from "./languages.js";
 const IMPORT_RE = /^\s*import\s+(?:[^'"]*from\s+)?['"]([^'"]+)['"]/;
 const CONT_IMPORT_RE = /^\s*\}?\s*from\s+['"]([^'"]+)['"]/; // multi-line: "} from 'x'"
 const REQUIRE_RE = /\brequire\(\s*['"]([^'"]+)['"]\s*\)/;
@@ -114,7 +114,7 @@ export function analyzeDiff(diff) {
             else if (raw.startsWith("rename to ") || raw.startsWith("copy to ")) {
                 const to = raw.slice(raw.indexOf(" to ") + 4).trim();
                 curFile = to;
-                if (isCode(to))
+                if (isSubstantive(to))
                     filesRenamed.push({ from: renameFrom, to });
             }
             else if (raw.startsWith("--- ")) {
@@ -126,7 +126,7 @@ export function analyzeDiff(diff) {
                 const p = raw.slice(4).trim();
                 if (p !== "/dev/null")
                     curFile = stripAB(p); // new path preferred
-                if (isCode(curFile)) {
+                if (isSubstantive(curFile)) {
                     if (curAdded)
                         filesAdded.add(curFile);
                     else if (curDeleted)
@@ -138,45 +138,50 @@ export function analyzeDiff(diff) {
         // ---- inside a hunk: content lines ----
         if (raw.startsWith("+")) {
             const body = raw.slice(1);
-            // Raw added lines are captured for EVERY file, before the code-only gate:
+            // Raw added lines are captured for EVERY file, before the substantive gate:
             // content-matched constraints and Veto tripwires are not code-only rules
             // (a blocking invariant legitimately scopes .github/workflows/**, *.sql,
             // Dockerfile). Skipping them here left `scopedAdded` empty, which
             // buildCheckReport reads as "cannot prove a violation ⇒ complies" — so the
             // pre-edit hook denied the edit while `hunch check --strict` passed the
-            // very commit that landed it. Symbol/import extraction and the churn
-            // counters below stay code-only, unchanged.
+            // very commit that landed it. The churn counters below now also include
+            // prose (isSubstantive, issue #12); symbol/import extraction stays
+            // code-only (isCode/languageFor) since declarations are a code concept.
             let lines = addedLinesBy.get(curFile);
             if (!lines) {
                 lines = [];
                 addedLinesBy.set(curFile, lines);
             }
             lines.push(body);
-            if (!isCode(curFile))
+            if (!isSubstantive(curFile))
                 continue;
             addedLines++;
             if (!curAdded && !curDeleted)
                 filesModified.add(curFile);
-            const d = declOf(body);
-            if (d)
-                declsFor(curFile)?.added.set(d.name, d);
-            const imp = importOf(body);
-            if (imp && !imp.startsWith("."))
-                addedImports.add(imp);
+            if (isCode(curFile)) {
+                const d = declOf(body);
+                if (d)
+                    declsFor(curFile)?.added.set(d.name, d);
+                const imp = importOf(body);
+                if (imp && !imp.startsWith("."))
+                    addedImports.add(imp);
+            }
         }
         else if (raw.startsWith("-")) {
-            if (!isCode(curFile))
+            if (!isSubstantive(curFile))
                 continue;
             removedLines++;
             if (!curAdded && !curDeleted)
                 filesModified.add(curFile);
-            const body = raw.slice(1);
-            const d = declOf(body);
-            if (d)
-                declsFor(curFile)?.removed.set(d.name, d);
-            const imp = importOf(body);
-            if (imp && !imp.startsWith("."))
-                removedImports.add(imp);
+            if (isCode(curFile)) {
+                const body = raw.slice(1);
+                const d = declOf(body);
+                if (d)
+                    declsFor(curFile)?.removed.set(d.name, d);
+                const imp = importOf(body);
+                if (imp && !imp.startsWith("."))
+                    removedImports.add(imp);
+            }
         }
     }
     // per-file symbol classification (added/removed/changed within the same file)

package/dist/extractors/git.js

@@ -748,6 +748,10 @@ export function headFileContent(root, rel) {
             encoding: "utf8",
             env: foreignRepoEnv(process.env),
             maxBuffer: 16 * 1024 * 1024,
+            // An untracked/absent-at-HEAD path is an expected, silently-handled case
+            // (falls through to the catch below) — don't let git's "fatal: path ...
+            // does not exist in 'HEAD'" leak onto the caller's stderr for it.
+            stdio: ["ignore", "pipe", "ignore"],
         });
     }
     catch {

package/dist/extractors/languages.js

@@ -281,4 +281,12 @@ export function languageFor(file) {
     }
     return null;
 }
+/** Prose formats worth drafting a decision from even though no LanguageSpec parses
+ *  them — no grammar, no symbols/edges, just eligible input to synthesis (issue #12). */
+export const PROSE_EXTENSIONS = [".md"];
+/** Broader than languageFor: "is this worth reasoning about" (synthesis input)
+ *  rather than "can tree-sitter parse this" (symbol/dependency extraction). */
+export function isSubstantive(file) {
+    return languageFor(file) !== null || PROSE_EXTENSIONS.some((ext) => file.endsWith(ext));
+}
 //# sourceMappingURL=languages.js.map

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)],