@davesheffer/hunch 1.32.7 → 1.33.0

package/dist/core/types.d.ts

@@ -7,7 +7,7 @@
  */
 import { z } from "zod";
 import { ProvenanceSchema, isCredentialFreeText, type Provenance } from "./provenance.js";
-import { type ActionReceipt, type Commitment, type DerivedState, type ExternalEntity, type StateRelationship } from "./stateRecords.js";
+import { type Convention, type ActionReceipt, type Commitment, type DerivedState, type ExternalEntity, type StateRelationship } from "./stateRecords.js";
 export { ProvenanceSchema, isCredentialFreeText };
 export type { Provenance };
 export declare const ComponentKind: z.ZodEnum<{
@@ -335,6 +335,11 @@ export declare const PremiseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Premise = z.infer<typeof PremiseSchema>;
 export declare const DecisionSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     title: z.ZodString;
     topic: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -416,6 +421,11 @@ export declare const BugLineageSchema: z.ZodObject<{
 export type BugLineage = z.infer<typeof BugLineageSchema>;
 /** A bug with root cause and lineage (introduced → fixed → recurred). */
 export declare const BugSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     title: z.ZodString;
     symptom: z.ZodDefault<z.ZodString>;
@@ -452,6 +462,11 @@ export declare const BugSchema: z.ZodObject<{
 export type Bug = z.infer<typeof BugSchema>;
 /** An invariant the system must respect. */
 export declare const ConstraintSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     type: z.ZodDefault<z.ZodEnum<{
         security: "security";
@@ -526,6 +541,11 @@ export type Runbook = z.infer<typeof RunbookSchema>;
  *  never enters any block path. Lifecycle is `triage`, not valid-time: a finding is
  *  resolved/stale-marked, never superseded. */
 export declare const FindingSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     title: z.ZodString;
     observation: z.ZodDefault<z.ZodString>;
@@ -538,8 +558,8 @@ export declare const FindingSchema: z.ZodObject<{
         critical: "critical";
     }>>;
     triage: z.ZodDefault<z.ZodEnum<{
-        open: "open";
         stale: "stale";
+        open: "open";
         "accepted-risk": "accepted-risk";
         scheduled: "scheduled";
         resolved: "resolved";
@@ -590,7 +610,7 @@ export declare function assertLandscapeDriftCandidate(value: unknown): asserts v
 /** Convert one valid external observation into advisory Hunch memory, never graph authority. */
 export declare function landscapeDriftCandidateFinding(value: unknown): Finding;
 /** The entity collections, keyed by their on-disk directory name. */
-export declare const ENTITY_KINDS: readonly ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings", "receipts", "commitments", "derived", "entities", "relationships"];
+export declare const ENTITY_KINDS: readonly ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings", "receipts", "commitments", "derived", "entities", "relationships", "conventions"];
 export type EntityKind = (typeof ENTITY_KINDS)[number];
 export declare const SCHEMAS: {
     readonly components: z.ZodObject<{
@@ -753,6 +773,11 @@ export declare const SCHEMAS: {
         last_changed: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>;
     readonly decisions: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         title: z.ZodString;
         topic: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -823,6 +848,11 @@ export declare const SCHEMAS: {
         date: z.ZodString;
     }, z.core.$strip>;
     readonly bugs: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         title: z.ZodString;
         symptom: z.ZodDefault<z.ZodString>;
@@ -857,6 +887,11 @@ export declare const SCHEMAS: {
         }, z.core.$strip>;
     }, z.core.$strip>;
     readonly constraints: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         type: z.ZodDefault<z.ZodEnum<{
             security: "security";
@@ -919,6 +954,11 @@ export declare const SCHEMAS: {
         date: z.ZodString;
     }, z.core.$strip>;
     readonly findings: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         title: z.ZodString;
         observation: z.ZodDefault<z.ZodString>;
@@ -931,8 +971,8 @@ export declare const SCHEMAS: {
             critical: "critical";
         }>>;
         triage: z.ZodDefault<z.ZodEnum<{
-            open: "open";
             stale: "stale";
+            open: "open";
             "accepted-risk": "accepted-risk";
             scheduled: "scheduled";
             resolved: "resolved";
@@ -950,7 +990,76 @@ export declare const SCHEMAS: {
             last_verified: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>;
+    readonly conventions: z.ZodObject<{
+        schema: z.ZodLiteral<"nuryel.convention/1">;
+        id: z.ZodString;
+        scope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        key: z.ZodString;
+        value: z.ZodString;
+        status: z.ZodEnum<{
+            stale: "stale";
+            proposed: "proposed";
+            accepted: "accepted";
+            withdrawn: "withdrawn";
+        }>;
+        sources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"record">;
+            id: z.ZodString;
+            record_hash: z.ZodString;
+            scope: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    repository: "repository";
+                    organization: "organization";
+                    team: "team";
+                    user: "user";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"external">;
+            ref: z.ZodObject<{
+                system: z.ZodString;
+                object_type: z.ZodString;
+                object_key: z.ZodString;
+                version: z.ZodOptional<z.ZodString>;
+                content_hash: z.ZodOptional<z.ZodString>;
+                observed_at: z.ZodString;
+                locator: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"schema">;
+            name: z.ZodString;
+            fingerprint: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+        valid_from: z.ZodString;
+        valid_to: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        review_by: z.ZodString;
+        provenance: z.ZodObject<{
+            source: z.ZodString;
+            confidence: z.ZodNumber;
+            evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            last_verified: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
     readonly receipts: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.receipt/1">;
         id: z.ZodString;
         scope: z.ZodObject<{
@@ -1023,6 +1132,11 @@ export declare const SCHEMAS: {
         }, z.core.$strip>;
     }, z.core.$strict>;
     readonly commitments: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.commitment/1">;
         id: z.ZodString;
         scope: z.ZodObject<{
@@ -1065,6 +1179,11 @@ export declare const SCHEMAS: {
         }, z.core.$strip>;
     }, z.core.$strict>;
     readonly derived: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.derived/1">;
         id: z.ZodString;
         scope: z.ZodObject<{
@@ -1108,6 +1227,18 @@ export declare const SCHEMAS: {
             name: z.ZodString;
             fingerprint: z.ZodString;
         }, z.core.$strict>], "kind">>;
+        field_provenance: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"json_pointer">;
+                path: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"text">;
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+            }, z.core.$strict>], "kind">;
+            value_hash: z.ZodString;
+            dependency_hashes: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
         transform_version: z.ZodString;
         computed_at: z.ZodString;
         valid_to: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -1142,6 +1273,11 @@ export declare const SCHEMAS: {
         }, z.core.$strip>;
     }, z.core.$strict>;
     readonly entities: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.entity/1">;
         id: z.ZodString;
         kind: z.ZodString;
@@ -1181,6 +1317,11 @@ export declare const SCHEMAS: {
         updated_at: z.ZodString;
     }, z.core.$strict>;
     readonly relationships: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.relationship/1">;
         id: z.ZodString;
         from: z.ZodString;
@@ -1228,6 +1369,7 @@ export type EntityFor = {
     constraints: Constraint;
     runbooks: Runbook;
     findings: Finding;
+    conventions: Convention;
     receipts: ActionReceipt;
     commitments: Commitment;
     derived: DerivedState;

package/dist/core/types.js

@@ -1,3 +1,4 @@
+import { RecordVisibilitySchema } from "./recordVisibility.js";
 /**
  * Core entity schema for the Project Hunch (DESIGN.md §3).
  *
@@ -9,7 +10,7 @@ import { z } from "zod";
 import { createHash } from "node:crypto";
 import { findingId, resourceId, resourceRelationshipId } from "./ids.js";
 import { ProvenanceSchema, SENSITIVE_METADATA_KEY, isCredentialFreeText } from "./provenance.js";
-import { ActionReceiptSchema, CommitmentSchema, DerivedStateSchema, ExternalEntitySchema, StateRelationshipSchema, } from "./stateRecords.js";
+import { ConventionSchema, ActionReceiptSchema, CommitmentSchema, DerivedStateSchema, ExternalEntitySchema, StateRelationshipSchema, } from "./stateRecords.js";
 // Provenance and the credential-free text check live in the leaf module ./provenance.js so
 // record schemas registered below can import them without a cycle; re-exported unchanged.
 export { ProvenanceSchema, isCredentialFreeText };
@@ -323,6 +324,7 @@ export const PremiseSchema = z.object({
     path: ["under"],
 });
 export const DecisionSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     id: z.string().describe("dec_*"),
     title: z.string(),
     // Decision-grounding anchor: the join key that relates a doc section, a decision,
@@ -372,6 +374,7 @@ export const BugLineageSchema = z.object({
 });
 /** A bug with root cause and lineage (introduced → fixed → recurred). */
 export const BugSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     id: z.string().describe("bug_*"),
     title: z.string(),
     symptom: z.string().default(""),
@@ -388,6 +391,7 @@ export const BugSchema = z.object({
 });
 /** An invariant the system must respect. */
 export const ConstraintSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     id: z.string().describe("con_*"),
     type: z.enum(["security", "performance", "correctness", "architecture", "compliance"]).default("correctness"),
     statement: z.string(),
@@ -448,6 +452,7 @@ export const RunbookSchema = z.object({
  *  never enters any block path. Lifecycle is `triage`, not valid-time: a finding is
  *  resolved/stale-marked, never superseded. */
 export const FindingSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     id: z.string().describe("fnd_*"),
     title: z.string(),
     observation: z.string().default("").describe("what was observed, in plain words"),
@@ -594,7 +599,7 @@ export function landscapeDriftCandidateFinding(value) {
 // loads exactly as before, and an older build ignores directories it does not know.
 export const ENTITY_KINDS = [
     "components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings",
-    "receipts", "commitments", "derived", "entities", "relationships",
+    "receipts", "commitments", "derived", "entities", "relationships", "conventions",
 ];
 export const SCHEMAS = {
     components: ComponentSchema,
@@ -606,6 +611,7 @@ export const SCHEMAS = {
     constraints: ConstraintSchema,
     runbooks: RunbookSchema,
     findings: FindingSchema,
+    conventions: ConventionSchema,
     receipts: ActionReceiptSchema,
     commitments: CommitmentSchema,
     derived: DerivedStateSchema,

package/dist/extractors/git.js

@@ -1838,16 +1838,9 @@ export function isLinkedWorktree(cwd) {
     const own = gitSafe(["rev-parse", "--absolute-git-dir"], cwd);
     if (!common || !own)
         return false;
-    // realpath BOTH before comparing: `--absolute-git-dir` is symlink-resolved while
-    // gitCommonDir is not, so on macOS the main checkout would otherwise mismatch on
-    // /var vs /private/var and falsely read as "linked".
-    const norm = (p) => { try {
-        return realpathSync(p);
-    }
-    catch {
-        return resolve(p);
-    } };
-    return norm(own) !== norm(common);
+    // Git can spell the same directory differently: /var vs /private/var on
+    // macOS, or long vs 8.3/case variants on Windows. Compare physical identity.
+    return !sameFilesystemEntry(own, common);
 }
 /** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
  *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */

package/dist/integrations/health.d.ts

@@ -75,7 +75,8 @@ export declare function inspectIntegrations(root: string, selected?: Harness): I
  * tooling/sync-version-pins.mjs) so hooks and MCP never point at a version npm
  * cannot serve. Unknown git state yields [] — callers then treat nothing as local. */
 export declare function machineLocalIntegrationFiles(root: string): string[];
-/** Repair only exact published pins. Preserve formatting and all other values.
+/** Repair exact published pins and the known misplaced MCP hook subcommand.
+ * Preserve formatting and all other values, including disabled hook settings.
  * Preflight every affected file before writing any; reject malformed JSON/TOML.
  * `skip` leaves a file untouched (used to keep machine-local pins on a version
  * npm can actually serve while a release is still publishing). */

package/dist/integrations/health.js

@@ -54,18 +54,33 @@ function strings(value) {
         return Object.values(value).flatMap(strings);
     return [];
 }
-function hookCommands(value) {
+function hookCommands(value, includeDisabled = false) {
     if (Array.isArray(value))
-        return value.flatMap(hookCommands);
+        return value.flatMap(v => hookCommands(v, includeDisabled));
     if (!value || typeof value !== "object")
         return [];
     const obj = value;
-    if (obj.enabled === false || (obj.type !== undefined && obj.type !== "command"))
+    if ((!includeDisabled && obj.enabled === false) || (obj.type !== undefined && obj.type !== "command"))
         return [];
     const command = typeof obj.command === "string" ? obj.command : "";
-    const own = /(?:@davesheffer\/hunch|(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts))/.test(command)
+    const own = publishedHookCommand(command) !== undefined || /(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)/.test(command)
         && /\s"?hook"?(?:\s+"?--provider"?\s+"?[a-z]+"?)?\s*$/.test(command);
-    return [...(own ? [command] : []), ...(obj.hooks ? hookCommands(obj.hooks) : [])];
+    return [...(own ? [command] : []), ...(obj.hooks ? hookCommands(obj.hooks, includeDisabled) : [])];
+}
+/** Recognize only generated npm commands, including their legacy quoted form.
+ * Never normalize a wrapper, shell expression, or another program's arguments. */
+function publishedHookCommand(command) {
+    const parts = command.trim().match(/"[^"\\]*"|'[^']*'|[^\s"'\\]+/g);
+    if (!parts || parts.join(" ") !== command.trim().replace(/\s+/g, " "))
+        return undefined;
+    const tokens = parts.map(p => /^["']/.test(p) ? p.slice(1, -1) : p);
+    if (tokens.some(token => /\s/.test(token)))
+        return undefined;
+    const bare = tokens.join(" ");
+    return /^npx(?:\.cmd)? (?:-y|--yes) --package=(?:hunch-exact@npm:)?@davesheffer\/hunch@[0-9A-Za-z.+-]+ (?:-- )?hunch (?:mcp )?hook(?: --provider [a-z]+)?$/.test(bare) ? bare : undefined;
+}
+function misroutedHook(command) {
+    return publishedHookCommand(command)?.includes(" hunch mcp hook") ?? false;
 }
 /** Pin repair is restricted to Hunch's marker-owned TOML block. */
 function codexBlock(raw) {
@@ -169,7 +184,13 @@ export function inspectIntegrations(root, selected) {
                 const config = object(parseJsonc(readFileSync(join(root, spec.hooks), "utf8")));
                 disabled = config.disableAllHooks === true;
                 events = object(harness === "antigravity" ? config.hunch : config.hooks);
-                recordPins(spec.hooks, Object.values(events).flatMap(hookCommands));
+                const commands = Object.values(events).flatMap(v => hookCommands(v));
+                recordPins(spec.hooks, commands);
+                if (commands.some(misroutedHook))
+                    report.issues.push({
+                        file: spec.hooks, code: "hook-command",
+                        detail: "Hunch hooks invoke the MCP subcommand instead of the hook handler; run hunch integrations repair-pins",
+                    });
             }
             catch (e) {
                 report.issues.push({ file: spec.hooks, code: "hook-config", detail: e.message });
@@ -178,6 +199,12 @@ export function inspectIntegrations(root, selected) {
         for (const [i, capability] of ["context", "edit-blocking", "failure-capture", "compaction"].entries()) {
             const event = spec.events[i];
             const status = capabilities[capability];
+            const matchesProvider = (command) => {
+                if (misroutedHook(command))
+                    return false;
+                const dialect = (publishedHookCommand(command) ?? command).match(/"?--provider"?\s+"?([a-z]+)"?/i)?.[1]?.toLowerCase() ?? "claude";
+                return dialect === harness;
+            };
             if (!event) {
                 status.status = capability === "context" ? "advisory-only" : "unsupported";
                 status.detail = capability === "context" ? "Hunch relies on instructions and voluntary MCP calls on this adapter" : "No Hunch lifecycle adapter for this capability";
@@ -189,12 +216,15 @@ export function inspectIntegrations(root, selected) {
                 status.status = "unsupported";
                 status.detail = "Disabled by local hook settings, firmness, or HUNCH_PIPELINE";
             }
-            else if (!hookCommands(events[event]).some(command => {
-                const dialect = command.match(/"?--provider"?\s+"?([a-z]+)"?/i)?.[1]?.toLowerCase() ?? "claude";
-                return dialect === harness;
-            })) {
-                status.detail = `Missing Hunch ${event} handler`;
-                report.issues.push({ file: spec.hooks, code: "missing-hook", detail: status.detail });
+            else if (!hookCommands(events[event]).some(matchesProvider)) {
+                if (hookCommands(events[event], true).some(matchesProvider)) {
+                    status.status = "unsupported";
+                    status.detail = `Hunch ${event} handler disabled by local hook settings`;
+                }
+                else {
+                    status.detail = `Missing Hunch ${event} handler`;
+                    report.issues.push({ file: spec.hooks, code: "missing-hook", detail: status.detail });
+                }
             }
             else if (capability === "edit-blocking" && firmness !== "strict") {
                 status.status = "advisory-only";
@@ -238,7 +268,8 @@ export function machineLocalIntegrationFiles(root) {
         return [];
     return (r.stdout ?? "").split(/\r?\n/).map(l => l.trim()).filter(Boolean);
 }
-/** Repair only exact published pins. Preserve formatting and all other values.
+/** Repair exact published pins and the known misplaced MCP hook subcommand.
+ * Preserve formatting and all other values, including disabled hook settings.
  * Preflight every affected file before writing any; reject malformed JSON/TOML.
  * `skip` leaves a file untouched (used to keep machine-local pins on a version
  * npm can actually serve while a release is still publishing). */
@@ -262,7 +293,7 @@ export function repairIntegrationPins(root, opts = {}) {
                 if (!exactVersion.test(old))
                     throw new Error(`refusing non-exact Hunch pin in ${file}`);
                 return `@davesheffer/hunch@${version}`;
-            });
+            }).replace(/--package=@davesheffer\/hunch@/g, "--package=hunch-exact@npm:@davesheffer/hunch@");
             let after;
             if (name === "codex" && file === spec.mcp) {
                 readLauncher(root, "codex");
@@ -282,8 +313,14 @@ export function repairIntegrationPins(root, opts = {}) {
                 const config = object(parseJsonc(before));
                 const values = file === spec.mcp
                     ? strings(object(object(config[spec.key]).hunch).args)
-                    : Object.values(object(name === "antigravity" ? config.hunch : config.hooks)).flatMap(hookCommands);
-                const replacements = new Map(values.map(v => [v, replace(v)]).filter(([a, b]) => a !== b));
+                    : Object.values(object(name === "antigravity" ? config.hunch : config.hooks)).flatMap(v => hookCommands(v, true));
+                const replacements = new Map(values.map(v => {
+                    // Every recognized npm token is shell-safe. Bare tokens also repair
+                    // the legacy quoted executable, which PowerShell treats as a string.
+                    const published = file === spec.hooks ? publishedHookCommand(v) : undefined;
+                    const repaired = published?.replace(" hunch mcp hook", " hunch hook") ?? v;
+                    return [v, replace(repaired)];
+                }).filter(([a, b]) => a !== b));
                 const counts = new Map();
                 // Tokenize comments too, so a quoted command in a comment is untouched.
                 after = before.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\/|"(?:[^"\\]|\\.)*"/g, token => {

package/dist/mcp/server.js

@@ -1,3 +1,5 @@
+import { conventionSupplements } from '../core/conventionDelivery.js';
+import { fieldCitationText } from "../core/fieldProvenance.js";
 /**
  * MCP server — the structured two-way API into the Hunch (DESIGN.md §7 / App. A).
  * Exposes read tools (query/why/bug_lineage/check_constraints/get_dependents) and
@@ -1102,7 +1104,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             decisionCorpus: store.recs("decisions"),
             historical: !!asOf,
             profile: profile ?? "builder",
-            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding],
+            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding, ...(asOf ? [] : conventionSupplements(store.recs("conventions")))],
         };
         // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
         // used to return an empty brief while the graph held the answer — fall back to
@@ -1822,7 +1824,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     const r = (response.records ?? {})[ref.id] ?? {};
                     const g = (k) => { const v = r[k]; return typeof v === "string" ? v : v == null ? "" : JSON.stringify(v); };
                     if (ref.facet === "derived")
-                        return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}`;
+                        return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}${fieldCitationText(r)}`;
                     if (ref.facet === "commitments")
                         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") {
@@ -1858,7 +1860,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                             : sor.observed_truncated ? ['- More observations exist; read this subject with observed_page:{} in one partition, then follow next_cursor.'] : []),
                         ...(sor.invalidated_by.length ? [`- invalidated by: ${sor.invalidated_by.join(", ")}`] : [])].join("\n") || "(nothing on record for this subject)"
                     : "";
-                return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}`, response);
+                const conventionText = response.conventions ? '\n\nExplicit conventions (advisory; no scope takes precedence):\n' + response.conventions.items.map(item => {
+                    const record = response.records?.[item.ref.id];
+                    return `- ${item.ref.scope.kind}/${item.ref.scope.id} · ${item.key} · ${record?.status}/${item.currentness}${item.conflict ? ' · CONFLICT' : ''}: ${String(record?.value ?? '').slice(0, 300)} (${item.ref.id})`;
+                }).join('\n') + (response.conventions.truncated ? '\nMore conventions exist; this view is incomplete.' : '') : '';
+                return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}${conventionText}`, response);
             }
             catch (e) {
                 return stateRefusal(e);
@@ -1866,7 +1872,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         });
         server.registerTool("nuryel_write", {
             title: "nuryel.state/1 write — provenance + idempotency in, durability out",
-            description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version.",
+            description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version. With capability nuryel.field-provenance/1, a derived record may carry field_provenance: [{selector:{kind:json_pointer,path:/field} or {kind:text,start:0,end:10}, value_hash:stateHash(selected scalar or text), dependency_hashes:[stateHash(existing dependency)]}]. Text offsets count Unicode code points, end exclusive. Citations are writer-supplied traceability, not verified support; negotiate support in every shared reader before writing them. With nuryel.record-visibility/1, records may carry visibility:{owner:principal-id,readers:[ids],writers:[ids]}; the owner is implicit in both lists, and writers must be readers. Owner-only audience changes require expected_version, including supersession. Restricted records require a dedicated partition; local stdio principal assertions assume trusted callers.",
             inputSchema: { ...WriteRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
             outputSchema: WriteResultSchema.shape,
         }, async ({ cwd: _cwd, ...input }) => {

package/dist/serve/app.d.ts

@@ -27,6 +27,8 @@ export declare class HttpProblem extends Error {
     constructor(status: number, code: string, message: string, extra?: Record<string, unknown>);
 }
 export interface ServeOptions {
+    /** Required for key-bound credentials when supplying an in-memory configuration. */
+    authStateDir?: string;
     version?: string;
     /** Injectable for tests: how a partition's store is opened. */
     openStore?: (root: string) => HunchStore;