@a-t-h-i/bot-lobby 0.1.0

package/src/execution/pi-runner.ts

@@ -0,0 +1,292 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { activityWord } from "../pi/activity.ts";
+
+export interface PiRunOptions {
+  cwd: string;
+  task: string;
+  systemPrompt?: string;
+  tools?: readonly string[];
+  model?: string;
+  thinking?: string;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  /** Reports the current one-word tool activity while the agent works. */
+  onActivity?: (activity: string) => void;
+}
+
+export interface ProcessOutcome {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  killed: boolean;
+  timedOut: boolean;
+}
+
+/** Streaming agent events forwarded as they arrive on stdout. */
+export interface PiStreamEvent {
+  type: "tool_execution_start";
+  toolName: string;
+}
+
+export interface ProcessRunOptions {
+  cwd: string;
+  signal?: AbortSignal;
+  timeoutMs: number;
+  /** Optional sink for streaming agent events (tool starts). */
+  onEvent?: (event: PiStreamEvent) => void;
+}
+
+export type ProcessRunner = (
+  args: string[],
+  options: ProcessRunOptions,
+) => Promise<ProcessOutcome>;
+
+export interface PiRunResult {
+  status: "success" | "failed" | "cancelled" | "timeout";
+  output: string;
+  error?: string;
+  usage: { input: number; output: number; cost: number; turns: number };
+  model?: string;
+}
+
+export interface ParsedStream {
+  text: string;
+  usage: { input: number; output: number; cost: number; turns: number };
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+const MAX_STREAM_CHARS = 5_000_000;
+
+/** Buffers one JSON-mode stream, keeping only lines parsePiStream consumes. */
+export interface StreamCollector {
+  push(chunk: string): void;
+  finish(): string;
+}
+
+/**
+ * Buffers one JSON-mode stream, keeping only lines parsePiStream consumes and
+ * forwarding tool-start events to an optional sink. Keeping only assistant
+ * `message_end` events means a tool-heavy run cannot exhaust memory or
+ * truncate the final report. Events split across chunk boundaries are
+ * reassembled; malformed lines are ignored exactly as parsePiStream ignores
+ * them.
+ */
+export function createStreamCollector(onEvent?: (event: PiStreamEvent) => void): StreamCollector {
+  let pending = "";
+  const kept: string[] = [];
+  const keep = (line: string) => {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(line);
+    } catch {
+      return; // Malformed lines never parse; drop them.
+    }
+    if (raw === null || typeof raw !== "object") return;
+    const event = raw as { type?: string; toolName?: string; message?: { role?: string } };
+    if (event.type === "tool_execution_start" && typeof event.toolName === "string") {
+      onEvent?.({ type: "tool_execution_start", toolName: event.toolName });
+    }
+    if (event.type === "message_end" && event.message?.role === "assistant") kept.push(line);
+  };
+  return {
+    push(chunk) {
+      pending += chunk;
+      const lines = pending.split("\n");
+      pending = lines.pop() ?? "";
+      for (const line of lines) keep(line);
+    },
+    finish() {
+      if (pending) keep(pending);
+      pending = "";
+      return kept.join("\n");
+    },
+  };
+}
+
+/** Build the `pi` argv for one isolated, non-interactive agent run. */
+export function buildPiArgs(options: PiRunOptions & { systemPromptFile?: string }): string[] {
+  const args = ["--mode", "json", "-p", "--no-session"];
+  if (options.model && options.model !== "inherit") args.push("--model", options.model);
+  if (options.thinking) args.push("--thinking", options.thinking);
+  if (options.tools && options.tools.length > 0) args.push("--tools", options.tools.join(","));
+  if (options.systemPromptFile) args.push("--append-system-prompt", options.systemPromptFile);
+  args.push(`Task: ${options.task}`);
+  return args;
+}
+
+interface MessageLike {
+  role?: string;
+  content?: unknown;
+  usage?: { input?: number; output?: number; cost?: { total?: number } };
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+function messageText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((part): part is { type: string; text: string } =>
+      typeof part === "object" && part !== null && (part as { type?: string }).type === "text",
+    )
+    .map((part) => part.text)
+    .join("");
+}
+
+/** Parse the JSON-mode stream defensively; malformed lines are ignored. */
+export function parsePiStream(stdout: string): ParsedStream {
+  const parsed: ParsedStream = { text: "", usage: { input: 0, output: 0, cost: 0, turns: 0 } };
+  for (const line of stdout.split("\n")) {
+    let event: { type?: string; message?: MessageLike };
+    try {
+      event = JSON.parse(line) as typeof event;
+    } catch {
+      continue;
+    }
+    if (event?.type !== "message_end" || event.message?.role !== "assistant") continue;
+    const message = event.message;
+    parsed.usage.turns += 1;
+    parsed.usage.input += message.usage?.input ?? 0;
+    parsed.usage.output += message.usage?.output ?? 0;
+    parsed.usage.cost += message.usage?.cost?.total ?? 0;
+    if (message.model) parsed.model = message.model;
+    if (message.stopReason) parsed.stopReason = message.stopReason;
+    if (message.errorMessage) parsed.errorMessage = message.errorMessage;
+    const text = messageText(message.content);
+    if (text.trim()) parsed.text = text;
+  }
+  return parsed;
+}
+
+/**
+ * Prefer the pi launcher that started this session so subagents use the same
+ * build; otherwise fall back to `pi` on PATH (or BOT_LOBBY_PI_BIN). We match
+ * on the launcher filename, not PI_SESSION_ID: that variable is inherited by
+ * every child process, including test runners and scripts, where argv[1] is
+ * not pi at all.
+ */
+function resolvePiInvocation(args: string[]): { command: string; args: string[] } {
+  const launcher = process.argv[1];
+  if (launcher && existsSync(launcher) && isPiLauncher(launcher)) {
+    return { command: launcher, args };
+  }
+  return { command: process.env.BOT_LOBBY_PI_BIN ?? "pi", args };
+}
+
+/** Exported for tests: mis-detecting a non-pi script re-runs it as an agent. */
+export function isPiLauncher(script: string): boolean {
+  const base = basename(script);
+  return base === "pi" || base === "pi.js" || script.includes("pi-coding-agent");
+}
+
+function terminate(proc: ChildProcess): void {
+  proc.kill("SIGTERM");
+  const escalation = setTimeout(() => {
+    if (proc.exitCode === null) proc.kill("SIGKILL");
+  }, 5000);
+  escalation.unref();
+}
+
+function wireOutput(
+  proc: ChildProcess,
+  buffers: { stdout: string; stderr: string },
+  onEvent?: (event: PiStreamEvent) => void,
+): () => void {
+  const collector = createStreamCollector(onEvent);
+  proc.stdout?.on("data", (chunk: Buffer) => collector.push(chunk.toString()));
+  proc.stderr?.on("data", (chunk: Buffer) => {
+    // Keep stderr head-bounded: it only feeds exit-code error messages.
+    if (buffers.stderr.length < MAX_STREAM_CHARS) buffers.stderr += chunk.toString();
+  });
+  return () => {
+    buffers.stdout = collector.finish();
+  };
+}
+
+/** Default runner: spawn the same pi binary in JSON mode and collect output. */
+export function spawnPiProcess(args: string[], options: ProcessRunOptions): Promise<ProcessOutcome> {
+  return new Promise((resolve) => {
+    const invocation = resolvePiInvocation(args);
+    const proc = spawn(invocation.command, invocation.args, {
+      cwd: options.cwd,
+      // Marks subagent processes so bot-lobby skips master-only quiet wiring.
+      env: { ...process.env, BOT_LOBBY_SUBAGENT: "1" },
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const buffers = { stdout: "", stderr: "" };
+    const state = { killed: false, timedOut: false };
+    const flush = wireOutput(proc, buffers, options.onEvent);
+
+    const finish = (exitCode: number) => {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      flush();
+      resolve({ exitCode, ...buffers, ...state });
+    };
+    const onAbort = () => {
+      state.killed = true;
+      terminate(proc);
+    };
+    const timer = setTimeout(() => {
+      state.killed = true;
+      state.timedOut = true;
+      terminate(proc);
+    }, options.timeoutMs);
+
+    proc.on("close", (code) => finish(code ?? 0));
+    proc.on("error", (error: Error) => {
+      buffers.stderr += error.message;
+      finish(1);
+    });
+    if (options.signal?.aborted) onAbort();
+    else options.signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function toResult(parsed: ParsedStream, outcome: ProcessOutcome, aborted: boolean): PiRunResult {
+  const base = { output: parsed.text, usage: parsed.usage, model: parsed.model };
+  if (outcome.timedOut) return { ...base, status: "timeout", error: "agent timed out" };
+  if (outcome.killed || aborted || parsed.stopReason === "aborted") {
+    return { ...base, status: "cancelled", error: "agent was cancelled" };
+  }
+  if (outcome.exitCode !== 0) {
+    const detail = parsed.errorMessage ?? outcome.stderr.trim();
+    return { ...base, status: "failed", error: detail || `pi exited with code ${outcome.exitCode}` };
+  }
+  if (parsed.stopReason === "error") {
+    return { ...base, status: "failed", error: parsed.errorMessage ?? "agent reported an error" };
+  }
+  if (!parsed.text.trim()) return { ...base, status: "failed", error: "agent produced no usable output" };
+  return { ...base, status: "success" };
+}
+
+function writePromptFile(prompt: string): { file: string; cleanup: () => void } {
+  const dir = mkdtempSync(join(tmpdir(), "bot-lobby-prompt-"));
+  const file = join(dir, "system.md");
+  writeFileSync(file, prompt, { encoding: "utf8", mode: 0o600 });
+  return { file, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+/** Run one isolated subagent and normalise its outcome. */
+export async function runPiAgent(options: PiRunOptions, run: ProcessRunner = spawnPiProcess): Promise<PiRunResult> {
+  const prompt = options.systemPrompt ? writePromptFile(options.systemPrompt) : undefined;
+  try {
+    const args = buildPiArgs({ ...options, systemPromptFile: prompt?.file });
+    const outcome = await run(args, {
+      cwd: options.cwd,
+      signal: options.signal,
+      timeoutMs: options.timeoutMs,
+      onEvent: (event) => options.onActivity?.(activityWord(event.toolName)),
+    });
+    return toResult(parsePiStream(outcome.stdout), outcome, options.signal?.aborted === true);
+  } finally {
+    prompt?.cleanup();
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerCommands } from "./pi/commands.ts";
+import { registerLifecycle } from "./pi/events.ts";
+import { registerOrchestrateTool } from "./pi/tools.ts";
+import { onTransition } from "./state/task-state.ts";
+import { ping } from "./pi/notify.ts";
+
+export default function (pi: ExtensionAPI): void {
+  registerLifecycle(pi, CONFIG_DIR_NAME);
+  onTransition((task) => ping(task.state, task.title));
+  registerCommands(pi, CONFIG_DIR_NAME);
+  registerOrchestrateTool(pi, CONFIG_DIR_NAME);
+}

package/src/knowledge/compactor.ts

@@ -0,0 +1,135 @@
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import type { KnowledgeAgent } from "./paths.ts";
+import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, knowledgeDir } from "./paths.ts";
+import { readFirstExisting, readFileOr, writeFileEnsured } from "./store.ts";
+
+export interface KnowledgeAnalysis {
+  /** Lines that say the same thing twice. */
+  duplicates: string[];
+  /** Lines with hedging or unresolved wording. */
+  ambiguity: string[];
+  /** Different statements sharing a subject: candidates for conflict review. */
+  conflictCandidates: { subject: string; statements: string[] }[];
+}
+
+const AMBIGUITY = /\bmaybe|possibly|probably|tbd|todo|unclear|not sure|some kind|etc\.|approximately\b/i;
+const HEDGE_STOPWORDS = new Set(["this", "that", "with", "from", "into", "when", "they", "have", "will", "should", "must"]);
+
+function significantLines(content: string, minLength = 12): string[] {
+  return content
+    .split("\n")
+    .map((line) => line.replace(/^[-*#>\s]+/, "").trim())
+    .filter((line) => line.length >= minLength);
+}
+
+function normalize(line: string): string {
+  return line
+    .toLowerCase()
+    .replace(/[^\w\s]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function subjectKey(line: string): string {
+  return normalize(line)
+    .split(" ")
+    .filter((word) => word.length > 3 && !HEDGE_STOPWORDS.has(word))
+    .slice(0, 2)
+    .join(" ");
+}
+
+function findDuplicates(lines: string[]): string[] {
+  const seen = new Map<string, string>();
+  const duplicates: string[] = [];
+  for (const line of lines) {
+    const key = normalize(line);
+    if (seen.has(key)) duplicates.push(line);
+    else seen.set(key, line);
+  }
+  return duplicates;
+}
+
+function findConflicts(lines: string[]): { subject: string; statements: string[] }[] {
+  const groups = new Map<string, Set<string>>();
+  for (const line of lines) {
+    const key = subjectKey(line);
+    if (key.split(" ").length < 2) continue;
+    const statements = groups.get(key) ?? new Set<string>();
+    statements.add(line);
+    groups.set(key, statements);
+  }
+  return [...groups.entries()]
+    .filter(([, statements]) => statements.size > 1)
+    .map(([subject, statements]) => ({ subject, statements: [...statements] }));
+}
+
+/** Mechanical candidates that help the Master decide what to compact (§24). */
+export function analyzeKnowledge(content: string): KnowledgeAnalysis {
+  const lines = significantLines(content);
+  return {
+    duplicates: findDuplicates(lines),
+    ambiguity: lines.filter((line) => AMBIGUITY.test(line)),
+    conflictCandidates: findConflicts(lines),
+  };
+}
+
+export interface OversizedFile {
+  agent: KnowledgeAgent;
+  file: string;
+  chars: number;
+}
+
+/** Knowledge files past the configured compaction threshold, sized from the merged read roots. */
+export function overThreshold(roots: readonly string[], threshold: number): OversizedFile[] {
+  const oversized: OversizedFile[] = [];
+  for (const agent of Object.keys(AGENT_DIR_NAMES) as KnowledgeAgent[]) {
+    for (const file of KNOWLEDGE_FILES[agent]) {
+      const paths = roots.map((root) => join(knowledgeDir(root, agent), file));
+      const chars = readFirstExisting(paths).length;
+      if (chars > threshold) oversized.push({ agent, file, chars });
+    }
+  }
+  return oversized.sort((a, b) => b.chars - a.chars);
+}
+
+function archiveDir(dataRoot: string, agent: KnowledgeAgent): string {
+  return join(dataRoot, "archive", AGENT_DIR_NAMES[agent]);
+}
+
+function pruneArchives(dir: string, file: string, keep: number): void {
+  const prefix = `${file}.`;
+  const backups = readdirSync(dir)
+    .filter((entry) => entry.startsWith(prefix) && entry.endsWith(".bak"))
+    .sort();
+  for (const stale of backups.slice(0, Math.max(0, backups.length - keep))) {
+    rmSync(join(dir, stale), { force: true });
+  }
+}
+
+/**
+ * §24: archive the current file outside the retrieval paths, then replace it
+ * with the compacted version the Master approved.
+ */
+export function compactKnowledgeFile(entry: {
+  dataRoot: string;
+  agent: KnowledgeAgent;
+  file: string;
+  content: string;
+  backupCount: number;
+  now?: Date;
+}): { archive: string; before: number; after: number } {
+  if (!KNOWLEDGE_FILES[entry.agent].includes(entry.file)) {
+    throw new Error(`"${entry.file}" is not a knowledge file for ${entry.agent}`);
+  }
+  const path = join(knowledgeDir(entry.dataRoot, entry.agent), entry.file);
+  const previous = readFileOr(path);
+  const dir = archiveDir(entry.dataRoot, entry.agent);
+  mkdirSync(dir, { recursive: true });
+  const stamp = (entry.now ?? new Date()).toISOString().replace(/[:.]/g, "-");
+  const archive = join(dir, `${basename(entry.file)}.${stamp}.bak`);
+  writeFileSync(archive, previous, "utf8");
+  writeFileEnsured(path, `${entry.content.trim()}\n`);
+  pruneArchives(dir, entry.file, Math.max(1, entry.backupCount));
+  return { archive, before: previous.length, after: entry.content.trim().length };
+}

package/src/knowledge/paths.ts

@@ -0,0 +1,43 @@
+import { join } from "node:path";
+import type { Domain } from "../schemas/agent.ts";
+
+export type KnowledgeAgent = Domain | "master";
+
+/** Title-cased directory names per the build plan §21. */
+export const AGENT_DIR_NAMES: Record<KnowledgeAgent, string> = {
+  master: "Master",
+  designer: "Designer",
+  backend: "Backend",
+  qa: "QA",
+};
+
+/** Domain-specific standards file per agent (§21). */
+export const STANDARDS_FILE: Record<KnowledgeAgent, string> = {
+  master: "standards.md",
+  designer: "design-language.md",
+  backend: "engineering-standards.md",
+  qa: "testing-standards.md",
+};
+
+export const KNOWLEDGE_FILES: Record<KnowledgeAgent, readonly string[]> = {
+  master: ["knowledge.md", STANDARDS_FILE.master, "decisions.md", "completed-tasks.md"],
+  designer: ["knowledge.md", STANDARDS_FILE.designer, "decisions.md", "completed-tasks.md"],
+  backend: ["knowledge.md", STANDARDS_FILE.backend, "decisions.md", "completed-tasks.md"],
+  qa: ["knowledge.md", STANDARDS_FILE.qa, "decisions.md", "completed-tasks.md"],
+};
+
+export function knowledgeDir(dataRoot: string, agent: KnowledgeAgent): string {
+  return join(dataRoot, AGENT_DIR_NAMES[agent], "knowledge");
+}
+
+export function tasksRoot(dataRoot: string): string {
+  return join(dataRoot, "tasks");
+}
+
+export function taskDir(dataRoot: string, taskId: string): string {
+  return join(tasksRoot(dataRoot), taskId);
+}
+
+export function scratchpadPath(taskDir: string, domain: Domain): string {
+  return join(taskDir, `${domain}.md`);
+}

package/src/knowledge/selector.ts

@@ -0,0 +1,82 @@
+const STOPWORDS = new Set([
+  "the", "and", "for", "with", "that", "this", "from", "into", "when", "then",
+  "than", "over", "under", "should", "must", "will", "not", "are", "was",
+  "has", "have", "its", "a", "an", "of", "to", "in", "on", "or", "is", "be",
+  "as", "by", "at", "it", "we", "you", "our", "use",
+]);
+
+export interface KnowledgeSelection {
+  knowledge: string;
+  standards: string;
+  decisions: string;
+}
+
+export interface KnowledgeInput {
+  knowledge?: string;
+  standards?: string;
+  decisions?: string;
+}
+
+export function tokenize(text: string): string[] {
+  return [
+    ...new Set(
+      text
+        .toLowerCase()
+        .split(/[^a-z0-9_.-]+/)
+        .filter((token) => token.length >= 4 && !STOPWORDS.has(token)),
+    ),
+  ];
+}
+
+/** Split markdown into heading-anchored sections, keeping the preamble. */
+export function splitSections(markdown: string): string[] {
+  return markdown
+    .split(/\n(?=#{1,3}\s)/)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+function score(sectionText: string, tokens: string[]): number {
+  const lower = sectionText.toLowerCase();
+  return tokens.reduce((total, token) => total + (lower.includes(token) ? 1 : 0), 0);
+}
+
+function takeWithin(parts: string[], budgetChars: number): string {
+  const kept: string[] = [];
+  let used = 0;
+  for (const part of parts) {
+    if (used + part.length > budgetChars) break;
+    kept.push(part);
+    used += part.length + 2;
+  }
+  return kept.join("\n\n").trim();
+}
+
+/**
+ * Keep the whole file when it fits; otherwise return the sections most
+ * relevant to the task, bounded by the budget.
+ */
+export function selectRelevant(query: string, content: string, budgetChars: number): string {
+  const trimmed = content.trim();
+  if (trimmed.length <= budgetChars) return trimmed;
+  const tokens = tokenize(query);
+  const ranked = splitSections(trimmed)
+    .map((text) => ({ text, score: score(text, tokens) }))
+    .sort((a, b) => b.score - a.score);
+  const relevant = ranked.filter((entry) => entry.score > 0);
+  const chosen = relevant.length > 0 ? relevant : ranked;
+  return takeWithin(chosen.map((entry) => entry.text), budgetChars);
+}
+
+/** Select the relevant slice of each knowledge file for this task. */
+export function selectKnowledge(
+  task: string,
+  files: KnowledgeInput,
+  budgetChars = 4000,
+): KnowledgeSelection {
+  return {
+    knowledge: selectRelevant(task, files.knowledge ?? "", budgetChars),
+    standards: selectRelevant(task, files.standards ?? "", budgetChars),
+    decisions: selectRelevant(task, files.decisions ?? "", budgetChars),
+  };
+}

package/src/knowledge/store.ts

@@ -0,0 +1,111 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { knowledgeDir, STANDARDS_FILE, type KnowledgeAgent } from "./paths.ts";
+
+export function readFileOr(path: string, fallback = ""): string {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return fallback;
+  }
+}
+
+/** First existing file among `paths`, in order; merged legacy reads use it per file. */
+export function readFirstExisting(paths: readonly string[], fallback = ""): string {
+  for (const path of paths) if (existsSync(path)) return readFileOr(path, fallback);
+  return fallback;
+}
+
+export function writeFileEnsured(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+}
+
+/** Seed content for freshly created knowledge files (§21). */
+export const DEFAULT_KNOWLEDGE_CONTENT: Record<string, string> = {
+  "knowledge.md": "# Knowledge\n\nStable facts and useful patterns for this project.\n",
+  "standards.md": "# Standards\n\nUniversal project rules.\n",
+  "decisions.md": "# Decisions\n\nSignificant decisions and their rationale.\n",
+  "completed-tasks.md": "# Completed Tasks\n\nShort operational history.\n",
+  "design-language.md": "# Design Language\n\nVisual language, accessibility, and frontend conventions.\n",
+  "engineering-standards.md": "# Engineering Standards\n\nBackend, API, and security standards.\n",
+  "testing-standards.md": "# Testing Standards\n\nTesting conventions and definition of done.\n",
+};
+
+export function ensureFile(path: string, content: string): void {
+  if (!existsSync(path)) writeFileEnsured(path, content);
+}
+
+/** Append a line under a date heading, creating the heading when needed. */
+function appendDatedEntry(path: string, line: string, now: Date): void {
+  const date = now.toISOString().slice(0, 10);
+  const header = `# ${date}`;
+  const body = readFileOr(path, "").trimEnd();
+  const updated = body.includes(header) ? `${body}\n${line}` : `${body}\n\n${header}\n\n${line}`;
+  writeFileEnsured(path, `${updated.trimStart()}\n`);
+}
+
+/** Append one operational-history line to an agent's completed-tasks log. */
+export function appendCompletedTask(dir: string, text: string, now = new Date()): void {
+  appendDatedEntry(join(dir, "completed-tasks.md"), `- [x] ${text}`, now);
+}
+
+/** Append one decision to an agent's decisions log. */
+export function appendDecision(dir: string, text: string, now = new Date()): void {
+  appendDatedEntry(join(dir, "decisions.md"), `- ${text}`, now);
+}
+
+export type KnowledgeKind = "knowledge" | "standard" | "decision" | "completed";
+
+/** The persistent file a knowledge kind belongs to for one agent (§21). */
+export function knowledgeFilePath(dataRoot: string, agent: KnowledgeAgent, kind: KnowledgeKind): string {
+  const dir = knowledgeDir(dataRoot, agent);
+  if (kind === "knowledge") return join(dir, "knowledge.md");
+  if (kind === "standard") return join(dir, STANDARDS_FILE[agent]);
+  if (kind === "decision") return join(dir, "decisions.md");
+  return join(dir, "completed-tasks.md");
+}
+
+export interface KnowledgeEntry {
+  dataRoot: string;
+  agent: KnowledgeAgent;
+  kind: KnowledgeKind;
+  text: string;
+  now?: Date;
+}
+
+/**
+ * The only write path into persistent knowledge. Deduplicates before writing,
+ * so re-accepting the same insight cannot bloat the file.
+ */
+export function applyKnowledge(entry: KnowledgeEntry): { path: string; result: "added" | "duplicate" | "empty" } {
+  const text = entry.text.trim();
+  if (!text) return { path: "", result: "empty" };
+  const path = knowledgeFilePath(entry.dataRoot, entry.agent, entry.kind);
+  const existing = readFileOr(path);
+  if (existing.toLowerCase().includes(text.toLowerCase())) return { path, result: "duplicate" };
+  const now = entry.now ?? new Date();
+  if (entry.kind === "decision") appendDecision(dirname(path), text, now);
+  else if (entry.kind === "completed") appendCompletedTask(dirname(path), text, now);
+  else writeFileEnsured(path, `${existing.trimEnd()}\n\n${text}\n`);
+  return { path, result: "added" };
+}
+
+/** Read an agent's knowledge slices for prompt context selection (§23). */
+export function readKnowledgeSlices(
+  dirs: readonly string[],
+  standardsFile: string,
+): { knowledge: string; standards: string; decisions: string; completed: string } {
+  const file = (name: string) => readFirstExisting(dirs.map((dir) => join(dir, name)));
+  return {
+    knowledge: file("knowledge.md"),
+    standards: file(standardsFile),
+    decisions: file("decisions.md"),
+    completed: file("completed-tasks.md"),
+  };
+}
+
+/** Read an agent's knowledge by agent key; bot-lobby dirs win per file over the pre-rename ones. */
+export function readAgentKnowledge(roots: readonly string[], agent: KnowledgeAgent) {
+  return readKnowledgeSlices(roots.map((root) => knowledgeDir(root, agent)), STANDARDS_FILE[agent]);
+}