@vonneollc/knbase 0.1.0

package/dist/core/engine.js

@@ -0,0 +1,350 @@
+import { existsSync } from "node:fs";
+import { DEFAULT_CONFIG, ensureDir, isInitialized, loadConfig, paths, resolveProjectRoot, saveConfig, } from "./config.js";
+import { checksum, missingSections, readDoc, writeDoc, } from "./files.js";
+import { currentChecksums, loadIndex, missingFiles, recordWrite, refreshIndex, saveIndex, } from "./index-store.js";
+import { appendLog, hasTaskCompletedSince, readLog } from "./log.js";
+import { renderMindmapDoc, writeMindmap } from "./mindmap.js";
+import { clearSession, contextMatchesDisk, isSessionFresh, loadSession, newSessionId, newTaskId, saveSession, } from "./session.js";
+import { TEMPLATES } from "./templates.js";
+/** Open a project handle (does not create anything). */
+export function openProject(startDir) {
+    const root = resolveProjectRoot(startDir);
+    const config = loadConfig(root);
+    return { root, config, p: paths(root, config) };
+}
+export function isKnownFile(config, key) {
+    return config.files.includes(key);
+}
+/**
+ * Initialize knbase in a project: create `.knbase/`, write config, scaffold
+ * any missing governance docs with templates, build index + mindmap.
+ */
+export function initProject(startDir, docsDir) {
+    const root = resolveProjectRoot(startDir);
+    const existed = isInitialized(root);
+    const config = existed
+        ? loadConfig(root)
+        : { ...DEFAULT_CONFIG, ...(docsDir ? { docsDir } : {}) };
+    const p = paths(root, config);
+    ensureDir(p.systemDir);
+    ensureDir(p.docsDir);
+    saveConfig(root, config);
+    const scaffolded = [];
+    const alreadyPresent = [];
+    for (const key of config.files) {
+        const docPath = p.docPath(key);
+        if (existsSync(docPath)) {
+            alreadyPresent.push(key);
+            continue;
+        }
+        writeDoc(docPath, TEMPLATES[key].scaffold);
+        scaffolded.push(key);
+    }
+    const index = refreshIndex(p, config);
+    saveIndex(p, index);
+    writeMindmap(p, config, index);
+    appendLog(p, {
+        event: "init",
+        detail: `Initialized knbase (docsDir=${config.docsDir})`,
+        meta: { scaffolded, alreadyPresent },
+    });
+    return { root, createdConfig: !existed, scaffolded, alreadyPresent };
+}
+function buildCompactContext(p, config, index) {
+    const files = config.files.map((key) => {
+        const e = index.files[key];
+        return {
+            key,
+            exists: e.exists,
+            summary: e.summary || TEMPLATES[key].purpose,
+            headings: e.headings,
+            bytes: e.bytes,
+            updatedAt: e.updatedAt,
+        };
+    });
+    return {
+        currentPhase: extractCurrentPhase(p, config),
+        mindmap: renderMindmapDoc(config, index),
+        files,
+    };
+}
+/** Pulls the "Current Phase" section body from phase.md, if present. */
+function extractCurrentPhase(p, config) {
+    if (!config.files.includes("phase"))
+        return "unknown";
+    const doc = readDoc(p.docPath("phase"));
+    if (!doc.exists)
+        return "unknown";
+    const lines = doc.content.split(/\r?\n/);
+    const idx = lines.findIndex((l) => /^##\s+Current Phase\s*$/i.test(l));
+    if (idx === -1)
+        return "unknown";
+    const body = [];
+    for (let i = idx + 1; i < lines.length; i++) {
+        if (/^##\s+/.test(lines[i]))
+            break;
+        const t = lines[i].trim();
+        if (t && !t.startsWith(">") && !t.startsWith("<!--"))
+            body.push(t);
+    }
+    return body.join(" ").trim() || "unspecified";
+}
+const BOOTSTRAP_INSTRUCTIONS = "Governance files are missing or empty. Before doing ANY work you must author them. " +
+    "For each file below, call `write_governance_file` with real content covering all required sections, " +
+    "derived from the user's request/prompt. Do not begin_task until all files exist.";
+const READY_INSTRUCTIONS = "Context loaded. You now have the mind map, per-file summaries, and current phase. " +
+    "Fetch full file contents with `get_context(files=[...], full=true)` ONLY when needed (to save tokens). " +
+    "Call `begin_task` before making changes, and `complete_task` after, updating memory.md.";
+export function startSession(project) {
+    const { p, config, root } = project;
+    ensureDir(p.systemDir);
+    // Persist config so MCP-only usage (without `knbase init`) is fully
+    // functional for status/guard checks.
+    if (!isInitialized(root))
+        saveConfig(root, config);
+    const index = refreshIndex(p, config);
+    saveIndex(p, index);
+    const missing = missingFiles(p, config);
+    const sessionId = newSessionId();
+    if (missing.length > 0) {
+        const session = {
+            sessionId,
+            state: "NEEDS_BOOTSTRAP",
+            startedAt: new Date().toISOString(),
+            contextChecksums: currentChecksums(p, config),
+            activeTask: null,
+        };
+        saveSession(p, session);
+        appendLog(p, {
+            sessionId,
+            event: "bootstrap_required",
+            detail: `Missing governance files: ${missing.join(", ")}`,
+            meta: { missing },
+        });
+        return {
+            sessionId,
+            state: "NEEDS_BOOTSTRAP",
+            needsBootstrap: true,
+            missing,
+            instructions: BOOTSTRAP_INSTRUCTIONS,
+            bootstrapTemplates: missing.map((key) => ({
+                key,
+                requiredSections: TEMPLATES[key].requiredSections,
+            })),
+        };
+    }
+    const session = {
+        sessionId,
+        state: "CONTEXT_LOADED",
+        startedAt: new Date().toISOString(),
+        contextChecksums: currentChecksums(p, config),
+        activeTask: null,
+    };
+    saveSession(p, session);
+    appendLog(p, { sessionId, event: "session_start", detail: "Context loaded" });
+    return {
+        sessionId,
+        state: "CONTEXT_LOADED",
+        needsBootstrap: false,
+        missing: [],
+        instructions: READY_INSTRUCTIONS,
+        compactContext: buildCompactContext(p, config, index),
+    };
+}
+export function getContext(project, files, full) {
+    const { p, config } = project;
+    const index = refreshIndex(p, config);
+    saveIndex(p, index);
+    const result = { compact: buildCompactContext(p, config, index) };
+    if (full && files && files.length > 0) {
+        result.fullContents = [];
+        for (const key of files) {
+            if (!isKnownFile(config, key))
+                continue;
+            result.fullContents.push({ key, content: readDoc(p.docPath(key)).content });
+        }
+    }
+    return result;
+}
+export function writeGovernanceFile(project, key, content, summary) {
+    const { p, config } = project;
+    if (!isKnownFile(config, key)) {
+        throw new Error(`Unknown governance file '${key}'. Valid: ${config.files.join(", ")}`);
+    }
+    const tpl = TEMPLATES[key];
+    const missing = missingSections(content, tpl.requiredSections);
+    if (missing.length > 0) {
+        return {
+            key,
+            bytes: 0,
+            ok: false,
+            missingSections: missing,
+            remainingBootstrap: missingFiles(p, config),
+            state: loadSession(p)?.state ?? "UNINITIALIZED",
+        };
+    }
+    writeDoc(p.docPath(key), content);
+    const sum = checksum(content.endsWith("\n") ? content : content + "\n");
+    const bytes = Buffer.byteLength(content, "utf8");
+    const doc = readDoc(p.docPath(key));
+    const index = loadIndex(p, config);
+    recordWrite(index, key, sum, bytes, doc.headings, summary);
+    saveIndex(p, index);
+    writeMindmap(p, config, index);
+    const session = loadSession(p);
+    const remaining = missingFiles(p, config);
+    // Once bootstrap is complete, advance the session to CONTEXT_LOADED.
+    if (session && session.state === "NEEDS_BOOTSTRAP" && remaining.length === 0) {
+        session.state = "CONTEXT_LOADED";
+        session.contextChecksums = currentChecksums(p, config);
+        saveSession(p, session);
+    }
+    appendLog(p, {
+        sessionId: session?.sessionId,
+        event: "file_written",
+        detail: `Wrote ${key}.md (${bytes} bytes)`,
+        meta: { key, summary },
+    });
+    return {
+        key,
+        bytes,
+        ok: true,
+        missingSections: [],
+        remainingBootstrap: remaining,
+        state: loadSession(p)?.state ?? "CONTEXT_LOADED",
+    };
+}
+export function beginTask(project, description) {
+    const { p, config } = project;
+    const session = loadSession(p);
+    if (!session || session.state === "UNINITIALIZED") {
+        return { ok: false, error: "No active session. Call start_session first." };
+    }
+    if (session.state === "NEEDS_BOOTSTRAP") {
+        return {
+            ok: false,
+            error: "Governance files are incomplete. Author them via write_governance_file before starting tasks.",
+        };
+    }
+    if (session.state === "TASK_ACTIVE") {
+        return {
+            ok: false,
+            error: `A task is already active (${session.activeTask?.taskId}). Call complete_task first.`,
+        };
+    }
+    // Gate: context must reflect what is on disk right now.
+    if (!contextMatchesDisk(session, currentChecksums(p, config))) {
+        return {
+            ok: false,
+            error: "Governance files changed since context was loaded. Call start_session/get_context again before starting a task.",
+        };
+    }
+    const taskId = newTaskId();
+    session.state = "TASK_ACTIVE";
+    session.activeTask = {
+        taskId,
+        description,
+        startedAt: new Date().toISOString(),
+        startChecksums: currentChecksums(p, config),
+    };
+    saveSession(p, session);
+    appendLog(p, {
+        sessionId: session.sessionId,
+        event: "task_begin",
+        detail: description,
+        meta: { taskId },
+    });
+    return {
+        ok: true,
+        taskId,
+        reminder: "When done, call complete_task with a summary and update memory.md (and phase.md if the phase advanced).",
+    };
+}
+export function completeTask(project, taskId, summary) {
+    const { p, config } = project;
+    const session = loadSession(p);
+    if (!session || session.state !== "TASK_ACTIVE" || !session.activeTask) {
+        return { ok: false, error: "No active task. Call begin_task first." };
+    }
+    if (session.activeTask.taskId !== taskId) {
+        return {
+            ok: false,
+            error: `Task id mismatch. Active task is ${session.activeTask.taskId}.`,
+        };
+    }
+    // Gate: memory.md must have changed since the task began.
+    const now = currentChecksums(p, config);
+    const start = session.activeTask.startChecksums;
+    const changed = config.files.filter((k) => now[k] !== start[k]);
+    if (config.files.includes("memory") && now.memory === start.memory) {
+        return {
+            ok: false,
+            error: "memory.md was not updated during this task. Update it via write_governance_file (record the change under 'Recent Changes'), then call complete_task again.",
+            updatedFiles: changed,
+            state: session.state,
+        };
+    }
+    session.state = "CONTEXT_LOADED";
+    session.activeTask = null;
+    session.contextChecksums = now;
+    saveSession(p, session);
+    const index = refreshIndex(p, config);
+    saveIndex(p, index);
+    writeMindmap(p, config, index);
+    appendLog(p, {
+        sessionId: session.sessionId,
+        event: "task_complete",
+        detail: summary,
+        meta: { taskId, updatedFiles: changed },
+    });
+    return { ok: true, updatedFiles: changed, state: "CONTEXT_LOADED" };
+}
+export function getStatus(project) {
+    const { p, config, root } = project;
+    const initialized = isInitialized(root);
+    const session = loadSession(p);
+    return {
+        initialized,
+        root,
+        docsDir: config.docsDir,
+        state: session?.state ?? "UNINITIALIZED",
+        sessionFresh: isSessionFresh(session, config),
+        missing: initialized ? missingFiles(p, config) : [...config.files],
+        activeTask: session?.activeTask ?? null,
+        recentLog: initialized ? readLog(p, 10) : [],
+    };
+}
+/**
+ * Decide whether a gated shell command may run. Requires: initialized project,
+ * all governance files present, and a fresh CONTEXT_LOADED/TASK_ACTIVE session
+ * whose loaded context still matches disk.
+ */
+export function guardDecision(project) {
+    const { p, config, root } = project;
+    if (!isInitialized(root)) {
+        return { allow: false, reason: "knbase is not initialized. Run `knbase init`." };
+    }
+    const missing = missingFiles(p, config);
+    if (missing.length > 0) {
+        return {
+            allow: false,
+            reason: `Governance files missing/empty: ${missing.join(", ")}. Author them first.`,
+        };
+    }
+    const session = loadSession(p);
+    if (!isSessionFresh(session, config)) {
+        return {
+            allow: false,
+            reason: "No fresh session. Start a session (read context) before acting.",
+        };
+    }
+    if (!contextMatchesDisk(session, currentChecksums(p, config))) {
+        return {
+            allow: false,
+            reason: "Governance files changed since context load. Re-read context.",
+        };
+    }
+    return { allow: true, reason: "Context is loaded and current." };
+}
+export { appendLog, clearSession, hasTaskCompletedSince, loadSession, readLog, };
+//# sourceMappingURL=engine.js.map

package/dist/core/engine.js.map

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

package/dist/core/files.d.ts

@@ -0,0 +1,23 @@
+/** SHA-256 of a string. */
+export declare function checksum(content: string): string;
+export interface DocFileState {
+    exists: boolean;
+    content: string;
+    checksum: string;
+    bytes: number;
+    /** True when the file is missing or contains only whitespace/template guidance. */
+    isEmpty: boolean;
+    headings: string[];
+}
+/** Reads a doc from disk and computes its derived state. */
+export declare function readDoc(absPath: string): DocFileState;
+export declare function writeDoc(absPath: string, content: string): void;
+/** Extract H2 (##) section headings, ignoring the H1 title and deeper levels. */
+export declare function extractHeadings(content: string): string[];
+/**
+ * Content is considered a "placeholder" (i.e. not yet authored) when every
+ * non-heading, non-comment line is empty or a guidance blockquote (`> ...`).
+ */
+export declare function isPlaceholderContent(content: string): boolean;
+/** Returns the required sections that are missing from the given content. */
+export declare function missingSections(content: string, required: string[]): string[];

package/dist/core/files.js

@@ -0,0 +1,66 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { ensureDir } from "./config.js";
+/** SHA-256 of a string. */
+export function checksum(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+/** Reads a doc from disk and computes its derived state. */
+export function readDoc(absPath) {
+    if (!existsSync(absPath)) {
+        return {
+            exists: false,
+            content: "",
+            checksum: "",
+            bytes: 0,
+            isEmpty: true,
+            headings: [],
+        };
+    }
+    const content = readFileSync(absPath, "utf8");
+    return {
+        exists: true,
+        content,
+        checksum: checksum(content),
+        bytes: Buffer.byteLength(content, "utf8"),
+        isEmpty: isPlaceholderContent(content),
+        headings: extractHeadings(content),
+    };
+}
+export function writeDoc(absPath, content) {
+    ensureDir(dirname(absPath));
+    const normalized = content.endsWith("\n") ? content : content + "\n";
+    writeFileSync(absPath, normalized, "utf8");
+}
+/** Extract H2 (##) section headings, ignoring the H1 title and deeper levels. */
+export function extractHeadings(content) {
+    const out = [];
+    for (const line of content.split(/\r?\n/)) {
+        const m = /^##\s+(.+?)\s*$/.exec(line);
+        if (m)
+            out.push(m[1].trim());
+    }
+    return out;
+}
+/**
+ * Content is considered a "placeholder" (i.e. not yet authored) when every
+ * non-heading, non-comment line is empty or a guidance blockquote (`> ...`).
+ */
+export function isPlaceholderContent(content) {
+    const meaningful = content
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .filter((l) => !l.startsWith("#")) // headings
+        .filter((l) => !l.startsWith("<!--")) // html comments
+        .filter((l) => !l.startsWith("-->"))
+        .filter((l) => !l.startsWith(">")); // guidance blockquotes
+    return meaningful.length === 0;
+}
+/** Returns the required sections that are missing from the given content. */
+export function missingSections(content, required) {
+    const present = new Set(extractHeadings(content).map((h) => h.toLowerCase()));
+    return required.filter((r) => !present.has(r.toLowerCase()));
+}
+//# sourceMappingURL=files.js.map

package/dist/core/files.js.map

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

package/dist/core/index-store.d.ts

@@ -0,0 +1,17 @@
+import { GOVERNANCE_FILES, type KnbaseConfig, type GovernanceFileKey, type IndexData } from "../types.js";
+import { paths, type ResolvedPaths } from "./config.js";
+export declare function loadIndex(p: ResolvedPaths, config: KnbaseConfig): IndexData;
+export declare function saveIndex(p: ResolvedPaths, index: IndexData): void;
+/**
+ * Re-scans all governance docs from disk and refreshes their checksum/heading/
+ * exists metadata. Preserves agent-supplied summaries unless the file changed
+ * and a new summary is provided elsewhere. Returns the refreshed index.
+ */
+export declare function refreshIndex(p: ResolvedPaths, config: KnbaseConfig, existing?: IndexData): IndexData;
+/** Update a single entry after an authored write, recording the agent summary. */
+export declare function recordWrite(index: IndexData, key: GovernanceFileKey, checksum: string, bytes: number, headings: string[], summary: string): void;
+/** Governance keys whose file is missing or still a placeholder. */
+export declare function missingFiles(p: ResolvedPaths, config: KnbaseConfig): GovernanceFileKey[];
+/** Current checksum map keyed by governance file key. */
+export declare function currentChecksums(p: ResolvedPaths, config: KnbaseConfig): Record<string, string>;
+export { GOVERNANCE_FILES, paths };

package/dist/core/index-store.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { relative } from "node:path";
+import { GOVERNANCE_FILES, } from "../types.js";
+import { ensureDir, paths } from "./config.js";
+import { readDoc } from "./files.js";
+const INDEX_VERSION = 1;
+function emptyEntry(key, path) {
+    return {
+        key,
+        path,
+        exists: false,
+        checksum: "",
+        bytes: 0,
+        summary: "",
+        headings: [],
+        updatedAt: null,
+    };
+}
+export function loadIndex(p, config) {
+    let data = null;
+    if (existsSync(p.indexPath)) {
+        try {
+            data = JSON.parse(readFileSync(p.indexPath, "utf8"));
+        }
+        catch {
+            data = null;
+        }
+    }
+    const files = {};
+    for (const key of config.files) {
+        const rel = relative(p.root, p.docPath(key));
+        files[key] = data?.files?.[key] ?? emptyEntry(key, rel);
+        files[key].path = rel;
+    }
+    return {
+        version: INDEX_VERSION,
+        updatedAt: data?.updatedAt ?? new Date().toISOString(),
+        files,
+    };
+}
+export function saveIndex(p, index) {
+    ensureDir(p.systemDir);
+    index.updatedAt = new Date().toISOString();
+    writeFileSync(p.indexPath, JSON.stringify(index, null, 2) + "\n", "utf8");
+}
+/**
+ * Re-scans all governance docs from disk and refreshes their checksum/heading/
+ * exists metadata. Preserves agent-supplied summaries unless the file changed
+ * and a new summary is provided elsewhere. Returns the refreshed index.
+ */
+export function refreshIndex(p, config, existing) {
+    const index = existing ?? loadIndex(p, config);
+    for (const key of config.files) {
+        const state = readDoc(p.docPath(key));
+        const entry = index.files[key];
+        const changed = entry.checksum !== state.checksum;
+        entry.exists = state.exists && !state.isEmpty;
+        entry.checksum = state.checksum;
+        entry.bytes = state.bytes;
+        entry.headings = state.headings;
+        if (changed && state.exists) {
+            entry.updatedAt = new Date().toISOString();
+        }
+    }
+    return index;
+}
+/** Update a single entry after an authored write, recording the agent summary. */
+export function recordWrite(index, key, checksum, bytes, headings, summary) {
+    const entry = index.files[key];
+    entry.exists = true;
+    entry.checksum = checksum;
+    entry.bytes = bytes;
+    entry.headings = headings;
+    if (summary.trim())
+        entry.summary = summary.trim();
+    entry.updatedAt = new Date().toISOString();
+}
+/** Governance keys whose file is missing or still a placeholder. */
+export function missingFiles(p, config) {
+    const out = [];
+    for (const key of config.files) {
+        const state = readDoc(p.docPath(key));
+        if (!state.exists || state.isEmpty)
+            out.push(key);
+    }
+    return out;
+}
+/** Current checksum map keyed by governance file key. */
+export function currentChecksums(p, config) {
+    const map = {};
+    for (const key of config.files) {
+        map[key] = readDoc(p.docPath(key)).checksum;
+    }
+    return map;
+}
+export { GOVERNANCE_FILES, paths };
+//# sourceMappingURL=index-store.js.map

package/dist/core/index-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-store.js","sourceRoot":"","sources":["../../src/core/index-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EACL,gBAAgB,GAKjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAsB,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,SAAS,UAAU,CAAC,GAAsB,EAAE,IAAY;IACtD,OAAO;QACL,GAAG;QACH,IAAI;QACJ,MAAM,EAAE,KAAK;QACb,QAAQ,EAAE,EAAE;QACZ,KAAK,EAAE,CAAC;QACR,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE;QACZ,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,CAAgB,EAAE,MAAoB;IAC9D,IAAI,IAAI,GAAqB,IAAI,CAAC;IAClC,IAAI,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAc,CAAC;QACpE,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,EAA+C,CAAC;IAC9D,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7C,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxD,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC;IACxB,CAAC;IACD,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,SAAS,EAAE,IAAI,EAAE,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtD,KAAK;KACN,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,CAAgB,EAAE,KAAgB;IAC1D,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvB,KAAK,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,aAAa,CAAC,CAAC,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAC1B,CAAgB,EAChB,MAAoB,EACpB,QAAoB;IAEpB,MAAM,KAAK,GAAG,QAAQ,IAAI,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,CAAC;QAClD,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QAC9C,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAChC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QAC1B,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAChC,IAAI,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YAC5B,KAAK,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC7C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,WAAW,CACzB,KAAgB,EAChB,GAAsB,EACtB,QAAgB,EAChB,KAAa,EACb,QAAkB,EAClB,OAAe;IAEf,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC1B,IAAI,OAAO,CAAC,IAAI,EAAE;QAAE,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IACnD,KAAK,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAC7C,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAC1B,CAAgB,EAChB,MAAoB;IAEpB,MAAM,GAAG,GAAwB,EAAE,CAAC;IACpC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,OAAO;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,gBAAgB,CAC9B,CAAgB,EAChB,MAAoB;IAEpB,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/B,GAAG,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC9C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,OAAO,EAAE,gBAAgB,EAAE,KAAK,EAAE,CAAC"}

package/dist/core/log.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedPaths } from "./config.js";
+import type { LogRecord } from "../types.js";
+/** Append a record to the JSONL activity log. */
+export declare function appendLog(p: ResolvedPaths, record: Omit<LogRecord, "ts">): LogRecord;
+/** Read the most recent `limit` log records (newest last). */
+export declare function readLog(p: ResolvedPaths, limit?: number): LogRecord[];
+/**
+ * Whether a task_complete event has been recorded since the given ISO time.
+ * Used by the git pre-commit gate to require a memory update per change set.
+ */
+export declare function hasTaskCompletedSince(p: ResolvedPaths, sinceIso: string | null): boolean;

package/dist/core/log.js

@@ -0,0 +1,38 @@
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { ensureDir } from "./config.js";
+/** Append a record to the JSONL activity log. */
+export function appendLog(p, record) {
+    ensureDir(p.systemDir);
+    const full = { ts: new Date().toISOString(), ...record };
+    appendFileSync(p.logPath, JSON.stringify(full) + "\n", "utf8");
+    return full;
+}
+/** Read the most recent `limit` log records (newest last). */
+export function readLog(p, limit = 50) {
+    if (!existsSync(p.logPath))
+        return [];
+    const lines = readFileSync(p.logPath, "utf8")
+        .split(/\r?\n/)
+        .filter((l) => l.trim().length > 0);
+    const slice = limit > 0 ? lines.slice(-limit) : lines;
+    const out = [];
+    for (const line of slice) {
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return out;
+}
+/**
+ * Whether a task_complete event has been recorded since the given ISO time.
+ * Used by the git pre-commit gate to require a memory update per change set.
+ */
+export function hasTaskCompletedSince(p, sinceIso) {
+    const records = readLog(p, 0);
+    const since = sinceIso ? Date.parse(sinceIso) : 0;
+    return records.some((r) => r.event === "task_complete" && Date.parse(r.ts) >= since);
+}
+//# sourceMappingURL=log.js.map

package/dist/core/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../src/core/log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAIxC,iDAAiD;AACjD,MAAM,UAAU,SAAS,CACvB,CAAgB,EAChB,MAA6B;IAE7B,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvB,MAAM,IAAI,GAAc,EAAE,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC;IACpE,cAAc,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,OAAO,CAAC,CAAgB,EAAE,KAAK,GAAG,EAAE;IAClD,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC;SAC1C,KAAK,CAAC,OAAO,CAAC;SACd,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACtD,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAc,CAAC,CAAC;QAC1C,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,CAAgB,EAAE,QAAuB;IAC7E,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,OAAO,OAAO,CAAC,IAAI,CACjB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,eAAe,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,KAAK,CAChE,CAAC;AACJ,CAAC"}

package/dist/core/mindmap.d.ts

@@ -0,0 +1,11 @@
+import { type ResolvedPaths } from "./config.js";
+import type { KnbaseConfig, IndexData } from "../types.js";
+/**
+ * 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 declare function buildMindmap(config: KnbaseConfig, index: IndexData): string;
+/** Render the full mindmap.md document (fenced mermaid + text summary table). */
+export declare function renderMindmapDoc(config: KnbaseConfig, index: IndexData): string;
+export declare function writeMindmap(p: ResolvedPaths, config: KnbaseConfig, index: IndexData): string;