@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/wiki/graph.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Wiki memory graph — one self-contained, zero-dependency HTML page
+ * (<dir>/graph.html): the VISUAL KNOWLEDGE BASE over the wiki.
+ *
+ *   • Components as circles — sized by code, colored by fragility, ringed when
+ *     a blocking invariant guards them; dependencies as links.
+ *   • Repo docs as squares wired to the components they describe — freshness is
+ *     the color: grounded ✅ green, STALE ⚠ amber-red (pulsing), unverified ◻
+ *     gray. A stale doc's click opens its wiki-managed healed copy.
+ *   • An ACT-NOW panel: stale docs, drafts awaiting `hunch review`, unverified
+ *     docs — each row highlights its nodes; nothing is ever mutated from here.
+ *   • A time scrubber that replays the memory compounding, plus a this-week
+ *     pulse on components whose decisions are fresh.
+ *
+ * Same doctrine as every wiki page: a derived VIEW, deterministic inputs only.
+ * The embedded JSON is the page's freshness hash input; the force layout and
+ * the "this week" cutoff run client-side at view time and are presentation.
+ * No CDN, no fetch — works as a local file in the private overlay repo
+ * (con_547fff76bd).
+ */
+export interface WikiGraphNode {
+    id: string;
+    name: string;
+    /** Wiki page filename stem — clicking the node opens `<slug>.md`. */
+    slug: string;
+    responsibility: string;
+    fragility: number;
+    symbols: number;
+    blocking: number;
+    constraints: number;
+    bugs: number;
+    /** ISO dates (YYYY-MM-DD) of this component's decisions, sorted ascending —
+     *  the scrubber's raw material and the this-week pulse. */
+    decisions: string[];
+}
+export interface WikiGraphDoc {
+    rel: string;
+    title: string;
+    status: "grounded" | "stale" | "unverified";
+    /** wiki-dir-relative path of the healed wiki-managed copy (stale docs only). */
+    adopted: string | null;
+    /** component ids whose files this doc references. */
+    components: string[];
+}
+export interface WikiGraphLink {
+    source: string;
+    target: string;
+}
+export interface WikiGraphData {
+    kind: "public" | "private";
+    nodes: WikiGraphNode[];
+    links: WikiGraphLink[];
+    docs: WikiGraphDoc[];
+    /** auto-drafted proposed decisions awaiting `hunch review` — actionable count. */
+    pendingReview: number;
+}
+/** Pure assembly from already-computed wiki inputs — sorted for a stable hash. */
+export declare function assembleGraphData(kind: "public" | "private", entries: ReadonlyArray<{
+    slug: string;
+    pack: {
+        component: {
+            id: string;
+            name: string;
+            responsibility: string;
+            fragility: number;
+        };
+        symbols: unknown[];
+        decisions: Array<{
+            id: string;
+        }>;
+        constraints: Array<{
+            severity: string;
+        }>;
+        bugs: unknown[];
+        dependsOn: Array<{
+            id: string;
+        }>;
+        docs: Array<{
+            path: string;
+        }>;
+    };
+}>, decisionDates: ReadonlyMap<string, string>, repoDocs?: ReadonlyArray<{
+    rel: string;
+    title: string;
+    status: string;
+}>, adoptedPageByRel?: ReadonlyMap<string, string>, pendingReview?: number): WikiGraphData;
+export declare function renderGraphPage(data: WikiGraphData): string;

package/dist/wiki/wiki.d.ts

