@vonneollc/knbase 0.1.0

package/dist/core/mindmap.js

@@ -0,0 +1,71 @@
+import { writeFileSync } from "node:fs";
+import { ensureDir } from "./config.js";
+import { TEMPLATES } from "./templates.js";
+/** Escape a label for use inside a mermaid mindmap node. */
+function safeLabel(text) {
+    return text
+        .replace(/[\r\n]+/g, " ")
+        .replace(/["`]/g, "'")
+        .replace(/[()]/g, "")
+        .replace(/[[\]{}]/g, "")
+        .trim();
+}
+/**
+ * Build a deterministic mermaid `mindmap` from the index: root -> one node per
+ * governance file (with its one-line summary) -> child nodes per H2 heading.
+ * No LLM involved; purely structural, so it is cheap and reproducible.
+ */
+export function buildMindmap(config, index) {
+    const lines = ["mindmap", "  root((Project))"];
+    for (const key of config.files) {
+        const entry = index.files[key];
+        const tpl = TEMPLATES[key];
+        const title = tpl?.title ?? key;
+        const status = entry.exists ? "" : " [missing]";
+        lines.push(`    ${safeLabel(title)}${status}`);
+        if (entry.summary) {
+            lines.push(`      ::icon(fa fa-info)`);
+            lines.push(`      ${safeLabel(entry.summary)}`);
+        }
+        for (const heading of entry.headings) {
+            lines.push(`      ${safeLabel(heading)}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Render the full mindmap.md document (fenced mermaid + text summary table). */
+export function renderMindmapDoc(config, index) {
+    const mermaid = buildMindmap(config, index);
+    const rows = config.files.map((key) => {
+        const e = index.files[key];
+        const tpl = TEMPLATES[key];
+        const state = e.exists ? "ok" : "missing";
+        const summary = e.summary || (tpl ? tpl.purpose : "");
+        return `| ${key} | ${state} | ${summary.replace(/\|/g, "\\|")} |`;
+    });
+    return [
+        "# Project Mind Map",
+        "",
+        "<!-- Auto-generated by knbase. Do not edit by hand. -->",
+        "",
+        "```mermaid",
+        mermaid,
+        "```",
+        "",
+        "## Index",
+        "",
+        "| File | State | Summary |",
+        "| --- | --- | --- |",
+        ...rows,
+        "",
+        `_Updated: ${new Date().toISOString()}_`,
+        "",
+    ].join("\n");
+}
+export function writeMindmap(p, config, index) {
+    ensureDir(p.systemDir);
+    const doc = renderMindmapDoc(config, index);
+    writeFileSync(p.mindmapPath, doc, "utf8");
+    return doc;
+}
+//# sourceMappingURL=mindmap.js.map

package/dist/core/mindmap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mindmap.js","sourceRoot":"","sources":["../../src/core/mindmap.ts"],"names":[],"mappings":"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"}

package/dist/core/session.d.ts

@@ -0,0 +1,15 @@
+import { type ResolvedPaths } from "./config.js";
+import type { KnbaseConfig, SessionData } from "../types.js";
+export declare function loadSession(p: ResolvedPaths): SessionData | null;
+export declare function saveSession(p: ResolvedPaths, session: SessionData): void;
+export declare function clearSession(p: ResolvedPaths): void;
+export declare function newSessionId(): string;
+export declare function newTaskId(): string;
+/**
+ * A session is fresh when it exists, is in a usable state, and started within
+ * the configured TTL. Stale sessions force the agent to re-load context, which
+ * is the CLI guard's primary gate.
+ */
+export declare function isSessionFresh(session: SessionData | null, config: KnbaseConfig): boolean;
+/** True when context loaded during the session matches files currently on disk. */
+export declare function contextMatchesDisk(session: SessionData | null, current: Record<string, string>): boolean;

package/dist/core/session.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { ensureDir } from "./config.js";
+export function loadSession(p) {
+    if (!existsSync(p.sessionPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p.sessionPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveSession(p, session) {
+    ensureDir(p.systemDir);
+    writeFileSync(p.sessionPath, JSON.stringify(session, null, 2) + "\n", "utf8");
+}
+export function clearSession(p) {
+    if (existsSync(p.sessionPath))
+        rmSync(p.sessionPath);
+}
+export function newSessionId() {
+    return `s_${randomUUID().slice(0, 8)}`;
+}
+export function newTaskId() {
+    return `t_${randomUUID().slice(0, 8)}`;
+}
+/**
+ * A session is fresh when it exists, is in a usable state, and started within
+ * the configured TTL. Stale sessions force the agent to re-load context, which
+ * is the CLI guard's primary gate.
+ */
+export function isSessionFresh(session, config) {
+    if (!session)
+        return false;
+    if (session.state === "UNINITIALIZED" || session.state === "NEEDS_BOOTSTRAP") {
+        return false;
+    }
+    const ageMs = Date.now() - Date.parse(session.startedAt);
+    const ttlMs = config.sessionTtlMinutes * 60_000;
+    return ageMs <= ttlMs;
+}
+/** True when context loaded during the session matches files currently on disk. */
+export function contextMatchesDisk(session, current) {
+    if (!session)
+        return false;
+    for (const [key, sum] of Object.entries(current)) {
+        if (session.contextChecksums[key] !== sum)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=session.js.map

package/dist/core/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAsB,MAAM,aAAa,CAAC;AAG5D,MAAM,UAAU,WAAW,CAAC,CAAgB;IAC1C,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAgB,CAAC;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAgB,EAAE,OAAoB;IAChE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvB,aAAa,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,CAAgB;IAC3C,IAAI,UAAU,CAAC,CAAC,CAAC,WAAW,CAAC;QAAE,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,KAAK,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,KAAK,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA2B,EAC3B,MAAoB;IAEpB,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,OAAO,CAAC,KAAK,KAAK,eAAe,IAAI,OAAO,CAAC,KAAK,KAAK,iBAAiB,EAAE,CAAC;QAC7E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,MAAM,CAAC,iBAAiB,GAAG,MAAM,CAAC;IAChD,OAAO,KAAK,IAAI,KAAK,CAAC;AACxB,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAChC,OAA2B,EAC3B,OAA+B;IAE/B,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,IAAI,OAAO,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/templates.d.ts

@@ -0,0 +1,16 @@
+import type { GovernanceFileKey } from "../types.js";
+export interface TemplateDef {
+    key: GovernanceFileKey;
+    title: string;
+    /** One-line description of the file's purpose. */
+    purpose: string;
+    /**
+     * Required H2 (##) section headings. Bootstrap templates include them, and
+     * `write_governance_file` validates that these are present.
+     */
+    requiredSections: string[];
+    /** Full markdown scaffold written when the file is missing. */
+    scaffold: string;
+}
+export declare const TEMPLATES: Record<GovernanceFileKey, TemplateDef>;
+export declare function templateFor(key: GovernanceFileKey): TemplateDef;

package/dist/core/templates.js

@@ -0,0 +1,163 @@
+function scaffoldFrom(title, purpose, sections) {
+    const body = sections
+        .map((s) => `## ${s.heading}\n\n> ${s.hint}\n`)
+        .join("\n");
+    return `# ${title}\n\n<!-- ${purpose} -->\n<!-- Managed by knbase. Replace the guidance blockquotes with real content. -->\n\n${body}`;
+}
+export const TEMPLATES = {
+    prd: {
+        key: "prd",
+        title: "Product Requirements (PRD)",
+        purpose: "What we are building and why. The single source of product truth.",
+        requiredSections: [
+            "Problem",
+            "Goals",
+            "Users & Personas",
+            "Functional Requirements",
+            "Non-Goals",
+            "Success Metrics",
+        ],
+        scaffold: scaffoldFrom("Product Requirements (PRD)", "What we are building and why.", [
+            { heading: "Problem", hint: "What problem does this solve? For whom?" },
+            { heading: "Goals", hint: "The concrete outcomes this project must achieve." },
+            { heading: "Users & Personas", hint: "Who uses this and what they need." },
+            {
+                heading: "Functional Requirements",
+                hint: "Numbered list of what the system must do.",
+            },
+            { heading: "Non-Goals", hint: "Explicitly out of scope, to prevent drift." },
+            { heading: "Success Metrics", hint: "How we measure that it works." },
+        ]),
+    },
+    architecture: {
+        key: "architecture",
+        title: "Architecture",
+        purpose: "High-level system structure, components, and data flow.",
+        requiredSections: [
+            "Overview",
+            "Components",
+            "Data Flow",
+            "Tech Stack",
+            "External Dependencies",
+        ],
+        scaffold: scaffoldFrom("Architecture", "High-level system structure and data flow.", [
+            { heading: "Overview", hint: "A paragraph describing the system shape." },
+            {
+                heading: "Components",
+                hint: "Each major component, its responsibility, and its location in the repo.",
+            },
+            { heading: "Data Flow", hint: "How data/requests move through components." },
+            { heading: "Tech Stack", hint: "Languages, frameworks, runtimes, databases." },
+            {
+                heading: "External Dependencies",
+                hint: "Third-party services, APIs, and libraries with a role.",
+            },
+        ]),
+    },
+    design: {
+        key: "design",
+        title: "Design",
+        purpose: "Detailed design decisions, interfaces, and conventions.",
+        requiredSections: [
+            "Modules & Interfaces",
+            "Key Decisions",
+            "Data Models",
+            "Conventions",
+            "Open Questions",
+        ],
+        scaffold: scaffoldFrom("Design", "Detailed design decisions and interfaces.", [
+            {
+                heading: "Modules & Interfaces",
+                hint: "Public APIs, function/class signatures, and contracts between modules.",
+            },
+            {
+                heading: "Key Decisions",
+                hint: "Decisions taken and the rationale/trade-offs (ADR-style).",
+            },
+            { heading: "Data Models", hint: "Schemas, types, and their relationships." },
+            {
+                heading: "Conventions",
+                hint: "Naming, error handling, folder layout, and style rules.",
+            },
+            { heading: "Open Questions", hint: "Unresolved design questions to revisit." },
+        ]),
+    },
+    phase: {
+        key: "phase",
+        title: "Phases & Roadmap",
+        purpose: "Where the project is now and what comes next.",
+        requiredSections: [
+            "Current Phase",
+            "Completed",
+            "In Progress",
+            "Next Up",
+            "Backlog",
+        ],
+        scaffold: scaffoldFrom("Phases & Roadmap", "Where the project is now and what comes next.", [
+            {
+                heading: "Current Phase",
+                hint: "Name and one-line status of the phase currently in flight.",
+            },
+            { heading: "Completed", hint: "Checklist of finished milestones." },
+            { heading: "In Progress", hint: "What is actively being worked on." },
+            { heading: "Next Up", hint: "The next 1-3 items to pick up." },
+            { heading: "Backlog", hint: "Everything else, unordered." },
+        ]),
+    },
+    rules: {
+        key: "rules",
+        title: "Rules & Constraints",
+        purpose: "Hard rules every agent must obey when working in this project.",
+        requiredSections: [
+            "Must Do",
+            "Must Not Do",
+            "Coding Standards",
+            "Guardrails",
+        ],
+        scaffold: scaffoldFrom("Rules & Constraints", "Hard rules every agent must obey.", [
+            { heading: "Must Do", hint: "Non-negotiable practices (tests, reviews, etc.)." },
+            {
+                heading: "Must Not Do",
+                hint: "Forbidden actions (e.g. never touch prod secrets).",
+            },
+            {
+                heading: "Coding Standards",
+                hint: "Language/style rules specific to this project.",
+            },
+            {
+                heading: "Guardrails",
+                hint: "Safety limits: files that are off-limits, destructive ops to avoid.",
+            },
+        ]),
+    },
+    memory: {
+        key: "memory",
+        title: "Project Memory",
+        purpose: "Running knowledge base updated after every task so future agents can extend the project.",
+        requiredSections: [
+            "Summary",
+            "Recent Changes",
+            "Learnings & Gotchas",
+            "Known Issues",
+        ],
+        scaffold: scaffoldFrom("Project Memory", "Running knowledge base updated after every task.", [
+            {
+                heading: "Summary",
+                hint: "Current state of the project in a few sentences.",
+            },
+            {
+                heading: "Recent Changes",
+                hint: "Reverse-chronological log of notable changes (append after each task).",
+            },
+            {
+                heading: "Learnings & Gotchas",
+                hint: "Things discovered that future agents must know.",
+            },
+            { heading: "Known Issues", hint: "Bugs, tech debt, and workarounds." },
+        ]),
+    },
+};
+export function templateFor(key) {
+    return TEMPLATES[key];
+}
+//# sourceMappingURL=templates.js.map

package/dist/core/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/core/templates.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./core/engine.js";
+export { createServer } from "./mcp/server.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./core/engine.js";
+export { createServer } from "./mcp/server.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/mcp/server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/mcp/server.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerTools } from "./tools.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "knbase",
+        version: "0.1.0",
+    });
+    registerTools(server);
+    return server;
+}
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logging; stdout is reserved for the MCP protocol.
+    process.stderr.write("[knbase] MCP server running on stdio\n");
+}
+function isMain() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain()) {
+    main().catch((err) => {
+        process.stderr.write(`[knbase] Fatal: ${err.stack ?? err}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IACH,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,uEAAuE;IACvE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,MAAM;IACb,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,CAAC,KAAK,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,MAAM,EAAE,EAAE,CAAC;IACb,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAoB,GAAa,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/mcp/tools.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerTools(server: McpServer): void;

package/dist/mcp/tools.js

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { beginTask, completeTask, getContext, getStatus, openProject, startSession, writeGovernanceFile, } from "../core/engine.js";
+import { renderMindmapDoc } from "../core/mindmap.js";
+import { refreshIndex, saveIndex } from "../core/index-store.js";
+import { GOVERNANCE_FILES } from "../types.js";
+function ok(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function fail(message, extra) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify({ error: message, ...(extra ? { extra } : {}) }, null, 2) },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Determines the project root for a tool call. The client may pass an explicit
+ * `root`; otherwise the server falls back to KNBASE_ROOT / cwd resolution.
+ */
+function project(root) {
+    return openProject(root);
+}
+export function registerTools(server) {
+    const fileEnum = z.enum(GOVERNANCE_FILES);
+    const rootArg = { root: z.string().optional().describe("Absolute project root. Defaults to KNBASE_ROOT or cwd.") };
+    server.registerTool("start_session", {
+        title: "Start governance session",
+        description: "MANDATORY FIRST CALL. Loads project governance context (mind map + summaries + current phase) token-efficiently. If governance files are missing, returns bootstrap templates and instructs you to author them before doing any work.",
+        inputSchema: { ...rootArg },
+    }, async ({ root }) => {
+        try {
+            return ok(startSession(project(root)));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool("get_context", {
+        title: "Get governance context",
+        description: "Returns the compact context (mind map + summaries + phase). Pass files=[...] with full=true to fetch full contents of specific docs ONLY when needed, to conserve tokens.",
+        inputSchema: {
+            ...rootArg,
+            files: z.array(fileEnum).optional().describe("Governance files to fetch in full."),
+            full: z.boolean().optional().describe("If true, include full contents of `files`."),
+        },
+    }, async ({ root, files, full }) => {
+        try {
+            return ok(getContext(project(root), files, full));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool("write_governance_file", {
+        title: "Write/update a governance file",
+        description: "Create or update one governance doc (prd, architecture, design, phase, rules, memory). Validates that all required sections are present, then refreshes the index and mind map. Use for bootstrap AND for post-task updates.",
+        inputSchema: {
+            ...rootArg,
+            file: fileEnum.describe("Which governance file to write."),
+            content: z.string().describe("Full markdown content (must include all required H2 sections)."),
+            summary: z
+                .string()
+                .describe("One-line summary of this file (shown in mind map to save tokens)."),
+        },
+    }, async ({ root, file, content, summary }) => {
+        try {
+            const result = writeGovernanceFile(project(root), file, content, summary);
+            if (!result.ok) {
+                return fail(`Missing required sections in ${file}.md: ${result.missingSections.join(", ")}`, result);
+            }
+            return ok(result);
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool("begin_task", {
+        title: "Begin a task (gated)",
+        description: "Call BEFORE making any changes. Refuses unless context has been loaded this session (the read-before-action gate). Returns a taskId.",
+        inputSchema: {
+            ...rootArg,
+            description: z.string().describe("What this task will accomplish."),
+        },
+    }, async ({ root, description }) => {
+        const result = beginTask(project(root), description);
+        return result.ok ? ok(result) : fail(result.error ?? "begin_task failed", result);
+    });
+    server.registerTool("complete_task", {
+        title: "Complete a task (gated)",
+        description: "Call AFTER finishing work. Refuses unless memory.md was updated during the task (the update-after-action gate). Regenerates the mind map and appends the activity log.",
+        inputSchema: {
+            ...rootArg,
+            taskId: z.string().describe("The taskId returned by begin_task."),
+            summary: z.string().describe("What was accomplished (recorded in the activity log)."),
+        },
+    }, async ({ root, taskId, summary }) => {
+        const result = completeTask(project(root), taskId, summary);
+        return result.ok ? ok(result) : fail(result.error ?? "complete_task failed", result);
+    });
+    server.registerTool("get_mindmap", {
+        title: "Get combined mind map",
+        description: "Returns the auto-generated mermaid mind map + index table combining all governance docs.",
+        inputSchema: { ...rootArg },
+    }, async ({ root }) => {
+        try {
+            const proj = project(root);
+            const index = refreshIndex(proj.p, proj.config);
+            saveIndex(proj.p, index);
+            return ok({ mindmap: renderMindmapDoc(proj.config, index) });
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool("get_status", {
+        title: "Get governance status",
+        description: "Returns session state, missing files, active task, and recent activity log.",
+        inputSchema: { ...rootArg },
+    }, async ({ root }) => {
+        try {
+            return ok(getStatus(project(root)));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+}
+//# sourceMappingURL=tools.js.map

package/dist/mcp/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/mcp/tools.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared types for the knbase governance system.
+ */
+/** Canonical governance document keys. Order defines display order everywhere. */
+export declare const GOVERNANCE_FILES: readonly ["prd", "architecture", "design", "phase", "rules", "memory"];
+export type GovernanceFileKey = (typeof GOVERNANCE_FILES)[number];
+/** Session gate states. The state machine enforces the read -> act -> update flow. */
+export type SessionState = "UNINITIALIZED" | "NEEDS_BOOTSTRAP" | "CONTEXT_LOADED" | "TASK_ACTIVE";
+/** Per-file metadata cached in .knbase/index.json. */
+export interface FileIndexEntry {
+    /** Governance file key. */
+    key: GovernanceFileKey;
+    /** Relative path from project root. */
+    path: string;
+    /** Whether the file currently exists on disk. */
+    exists: boolean;
+    /** SHA-256 checksum of file contents (empty string when missing). */
+    checksum: string;
+    /** Size in bytes. */
+    bytes: number;
+    /** One-line summary supplied by the agent at write time. */
+    summary: string;
+    /** Markdown H2 (##) section headings extracted from the file. */
+    headings: string[];
+    /** ISO timestamp of the last write through the system. */
+    updatedAt: string | null;
+}
+export interface IndexData {
+    version: number;
+    updatedAt: string;
+    files: Record<GovernanceFileKey, FileIndexEntry>;
+}
+export interface SessionData {
+    sessionId: string;
+    state: SessionState;
+    startedAt: string;
+    /** Checksums of governance files at the moment context was loaded. */
+    contextChecksums: Record<string, string>;
+    activeTask: ActiveTask | null;
+}
+export interface ActiveTask {
+    taskId: string;
+    description: string;
+    startedAt: string;
+    /** Checksums of governance files when the task began (to detect updates). */
+    startChecksums: Record<string, string>;
+}
+export interface KnbaseConfig {
+    version: number;
+    /** Directory (relative to project root) holding the governance docs. */
+    docsDir: string;
+    /** Governance file keys managed by the system. */
+    files: GovernanceFileKey[];
+    /**
+     * Session freshness TTL in minutes. A session older than this is considered
+     * stale and the agent must re-load context. Used by the CLI guard.
+     */
+    sessionTtlMinutes: number;
+}
+/** A single append-only activity log record. */
+export interface LogRecord {
+    ts: string;
+    sessionId?: string;
+    event: "session_start" | "bootstrap_required" | "file_written" | "task_begin" | "task_complete" | "guard_allow" | "guard_block" | "init";
+    detail: string;
+    meta?: Record<string, unknown>;
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * Shared types for the knbase governance system.
+ */
+/** Canonical governance document keys. Order defines display order everywhere. */
+export const GOVERNANCE_FILES = [
+    "prd",
+    "architecture",
+    "design",
+    "phase",
+    "rules",
+    "memory",
+];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK;IACL,cAAc;IACd,QAAQ;IACR,OAAO;IACP,OAAO;IACP,QAAQ;CACA,CAAC"}