@davesheffer/hunch 1.2.0 → 1.2.2

package/README.md

@@ -120,6 +120,17 @@ graphs are unaffected until you opt in.
   one topic**. `hunch reconcile-topics` catches the one case a git merge can create, for human resolution.
 - **`hunch heal`** + the **`/heal`** slash command do **read-only** doc↔graph reconciliation — they show
   exactly what disagrees and never rewrite your prose silently.
+- **`hunch wiki`** — a generated component wiki + **specs ledger** rendered *from* the graph. Every repo
+  doc is graded deterministically (✅ grounded / ⚠ stale / ◻ unverified); a stale doc is **adopted** — a
+  wiki-managed copy re-pinned to the current decision with the correction inline, while your original
+  file is never touched (and the copy retires once you heal the original). Freshness is hash-gated:
+  `hunch drift` names exactly which pages went stale, `hunch wiki --heal` regenerates only those, and
+  `hunch wiki --check` is the CI gate. With a private overlay, `hunch wiki --private` renders the FULL
+  graph into the overlay repo — nothing private ever lands in the committed wiki.
+
+  ```bash
+  npm run build && bash demo/wiki.sh   # watch a spec go stale, get adopted + healed, then released
+  ```
 
 → [docs](https://hunch-pi.vercel.app/docs#grounding)
 

package/dist/cli/index.js

@@ -13,6 +13,7 @@
  *   mcp       start the MCP server (Claude Code connects here)
  *   doctor    environment diagnostics
  */
+import "./preflight.js"; // MUST stay the first import — Node-version gate before node:sqlite loads
 import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { join, relative, dirname, basename, resolve, isAbsolute } from "node:path";
@@ -51,6 +52,7 @@ import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpol
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
 import { loadGuardCases, evalGuards, generateGuardCases } from "../eval/guards.js";
 import { computeDrift } from "../core/drift.js";
+import { generateWiki, wikiStatus, wikiPrompt, publicHome, privateHome, readWikiManifestAt } from "../wiki/wiki.js";
 import { topicCollisions, renderGrounding } from "../core/topics.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
 import { compareCandidates } from "../core/compare.js";
@@ -1887,6 +1889,108 @@ program
         store.close();
     }
 });
+// ---- wiki (generated component wiki — a derived VIEW of the graph) ----------
+program
+    .command("wiki")
+    .description("Generate a component wiki from the graph — pages are a derived VIEW (the graph stays the source of truth), pinned with hunch:topic anchors and freshness-hashed into a wiki-manifest. Stale pages surface as wiki-stale in `hunch drift`; --heal regenerates ONLY those. Prose via a subscription CLI when available; deterministic template otherwise. Default: PUBLIC-store records only, written to <repo>/wiki/. With --private: the FULL graph (overlay included), written into the private overlay repo — never committed here.")
+    .option("--dir <dir>", "output directory (default: wiki/, or the manifest's dir once adopted)")
+    .option("--heal", "regenerate only new/stale pages (manifest hash mismatch) and remove orphans")
+    .option("--check", "report stale pages and exit non-zero (CI gate); writes nothing")
+    .option("--no-llm", "skip LLM prose; deterministic template pages only")
+    .option("--private", "render the FULL graph (private overlay included) and write the wiki into the OVERLAY repo — nothing lands in this repo")
+    .action(async (opts) => {
+    const { store, root } = storeFor();
+    try {
+        store.reindex(); // reflect out-of-band JSON edits before reading the graph
+        // The home pairs source with destination: overlay-inclusive reads may only
+        // ever land in the overlay repo (a committed public page is a leak surface).
+        const home = opts.private ? privateHome(store, opts.dir) : publicHome(root, opts.dir);
+        if (!home)
+            return fail("no private overlay configured — run `hunch private` (or `hunch shared`) first.");
+        // A union-fed wiki must never land inside the public work tree: refuse the
+        // degenerate overlay layout where the overlay's parent IS this repo's root.
+        if (home.kind === "private" && resolve(home.pagesRoot) === resolve(root)) {
+            return fail("the private overlay resolves directly under this repo's root — a private wiki here would land in the committed tree. Point the overlay at its own directory (e.g. .hunch-private/.hunch) and re-run.");
+        }
+        const manifest = readWikiManifestAt(home.manifestPath);
+        // A wiki lives where its manifest says; a different --dir would strand the
+        // old directory (its pages aren't orphans — their components are live).
+        if (manifest && opts.dir && manifest.dir !== opts.dir) {
+            return fail(`wiki already adopted at "${manifest.dir}/" — omit --dir (or delete ${manifest.dir}/ and the wiki manifest first, then re-run with --dir ${opts.dir}).`);
+        }
+        // CI-safe: checking a repo that never adopted a wiki is a no-op, not a failure.
+        if (opts.check && !manifest) {
+            console.log("✓ No wiki adopted here (no wiki manifest) — nothing to check.");
+            return;
+        }
+        const status = wikiStatus(store, home, root);
+        const healHint = `hunch wiki --heal${home.kind === "private" ? " --private" : ""}`;
+        if (opts.check) {
+            const stale = status.entries.filter((e) => e.state !== "fresh");
+            const staleAdoptions = status.adoptions.filter((a) => a.state !== "fresh");
+            const specsStale = status.specs.state !== "fresh";
+            const indexStale = status.index.state !== "fresh";
+            const orphanCount = status.orphans.length + status.adoptionOrphans.length;
+            if (!stale.length && !staleAdoptions.length && !specsStale && !indexStale && !orphanCount) {
+                console.log(`✓ Wiki is fresh — ${status.entries.length + status.adoptions.length + 2} page(s) match the graph and the doc ledger.`);
+                return;
+            }
+            for (const e of stale)
+                console.log(`· ${e.page} — ${e.state === "new" ? "no page generated yet" : e.reason}`);
+            for (const a of staleAdoptions)
+                console.log(`· ${a.page} — ${a.state === "new" ? `stale doc "${a.doc.rel}" awaits adoption` : `adopted copy of "${a.doc.rel}" out of date`}`);
+            if (specsStale)
+                console.log(`· ${status.specs.page} — the repo's doc freshness snapshot changed`);
+            if (indexStale)
+                console.log(`· ${status.index.page} — the index's inputs moved`);
+            for (const p of status.adoptionOrphans)
+                console.log(`· ${p} — original healed or removed; copy retires`);
+            for (const p of status.orphans)
+                console.log(`· ${p} — no current artifact claims this page`);
+            console.log(`\n${stale.length + staleAdoptions.length + (specsStale ? 1 : 0) + (indexStale ? 1 : 0) + orphanCount} stale page(s) — run \`${healHint}\`.`);
+            process.exitCode = 1;
+            return;
+        }
+        // An empty graph still needs --heal reachable for orphan/adoption cleanup —
+        // only a plain generate demands components (a broken drift↔heal loop
+        // otherwise: drift says "remove with --heal", --heal refuses to run).
+        if (!status.entries.length && !opts.heal)
+            return fail("no active components in the graph — run `hunch index` first.");
+        // Prose is optional garnish on the deterministic skeleton: subscription CLI
+        // only (same rule as synthesis), feature-detected, and any failure degrades
+        // to a template page — generation never depends on a model being present.
+        let prose;
+        if (opts.llm !== false) {
+            const provider = await selectProvider();
+            if (provider.draftProse) {
+                console.log(`Prose via ${provider.name} (subscription); the drift-bearing skeleton stays deterministic.`);
+                prose = (pack, excerpts) => provider.draftProse(wikiPrompt(pack, excerpts));
+            }
+            else {
+                console.log("No subscription CLI available — deterministic template pages.");
+            }
+        }
+        const res = await generateWiki(store, root, home, {
+            now: new Date().toISOString(),
+            only: opts.heal ? "stale" : "all",
+            prose,
+            log: (l) => console.log(l),
+        });
+        if (!res.written.length && !res.removed.length) {
+            console.log(`✓ Nothing to regenerate — ${res.unchanged} page(s) already fresh.`);
+            return;
+        }
+        const dest = home.kind === "private" ? `${join(home.pagesRoot, home.dir)} (private overlay repo — NOT committed here)` : `${home.dir}/`;
+        console.log(`\n✓ ${res.written.length} page(s) written${res.removed.length ? `, ${res.removed.length} orphan(s) removed` : ""}${res.unchanged ? `, ${res.unchanged} fresh page(s) untouched` : ""} → ${dest}`);
+        // Committed grounding docs advertise the PUBLIC wiki only — they must not
+        // reveal that (or what) a private overlay wiki exists.
+        if (home.kind === "public")
+            refreshExistingGrounding(root, store);
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- heal (decision-grounded drift reconciliation front door) -------------
 program
     .command("heal")
@@ -1938,6 +2042,13 @@ program
                 console.log(`· ${f.id} — ${f.detail}`);
             console.log(`\nHeal: update the doc's status marker to match reality.\n`);
         }
+        const wikiStale = kind("wiki-stale");
+        if (wikiStale.length) {
+            console.log(`${wikiStale.length} generated wiki page(s) drifted from the graph:\n`);
+            for (const f of wikiStale)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: run \`hunch wiki --heal\` — regenerates only the stale pages (the wiki is a derived view; never edit it by hand).\n`);
+        }
         console.log(`Hunch never rewrites prose for you; this is a read-only reconciliation report.`);
     }
     finally {

package/dist/cli/preflight.js

@@ -0,0 +1,19 @@
+/**
+ * Node-version gate — MUST be the first import of the CLI entry, and must itself
+ * import nothing: the store loads `node:sqlite` eagerly (db.ts), so on Node < 22.13
+ * the import graph dies with a raw ERR_UNKNOWN_BUILTIN_MODULE before Commander can
+ * print anything helpful. ESM evaluates this module (no deps) before the rest of
+ * the graph, so the check runs first and the user gets an actionable message.
+ */
+const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 13)) {
+    // The agent edit-hook must never block an edit on failure (con_03a0b94b2e):
+    // emit nothing and exit 0 — the edit proceeds ungrounded rather than blocked.
+    if (process.argv[2] === "hook")
+        process.exit(0);
+    process.stderr.write(`hunch: Node ${process.versions.node} is too old — hunch needs Node >= 22.13 (its index uses the built-in node:sqlite).\n` +
+        "Upgrade Node (e.g. `nvm install 24 && nvm use 24`) and re-run.\n");
+    process.exit(1);
+}
+export {};
+//# sourceMappingURL=preflight.js.map

