@davesheffer/hunch 1.29.0 → 1.30.0

package/README.md

@@ -207,6 +207,12 @@ Hunch Memory service into Hunch.
 
 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
@@ -268,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";
@@ -108,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";
@@ -118,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
@@ -469,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) ----------------------------------------------
@@ -5448,23 +5475,33 @@ 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 {

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/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";
@@ -234,9 +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) {

package/dist/core/stateRecords.js

@@ -44,6 +44,24 @@ 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", [
     /** `scope` (additive) points into ANOTHER partition — the repository decision an
@@ -124,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