@@ -0,0 +1,242 @@
+import { type RepoDoc } from "../core/docscan.js";
+import { type WikiGraphData } from "./graph.js";
+import type { Decision } from "../core/types.js";
+import type { HunchStore } from "../store/hunchStore.js";
+import type { Component, Constraint } from "../core/types.js";
+import type { DriftFinding } from "../core/drift.js";
+export type WikiSource = "public" | "all";
+export interface WikiHome {
+    kind: "public" | "private";
+    /** Repo the pages are written into (main repo root, or the overlay repo root). */
+    pagesRoot: string;
+    /** Output directory name under pagesRoot (manifest remembers it once adopted). */
+    dir: string;
+    manifestPath: string;
+    source: WikiSource;
+}
+export declare function publicHome(root: string, dirOverride?: string): WikiHome;
+/** The private overlay's wiki home, or null when no overlay is configured.
+ *  `store.privateDir` is the overlay's .hunch dir; pages go to the overlay repo
+ *  root beside it (never inside .hunch/, which must stay memory-JSON-only for
+ *  the overlay auto-commit guard), and the manifest rides the overlay store. */
+export declare function privateHome(store: HunchStore, dirOverride?: string): WikiHome | null;
+export interface WikiPack {
+    component: {
+        id: string;
+        name: string;
+        kind: string;
+        responsibility: string;
+        paths: string[];
+        fragility: number;
+    };
+    /** repo-relative POSIX files the component owns (via its path globs). */
+    files: string[];
+    symbols: Array<{
+        name: string;
+        file: string;
+        kind: string;
+        fan_in: number;
+        fan_out: number;
+        loc: number;
+    }>;
+    decisions: Array<{
+        id: string;
+        topic: string | null;
+        title: string;
+        decision: string;
+        context: string;
+        consequences: string[];
+        alternatives_rejected: string[];
+    }>;
+    constraints: Array<{
+        id: string;
+        severity: string;
+        statement: string;
+        rationale: string;
+    }>;
+    bugs: Array<{
+        id: string;
+        title: string;
+        root_cause: string;
+        severity: string;
+        status: string;
+    }>;
+    /** Repo docs (specs) that reference this component's files, with their
+     *  deterministic freshness grade — status changes re-hash the page. `adopted`
+     *  is the wiki-dir-relative path of the doc's wiki-managed copy (stale docs
+     *  only), assigned by wikiStatus — the single slug authority. */
+    docs: Array<{
+        path: string;
+        title: string;
+        status: string;
+        adopted: string | null;
+    }>;
+    /** `slug` is the related page's filename stem, assigned by wikiStatus (the
+     *  slug authority) and HASHED with the pack — a sibling rename re-renders
+     *  every page that links to it (closes the dec_c205c26472 residual). */
+    dependsOn: Array<{
+        id: string;
+        name: string;
+        slug: string | null;
+    }>;
+    usedBy: Array<{
+        id: string;
+        name: string;
+        slug: string | null;
+    }>;
+}
+/** Assemble one component's pack — pure graph queries, no LLM. `source` decides
+ *  the leak boundary: "public" reads the committed store only; "all" unions the
+ *  private overlay and must only ever feed a PRIVATE home's pages. `repoDocs`
+ *  (pre-scanned specs) associate by the src files they mention. */
+export declare function assemblePack(store: HunchStore, component: Component, source?: WikiSource, repoDocs?: readonly RepoDoc[], adoptedPageByRel?: ReadonlyMap<string, string>, slugById?: ReadonlyMap<string, string>): WikiPack;
+export declare function packHash(pack: WikiPack): string;
+export declare function slugFor(name: string, id: string, taken: Set<string>): string;
+/** `docsLinkable`: pages in the MAIN repo can relative-link ../<doc>; a private
+ *  home's pages live in the OVERLAY repo where those paths don't resolve, so
+ *  they render doc paths as plain text instead. */
+export declare function renderPage(pack: WikiPack, prose: string | null, docsLinkable?: boolean): string;
+export declare function renderIndex(entries: Array<{
+    pack: WikiPack;
+    slug: string;
+}>, repoWide: Constraint[], home: Pick<WikiHome, "kind">, docs?: readonly RepoDoc[]): string;
+/** The specs ledger — every repo doc with its deterministic freshness grade.
+ *  This page is what makes the wiki usable as the trusted READING surface over
+ *  the repo's own documentation: grounded docs are safe, stale docs carry their
+ *  exact drift, unverified docs show how to get grounded. Prose is never
+ *  rewritten — healing a stale doc is a human edit guided by `hunch heal`. */
+export declare function renderSpecsPage(docs: readonly RepoDoc[], home: Pick<WikiHome, "kind">, adoptedPageByRel?: ReadonlyMap<string, string>): string;
+export interface WikiManifest {
+    version: 1;
+    dir: string;
+    /** `bytes` = hash of the page as WRITTEN — the hand-edit tripwire. Optional
+     *  for forward-compat with manifests written before it existed. */
+    pages: Record<string, {
+        component: string;
+        hash: string;
+        generated: string;
+        bytes?: string;
+    }>;
+}
+export declare function readWikiManifestAt(manifestPath: string): WikiManifest | null;
+export declare function writeWikiManifestAt(manifestPath: string, manifest: WikiManifest): void;
+/** For the committed grounding docs (CLAUDE.md et al): is a PUBLIC wiki adopted
+ *  here, and how big? Deliberately blind to the private home — committed docs
+ *  must not advertise what the overlay holds. */
+export declare function wikiSummary(root: string): {
+    dir: string;
+    pages: number;
+} | null;
+export interface WikiEntry {
+    pack: WikiPack;
+    slug: string;
+    /** pagesRoot-relative POSIX page path, e.g. "wiki/store-layer.md". */
+    page: string;
+    hash: string;
+    state: "fresh" | "stale" | "new";
+    reason: string;
+}
+/** One row of the NOW page — a decision reduced to its ledger-relevant surface.
+ *  Everything here participates in the page's freshness hash. */
+export interface NowItem {
+    id: string;
+    topic: string | null;
+    title: string;
+    status: string;
+    date: string;
+    /** decision text for recent items; CONTEXT (the why-it's-planned) for roadmap items. */
+    note: string;
+}
+/** The hot view's inputs: last `recentLimit` decisions by date (any status — a
+ *  supersession IS activity), and every live PROPOSED decision (the roadmap:
+ *  record intent as a proposed decision; accepting or superseding it removes it
+ *  from the roadmap with zero file maintenance). Home-scoped like every read. */
+export declare function nowData(decisions: readonly Decision[], recentLimit?: number): {
+    recent: NowItem[];
+    roadmap: NowItem[];
+    pendingReview: number;
+};
+/** The hot file — a DERIVED view like every other page: what just happened
+ *  (last N decisions) and what's next (live proposed decisions). No topic pins
+ *  by design: ledger entries going stale is history, not drift — the freshness
+ *  hash alone re-renders the page when the graph moves. */
+export declare function renderNowPage(recent: readonly NowItem[], roadmap: readonly NowItem[], home: Pick<WikiHome, "kind">, pendingReview?: number): string;
+/** A stale doc the wiki takes over: a healed, wiki-managed copy under <dir>/docs/. */
+export interface WikiAdoption {
+    doc: RepoDoc;
+    /** Source content the copy is healed from (read once during status). */
+    content: string;
+    /** pagesRoot-relative page path, e.g. "wiki/docs/docs-api.md". */
+    page: string;
+    hash: string;
+    state: WikiEntry["state"];
+}
+export interface WikiStatus {
+    home: WikiHome;
+    entries: WikiEntry[];
+    /** Every repo doc with its freshness grade (input to specs page + Docs sections). */
+    docs: RepoDoc[];
+    /** Stale docs the wiki adopts (copies in + heals + manages). */
+    adoptions: WikiAdoption[];
+    /** Adopted copies whose ORIGINAL healed or vanished — the copy retires. */
+    adoptionOrphans: string[];
+    /** The decisions the home may read (needed to heal adopted copies). */
+    decisions: Decision[];
+    /** The specs ledger page's own freshness (hashed over the doc-status snapshot). */
+    specs: {
+        page: string;
+        hash: string;
+        state: WikiEntry["state"];
+    };
+    /** The README index page's freshness (hashed over rows + repo-wide invariants). */
+    index: {
+        page: string;
+        hash: string;
+        state: WikiEntry["state"];
+    };
+    /** The NOW page (activity ledger + roadmap) — hashed over its item snapshot. */
+    now: {
+        page: string;
+        hash: string;
+        state: WikiEntry["state"];
+        recent: NowItem[];
+        roadmap: NowItem[];
+        pendingReview: number;
+    };
+    /** The interactive memory-graph page — hashed over its embedded data. */
+    graph: {
+        page: string;
+        hash: string;
+        state: WikiEntry["state"];
+        data: WikiGraphData;
+    };
+    /** Repo-wide (scope []) constraints — rendered on the index, hashed into it. */
+    repoWide: Constraint[];
+    /** Manifest pages no current artifact claims (deleted/renamed components, an
+     *  abandoned --dir…) — removed on heal so nothing generated is ever stranded. */
+    orphans: string[];
+}
+/** Stable component order is part of page identity because slug collisions are
+ * resolved first-come. Keep it independent of the host's collation locale. */
+export declare function compareWikiComponents(left: Pick<Component, "id" | "name">, right: Pick<Component, "id" | "name">): number;
+export declare function wikiStatus(store: HunchStore, home: WikiHome, srcRoot: string): WikiStatus;
+export interface GenerateOptions {
+    /** ISO instant recorded per page in the manifest (caller supplies the clock). */
+    now: string;
+    /** "all" regenerates every page; "stale" only new/stale ones (--heal). */
+    only: "all" | "stale";
+    /** Optional grounded-prose hook (guarded LLM provider). null/throw → template-only page. */
+    prose?: (pack: WikiPack, excerpts: string) => Promise<string | null>;
+    /** Optional prose-heal for ADOPTED copies (--prose-heal): an LLM "reconciled
+     *  overview" under the banner. null/throw → deterministic copy, exactly as
+     *  without the flag; output is never hashed (same doctrine as page prose). */
+    adoptionProse?: (doc: RepoDoc, content: string) => Promise<string | null>;
+    log?: (line: string) => void;
+}
+export declare function wikiPrompt(pack: WikiPack, excerpts: string): string;
+export declare function generateWiki(store: HunchStore, srcRoot: string, home: WikiHome, opts: GenerateOptions): Promise<{
+    written: string[];
+    removed: string[];
+    unchanged: number;
+}>;
+export declare function computeWikiDrift(store: HunchStore, root: string): DriftFinding[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -27,15 +27,16 @@
       "default": "./dist/projectDna.js"
     },
     "./state": "./dist/client/state.js",
+    "./reports": {
+      "types": "./dist/taskReports.d.ts",
+      "default": "./dist/taskReports.js"
+    },
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
   "files": [
     "dist/**/*.js",
-    "dist/changeProof.d.ts",
-    "dist/core/changeProofContract.d.ts",
-    "dist/projectDna.d.ts",
-    "dist/core/projectDna*.d.ts",
+    "dist/**/*.d.ts",
     "contracts/change-proof/*.json",
     "server.json",
     "bench/constitution-exp03-v1.json",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.31.0",
+      "version": "1.32.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {