@vonneollc/knbase 0.1.0

package/README.md

@@ -0,0 +1,182 @@
+# knbase
+
+Agent-agnostic AI project governance and memory system.
+
+`knbase` forces any AI agent to work on a project the *right* way:
+
+1. **Read before acting.** Before doing anything, an agent must load the project's
+   governance context (a compact mind map + per-file summaries + current phase).
+2. **Bootstrap if missing.** If the governance docs don't exist, the system
+   generates templates and instructs the agent to author them *first*, based on
+   its understanding of the user's request.
+3. **Gate every task.** An agent must open a task before making changes and close
+   it afterwards; closing is refused until project memory is updated.
+4. **Build a knowledge base.** Every task appends to `memory.md`, regenerates a
+   combined mind map, and writes an activity log, so the next agent can extend the
+   project from existing code and design instead of re-deriving everything.
+5. **Save tokens.** Full documents are only loaded on demand; by default agents
+   get compact summaries + a mind map.
+
+## Governance documents
+
+Stored in `memory-bank/` (configurable) in each project root:
+
+| File | Purpose |
+| --- | --- |
+| `prd.md` | Product requirements: what we're building and why |
+| `architecture.md` | System structure, components, data flow |
+| `design.md` | Detailed design, interfaces, decisions |
+| `phase.md` | Current phase and roadmap |
+| `rules.md` | Hard rules and guardrails every agent must obey |
+| `memory.md` | Running knowledge base, updated after every task |
+
+System artifacts live in `.knbase/` (`config.json`, `index.json`,
+`mindmap.md`, `activity.log`, `session.json`) and should not be edited by hand.
+
+## Quick setup (recommended, no clone)
+
+Once `knbase` is published to npm (see [Publishing to npm](#publishing-to-npm)),
+you can use it without cloning this repo.
+
+Install it once, globally:
+
+```bash
+npm install -g knbase
+```
+
+**1. Initialize governance in your project:**
+
+```bash
+cd /path/to/your/project
+knbase init
+```
+
+**2. Register the MCP server** with your agent. Cursor example
+(`~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project):
+
+```json
+{
+  "mcpServers": {
+    "knbase": {
+      "command": "knbase-mcp",
+      "env": { "KNBASE_ROOT": "/absolute/path/to/your/project" }
+    }
+  }
+}
+```
+
+Prefer not to install globally? Use `npx` instead — no install step at all:
+
+```json
+{
+  "mcpServers": {
+    "knbase": {
+      "command": "npx",
+      "args": ["-y", "--package", "knbase", "knbase-mcp"],
+      "env": { "KNBASE_ROOT": "/absolute/path/to/your/project" }
+    }
+  }
+}
+```
+
+…and run CLI commands with `npx knbase <command>` (e.g. `npx knbase init`).
+
+`KNBASE_ROOT` is optional; if omitted the server resolves the project root by
+walking up from the working directory (looking for `.knbase/` or `.git`). Each
+tool also accepts an explicit `root` argument.
+
+## Complete setup (from source)
+
+Use this while developing knbase, or before it is published to npm.
+
+```bash
+git clone <repo-url> knbase
+cd knbase
+npm install
+npm run build        # compiles TypeScript into dist/
+```
+
+Then either expose the binaries on your PATH with `npm link`:
+
+```bash
+npm link             # makes `knbase` and `knbase-mcp` available globally
+cd /path/to/your/project
+knbase init
+```
+
+…or reference the built files directly by absolute path.
+
+MCP config (from source):
+
+```json
+{
+  "mcpServers": {
+    "knbase": {
+      "command": "node",
+      "args": ["/absolute/path/to/knbase/dist/mcp/server.js"],
+      "env": { "KNBASE_ROOT": "/absolute/path/to/your/project" }
+    }
+  }
+}
+```
+
+CLI (from source):
+
+```bash
+node /absolute/path/to/knbase/dist/cli/index.js init
+```
+
+### MCP tools
+
+| Tool | Description |
+| --- | --- |
+| `start_session` | **Mandatory first call.** Loads compact context, or returns bootstrap templates if docs are missing. |
+| `get_context` | Returns compact context; pass `files=[...] full=true` to fetch specific docs in full. |
+| `write_governance_file` | Create/update a doc (validates required sections, refreshes index + mind map). |
+| `begin_task` | Gate: refuses unless context was loaded this session. |
+| `complete_task` | Gate: refuses unless `memory.md` was updated for the task. |
+| `get_mindmap` | Returns the combined mermaid mind map + index. |
+| `get_status` | Session state, missing files, active task, recent log. |
+
+## CLI commands
+
+```bash
+knbase init                 # scaffold governance docs, index, mind map, AGENTS.md
+knbase status               # show session state, missing files, recent log
+knbase check                # exit 0 only if context is loaded and current
+knbase guard -- <command>   # run a command only if governance context is loaded
+knbase install-hooks        # install a git pre-commit hook that enforces updates
+knbase agents-doc           # print the AGENTS.md contract
+```
+
+## Enforcement model
+
+A stdio MCP server cannot intercept another process's file edits at the OS level,
+so enforcement is layered:
+
+1. **State machine** — MCP tools refuse out-of-order calls
+   (`UNINITIALIZED -> NEEDS_BOOTSTRAP -> CONTEXT_LOADED -> TASK_ACTIVE -> ...`).
+2. **Contract** — `init` writes an `AGENTS.md` that every agent reads by convention.
+3. **Hard gates** — the `git pre-commit` hook and `knbase guard` wrapper block
+   real actions (commits, shell commands) until governance is satisfied.
+
+## Token discipline
+
+- `start_session` / `get_context` return only the mind map, one-line summaries,
+  and current phase by default.
+- Summaries are supplied by the agent at write time, so the server makes **no LLM
+  calls** and adds no API cost.
+- The mind map is built deterministically from headings + summaries.
+- Checksums in `index.json` skip regeneration for unchanged files.
+
+## Development
+
+```bash
+npm run typecheck
+npm run dev:mcp     # run the MCP server with tsx
+npm run dev:cli -- status
+```
+
+## License
+
+MIT

package/bin/knbase

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("../dist/cli/index.js").catch((err) => {
+  console.error("[knbase] Failed to start CLI:", err);
+  process.exit(1);
+});

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Command } from "commander";
+import { appendLog, getStatus, guardDecision, hasTaskCompletedSince, initProject, openProject, } from "../core/engine.js";
+import { renderAgentsDoc } from "../core/agents-doc.js";
+import { isInitialized } from "../core/config.js";
+const program = new Command();
+program
+    .name("knbase")
+    .description("Agent-agnostic AI project governance and memory system")
+    .version("0.1.0");
+/* -------------------------------------------------------------------- init --- */
+program
+    .command("init")
+    .description("Initialize governance in the current project (scaffold docs, index, mind map, AGENTS.md)")
+    .option("-d, --docs-dir <dir>", "Directory for governance docs (default: memory-bank)")
+    .action((opts) => {
+    const result = initProject(process.cwd(), opts.docsDir);
+    const project = openProject(result.root);
+    const agentsPath = join(result.root, "AGENTS.md");
+    if (!existsSync(agentsPath)) {
+        writeFileSync(agentsPath, renderAgentsDoc(project.config), "utf8");
+    }
+    console.log(`knbase initialized at ${result.root}`);
+    console.log(`  docs dir:    ${project.config.docsDir}/`);
+    console.log(`  scaffolded:  ${result.scaffolded.join(", ") || "(none)"}`);
+    console.log(`  already set: ${result.alreadyPresent.join(", ") || "(none)"}`);
+    console.log(`  AGENTS.md:   ${existsSync(agentsPath) ? "written" : "present"}`);
+    console.log("\nNext: agents should call the `start_session` MCP tool, or run `knbase status`.");
+});
+/* ------------------------------------------------------------------ status --- */
+program
+    .command("status")
+    .description("Show governance status (session state, missing files, recent log)")
+    .action(() => {
+    const status = getStatus(openProject(process.cwd()));
+    console.log(JSON.stringify(status, null, 2));
+});
+/* ------------------------------------------------------------------- check --- */
+program
+    .command("check")
+    .description("Exit 0 only if initialized, no files missing, and a fresh session exists")
+    .action(() => {
+    const project = openProject(process.cwd());
+    const decision = guardDecision(project);
+    console.log(decision.allow ? `OK: ${decision.reason}` : `BLOCKED: ${decision.reason}`);
+    process.exit(decision.allow ? 0 : 1);
+});
+/* ------------------------------------------------------------------- guard --- */
+program
+    .command("guard")
+    .description("Run a command only if governance context is loaded and current")
+    .allowUnknownOption(true)
+    .argument("[command...]", "Command to run after `--`")
+    .action((command) => {
+    const project = openProject(process.cwd());
+    const decision = guardDecision(project);
+    if (!decision.allow) {
+        if (isInitialized(project.root)) {
+            appendLog(project.p, { event: "guard_block", detail: decision.reason });
+        }
+        console.error(`[knbase] BLOCKED: ${decision.reason}`);
+        process.exit(1);
+    }
+    if (!command || command.length === 0) {
+        console.log(`[knbase] OK: ${decision.reason} (no command supplied)`);
+        return;
+    }
+    appendLog(project.p, { event: "guard_allow", detail: command.join(" ") });
+    const [cmd, ...args] = command;
+    const child = spawn(cmd, args, { stdio: "inherit", shell: false });
+    child.on("exit", (code) => process.exit(code ?? 0));
+    child.on("error", (err) => {
+        console.error(`[knbase] Failed to run command: ${err.message}`);
+        process.exit(1);
+    });
+});
+/* ----------------------------------------------------------- install-hooks --- */
+program
+    .command("install-hooks")
+    .description("Install a git pre-commit hook that enforces governance updates")
+    .action(() => {
+    const project = openProject(process.cwd());
+    const gitDir = join(project.root, ".git");
+    if (!existsSync(gitDir)) {
+        console.error("[knbase] Not a git repository (no .git dir). Run `git init` first.");
+        process.exit(1);
+    }
+    const hookPath = join(gitDir, "hooks", "pre-commit");
+    const script = `#!/bin/sh
+# Installed by knbase. Blocks commits unless governance is satisfied.
+exec npx --no-install knbase precommit || knbase precommit
+`;
+    writeFileSync(hookPath, script, "utf8");
+    chmodSync(hookPath, 0o755);
+    console.log(`[knbase] Installed pre-commit hook at ${hookPath}`);
+});
+/* --------------------------------------------------------------- precommit --- */
+program
+    .command("precommit")
+    .description("Internal: git pre-commit gate. Exits non-zero to block the commit.")
+    .action(() => {
+    const project = openProject(process.cwd());
+    if (!isInitialized(project.root)) {
+        console.error("[knbase] pre-commit: not initialized. Run `knbase init`.");
+        process.exit(1);
+    }
+    const status = getStatus(project);
+    if (status.missing.length > 0) {
+        console.error(`[knbase] pre-commit BLOCKED: governance files missing/empty: ${status.missing.join(", ")}`);
+        process.exit(1);
+    }
+    const lastCommit = spawnSync("git", ["log", "-1", "--format=%cI"], {
+        cwd: project.root,
+        encoding: "utf8",
+    });
+    const sinceIso = lastCommit.status === 0 ? lastCommit.stdout.trim() || null : null;
+    if (!hasTaskCompletedSince(project.p, sinceIso)) {
+        console.error("[knbase] pre-commit BLOCKED: no task completed since last commit. " +
+            "Complete a task (update memory.md) via the MCP `complete_task` tool before committing.");
+        process.exit(1);
+    }
+    console.error("[knbase] pre-commit OK: governance satisfied.");
+    process.exit(0);
+});
+/* ------------------------------------------------------------ agents-doc --- */
+program
+    .command("agents-doc")
+    .description("Print the AGENTS.md governance contract for this project")
+    .action(() => {
+    const project = openProject(process.cwd());
+    const path = join(project.root, "AGENTS.md");
+    if (existsSync(path)) {
+        process.stdout.write(readFileSync(path, "utf8"));
+    }
+    else {
+        process.stdout.write(renderAgentsDoc(project.config));
+    }
+});
+program.parseAsync(process.argv);
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

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

package/dist/core/agents-doc.d.ts

@@ -0,0 +1,6 @@
+import type { KnbaseConfig } from "../types.js";
+/**
+ * Generates the AGENTS.md contract placed at the project root. Every agent reads
+ * this by convention; it is the primary "soft" enforcement layer.
+ */
+export declare function renderAgentsDoc(config: KnbaseConfig): string;

package/dist/core/agents-doc.js

@@ -0,0 +1,50 @@
+import { TEMPLATES } from "./templates.js";
+/**
+ * Generates the AGENTS.md contract placed at the project root. Every agent reads
+ * this by convention; it is the primary "soft" enforcement layer.
+ */
+export function renderAgentsDoc(config) {
+    const fileList = config.files
+        .map((k) => `- \`${config.docsDir}/${k}.md\` — ${TEMPLATES[k].purpose}`)
+        .join("\n");
+    return `# AGENTS.md — Governance Contract (managed by knbase)
+
+This project is governed by **knbase**. Any AI agent working here MUST follow
+this workflow. Do not skip steps. This exists so any agent can safely extend the
+project from existing code and design without re-deriving context.
+
+## Governance documents (${config.docsDir}/)
+
+${fileList}
+
+Plus system artifacts in \`.knbase/\` (index, mind map, activity log) — do not edit by hand.
+
+## Required workflow
+
+1. **Read before acting.** Call the \`start_session\` MCP tool first. It returns a
+   compact mind map, per-file summaries, and the current phase. Fetch a full doc
+   only when needed via \`get_context(files=[...], full=true)\` to conserve tokens.
+2. **Bootstrap if missing.** If \`start_session\` reports \`NEEDS_BOOTSTRAP\`, author
+   every missing file with \`write_governance_file\` (all required sections) based on
+   your understanding of the user's request, BEFORE doing any other work.
+3. **Gate every task.** Call \`begin_task\` before making changes and \`complete_task\`
+   after. \`begin_task\` refuses until context is loaded; \`complete_task\` refuses
+   until \`memory.md\` was updated for that task.
+4. **Update knowledge after each task.** Append what changed to \`memory.md\`
+   ("Recent Changes", "Learnings & Gotchas") and advance \`phase.md\` when relevant.
+
+## Without MCP (any agent / shell)
+
+- Initialize: \`npx knbase init\`
+- Check status / gate: \`knbase status\` or \`knbase check\`
+- Run gated commands: \`knbase guard -- <your command>\` (refuses until context is loaded)
+- A git \`pre-commit\` hook (via \`knbase install-hooks\`) blocks commits unless a task
+  was completed with a memory update.
+
+## Token discipline
+
+Prefer summaries and the mind map over full files. Only load full document content
+when a task truly requires it.
+`;
+}
+//# sourceMappingURL=agents-doc.js.map

package/dist/core/agents-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-doc.js","sourceRoot":"","sources":["../../src/core/agents-doc.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAoB;IAClD,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,MAAM,CAAC,OAAO,IAAI,CAAC,WAAW,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SACvE,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,OAAO;;;;;;2BAMkB,MAAM,CAAC,OAAO;;EAEvC,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BT,CAAC;AACF,CAAC"}

package/dist/core/config.d.ts

@@ -0,0 +1,30 @@
+import { type KnbaseConfig, type GovernanceFileKey } from "../types.js";
+/** Name of the system artifact directory. */
+export declare const SYSTEM_DIR = ".knbase";
+/** Default directory (relative to project root) for the governance docs. */
+export declare const DEFAULT_DOCS_DIR = "memory-bank";
+export declare const DEFAULT_CONFIG: KnbaseConfig;
+/**
+ * Resolves the project root. Honors the KNBASE_ROOT env var, otherwise walks
+ * up from `startDir` looking for an existing `.knbase` dir or a `.git` dir,
+ * falling back to `startDir` itself.
+ */
+export declare function resolveProjectRoot(startDir?: string): string;
+export interface ResolvedPaths {
+    root: string;
+    systemDir: string;
+    configPath: string;
+    indexPath: string;
+    mindmapPath: string;
+    logPath: string;
+    sessionPath: string;
+    docsDir: string;
+    /** Absolute path for a given governance file key. */
+    docPath: (key: GovernanceFileKey) => string;
+}
+export declare function paths(root: string, config: KnbaseConfig): ResolvedPaths;
+export declare function loadConfig(root: string): KnbaseConfig;
+export declare function saveConfig(root: string, config: KnbaseConfig): void;
+export declare function ensureDir(dir: string): void;
+/** Whether knbase has been initialized in the given root. */
+export declare function isInitialized(root: string): boolean;

package/dist/core/config.js

@@ -0,0 +1,89 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { GOVERNANCE_FILES, } from "../types.js";
+/** Name of the system artifact directory. */
+export const SYSTEM_DIR = ".knbase";
+/** Default directory (relative to project root) for the governance docs. */
+export const DEFAULT_DOCS_DIR = "memory-bank";
+const CONFIG_VERSION = 1;
+export const DEFAULT_CONFIG = {
+    version: CONFIG_VERSION,
+    docsDir: DEFAULT_DOCS_DIR,
+    files: [...GOVERNANCE_FILES],
+    sessionTtlMinutes: 120,
+};
+/**
+ * Resolves the project root. Honors the KNBASE_ROOT env var, otherwise walks
+ * up from `startDir` looking for an existing `.knbase` dir or a `.git` dir,
+ * falling back to `startDir` itself.
+ */
+export function resolveProjectRoot(startDir = process.cwd()) {
+    const envRoot = process.env.KNBASE_ROOT;
+    if (envRoot && envRoot.trim()) {
+        return resolve(envRoot.trim());
+    }
+    let current = resolve(startDir);
+    // Walk upward until filesystem root.
+    // Prefer an existing .knbase dir; otherwise use the nearest .git.
+    let gitFallback = null;
+    while (true) {
+        if (existsSync(join(current, SYSTEM_DIR)))
+            return current;
+        if (!gitFallback && existsSync(join(current, ".git")))
+            gitFallback = current;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return gitFallback ?? resolve(startDir);
+}
+export function paths(root, config) {
+    const systemDir = join(root, SYSTEM_DIR);
+    const docsDir = isAbsolute(config.docsDir)
+        ? config.docsDir
+        : join(root, config.docsDir);
+    return {
+        root,
+        systemDir,
+        configPath: join(systemDir, "config.json"),
+        indexPath: join(systemDir, "index.json"),
+        mindmapPath: join(systemDir, "mindmap.md"),
+        logPath: join(systemDir, "activity.log"),
+        sessionPath: join(systemDir, "session.json"),
+        docsDir,
+        docPath: (key) => join(docsDir, `${key}.md`),
+    };
+}
+export function loadConfig(root) {
+    const configPath = join(root, SYSTEM_DIR, "config.json");
+    if (!existsSync(configPath))
+        return { ...DEFAULT_CONFIG };
+    try {
+        const raw = JSON.parse(readFileSync(configPath, "utf8"));
+        return {
+            ...DEFAULT_CONFIG,
+            ...raw,
+            files: Array.isArray(raw.files) && raw.files.length > 0
+                ? raw.files
+                : DEFAULT_CONFIG.files,
+        };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+export function saveConfig(root, config) {
+    const configPath = join(root, SYSTEM_DIR, "config.json");
+    ensureDir(dirname(configPath));
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+export function ensureDir(dir) {
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+/** Whether knbase has been initialized in the given root. */
+export function isInitialized(root) {
+    return existsSync(join(root, SYSTEM_DIR, "config.json"));
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

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

package/dist/core/engine.d.ts

@@ -0,0 +1,101 @@
+import { type ResolvedPaths } from "./config.js";
+import { appendLog, hasTaskCompletedSince, readLog } from "./log.js";
+import { clearSession, loadSession } from "./session.js";
+import type { KnbaseConfig, GovernanceFileKey, SessionData } from "../types.js";
+export interface Project {
+    root: string;
+    config: KnbaseConfig;
+    p: ResolvedPaths;
+}
+/** Open a project handle (does not create anything). */
+export declare function openProject(startDir?: string): Project;
+export declare function isKnownFile(config: KnbaseConfig, key: string): key is GovernanceFileKey;
+export interface InitResult {
+    root: string;
+    createdConfig: boolean;
+    scaffolded: GovernanceFileKey[];
+    alreadyPresent: GovernanceFileKey[];
+}
+/**
+ * Initialize knbase in a project: create `.knbase/`, write config, scaffold
+ * any missing governance docs with templates, build index + mindmap.
+ */
+export declare function initProject(startDir?: string, docsDir?: string): InitResult;
+export interface StartSessionResult {
+    sessionId: string;
+    state: SessionData["state"];
+    needsBootstrap: boolean;
+    missing: GovernanceFileKey[];
+    instructions: string;
+    compactContext?: CompactContext;
+    bootstrapTemplates?: {
+        key: GovernanceFileKey;
+        requiredSections: string[];
+    }[];
+}
+export interface CompactContext {
+    currentPhase: string;
+    mindmap: string;
+    files: {
+        key: GovernanceFileKey;
+        exists: boolean;
+        summary: string;
+        headings: string[];
+        bytes: number;
+        updatedAt: string | null;
+    }[];
+}
+export declare function startSession(project: Project): StartSessionResult;
+export interface GetContextResult {
+    compact: CompactContext;
+    fullContents?: {
+        key: GovernanceFileKey;
+        content: string;
+    }[];
+}
+export declare function getContext(project: Project, files?: string[], full?: boolean): GetContextResult;
+export interface WriteResult {
+    key: GovernanceFileKey;
+    bytes: number;
+    ok: boolean;
+    missingSections: string[];
+    remainingBootstrap: GovernanceFileKey[];
+    state: SessionData["state"];
+}
+export declare function writeGovernanceFile(project: Project, key: string, content: string, summary: string): WriteResult;
+export interface BeginTaskResult {
+    ok: boolean;
+    taskId?: string;
+    error?: string;
+    reminder?: string;
+}
+export declare function beginTask(project: Project, description: string): BeginTaskResult;
+export interface CompleteTaskResult {
+    ok: boolean;
+    error?: string;
+    updatedFiles?: GovernanceFileKey[];
+    state?: SessionData["state"];
+}
+export declare function completeTask(project: Project, taskId: string, summary: string): CompleteTaskResult;
+export interface StatusResult {
+    initialized: boolean;
+    root: string;
+    docsDir: string;
+    state: SessionData["state"];
+    sessionFresh: boolean;
+    missing: GovernanceFileKey[];
+    activeTask: SessionData["activeTask"];
+    recentLog: ReturnType<typeof readLog>;
+}
+export declare function getStatus(project: Project): StatusResult;
+export interface GuardDecision {
+    allow: boolean;
+    reason: string;
+}
+/**
+ * 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 declare function guardDecision(project: Project): GuardDecision;
+export { appendLog, clearSession, hasTaskCompletedSince, loadSession, readLog, };