@davesheffer/hunch 1.23.3 → 1.25.0

package/README.md

@@ -6,28 +6,20 @@
 [![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 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.
 
-That is how settled decisions get reopened, fixed bugs return, and technically plausible changes
-arrive feeling foreign to the project.
+That is how settled decisions get reopened, fixed bugs return, and technically plausible changes arrive feeling foreign to the project.
 
-**Hunch is evidence-backed 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 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:
 
 - why the code is shaped this way;
-- how the repository communicates, reviews, and builds;
+- 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.
+- which trusted decisions, fixes and architectural boundaries the result must preserve.
 
-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.
+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 starts advisory. Nothing blocks until a human deliberately trusts a precise rule and opts
-into strict enforcement.
+Memory starts advisory. Nothing blocks until a human deliberately trusts a precise rule and opts into strict enforcement.
 
 ## Start in five minutes
 
@@ -44,12 +36,19 @@ Reload your coding assistant, then ask a normal question:
 
 > Why is this built this way?
 
-`hunch init` indexes the repository, installs local lifecycle hooks, and connects supported
-assistants without replacing their existing configuration. The next session receives the relevant
-story with its sources, not a giant transcript or a generic prompt wall. Lifecycle coverage
-depends on the harness; MCP connectivity alone does not establish automatic grounding or enforcement.
+`hunch init` indexes the repository, installs local lifecycle hooks and connects supported assistants without replacing their existing configuration. The next session receives the relevant story with its sources, not a giant transcript or generic prompt wall.
 
-Check the repository's integrations after upgrading Hunch or switching assistants:
+Lifecycle coverage depends on the harness; MCP connectivity alone does not establish automatic grounding or enforcement.
+
+To update Hunch and configured harness pins for the current repository:
+
+```sh
+hunch update
+```
+
+Agents receive an instruction to run this when you ask **“update Hunch”** in generated Hunch guidance. Restart active harnesses afterward.
+
+Check integrations after upgrading Hunch or switching assistants:
 
 ```sh
 hunch integrations check
@@ -58,25 +57,11 @@ hunch integrations check --harness claude --probe --require mcp
 hunch integrations check --harness codex --require context,edit-blocking
 ```
 
-`check` exits nonzero on stale pins, malformed configuration, or missing expected hooks.
-`repair-pins` aligns existing exact npm pins with the exact Hunch dependency in `package.json`
-(or the running Hunch version when no dependency is declared). It preserves other settings,
-refuses ambiguous/custom TOML and malformed files, and does not enable enforcement.
-Reconnect active MCP sessions after repairing pins.
-
-Capabilities are reported as **verified**, **advisory-only**, **unsupported**, or **untested**.
-`--require` fails unless every named capability is verified. The Codex example currently fails:
-Hunch's Codex integration supplies MCP and instructions, with no native lifecycle adapter.
-The opt-in `--probe` starts the selected generated npm launcher, checks the server version,
-and reads memory; it may download the pinned package. It verifies a fresh MCP process only,
-not the existing host session, hook delivery, or whether a model follows the memory.
-Custom launchers and environment overrides require host-side verification.
-
-`doctor` includes this report, and session hooks with a context channel surface configuration
-problems. Checks cover repository-local configurations; global/managed overrides remain
-outside this inspection. Use `hunch integrations check` in CI to prevent pin drift; add
-`--require` for capabilities your workflow cannot operate without. Hook failure remains
-non-blocking; this explicit CI/preflight gate fails closed on unmet requirements.
+Capabilities are reported as **verified**, **advisory-only**, **unsupported** or **untested**. `--require` fails unless every named capability is verified.
+
+The Codex integration currently supplies MCP and instructions, with no native lifecycle adapter. The opt-in `--probe` verifies a fresh MCP process, not whether an existing host session or model actually followed the memory.
+
+Use `hunch integrations check` in CI to prevent pin drift; add `--require` for capabilities your workflow cannot operate without.
 
 ## One evidence loop, not another model
 
@@ -98,37 +83,29 @@ Git history + ADRs + corrections + tests + repository conventions
                   deterministic change receipt
 ```
 
-Hunch is not an agent, orchestrator, or hosted knowledge service. It is the durable reasoning and
-validation layer behind the tools that write the code.
+Hunch is not the agent and is not the workflow engine. The model thinks; Hunch holds deterministic, evidence-backed state about the project and validates what must remain true.
 
 ## What Hunch understands
 
 | Layer | What it adds |
 | --- | --- |
-| **Engineering Memory** | Decisions, rejected alternatives, corrections, bug lineage, findings, and the rationale a future session would otherwise miss. |
-| **Code Graph** | Symbols, calls, imports, dependencies, components, blast radius, and architectural reachability across TypeScript, JavaScript, Python, Go, PHP, YAML, and Helm. Memory itself works with any language. |
-| **Project DNA** | Revision-specific, evidence-backed observations about how a repository communicates and works: vocabulary, contribution habits, review expectations, engineering conventions, and culture. |
-| **Engineering Landscape** | Human-reviewed links from product and capability to system, repository, service, interface, data, delivery resources, runbooks, ownership, dashboards, and SLOs. |
-| **Validated Delivery** | The smallest relevant evidence for the current builder, reviewer, or architect, with provenance, currentness, omissions, authority, and a content-addressed receipt. |
-| **Native Change Proof** | A sealed exact-change artifact binding revisions, DNA, base/result graphs, memory, blast radius, conformance, guard verdict, and explicit gaps without granting workflow authority. |
-| **Change Gate + Constitution** | Deterministic checks for trusted constraints and architectural intent. Policies are compiled, proved, inspected, and explicitly activated by a human—never promoted by an agent in the background. |
+| **Engineering Memory** | Decisions, rejected alternatives, corrections, bug lineage, findings and rationale a future session would otherwise miss. |
+| **Code Graph** | Symbols, calls, imports, dependencies, components, blast radius and architectural reachability across supported languages/configuration. Memory itself works with any language. |
+| **Project DNA** | Revision-specific, evidence-backed observations about how a repository communicates and works: vocabulary, contribution habits, review expectations, engineering conventions and culture. |
+| **Engineering Landscape** | Durable links from product/capability to system, repository, service, interface, data, delivery resources, runbooks, ownership, dashboards and SLOs. |
+| **Validated Delivery** | The smallest relevant evidence for the current builder/reviewer/architect, with provenance, currentness, omissions, authority and a content-addressed receipt. |
+| **Native Change Proof** | A sealed exact-change artifact binding revisions, DNA, base/result graphs, memory, blast radius, conformance, guard verdict and explicit gaps without granting workflow authority. |
+| **Change Gate + Constitution** | Deterministic checks for trusted constraints and architectural intent. Policies are compiled, proved, inspected and explicitly activated by a human. |
 
-Readable JSON in `.hunch/` is the source of truth. SQLite is a fast, rebuildable projection. Git
-keeps the memory portable, reviewable, and reversible.
+Readable JSON in `.hunch/` is the repository-scoped source of truth. SQLite is a fast, rebuildable projection. Git keeps the state portable, reviewable and reversible.
 
 ## Project DNA: help the agent work like it belongs here
 
-Project DNA is Hunch's evidence-bound model of **how a repository communicates and works**. It is
-not a persona, does not impersonate a maintainer, and does not turn frequent behavior into policy.
+Project DNA is Hunch's evidence-bound model of **how a repository communicates and works**. It is not a persona, does not impersonate a maintainer and does not turn frequent behavior into policy.
 
-The deterministic baseline reads an exact Git revision, bounded commit history, and committed
-convention files. The current release can also accept bounded, caller-authorized pull-request and
-review evidence. Every evidence batch is validated and sealed; raw collaboration text does not
-enter the profile.
+The deterministic baseline reads an exact Git revision, bounded commit history and committed convention files. The current release can also accept bounded, caller-authorized pull-request/review evidence. Every evidence batch is validated and sealed; raw collaboration text does not enter the profile.
 
-Each trait keeps its category, confidence, freshness, repository revision, and evidence hash. Hunch
-can then include only the relevant DNA in normal context, explain how well a commit, PR, issue, or
-message matches repository conventions, and show how the profile changed between two revisions.
+Each trait keeps its category, confidence, freshness, repository revision and evidence hash. Hunch can include only the relevant DNA in normal context, explain how an artifact matches repository conventions and show profile change between revisions.
 
 ```bash
 hunch dna inspect
@@ -136,32 +113,27 @@ hunch dna context
 hunch dna diff <older-ref> <newer-ref>
 ```
 
-DNA may shape orientation, terminology, and advisory Project Match checks. It cannot create or
-override a decision, constraint, finding, conformance rule, policy, or permission.
+DNA may shape orientation, terminology and advisory Project Match checks. It cannot create or override a decision, constraint, finding, conformance rule, policy or permission.
 
-Read the [Project DNA contract](docs/project-dna.md) and the broader
-[Project DNA vision](docs/project-dna-engine.md).
+Read the [Project DNA contract](docs/project-dna.md) and broader [Project DNA vision](docs/project-dna-engine.md).
 
 ## Day-to-day
 
-Most capture happens around normal commits and test failures. These commands cover the common
-manual paths:
-
 | Command | Use it for |
 | --- | --- |
-| `hunch context "<task>" --profile builder` | Get a bounded builder, reviewer, or architect brief before work starts |
-| `hunch why <file-or-symbol>` | See the decisions, bugs, constraints, and blast radius behind code |
-| `hunch structure [target]` | Inspect the indexed repository shape without repeated search rounds |
+| `hunch context "<task>" --profile builder` | Get a bounded builder/reviewer/architect brief before work starts |
+| `hunch why <file-or-symbol>` | See decisions, bugs, constraints and blast radius behind code |
+| `hunch structure [target]` | Inspect indexed repository shape without repeated search rounds |
 | `hunch findings [scope]` | Inherit known-but-unfixed gaps instead of rediscovering them |
 | `hunch check --working` | Review the current tree against trusted project rules |
 | `hunch conform` | Prove the code still satisfies recorded architectural intent |
 | `hunch impact origin/main` | See the dependency and memory surface of a branch |
-| `hunch compare branch-a branch-b` | Rank candidate changes by the fewest invariant and decision conflicts |
+| `hunch compare branch-a branch-b` | Rank candidate changes by invariant/decision conflicts |
 | `hunch prove origin/main --public-only` | Produce a publication-safe `hunch.change-proof/1` artifact for an exact committed change |
 | `hunch landscape review` | Inspect a hash-bound repository landscape without writing authority |
-| `hunch now` | See recent memory and the live decision-backed roadmap |
-| `hunch escalations` | See the rare questions that genuinely require a human answer |
-| `hunch doctor` | Diagnose setup, provider, index, or overlay problems |
+| `hunch now` | See recent memory and live decision-backed roadmap |
+| `hunch escalations` | See questions that genuinely require a human answer |
+| `hunch doctor` | Diagnose setup, provider, index or overlay problems |
 
 When you are ready for deterministic enforcement:
 
@@ -170,45 +142,70 @@ hunch firmness strict
 hunch check --staged --strict
 ```
 
-That is the one moment of teeth. Captured memory cannot silently hard-block on its own.
+Captured memory cannot silently hard-block on its own.
 
-## What changed after v1.19
+## Deterministic organizational state — next product direction
+
+Repository memory solves one version of a larger problem.
+
+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:
+
+> **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.
 
-The v1.19 correction-search benchmark is still useful evidence, but it no longer describes the
-whole product.
+Planned state includes:
 
-- **v1.20 — one validated path from reason to result.** Role-shaped context, reviewed Engineering
-  Landscape fragments, exact change identity, PHP graph support, and hash-bound ADR review moved
-  source, provenance, currentness, omissions, and human authority through one delivery contract.
-- **v1.21 — Project DNA.** Hunch gained deterministic, revision-specific repository profiles,
-  bounded DNA context delivery, explainable Project Match checks, and auditable profile deltas.
-- **v1.22 — authorized collaboration evidence.** Hosts can contribute bounded PR and review
-  evidence to Project DNA through a typed, sealed contract without storing raw collaboration text
-  or changing policy authority.
+- decisions currently in force;
+- verified action receipts / what was done;
+- commitments and due-state;
+- entities and relationships;
+- code/system changes with proof;
+- repository/user/team/org DNA;
+- derived current state with exact dependencies/invalidation.
 
-See the [changelog](CHANGELOG.md) for the release-by-release detail and the
-[roadmap](ROADMAP.md) for what is next and deliberately out of scope.
+Agents continue to own live connector mechanics. Hunch must **not** become a managed proxy that fetches Gmail, CRM, WhatsApp or GitHub on an agent's behalf.
 
-<details>
-<summary><strong>The scoped v1.19 benchmark</strong></summary>
+Instead:
 
-On a preregistered 12-problem transfer, the supplemental inspection view found the changed
-declaration in 6 cases instead of 3 and the correct file in 10 cases instead of 8. On a separate
-12-case transfer, its progressive queue retained the same five successful finds while reducing the
-average declarations to inspect from 18.9 to 11 (41.9% less).
+```text
+                  Hunch deterministic state
+                        ↑       ↓
+agent -> deterministic action gate -> connector -> source system
+```
+
+Hunch may hold durable state **about** external work with credential-free provenance pointers, but should not mirror raw source-system contents into a universal cache.
+
+The first real-world pilot is **Sofia**, a working operations agent over CRM, Gmail and WhatsApp. Sofia's approved actions, follow-ups, customer/source relationships and cited summaries map naturally to action receipts, commitments, entities/relationships and dependency-bound state.
+
+The pilot measures whether Sofia and a second, different agent stop re-deriving contradictory state when the deterministic state is delivered before they answer or act.
+
+### The state contract, shipped
+
+As of 1.25.0 the contract exists as code: `nuryel.state/1` — three verbs (`read` under the
+delivery envelope's receipt, `write` with provenance and an idempotency key, `subscribe` to a
+strictly ordered change stream) over five new record facets: action receipts, commitments,
+derived state that names what it rests on, external entities and their relationships. Ids are
+derived from a record's facts, a replay returns the original, a second live decision on a topic is
+refused with the incumbent named, and derived state without dependencies is not state. Each scope
+keeps a git-native change ledger under `.hunch/changes/`; organization, team and user partitions
+are homed in an overlay, never in a repository. The MCP server binds it as `nuryel_capabilities`,
+`nuryel_read`, `nuryel_write` and `nuryel_subscribe`; every other transport will call the same
+store binding. Contract and evidence: [docs/nuryel-state-contract.md](docs/nuryel-state-contract.md).
+
+Read [Deterministic organizational state](docs/deterministic-state.md) and the [roadmap](ROADMAP.md).
 
-These are bounded diagnostic results, not a claim that Hunch is universally twice as accurate.
-Failed evidence and causal rerankers remain disabled; evidence can annotate the shortlist but does
-not reorder it or claim an exact correction owner. The detailed receipts live in
-[`bench/external/results`](bench/external/results).
+### Naming
 
-</details>
+The product is still **Hunch**. A possible hosted-platform name, **Nuryel**, is intentionally deferred until the state contract and Sofia pilot have evidence. Rename work is not the deliverable.
 
-## Share one living memory with your team
+## Share one living repository memory with your team
 
-Hunch can keep a team's memory in a dedicated private Git repository, separate from the code. Hunch
-does not host that repository. Give teammates and CI normal Git access, keep credentials in SSH or
-the Git credential helper, and have one maintainer connect it:
+The current release can keep a team's **repository-scoped** memory in a dedicated private Git repository, separate from the code.
+
+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
@@ -227,34 +224,39 @@ hunch init
 hunch doctor
 ```
 
-The committed pointer contains a credential-free repository locator and branch. The local clone,
-paths, preferences, and private overlays stay ignored. MCP sessions refresh shared memory at tool
-boundaries, and failed pushes are retried by a later capture or `hunch shared --sync`.
+The committed pointer contains a credential-free repository locator and branch. Local clone paths, preferences and private overlays stay ignored. MCP sessions refresh shared memory at tool boundaries; failed pushes can be retried by later capture or `hunch shared --sync`.
+
+Use `hunch firmness off` to pause hook enforcement without deleting history. Use `hunch shared --repo <url> --no-auto-commit` when captures should remain local until explicit `hunch shared --sync`.
 
-Use `hunch firmness off` to pause hook enforcement without deleting history. Use
-`hunch shared --repo <url> --no-auto-commit` when captures should remain local until an explicit
-`hunch shared --sync`.
+This existing Git-sharing feature is not the same thing as the planned organization/team/user state service. The roadmap extends the git-native model rather than declaring today's shared-memory repository to be an organization control plane.
 
 ## Trust boundaries that stay visible
 
-- **Local-first.** Hunch has no hosted memory service or telemetry. The graph travels with Git and
-  speaks MCP instead of belonging to one editor or model provider.
-- **Private when needed.** `hunch private --repo <url>` keeps sensitive reasoning in a separate
-  overlay. Local tools see the union; public CI and documentation remain public-only.
-- **Human authority.** Observations, generated drafts, imported ADRs, discovered landscape records,
-  and proved policy candidates do not silently become trusted truth.
-- **Deterministic core.** Indexing, retrieval receipts, currentness, conformance, checks, Project
-  DNA discovery, and policy evaluation do not require a model.
-- **No surprise synthesis bill.** Optional drafting can use a selected Claude Code, Codex, or
-  Cursor subscription CLI, a local OpenAI-compatible endpoint, or the deterministic fallback.
-  Public remote endpoints require explicit `HUNCH_SYNTH_ALLOW_METERED=1` opt-in.
-- **Traceable releases.** npm packages and the VS Code extension are content-addressed, verified
-  against their public registries, and tied back to exact source tags.
+- **Local-first today.** Repository Hunch works without a hosted service or telemetry. Git remains the repository-scoped authority.
+- **Hosted state is a roadmap extension, not a shipped claim.** Organization/team/user state will require authenticated scope/visibility, idempotency and durability while preserving git-native truth.
+- **Private when needed.** `hunch private --repo <url>` keeps sensitive repository reasoning in a separate overlay; public CI/documentation remain public-only.
+- **Human authority.** Observations, generated drafts, imported ADRs, discovered landscape records and proved policy candidates do not silently become trusted truth.
+- **Deterministic core.** Indexing, retrieval receipts, currentness, conformance, Project DNA discovery and policy evaluation do not require a model.
+- **Agents own execution.** Hunch state does not silently grant connector permissions, send messages or become a source-system proxy.
+- **No surprise synthesis bill.** Optional drafting can use a selected Claude Code, Codex or Cursor subscription CLI, a local OpenAI-compatible endpoint or deterministic fallback. Public remote endpoints require explicit opt-in.
+- **Traceable releases.** npm packages and the VS Code extension are content-addressed, verified against public registries and tied back to exact source tags.
+
+## What changed after v1.19
+
+The v1.19 correction-search benchmark remains scoped evidence, but it no longer describes the whole product.
+
+- **v1.20 — one validated path from reason to result.** Role-shaped context, reviewed Engineering Landscape fragments, exact change identity, PHP graph support and hash-bound ADR review moved source, provenance, currentness, omissions and human authority through one delivery contract.
+- **v1.21 — Project DNA.** Hunch gained deterministic, revision-specific repository profiles, bounded DNA context delivery, explainable Project Match checks and auditable profile deltas.
+- **v1.22 — authorized collaboration evidence.** Hosts can contribute bounded PR/review evidence to Project DNA through a typed, sealed contract without raw collaboration persistence or policy-authority change.
+- **v1.23 — native change proof and proof-carrying evidence work.** Exact Git change identity, graph before/after, decisions/constraints, blast radius and Change Gate result can be bound into a sealed evidence artifact without granting authority.
+
+See the [changelog](CHANGELOG.md) for release detail and the [roadmap](ROADMAP.md) for active work.
 
 ## Learn more
 
 - [Full documentation](https://www.hunchmemory.com/docs)
 - [Copy-paste cookbook](https://www.hunchmemory.com/cookbook)
+- [Deterministic organizational state](docs/deterministic-state.md)
 - [Project DNA](docs/project-dna.md)
 - [Native change proof](docs/change-proof.md)
 - [Engineering Landscape Graph](docs/engineering-landscape.md)

package/dist/cli/index.js

@@ -25,6 +25,7 @@ import { writeFileAtomic } from "../core/io.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { registerIntegrationCommands } from "./integrations.js";
+import { registerUpdateCommand } from "./update.js";
 import { inspectIntegrations, formatIntegrationHealth, integrationHealthFails, integrationSessionWarning } from "../integrations/health.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { JsonStore } from "../store/jsonStore.js";
@@ -112,6 +113,7 @@ import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext }
 const program = new Command();
 program.name("hunch").description("Hunch — engineering memory and a deterministic Change Gate for AI-assisted codebases.").version(HUNCH_VERSION);
 registerIntegrationCommands(program);
+registerUpdateCommand(program);
 let openStore = null;
 function openTeamStore(root, opts = {}) {
     // A committed team.json is an explicit declaration that this checkout belongs

package/dist/cli/update.js

@@ -0,0 +1,72 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findRoot } from "../core/paths.js";
+const PACKAGE = "@davesheffer/hunch";
+/** Arguments come only from fixed commands and a validated registry version.
+ * Windows needs the shell to resolve npm.cmd; cwd is never interpolated. */
+export function runNpm(root, args, capture = false) {
+    if (args.some(arg => !/^[a-zA-Z0-9@/_.=+:-]+$/.test(arg)))
+        throw new Error("unsafe npm argument");
+    const windows = process.platform === "win32";
+    const result = spawnSync(windows ? `npm ${args.join(" ")}` : "npm", windows ? [] : args, {
+        cwd: root, shell: windows, windowsHide: true,
+        encoding: "utf8", stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(`npm ${args.join(" ")} failed (${result.status ?? result.signal})${result.stderr ? `: ${result.stderr.trim()}` : ""}`);
+    return result.stdout ?? "";
+}
+/** Fresh child execution is essential: the currently running CLI still has the
+ * old modules loaded after npm replaces its installation. */
+export function updateHunch(root, opts = {}, run = (args, capture) => runNpm(root, args, capture), log = console.log) {
+    const file = join(root, "package.json");
+    const manifest = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("package.json must contain an object");
+    if (manifest.name === PACKAGE)
+        throw new Error("Run hunch update in a consumer repository, not Hunch's own source checkout.");
+    const sections = ["dependencies", "devDependencies", "optionalDependencies"];
+    const declared = sections.filter(section => {
+        const deps = manifest[section];
+        if (deps !== undefined && (!deps || typeof deps !== "object" || Array.isArray(deps)))
+            throw new Error(`invalid ${section} in package.json`);
+        return deps && Object.hasOwn(deps, PACKAGE);
+    });
+    if (declared.length > 1)
+        throw new Error("Hunch is declared in multiple dependency sections; resolve the duplicate before updating.");
+    if (declared.length && (manifest.workspaces || (manifest.packageManager && !/^npm@/.test(manifest.packageManager)) || ["pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"].some(name => existsSync(join(root, name))))) {
+        throw new Error("Automatic dependency updates currently support standalone npm projects. Update Hunch to an exact version with your package manager, then run hunch integrations repair-pins.");
+    }
+    const version = JSON.parse(run(["view", `${PACKAGE}@latest`, "version", "--json"], true));
+    if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version))
+        throw new Error("npm returned an invalid Hunch version");
+    const spec = `${PACKAGE}@${version}`;
+    const commands = [];
+    if (declared.length) {
+        const flag = { dependencies: "--save-prod", devDependencies: "--save-dev", optionalDependencies: "--save-optional" }[declared[0]];
+        commands.push(["install", flag, "--save-exact", spec]);
+    }
+    if (!declared.length || opts.global)
+        commands.push(["install", "--global", spec]);
+    // The alias prevents npm exec from substituting a stale local hunch binary.
+    commands.push(["exec", "--yes", `--package=hunch-exact@npm:${spec}`, "--", "hunch", "integrations", "repair-pins"]);
+    log(`${opts.dryRun ? "Preview" : "Updating"}: Hunch ${version} for ${root}`);
+    for (const args of commands) {
+        log(`npm ${args.join(" ")}`);
+        if (!opts.dryRun)
+            run(args);
+    }
+    if (!opts.dryRun)
+        log("Hunch updated; repository integration check passed. Restart or reconnect active harnesses to load the new MCP version.");
+}
+export function registerUpdateCommand(program) {
+    program.command("update")
+        .description("Update Hunch to latest and repair all configured harness pins in this repository")
+        .option("--global", "also update the global CLI when a repository dependency exists")
+        .option("--dry-run", "resolve latest and print commands without changing files")
+        .action((opts) => updateHunch(findRoot(), opts));
+}
+//# sourceMappingURL=update.js.map

package/dist/core/provenance.js

@@ -0,0 +1,43 @@
+/**
+ * Provenance and credential-free text — a LEAF module (zod only) so that record
+ * schemas registered in the store can import it without pulling in types.ts,
+ * which itself imports the store's kind registry. types.ts re-exports everything
+ * here, so existing imports keep working unchanged.
+ */
+import { z } from "zod";
+/** Where a fact came from and how much to trust it. Confidence tiers (DESIGN §4):
+ *  inferred < extracted < llm_draft < llm_draft+human_confirmed/derived. */
+export const ProvenanceSchema = z.object({
+    source: z.string().describe("e.g. extracted | inferred | llm_draft | human_confirmed | test_failure+llm | derived"),
+    confidence: z.number().min(0).max(1),
+    evidence: z.array(z.string()).default([]).describe("file paths, commit ids, test ids backing the claim"),
+    last_verified: z.string().optional().describe("ISO timestamp of last re-validation"),
+});
+export const SENSITIVE_METADATA_KEY = /(^|[_-])(authorization|bearer|credential|password|passwd|private[_-]?key|secret|token|api[_-]?key)($|[_-])/i;
+const SENSITIVE_ASSIGNMENT = /\b(authorization|password|passwd|private[_-]?key|secret|access[_-]?token|refresh[_-]?token|api[_-]?key)\s*[:=]\s*[^\s,;]{4,}/i;
+const PRIVATE_KEY_BLOCK = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/i;
+const BEARER_VALUE = /\bBearer\s+[A-Za-z0-9._~+\/-]{12,}/i;
+/** Reject credential material while allowing ordinary architecture prose such as
+ * "authentication service" or "secrets are managed externally". */
+export function isCredentialFreeText(value) {
+    if (PRIVATE_KEY_BLOCK.test(value) || BEARER_VALUE.test(value) || SENSITIVE_ASSIGNMENT.test(value))
+        return false;
+    try {
+        const url = new URL(value);
+        if (url.username || url.password)
+            return false;
+        for (const [key] of url.searchParams)
+            if (SENSITIVE_METADATA_KEY.test(key))
+                return false;
+    }
+    catch { /* credential-free canonical locators need not be absolute URLs */ }
+    return true;
+}
+/** Bare secret shapes the general detector does not cover: it looks for assignments, bearer
+ *  values, private-key blocks and URL userinfo; a token pasted on its own into an object key or
+ *  locator would pass. These prefixes are the common ones. */
+const BARE_SECRET = /(?:^|[^A-Za-z0-9])(?:ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9_-]{16,}|xox[abpr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})/;
+export function isCredentialFreeValue(value) {
+    return isCredentialFreeText(value) && !BARE_SECRET.test(value);
+}
+//# sourceMappingURL=provenance.js.map