package/dist/core/docscan.js

@@ -0,0 +1,110 @@
+/**
+ * Repo-doc scanner — the "specs" half of the doc≠graph spoke. Walks the repo's
+ * own markdown (same bounded walk `hunch drift` uses) and grades every doc with
+ * a DETERMINISTIC freshness status from signals that already exist:
+ *
+ *   - grounded   — carries `<!-- hunch:topic … -->` anchors and every pin points
+ *                  at the CURRENT decision for its topic: safe to trust.
+ *   - stale      — a pin points at a superseded/missing decision, the doc still
+ *                  says "proposed / not yet implemented" while referencing shipped
+ *                  code, or it references src files that no longer exist.
+ *   - unverified — no anchors and no stale signal: Hunch can't vouch either way
+ *                  (the honest tier; ground it by adding a topic marker).
+ *
+ * No semantic guessing and no LLM — same philosophy as drift.ts. The wiki uses
+ * these statuses to become the trusted READING surface over the repo's docs
+ * (route to grounded prose, warn on stale) without ever rewriting prose.
+ */
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, extname } from "node:path";
+import { parseDocAnchors } from "./docanchors.js";
+import { currentForTopic } from "./topics.js";
+export const STALE_MARKER = /\b(proposed|not yet implemented|no code yet)\b/i;
+export const SRC_REF = /\bsrc\/[A-Za-z0-9_\-/]+\.ts\b/g;
+const SKIP_DIRS = new Set(["node_modules", ".git", ".hunch", ".hunch-private", "dist", "vscode-extension", "site"]);
+/** Bounded walk for repo markdown (root + docs/, depth-limited; heavy/irrelevant trees skipped). */
+export function markdownDocs(root) {
+    const out = [];
+    const walk = (dir, rel, depth) => {
+        if (depth > 4)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                if (e.name.startsWith(".") || SKIP_DIRS.has(e.name))
+                    continue;
+                walk(join(dir, e.name), rel ? `${rel}/${e.name}` : e.name, depth + 1);
+            }
+            else if (extname(e.name) === ".md") {
+                out.push({ path: join(dir, e.name), rel: rel ? `${rel}/${e.name}` : e.name });
+            }
+        }
+    };
+    walk(root, "", 0);
+    return out;
+}
+/** Grade every repo doc. GENERATED wiki pages (hunch:wiki header) are views of
+ *  the graph, not specs — they are excluded here and freshness-gated by their
+ *  own manifest hash instead. */
+export function scanRepoDocs(decisions, root) {
+    const byId = new Map(decisions.map((d) => [d.id, d]));
+    const out = [];
+    for (const doc of markdownDocs(root)) {
+        let text;
+        try {
+            text = readFileSync(doc.path, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (text.startsWith("<!-- hunch:wiki "))
+            continue; // generated view, not a spec
+        const anchors = parseDocAnchors(text);
+        const topics = [...new Set(anchors.map((a) => a.topic))];
+        const srcRefs = [...new Set(text.match(SRC_REF) ?? [])];
+        const issues = [];
+        let groundedPins = 0;
+        for (const a of anchors) {
+            if (!a.pin)
+                continue;
+            const pinned = byId.get(a.pin);
+            const current = currentForTopic(decisions, a.topic);
+            const superseded = !!pinned && (pinned.status === "superseded" || !!pinned.superseded_by);
+            if (!pinned) {
+                issues.push(`line ${a.line}: pinned to ${a.pin} (topic "${a.topic}"), which does not exist`);
+            }
+            else if (superseded && current && current.id !== a.pin) {
+                issues.push(`line ${a.line}: pinned to superseded ${a.pin}; current for "${a.topic}" is ${current.id}`);
+            }
+            else if (!superseded) {
+                groundedPins++;
+            }
+            // superseded with NO visible successor: this store cannot vouch either way
+            // (the successor may live in a private overlay) → neither grounds nor stales,
+            // mirroring drift's explicit-pin-plus-live-successor rule.
+        }
+        if (STALE_MARKER.test(text.slice(0, 1500)) && srcRefs.some((r) => existsSync(join(root, r)))) {
+            issues.push("marked proposed/not-implemented but references shipped code");
+        }
+        const missing = srcRefs.filter((r) => !existsSync(join(root, r)));
+        if (missing.length && missing.length === srcRefs.length) {
+            // every code reference is gone — the doc describes code that no longer exists
+            issues.push(`references only missing files (${missing.slice(0, 3).join(", ")}${missing.length > 3 ? ", …" : ""})`);
+        }
+        const status = issues.length
+            ? "stale"
+            : anchors.length && (groundedPins > 0 || anchors.some((a) => !a.pin && currentForTopic(decisions, a.topic)))
+                ? "grounded"
+                : "unverified";
+        const title = /^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? doc.rel;
+        out.push({ rel: doc.rel, title, topics, srcRefs, status, issues });
+    }
+    return out.sort((a, b) => a.rel.localeCompare(b.rel));
+}
+//# sourceMappingURL=docscan.js.map

package/dist/core/drift.js

@@ -7,14 +7,18 @@
  *   - dead-ref:   an in-force decision points at a file that no longer exists.
  *   - supersede:  A claims to supersede B, but B was never properly closed.
  *   - doc-stale:  a doc marked "proposed / not yet implemented" references shipped code.
+ *   - wiki-stale: a generated wiki page's graph inputs changed since generation
+ *                 (hash-compared via .hunch/wiki-manifest.json; only when a wiki
+ *                 was adopted — see src/wiki/wiki.ts). Advisory, healed by
+ *                 `hunch wiki --heal`, never a gate.
  */
-import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join, extname } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { toPosixTarget } from "./paths.js";
 import { currentForTopic, isLive } from "./topics.js";
 import { parseDocAnchors } from "./docanchors.js";
-const STALE_MARKER = /\b(proposed|not yet implemented|no code yet)\b/i;
-const SRC_REF = /\bsrc\/[A-Za-z0-9_\-/]+\.ts\b/g;
+import { markdownDocs, STALE_MARKER, SRC_REF } from "./docscan.js";
+import { computeWikiDrift } from "../wiki/wiki.js";
 export function computeDrift(store, root) {
     const findings = [];
     const decisions = store.recs("decisions");
@@ -78,8 +82,10 @@ export function computeDrift(store, root) {
         const text = safeRead(doc.path);
         // 3. DOC-STALE — a doc that still advertises "proposed / not implemented" while
         //    referencing code that exists. Heuristic + advisory; scoped to the repo's own
-        //    markdown (node_modules and sub-projects skipped).
-        if (STALE_MARKER.test(text.slice(0, 1500))) {
+        //    markdown (node_modules and sub-projects skipped). GENERATED wiki pages are
+        //    exempt: they quote decision prose verbatim (which may legitimately contain
+        //    "proposed"), and their staleness is already hash-gated (wiki-stale).
+        if (!text.startsWith("<!-- hunch:wiki ") && STALE_MARKER.test(text.slice(0, 1500))) {
             const existing = (text.match(SRC_REF) ?? []).find((r) => existsSync(join(root, r)));
             if (existing) {
                 findings.push({ kind: "doc-stale", id: doc.rel, detail: `marked proposed/not-implemented but references shipped code (${existing})` });
@@ -108,6 +114,10 @@ export function computeDrift(store, root) {
             }
         }
     }
+    // 6. WIKI-STALE — generated wiki pages whose graph inputs drifted (or whose
+    //    component vanished). Deterministic hash comparison against the manifest;
+    //    fires only when a wiki was adopted. Advisory like every other kind here.
+    findings.push(...computeWikiDrift(store, root));
     return { findings };
 }
 function safeRead(path) {
@@ -118,32 +128,4 @@ function safeRead(path) {
         return "";
     }
 }
-const SKIP_DIRS = new Set(["node_modules", ".git", ".hunch", ".hunch-private", "dist", "vscode-extension", "site"]);
-/** Bounded walk for repo markdown (root + docs/, depth-limited; heavy/irrelevant trees skipped). */
-function markdownDocs(root) {
-    const out = [];
-    const walk = (dir, rel, depth) => {
-        if (depth > 4)
-            return;
-        let entries;
-        try {
-            entries = readdirSync(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const e of entries) {
-            if (e.isDirectory()) {
-                if (e.name.startsWith(".") || SKIP_DIRS.has(e.name))
-                    continue;
-                walk(join(dir, e.name), rel ? `${rel}/${e.name}` : e.name, depth + 1);
-            }
-            else if (extname(e.name) === ".md") {
-                out.push({ path: join(dir, e.name), rel: rel ? `${rel}/${e.name}` : e.name });
-            }
-        }
-    };
-    walk(root, "", 0);
-    return out;
-}
 //# sourceMappingURL=drift.js.map

package/dist/extractors/git.js

@@ -41,7 +41,11 @@ export function mainWorktreeRoot(root) {
  *  `push: false` commits WITHOUT merging or pushing — required when hunchDir is the PUBLIC
  *  .hunch/ inside the user's code repo: an automatic pull/push there would merge the remote
  *  into their working branch and publish their unpushed code commits. The memory commit
- *  simply rides the user's next push. */
+ *  simply rides the user's next push.
+ *  Returns what ACTUALLY happened, so callers never report a commit that was skipped:
+ *  "pushed" (commit created and pushed), "committed" (commit created; push not requested,
+ *  or the merge/push failed — retry rides the next flush), null (nothing committed: lock
+ *  held, backstop refusal, nothing staged, or not a repo). */
 export function commitAndPushHunch(hunchDir, message, opts = {}) {
     // Serialize across worktrees: several worktrees auto-committing the SAME overlay repo
     // at once would race git's index.lock. An atomic-mkdir lock lets one proceed; the others
@@ -49,7 +53,7 @@ export function commitAndPushHunch(hunchDir, message, opts = {}) {
     // up anything a skipped run left pending (eventually-consistent, never lost).
     const lock = join(hunchDir, ".hunch-commit.lock");
     if (!acquireCommitLock(lock))
-        return;
+        return null;
     try {
         const env = { ...process.env, HUNCH_SYNC: "1" };
         const run = (args) => {
@@ -76,7 +80,7 @@ export function commitAndPushHunch(hunchDir, message, opts = {}) {
             if (opts.push !== false) {
                 console.error(`hunch: refusing to auto-commit memory at "${hunchDir}" — the staged change includes deletions or non-memory files, so this is not a clean overlay repo. Nothing was committed or pushed. (Use \`hunch shared --repo <url>\` so the overlay is its OWN git repo.)`);
             }
-            return;
+            return null;
         }
         // Only sync+push when a memory commit was actually created — never run pull/push against the
         // enclosing repo on an empty stage. Two-way sync: MERGE the remote BEFORE pushing so a push
@@ -88,8 +92,18 @@ export function commitAndPushHunch(hunchDir, message, opts = {}) {
             committed = true;
         }
         catch { /* nothing staged / not a repo */ }
-        if (committed && opts.push !== false && mergeRemote(hunchDir, env))
-            run(["push"]);
+        if (!committed)
+            return null;
+        if (opts.push !== false && mergeRemote(hunchDir, env)) {
+            // Push tracked (not via run): a no-upstream/offline/rejected push must report
+            // "committed", not overclaim "pushed" — the next flush's merge+push retries.
+            try {
+                execFileSync("git", ["-C", hunchDir, "push"], { stdio: "ignore", env });
+                return "pushed";
+            }
+            catch { /* offline / no upstream */ }
+        }
+        return "committed";
     }
     finally {
         try {

package/dist/extractors/indexer.js

@@ -162,7 +162,29 @@ export function indexRepo(store, root, opts = {}) {
     // persist
     store.json.replaceAll("symbols", symbols);
     store.json.replaceAll("edges", edges);
-    const compsOut = components.map(({ _files, ...c }) => c);
+    // Components are derived-but-ENRICHED records: layout facts (paths, kind, name)
+    // come from this scan, while curation/synthesis (responsibility, owners, status,
+    // fragility from raiseFragility, upgraded provenance) lives only on the stored
+    // record and must survive a reindex. Timestamps are preserved so an unchanged
+    // component is byte-identical — reindexing must not churn git.
+    const prior = new Map(store.json.loadAll("components").map((c) => [c.id, c]));
+    const stamp = (c) => JSON.stringify({ ...c, created_at: "", updated_at: "" });
+    const compsOut = components.map(({ _files, ...draft }) => {
+        const prev = prior.get(draft.id);
+        if (!prev)
+            return draft;
+        const merged = {
+            ...draft,
+            responsibility: prev.responsibility || draft.responsibility,
+            owners: prev.owners.length ? prev.owners : draft.owners,
+            status: prev.status,
+            fragility: Math.max(prev.fragility, draft.fragility),
+            provenance: prev.provenance.source !== "inferred" ? prev.provenance : draft.provenance,
+            created_at: prev.created_at,
+            updated_at: prev.updated_at,
+        };
+        return stamp(merged) === stamp(prev) ? prev : { ...merged, updated_at: draft.updated_at };
+    });
     store.json.replaceAll("components", compsOut);
     return { files: files.length, symbols: symbols.length, edges: edges.length, components: compsOut.length, skipped };
 }

package/dist/integrations/claudemd.js

@@ -5,9 +5,10 @@
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { wikiSummary } from "../wiki/wiki.js";
 const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
 const END = "<!-- HUNCH:END -->";
-export function renderHunchSection(store) {
+export function renderHunchSection(store, root) {
     const constraints = store.json
         .loadAll("constraints")
         .sort((a, b) => sev(b.severity) - sev(a.severity))
@@ -36,6 +37,11 @@ export function renderHunchSection(store) {
     lines.push("- `hunch_compare(candidates)` — rank N candidate branches/commits by architectural fit (fewest invariant hits).");
     lines.push("- `hunch_conformance()` — does the code still SATISFY recorded intent? (e.g. `pay` still reaches `verifySession`). Run before a refactor.");
     lines.push("- `hunch_record_decision(...)` — write back a decision after a non-trivial choice.");
+    const wiki = root ? wikiSummary(root) : null;
+    if (wiki) {
+        lines.push("");
+        lines.push(`📖 Component wiki: \`${wiki.dir}/\` (${wiki.pages} page(s)) — a GENERATED view of this graph; the graph stays the source of truth. Stale pages surface in \`hunch drift\`; regenerate with \`hunch wiki --heal\`.`);
+    }
     if (constraints.length) {
         lines.push("");
         lines.push("### ⛔ Top invariants (do not break)");
@@ -75,7 +81,7 @@ export function upsertSection(file, section, fallbackTitle) {
 }
 /** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
 export function updateClaudeMd(root, store) {
-    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store), `# ${root.split("/").pop()}`);
+    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store, root), `# ${root.split("/").pop()}`);
 }
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;

package/dist/integrations/providers.js

@@ -224,17 +224,17 @@ export function writeCodexConfig(root, inv) {
 /** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
  *  set of assistants read it). Marker-delimited so user prose is preserved. */
 export function writeAgentsMd(root, store) {
-    return upsertSection(join(root, "AGENTS.md"), renderHunchSection(store), "# AGENTS.md");
+    return upsertSection(join(root, "AGENTS.md"), renderHunchSection(store, root), "# AGENTS.md");
 }
 /** GitHub Copilot custom instructions (VS Code / github.com). Same grounding. */
 export function writeCopilotInstructions(root, store) {
-    return upsertSection(join(root, ".github", "copilot-instructions.md"), renderHunchSection(store), "# Copilot instructions");
+    return upsertSection(join(root, ".github", "copilot-instructions.md"), renderHunchSection(store, root), "# Copilot instructions");
 }
 /** Cursor project rule (.mdc = frontmatter + body). `alwaysApply` keeps the Hunch
  *  grounding in context for every request. Fully managed by Hunch (overwritten). */
 export function writeCursorRule(root, store) {
     const file = join(root, ".cursor", "rules", "hunch.mdc");
-    const body = `---\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\nalwaysApply: true\n---\n\n${renderHunchSection(store)}\n`;
+    const body = `---\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\nalwaysApply: true\n---\n\n${renderHunchSection(store, root)}\n`;
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, body);
     return file;
@@ -253,7 +253,7 @@ export function writeWindsurfMcp(root, inv) {
  *  Hunch grounding in Cascade's context for every request. Fully managed (overwritten). */
 export function writeWindsurfRule(root, store) {
     const file = join(root, ".windsurf", "rules", "hunch.md");
-    const body = `---\ntrigger: always_on\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\n---\n\n${renderHunchSection(store)}\n`;
+    const body = `---\ntrigger: always_on\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\n---\n\n${renderHunchSection(store, root)}\n`;
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, body);
     return file;

package/dist/integrations/sync.js

@@ -5,22 +5,22 @@ export function flushPrivate(store, message) {
     if (store.privateAutoCommit && store.privateDir)
         commitAndPushHunch(store.privateDir, message);
 }
-/** Auto-commit the store a capture landed in. Returns what happened so callers can report it:
- *  "pushed" (private overlay, committed + pushed), "committed" (public .hunch/, commit only —
- *  rides the next push), or null (auto-commit off / no overlay for a private record). */
+/** Auto-commit the store a capture landed in. Returns what ACTUALLY happened so callers
+ *  never report a commit that was skipped: "pushed" (overlay committed + pushed),
+ *  "committed" (commit created but not pushed — public .hunch/ rides the next push; an
+ *  overlay commit whose merge/push failed retries on the next flush), or null (auto-commit
+ *  off, no overlay for a private record, or the commit was skipped — lock held, safety
+ *  backstop, nothing staged; the record stays on disk and the next flush sweeps it up). */
 export function flushCapture(store, publicHunchDir, isPrivate, message) {
     // Follow the same routing as HunchStore.captureHome: unified ("shared") mode homes
     // EVERY capture in the overlay, so the flush must go there too — one source of truth.
     if (store.captureHome(isPrivate) === "private") {
-        if (store.privateAutoCommit && store.privateDir) {
-            commitAndPushHunch(store.privateDir, message);
-            return "pushed";
-        }
+        if (store.privateAutoCommit && store.privateDir)
+            return commitAndPushHunch(store.privateDir, message);
         return null;
     }
     if (!store.autoCommit)
         return null;
-    commitAndPushHunch(publicHunchDir, message, { push: false });
-    return "committed";
+    return commitAndPushHunch(publicHunchDir, message, { push: false });
 }
 //# sourceMappingURL=sync.js.map

package/dist/mcp/server.js

@@ -29,6 +29,15 @@ import { issueCaptureToken as issueToken, consumeCaptureToken as consumeToken }
 import { randomUUID } from "node:crypto";
 const ok = (text) => ({ content: [{ type: "text", text }] });
 const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+/** Honest auto-commit suffix: reports only what flushCapture ACTUALLY did. A skipped
+ *  commit (backstop/lock/nothing staged) says nothing — the record is on disk and the
+ *  next flush sweeps it up; claiming "auto-committed" there would be a lie. */
+const flushNote = (flush, home, mode) => flush === "pushed" ? ` (committed + pushed to the ${mode === "shared" ? "shared team store" : "private repo"})`
+    : flush === "committed"
+        ? home === "private"
+            ? " (committed to the overlay repo — push deferred: offline, no upstream, or merge conflict; the next capture or `hunch private --sync` retries)"
+            : " (auto-committed to .hunch/ — rides your next push)"
+        : "";
 // Read-side token budgets: every tool result is injected into a Claude Code
 // session, so an uncapped list pollutes the context window. Cap each list to its
 // highest-signal head (records are pre-sorted by severity/confidence) and tell the
@@ -422,8 +431,7 @@ export function buildServer(root) {
             // record commits+pushes its overlay repo; a public one commits .hunch/ in THIS repo
             // (commit only — it rides the user's next push, never auto-pushing their code branch).
             const flush = flushCapture(store, hunchPaths(root).hunch, !!decision.private, `hunch: capture ${id}`);
-            const flushed = flush === "pushed" ? ` (committed + pushed to the ${store.mode === "shared" ? "shared team store" : "private repo"})`
-                : flush === "committed" ? " (auto-committed to .hunch/ — rides your next push)" : "";
+            const flushed = flushNote(flush, home, store.mode);
             // Capture-session gate (staged deprecation, §9.3): a token proves an interview
             // preceded the write. No token still writes (non-breaking), but returns a nudge
             // toward /capture so the un-interviewed bypass is visible, not silent. A token
@@ -480,8 +488,7 @@ export function buildServer(root) {
             if (home === "public")
                 refreshExistingGrounding(root, store); // overlay rules never render into committed grounding
             const flush = flushCapture(store, hunchPaths(root).hunch, !!input.private, `hunch: capture ${rec.id}`);
-            const flushed = flush === "pushed" ? ` (committed + pushed to the ${store.mode === "shared" ? "shared team store" : "private repo"})`
-                : flush === "committed" ? " (auto-committed to .hunch/ — rides your next push)" : "";
+            const flushed = flushNote(flush, home, store.mode);
             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)";

package/dist/synthesis/provider.js

@@ -197,6 +197,15 @@ class CliSynthProvider {
             throw new Error(`${this.name}: no usable bug JSON in output`);
         return draft;
     }
+    /** Grounded prose for the wiki. Same subscription-only run() path (API keys
+     *  stripped). Throws on empty output so the caller falls back to its
+     *  deterministic template page. */
+    async draftProse(prompt) {
+        const text = (await this.run(prompt)).trim();
+        if (!text)
+            throw new Error(`${this.name}: empty prose output`);
+        return text;
+    }
     /** The Critic pass: audit a draft against its commit. Same subscription-only
      *  run() path (API keys stripped), so this never bills the pay-per-token API.
      *  Throws on unusable output so verifyDecisionSafe degrades to the un-audited