@davesheffer/hunch 0.16.0 → 0.17.0

package/README.md

@@ -135,6 +135,16 @@ forbidden dependency) — code that never existed, so a diff reviewer is blind t
 decision carries machine-checkable **tripwires**; re-introduce one and Hunch blocks it with
 the receipt of what you rejected and why. → [docs](https://hunch-pi.vercel.app/docs#veto)
 
+### Redundancy Guard — "this already exists"
+
+An agent works from a *local* context window, so it re-implements a helper that already
+lives three modules over, or re-adds a dependency the codebase already has — sprawl a
+diff-only reviewer can't see, but Hunch's symbol graph can. Add a function or class already
+defined elsewhere and `hunch check` / the CI guard / `hunch_merge_verdict` flag it with the
+existing location. Deterministic and **advisory** — it never blocks; tuned to stay quiet
+(stopword + length filters, scoped to the change's own project root, move-aware so a
+refactor isn't mistaken for a duplicate). → [docs](https://hunch-pi.vercel.app/docs#redundancy)
+
 Plus the **Regression Guard** (re-adding deliberately-retired code) and the
 **[CI Constraint Guard](https://hunch-pi.vercel.app/docs#ci)** (`hunch ci` — a PR gate that
 comments the affected `con_`/`dec_` ids and fails on a blocking one).
@@ -148,6 +158,17 @@ is **OS-agnostic**: paths are stored in POSIX form and an installed Hunch regist
 server by package name, so Windows / macOS / Linux teammates share one memory without
 per-machine fixups. → [docs](https://hunch-pi.vercel.app/docs#team)
 
+## Private memory (public repo, private context)
+
+Open-source your code without open-sourcing your *reasoning*. Point `HUNCH_PRIVATE_DIR` at a
+separate **private repo** and Hunch unions that store into every query and guard **locally** —
+MCP and the pre-edit hook see your sensitive decisions/bugs/constraints — while your public
+`.hunch/` stays clean. It's **opt-in and default-off** (unset the var → fully inert), and
+**leak-safe by construction**: committed files and the CI PR comment render *public-only*, so a
+private record can't reach a public surface. Record sensitive items with `private: true`
+(`hunch_record_decision` / `hunch_record_correction`); `hunch doctor` shows whether the overlay
+is on. → [docs](https://hunch-pi.vercel.app/docs#private)
+
 ## Continuous learning (CI)
 
 The decision half of the loop is automatic (the post-commit hook). Light up the bug/constraint

package/dist/cli/index.js

@@ -15,7 +15,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
-import { relative } from "node:path";
+import { relative, resolve } from "node:path";
 import { Command } from "commander";
 import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
@@ -545,13 +545,14 @@ program
 // ---- check (constraint enforcement) ---------------------------------------
 program
     .command("check")
-    .description("Flag changes that touch a do-not-break invariant — the local guardrail AND the CI/PR Constraint Guard.")
+    .description("Flag changes that touch a do-not-break invariant — the local guardrail AND the CI/PR Constraint Guard. Also flags (advisory) symbols you add that already exist elsewhere — possible re-implementation/sprawl.")
     .option("--staged", "check git staged files (default)")
     .option("--commit <sha>", "check a specific commit's files")
     .option("--base <ref>", "check a PR/branch: files changed vs <ref> (e.g. origin/main) — for CI")
     .option("--strict", "exit non-zero ONLY on a direct, high-confidence, non-stale blocking invariant (near/stale/low-confidence stay advisory)")
     .option("--format <fmt>", "output: text (default) | markdown (a PR comment)", "text")
     .option("--blast", "also print the dependency blast radius of the changed files")
+    .option("--public-only", "exclude the private overlay (HUNCH_PRIVATE_DIR) from the report — use for any output that may be posted publicly (the CI PR comment passes this)")
     .action((opts) => {
     const sources = [opts.commit && "--commit", opts.base && "--base", opts.staged && "--staged"].filter(Boolean);
     if (sources.length > 1)
@@ -575,12 +576,14 @@ program
         return;
     }
     // DIRECT (scope match) + NEAR (blast radius) + REGRESSION (re-added retired
-    // code) + the hardened strict gate + causal `why` citations — all assembled by
-    // the shared store.buildCheckReport (also used by the hunch_merge_verdict tool).
+    // code) + REDUNDANT (adds a symbol already defined elsewhere — advisory) + the
+    // hardened strict gate + causal `why` citations — all assembled by the shared
+    // store.buildCheckReport (also used by the hunch_merge_verdict tool).
     const diff = opts.commit ? commitDiff(opts.commit, root) : opts.base ? rangeDiff(opts.base, root) : stagedDiff(root);
     const report = store.buildCheckReport(files, diff, {
         strict: !!opts.strict,
         lastChange: (f) => lastChangeDate(f, root),
+        publicOnly: !!opts.publicOnly,
     });
     if (opts.blast && !markdown) {
         console.log(`Blast radius of ${files.length} changed file(s):`);
@@ -1040,6 +1043,10 @@ program
     }
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
+    const privDir = process.env.HUNCH_PRIVATE_DIR?.trim();
+    console.log(privDir
+        ? `private:    on → ${resolve(privDir)} (local overlay — unioned into queries; never committed or posted publicly)`
+        : dim(`private:    off — set HUNCH_PRIVATE_DIR to overlay a separate private memory repo for sensitive records`));
     // Semantic search is opt-in and local. Report availability + coverage without
     // loading the model (selectEmbedder only probes; embeddingStats just counts rows).
     const emb = await selectEmbedder();

package/dist/core/paths.js

@@ -22,6 +22,21 @@ export function hunchPaths(root) {
         dir: (kind) => join(hunch, kind),
     };
 }
+/** Build paths for a hunch-layout directory given DIRECTLY — i.e. `hunchDir` IS
+ *  the dir holding the kind subdirs (decisions/, bugs/, …). Used for an external
+ *  PRIVATE overlay store (HUNCH_PRIVATE_DIR), which lives in a separate repo the
+ *  user controls rather than under the current repo's `.hunch/`. */
+export function hunchPathsForDir(hunchDir) {
+    const hunch = resolve(hunchDir);
+    return {
+        root: dirname(hunch),
+        hunch,
+        sqlite: join(hunch, "hunch.sqlite"),
+        manifest: join(hunch, "manifest.json"),
+        config: join(hunch, "config.json"),
+        dir: (kind) => join(hunch, kind),
+    };
+}
 /** Walk up from `start` to find the nearest repo containing a .hunch/ dir,
  *  else the nearest git repo, else `start`. Lets `hunch` run from subdirs. */
 export function findRoot(start = process.cwd()) {

package/dist/integrations/ciAction.js

@@ -46,9 +46,14 @@ jobs:
 
       - name: Run Constraint Guard
         id: guard
+        # The report is posted as a public PR comment, so it MUST stay public-only:
+        # --public-only excludes any private overlay, and HUNCH_PRIVATE_DIR is neutralized
+        # here as defense-in-depth. Never wire a private memory store into CI.
+        env:
+          HUNCH_PRIVATE_DIR: ""
         run: |
           set +e
-          hunch check --base "origin/\${{ github.base_ref }}" --strict --format markdown > hunch-report.md
+          hunch check --base "origin/\${{ github.base_ref }}" --strict --format markdown --public-only > hunch-report.md
           echo "exit=$?" >> "$GITHUB_OUTPUT"
           set -e
 

package/dist/integrations/gitignore.js

@@ -19,6 +19,10 @@ const ENTRIES = [
     ".hunch/*.sqlite-wal",
     ".hunch/*.sqlite-journal",
     ".hunch/**/*.tmp*",
+    // A local PRIVATE overlay store (HUNCH_PRIVATE_DIR) for sensitive memory — never
+    // committed. This is the conventional in-repo path; point the env elsewhere for a
+    // fully separate private repo.
+    ".hunch-private/",
 ];
 export function ensureGitignore(root) {
     const path = join(root, ".gitignore");

package/dist/mcp/server.js

@@ -223,7 +223,7 @@ export function buildServer(root) {
     // -- hunch_record_decision (write-back) -----------------------------------
     server.registerTool("hunch_record_decision", {
         title: "Record a decision (write-back)",
-        description: "Persist a new Decision (ADR) into Hunch with provenance. Use after making a non-trivial design choice so future sessions are grounded in it.",
+        description: "Persist a new Decision (ADR) into Hunch with provenance. Use after making a non-trivial design choice so future sessions are grounded in it. Set private:true to keep a SENSITIVE decision out of a (possibly public) repo — it is written to the HUNCH_PRIVATE_DIR overlay store and stays queryable locally, never committed here.",
         inputSchema: {
             decision: z.object({
                 title: z.string(),
@@ -236,6 +236,7 @@ export function buildServer(root) {
                 status: z.enum(["proposed", "accepted", "rejected", "superseded"]).optional(),
                 commit: z.string().optional(),
                 supersedes: z.string().optional().describe("id of a decision this one replaces — closes its valid-time window (invalidate, don't delete)"),
+                private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — for sensitive decisions kept out of a public repo. Errors if no private store is configured."),
             }),
         },
     }, async ({ decision }) => {
@@ -251,7 +252,9 @@ export function buildServer(root) {
             const id = fullSha ? decisionId(fullSha) : decisionId(`manual:${decision.title}`);
             // Preserve the ADR lineage: upgrading an auto-draft yields the composite
             // provenance the design specifies.
-            const existing = store.json.get("decisions", id);
+            // Public-only lookup; skip it for a private write so a private decision never
+            // inherits fields from a same-id PUBLIC record (and vice-versa).
+            const existing = decision.private ? undefined : store.json.get("decisions", id);
             const source = existing && existing.provenance.source.includes("llm_draft")
                 ? "llm_draft+human_confirmed"
                 : "human_confirmed";
@@ -277,14 +280,22 @@ export function buildServer(root) {
                 provenance: { source, confidence: 0.95, evidence: (decision.related_files ?? existing?.provenance.evidence ?? []).map(toPosixTarget) },
                 date: now,
             };
-            store.json.put("decisions", rec);
-            // Invalidate, don't delete: closing the superseded decision's valid-time
-            // window (+ a supersedes edge) preserves the why-it-changed trail.
-            const superseded = decision.supersedes ? store.supersede(decision.supersedes, rec) : null;
+            // Route the write: private records go to the HUNCH_PRIVATE_DIR overlay (never
+            // the committed repo); everything else to the public store. putPrivate throws
+            // if no private store is configured, so "private" can't silently fall public.
+            if (decision.private)
+                store.putPrivate("decisions", rec);
+            else
+                store.json.put("decisions", rec);
+            // Invalidate, don't delete: closing the superseded decision's valid-time window
+            // (+ a supersedes edge) preserves the why-it-changed trail. Supersede operates on
+            // the public store, so skip it for a private record (a v1 limitation, not a leak).
+            const superseded = decision.supersedes && !decision.private ? store.supersede(decision.supersedes, rec) : null;
             store.reindex();
             const supNote = superseded ? ` Superseded ${superseded.id} (window closed at ${rec.valid_from}).` : "";
             const note = decision.commit && !fullSha ? ` (note: commit "${decision.commit}" could not be resolved — recorded as a standalone decision, not linked to a commit)` : "";
-            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${supNote}${note}`);
+            const where = decision.private ? " [PRIVATE overlay — not committed to this repo]" : "";
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${where}${supNote}${note}`);
         }
         catch (e) {
             return err(`Failed to record decision: ${e.message}`);
@@ -302,19 +313,26 @@ export function buildServer(root) {
             type: z.enum(["security", "performance", "correctness", "architecture", "compliance"]).optional(),
             rationale: z.string().optional().describe("Why it must hold."),
             source_decision: z.string().optional().describe("id of a decision this correction derives from."),
+            private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — a sensitive rule enforced locally (pre-edit hook + local check) but never exposed in a public PR comment. Errors if no private store is configured."),
         },
     }, async (input) => {
         try {
             if (!input.rule || !input.rule.trim())
                 return err("rule is required — state the invariant in plain words.");
             const rec = buildCorrectionConstraint(input, new Date().toISOString());
-            const existing = store.json.get("constraints", rec.id);
-            store.json.put("constraints", rec);
+            // Private corrections go to the overlay (enforced locally via the merged read,
+            // never rendered into the public CI comment, which is public-only by construction).
+            const existing = input.private ? undefined : store.json.get("constraints", rec.id);
+            if (input.private)
+                store.putPrivate("constraints", rec);
+            else
+                store.json.put("constraints", rec);
             store.reindex();
             const enforce = rec.severity === "blocking"
                 ? "blocks a DIRECT edit to its scope at strict firmness, and fails a PR whose diff touches that scope (CI guard); blast-radius hits and lower firmness stay advisory"
                 : "flags violating edits and PRs (advisory)";
-            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}). It now ${enforce}.`);
+            const where = input.private ? " [PRIVATE overlay — not committed to this repo]" : "";
+            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.`);
         }
         catch (e) {
             return err(`Failed to record correction: ${e.message}`);
@@ -323,7 +341,7 @@ export function buildServer(root) {
     // -- hunch_merge_verdict (Causal Merge Verdict — read-only, client-agnostic) --
     server.registerTool("hunch_merge_verdict", {
         title: "Causal merge verdict: is this change safe against the recorded WHY?",
-        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory) and any deliberately-retired code the diff re-introduces. Deterministic, no LLM. Omit base AND commit to check STAGED changes; pass base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
+        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base AND commit to check STAGED changes; pass base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Diff a single commit (sha/ref). Omit base AND commit to check staged changes."),

package/dist/store/hunchStore.js

@@ -10,7 +10,8 @@
  *   - bugLineage():     bugs matching a symptom/symbol + their lineage
  *   - fragility():      ranked fragility report with evidence
  */
-import { toPosixTarget } from "../core/paths.js";
+import { resolve } from "node:path";
+import { toPosixTarget, hunchPathsForDir } from "../core/paths.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { openDb } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
@@ -23,10 +24,51 @@ import { analyzeDiff } from "../extractors/diff.js";
 export class HunchStore {
     paths;
     json;
+    /** Optional PRIVATE overlay (HUNCH_PRIVATE_DIR) — a second store in a repo the
+     *  user controls. Unioned into reads via recs(); never written by public paths. */
+    privateJson;
+    /** When true, recs() ignores the private overlay (public-only). Set transiently by
+     *  buildCheckReport({publicOnly}) so any PUBLICLY-POSTED report (the CI PR comment)
+     *  can never render a private record — a publicly-posted output is a leak surface
+     *  equal to a committed file (dec_d7bad4ccb7). */
+    suppressPrivate = false;
     _db = null;
     constructor(paths) {
         this.paths = paths;
         this.json = new JsonStore(paths);
+        const priv = process.env.HUNCH_PRIVATE_DIR?.trim();
+        if (priv)
+            this.privateJson = new JsonStore(hunchPathsForDir(resolve(priv)));
+    }
+    /** Merged read: public ∪ private overlay (private wins on id collision). Every
+     *  QUERY / REINDEX path uses this so MCP + the guards see private memory. Public-
+     *  artifact writers keep using this.json.loadAll (public-only) so a private record
+     *  can never reach a committed file — see dec_d7bad4ccb7. */
+    recs(kind) {
+        const pub = this.json.loadAll(kind);
+        const priv = this.suppressPrivate ? undefined : this.privateJson?.loadAll(kind);
+        if (!priv?.length)
+            return pub;
+        const byId = new Map();
+        for (const r of pub)
+            byId.set(r.id, r);
+        for (const r of priv)
+            byId.set(r.id, r);
+        return [...byId.values()];
+    }
+    /** Whether a private overlay store is configured (HUNCH_PRIVATE_DIR is set). */
+    get hasPrivate() {
+        return !!this.privateJson;
+    }
+    /** Write a record into the PRIVATE overlay (never the public repo). Throws if no
+     *  HUNCH_PRIVATE_DIR is configured, so a "private" write can never silently land
+     *  in the public `.hunch/`. */
+    putPrivate(kind, record) {
+        if (!this.privateJson) {
+            throw new Error("No private store configured — set HUNCH_PRIVATE_DIR to a directory Hunch can write sensitive records into.");
+        }
+        this.privateJson.ensureDirs();
+        return this.privateJson.put(kind, record);
     }
     get db() {
         if (!this._db)
@@ -50,7 +92,7 @@ export class HunchStore {
             const fts = (ref, kind, title, body) => {
                 insFts.run(ref, kind, title, body ?? "");
             };
-            const comps = this.json.loadAll("components");
+            const comps = this.recs("components");
             const insComp = db.prepare(`INSERT INTO components VALUES (@id,@kind,@name,@responsibility,@paths,@status,@owners,@fragility,@ps,@pc,@pe,@created_at,@updated_at)`);
             for (const c of comps) {
                 insComp.run({
@@ -62,14 +104,14 @@ export class HunchStore {
                 fts(c.id, "components", c.name, `${c.responsibility} ${c.paths.join(" ")}`);
             }
             counts.components = comps.length;
-            const edges = this.json.loadAll("edges");
+            const edges = this.recs("edges");
             const insEdge = db.prepare(`INSERT INTO edges VALUES (@id,@from,@to,@type,@reason,@strength,@ps,@pc,@pe)`);
             for (const e of edges) {
                 insEdge.run({ id: e.id, from: e.from, to: e.to, type: e.type, reason: e.reason, strength: e.strength,
                     ps: e.provenance.source, pc: e.provenance.confidence, pe: JSON.stringify(e.provenance.evidence) });
             }
             counts.edges = edges.length;
-            const syms = this.json.loadAll("symbols");
+            const syms = this.recs("symbols");
             const insSym = db.prepare(`INSERT INTO symbols VALUES (@id,@file,@name,@kind,@sh,@calls,@called_by,@loc,@churn,@bug,@fanin,@fanout,@last)`);
             for (const s of syms) {
                 insSym.run({ id: s.id, file: s.file, name: s.name, kind: s.kind, sh: s.signature_hash,
@@ -79,7 +121,7 @@ export class HunchStore {
                 fts(s.id, "symbols", `${s.name} (${s.kind})`, s.file);
             }
             counts.symbols = syms.length;
-            const decs = this.json.loadAll("decisions");
+            const decs = this.recs("decisions");
             const insDec = db.prepare(`INSERT INTO decisions VALUES (@id,@title,@status,@context,@decision,@cons,@alts,@rc,@rf,@sup,@cbb,@commit,@ps,@pc,@pe,@date)`);
             for (const d of decs) {
                 insDec.run({ id: d.id, title: d.title, status: d.status, context: d.context, decision: d.decision,
@@ -90,7 +132,7 @@ export class HunchStore {
                 fts(d.id, "decisions", d.title, `${d.context} ${d.decision} ${d.consequences.join(" ")}`);
             }
             counts.decisions = decs.length;
-            const bugs = this.json.loadAll("bugs");
+            const bugs = this.recs("bugs");
             const insBug = db.prepare(`INSERT INTO bugs VALUES (@id,@title,@symptom,@rc,@sev,@status,@af,@as,@lin,@ps,@pc,@pe)`);
             for (const b of bugs) {
                 insBug.run({ id: b.id, title: b.title, symptom: b.symptom, rc: b.root_cause, sev: b.severity, status: b.status,
@@ -99,7 +141,7 @@ export class HunchStore {
                 fts(b.id, "bugs", b.title, `${b.symptom} ${b.root_cause}`);
             }
             counts.bugs = bugs.length;
-            const cons = this.json.loadAll("constraints");
+            const cons = this.recs("constraints");
             const insCon = db.prepare(`INSERT INTO constraints VALUES (@id,@type,@statement,@scope,@sev,@enf,@rat,@sd,@viol,@ps,@pc,@pe)`);
             for (const c of cons) {
                 insCon.run({ id: c.id, type: c.type, statement: c.statement, scope: JSON.stringify(c.scope),
@@ -297,11 +339,11 @@ export class HunchStore {
      *  history-inclusive view (backward-compatible default). */
     why(target, opts = {}) {
         target = toPosixTarget(target);
-        const decisions = this.json.loadAll("decisions");
-        const bugs = this.json.loadAll("bugs");
-        const constraints = this.json.loadAll("constraints");
-        const symbols = this.json.loadAll("symbols");
-        const components = this.json.loadAll("components");
+        const decisions = this.recs("decisions");
+        const bugs = this.recs("bugs");
+        const constraints = this.recs("constraints");
+        const symbols = this.recs("symbols");
+        const components = this.recs("components");
         const asOf = opts.asOf;
         const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || s.file.endsWith(target));
         const symIds = new Set(matchedSymbols.map((s) => s.id));
@@ -384,7 +426,7 @@ export class HunchStore {
      *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at
      *  that instant (time-travel: "what must I not have broken as of commit X?"). */
     checkConstraints(scope, opts = {}) {
-        const all = this.json.loadAll("constraints");
+        const all = this.recs("constraints");
         const asOf = opts.asOf;
         return all
             .filter((c) => c.scope.some((g) => pathMatchesGlob(scope, g) || pathMatchesGlob(g, scope) || g === scope))
@@ -403,7 +445,7 @@ export class HunchStore {
         const dec = c.source_decision ? this.json.get("decisions", c.source_decision) : null;
         if (dec)
             out.decision = { id: dec.id, title: dec.title, decision: dec.decision };
-        const bugs = this.json.loadAll("bugs");
+        const bugs = this.recs("bugs");
         // Deterministic when several bugs link one constraint (the verdict claims to be
         // deterministic): highest severity first, then lowest id — never filesystem order.
         const SEV = { critical: 3, high: 2, medium: 1, low: 0 };
@@ -420,55 +462,66 @@ export class HunchStore {
      *  gate and a causal `why` citation per direct hit. Read-only — shared by
      *  `hunch check`, the CI guard, and hunch_merge_verdict so they never drift. */
     buildCheckReport(files, diff, opts) {
-        const direct = new Map();
-        for (const f of files)
-            for (const c of this.checkConstraints(f)) {
-                const e = direct.get(c.id) ?? { c, files: [] };
-                e.files.push(f);
-                direct.set(c.id, e);
-            }
-        const near = new Map();
-        for (const f of files)
-            for (const b of this.blastRadiusFiles(f))
-                for (const c of this.checkConstraints(b.file)) {
-                    if (direct.has(c.id))
-                        continue;
-                    const e = near.get(c.id) ?? { c, via: [] };
-                    e.via.push(`${f} → ${b.file} (${b.via}, depth ${b.depth})`);
-                    near.set(c.id, e);
+        // publicOnly excludes the private overlay from THIS report — required for any output
+        // that may be posted publicly (the CI PR comment), since a posted comment is a leak
+        // surface equal to a committed file. Local `hunch check` / the pre-edit hook omit it
+        // and so still enforce private constraints. See dec_d7bad4ccb7.
+        const prevSuppress = this.suppressPrivate;
+        this.suppressPrivate = opts.publicOnly ?? false;
+        try {
+            const direct = new Map();
+            for (const f of files)
+                for (const c of this.checkConstraints(f)) {
+                    const e = direct.get(c.id) ?? { c, files: [] };
+                    e.files.push(f);
+                    direct.set(c.id, e);
                 }
-        const an = analyzeDiff(diff);
-        const regHits = this.regressionHits({ symbols: an.addedSymbols.map((s) => s.name), deps: an.addedDeps }, files);
-        const staleRecords = opts.strict && opts.lastChange ? this.staleness(opts.lastChange) : [];
-        const staleIds = new Set(staleRecords.filter((s) => s.kind === "constraint").map((s) => s.id));
-        const staleDecisionIds = new Set(staleRecords.filter((s) => s.kind === "decision").map((s) => s.id));
-        const vetoes = this.vetoHits(an, files, staleDecisionIds);
-        const redundant = this.redundantSymbols(an.addedSymbols, files, {
-            movedFrom: [...an.filesRenamed.map((r) => r.from), ...an.filesDeleted],
-            removedNames: new Set(an.removedSymbols.map((s) => s.name)),
-        });
-        const directReport = [...direct.values()].map(({ c, files: fs }) => {
-            const stale = staleIds.has(c.id);
-            const strictBlocks = isStrictBlocker(c, stale);
+            const near = new Map();
+            for (const f of files)
+                for (const b of this.blastRadiusFiles(f))
+                    for (const c of this.checkConstraints(b.file)) {
+                        if (direct.has(c.id))
+                            continue;
+                        const e = near.get(c.id) ?? { c, via: [] };
+                        e.via.push(`${f} → ${b.file} (${b.via}, depth ${b.depth})`);
+                        near.set(c.id, e);
+                    }
+            const an = analyzeDiff(diff);
+            const regHits = this.regressionHits({ symbols: an.addedSymbols.map((s) => s.name), deps: an.addedDeps }, files);
+            const staleRecords = opts.strict && opts.lastChange ? this.staleness(opts.lastChange) : [];
+            const staleIds = new Set(staleRecords.filter((s) => s.kind === "constraint").map((s) => s.id));
+            const staleDecisionIds = new Set(staleRecords.filter((s) => s.kind === "decision").map((s) => s.id));
+            const vetoes = this.vetoHits(an, files, staleDecisionIds);
+            const redundant = this.redundantSymbols(an.addedSymbols, files, {
+                movedFrom: [...an.filesRenamed.map((r) => r.from), ...an.filesDeleted],
+                removedNames: new Set(an.removedSymbols.map((s) => s.name)),
+            });
+            const directReport = [...direct.values()].map(({ c, files: fs }) => {
+                const stale = staleIds.has(c.id);
+                const strictBlocks = isStrictBlocker(c, stale);
+                return {
+                    id: c.id, severity: c.severity ?? "advisory", statement: c.statement, rationale: c.rationale ?? "",
+                    files: fs, strictBlocks,
+                    downgrade: c.severity === "blocking" && !strictBlocks ? (stale ? "stale" : "low-confidence") : undefined,
+                    why: this.causalChain(c.id),
+                };
+            });
             return {
-                id: c.id, severity: c.severity ?? "advisory", statement: c.statement, rationale: c.rationale ?? "",
-                files: fs, strictBlocks,
-                downgrade: c.severity === "blocking" && !strictBlocks ? (stale ? "stale" : "low-confidence") : undefined,
-                why: this.causalChain(c.id),
+                fileCount: files.length,
+                strict: opts.strict,
+                direct: directReport,
+                near: [...near.values()].map(({ c, via }) => ({ id: c.id, severity: c.severity ?? "advisory", statement: c.statement, via })),
+                regressions: regHits.map((h) => ({ kind: h.kind, name: h.name, decision: h.decision, title: h.title, reason: h.reason, blocking: h.blocking })),
+                vetoes: vetoes.map((v) => ({ decision: v.decision, title: v.title, alternative: v.alternative, chosen: v.chosen, tier: v.tier, evidence: v.evidence, blocking: v.blocks })),
+                redundant,
+                strictBlockers: directReport.filter((d) => d.strictBlocks).length,
+                regBlocking: regHits.filter((h) => h.blocking).length,
+                vetoBlocking: vetoes.filter((v) => v.blocks).length,
             };
-        });
-        return {
-            fileCount: files.length,
-            strict: opts.strict,
-            direct: directReport,
-            near: [...near.values()].map(({ c, via }) => ({ id: c.id, severity: c.severity ?? "advisory", statement: c.statement, via })),
-            regressions: regHits.map((h) => ({ kind: h.kind, name: h.name, decision: h.decision, title: h.title, reason: h.reason, blocking: h.blocking })),
-            vetoes: vetoes.map((v) => ({ decision: v.decision, title: v.title, alternative: v.alternative, chosen: v.chosen, tier: v.tier, evidence: v.evidence, blocking: v.blocks })),
-            redundant,
-            strictBlockers: directReport.filter((d) => d.strictBlocks).length,
-            regBlocking: regHits.filter((h) => h.blocking).length,
-            vetoBlocking: vetoes.filter((v) => v.blocks).length,
-        };
+        }
+        finally {
+            this.suppressPrivate = prevSuppress;
+        }
     }
     /** Sprawl/"this already exists" guard (ADVISORY, never blocks). A symbol the diff
      *  ADDS whose name already exists in the indexed graph in a file NOT touched by the
@@ -503,7 +556,7 @@ export class HunchStore {
         // test fixture or a separate sub-project (test/, vscode-extension/, site/) is not
         // sprawl in the source under change — different roots, different ownership.
         const roots = new Set(files.map((f) => f.split("/")[0]));
-        const symbols = this.json.loadAll("symbols");
+        const symbols = this.recs("symbols");
         const out = [];
         const seen = new Set();
         for (const sc of added) {
@@ -567,9 +620,9 @@ export class HunchStore {
         if (!addedSyms.size && !addedDeps.size)
             return [];
         const fileRelevant = (related) => related.some((f) => files.some((x) => pathRelated(x, f)));
-        const decisions = this.json.loadAll("decisions");
+        const decisions = this.recs("decisions");
         // decisions tied to an active blocking constraint via source_decision
-        const blockingDec = new Set(this.json.loadAll("constraints")
+        const blockingDec = new Set(this.recs("constraints")
             .filter((c) => c.severity === "blocking" && c.status !== "retired" && c.source_decision)
             .map((c) => c.source_decision));
         const out = [];
@@ -613,7 +666,7 @@ export class HunchStore {
         const addedDeps = new Set(an.addedDeps);
         const out = [];
         const seen = new Set(); // dedup: one hit per decision+alternative
-        for (const d of this.json.loadAll("decisions")) {
+        for (const d of this.recs("decisions")) {
             if (d.superseded_by || d.status === "superseded")
                 continue; // in-force only
             const tripwires = d.rejected_tripwires ?? [];
@@ -683,7 +736,7 @@ export class HunchStore {
      *  available at edit time, so this surfaces the risk as context, not a block. */
     retiredForFile(file) {
         const out = [];
-        for (const d of this.json.loadAll("decisions")) {
+        for (const d of this.recs("decisions")) {
             if (d.superseded_by || d.status === "superseded")
                 continue;
             if (!d.retired.symbols.length && !d.retired.deps.length)
@@ -696,7 +749,7 @@ export class HunchStore {
     }
     /** Bugs matching a symptom (FTS over bugs) or a symbol, with lineage (hunch_bug_lineage). */
     bugLineage(symptomOrSymbol) {
-        const bugs = this.json.loadAll("bugs");
+        const bugs = this.recs("bugs");
         const direct = bugs.filter((b) => b.affected_symbols.includes(symptomOrSymbol) || b.affected_files.includes(symptomOrSymbol));
         if (direct.length)
             return direct;
@@ -711,8 +764,8 @@ export class HunchStore {
     }
     /** Ranked fragility report (hunch fragile). fragility = weighted churn + bugs + fan-in. */
     fragility(limit = 15) {
-        const syms = this.json.loadAll("symbols");
-        const bugs = this.json.loadAll("bugs");
+        const syms = this.recs("symbols");
+        const bugs = this.recs("bugs");
         // bug counts per symbol from actual bug records (authoritative over stale metric)
         const bugBySym = new Map();
         for (const b of bugs)
@@ -749,7 +802,7 @@ export class HunchStore {
     }
     /** All edges (for graph export). */
     allEdges() {
-        return this.json.loadAll("edges");
+        return this.recs("edges");
     }
     /** Drift detection (DESIGN §9 "staleness kills trust"): a decision/constraint
      *  is STALE when a file in its scope changed AFTER it was last verified. The
@@ -771,9 +824,9 @@ export class HunchStore {
             if (newest)
                 out.push({ kind, id, last_verified: verified, changed_at: newest, files: files.slice(0, 8) });
         };
-        for (const d of this.json.loadAll("decisions"))
+        for (const d of this.recs("decisions"))
             check("decision", d.id, d.related_files, d.provenance.last_verified);
-        for (const c of this.json.loadAll("constraints"))
+        for (const c of this.recs("constraints"))
             check("constraint", c.id, c.scope, c.provenance.last_verified);
         return out.sort((a, b) => b.changed_at.localeCompare(a.changed_at));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",