@taicho-ai/framework 0.1.0

package/src/store/teams.ts

@@ -0,0 +1,227 @@
+/** Plan 19: team store. teams/<id>/team.md is canon — YAML frontmatter + a markdown charter body,
+ *  exactly like agents/<id>/agent.md.
+ *
+ *  There is NO teams table. A squad has a handful of teams, so a directory scan IS the whole query
+ *  surface (the same call made for schedules.ts). Membership lives on the AGENT — `team: <id>` in
+ *  agent.md — and is queried through the registry's `team` column, which is where the index earns its
+ *  keep. Nothing about a team is stored in two places.
+ *
+ *  Teams are captain-owned: created by `taicho team add` / `/teams`, never by a model. A team grants
+ *  capability to its members (TeamTools.grant), so a model that could mint teams could escalate its own
+ *  privileges. This is why there is no create_team tool, and why grant may name privileged tools. */
+import { YAML } from "bun";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync } from "node:fs";
+import type { Database } from "bun:sqlite";
+import { TeamDef, DEFAULT_TEAM_ID } from "@taicho-ai/contracts/team";
+import { paths } from "./files";
+import { DEFAULT_WORKER_TOOLS, loadAgent, setAgentTeams } from "./roster";
+import { log } from "../core/logger";
+
+const FRONTMATTER = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+
+export function serializeTeam(t: TeamDef): string {
+  const { charterBody, ...meta } = t;
+  return `---\n${YAML.stringify(meta, null, 2)}\n---\n${charterBody}\n`;
+}
+
+export function parseTeam(text: string): TeamDef {
+  const m = FRONTMATTER.exec(text);
+  if (!m) throw new Error("team.md is missing YAML frontmatter");
+  const meta = YAML.parse(m[1]) as Record<string, unknown>;
+  const team = TeamDef.parse({ ...meta, charterBody: m[2].trim() });
+  assertPolicyRespectsFloor(team);
+  return team;
+}
+
+/** Plan 14's floor is not a team's to punch through. A worker must ALWAYS be able to produce an artifact
+ *  and hand it off by reference; a team that denies `write_artifact` would mint exactly the toolless
+ *  worker `reconcileWorkerTools` exists to rescue. Reject at LOAD, naming the offending tool — a silent
+ *  drop here would be invisible until a member failed to save its work. */
+export function assertPolicyRespectsFloor(team: TeamDef): void {
+  const punched = team.tools.deny.filter((t) => DEFAULT_WORKER_TOOLS.includes(t));
+  if (punched.length)
+    throw new Error(
+      `team "${team.id}" denies ${punched.join(", ")}, which every worker must keep ` +
+        `(the artifact baseline: ${DEFAULT_WORKER_TOOLS.join(", ")}). Remove it from tools.deny.`,
+    );
+}
+
+export function teamExists(ws: string, id: string): boolean {
+  return existsSync(paths.teamFile(ws, id));
+}
+
+export function loadTeam(ws: string, id: string): TeamDef | null {
+  const file = paths.teamFile(ws, id);
+  if (!existsSync(file)) return null;
+  return parseTeam(readFileSync(file, "utf8"));
+}
+
+/** Every team on the squad. A bad team.md is SKIPPED with a warning rather than killing boot — one
+ *  malformed file must not take the whole squad down. */
+export function listTeams(ws: string): TeamDef[] {
+  const dir = paths.teamsDir(ws);
+  if (!existsSync(dir)) return [];
+  const out: TeamDef[] = [];
+  for (const id of readdirSync(dir)) {
+    const file = paths.teamFile(ws, id);
+    if (!existsSync(file)) continue;
+    try { out.push(parseTeam(readFileSync(file, "utf8"))); }
+    catch (e) { log.warn(`skipping team ${id}`, e); }
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function writeTeam(ws: string, team: TeamDef): void {
+  assertPolicyRespectsFloor(team);
+  mkdirSync(paths.teamDir(ws, team.id), { recursive: true });
+  writeFileSync(paths.teamFile(ws, team.id), serializeTeam(team));
+}
+
+export interface NewTeamDraft {
+  id: string;
+  charter: string;
+  lead?: string;
+  tools?: { grant?: string[]; deny?: string[] };
+  charterBody?: string;
+}
+
+/** Agent ids and team ids share ONE namespace, so `delegate_task(to: "news")` is never ambiguous and
+ *  needs no prefix at the call site. The mirror-image guard lives in roster.createAgent, which checks
+ *  paths.teamFile directly rather than importing this module — teams.ts already depends on roster.ts
+ *  for DEFAULT_WORKER_TOOLS, and a cycle here would be gratuitous. */
+export function assertTeamIdFree(ws: string, id: string): void {
+  if (existsSync(paths.agentFile(ws, id)))
+    throw new Error(`cannot create team "${id}": an agent already has that id (ids are one namespace)`);
+}
+
+export function createTeam(ws: string, draft: NewTeamDraft): TeamDef {
+  if (teamExists(ws, draft.id)) throw new Error(`team "${draft.id}" already exists`);
+  assertTeamIdFree(ws, draft.id);
+  const team = TeamDef.parse({
+    id: draft.id,
+    charter: draft.charter,
+    lead: draft.lead,
+    tools: draft.tools ?? {},
+    charterBody: draft.charterBody ?? "",
+    created: new Date().toISOString(),
+  });
+  writeTeam(ws, team);
+  return team;
+}
+
+/** Plan 22: seed the universal `default` team if it does not exist. Every agent belongs to it (the
+ *  membership is implicit — effectiveTeams adds it — so no agent.md is touched), root leads it, and it
+ *  cannot be deleted (deleteTeam guards the id). Idempotent: a squad that already has the file, or one a
+ *  captain has customised, is left alone. Runs on boot next to seedRoot. */
+export function seedDefaultTeam(ws: string): void {
+  if (teamExists(ws, DEFAULT_TEAM_ID)) return;
+  const team = TeamDef.parse({
+    id: DEFAULT_TEAM_ID,
+    charter: "Everyone on the squad.",
+    lead: "root",
+    tools: {},
+    charterBody:
+      "The whole squad. Every agent belongs to this team and it cannot be deleted. " +
+      "Form a focused team to address a subset of the squad by capability.",
+    created: new Date().toISOString(),
+  });
+  writeTeam(ws, team);
+}
+
+export interface TeamPatch { charter?: string; lead?: string | null; tools?: { grant?: string[]; deny?: string[] }; charterBody?: string; }
+
+/** Edit an existing team's charter, lead, tool policy, or body (the captain's `e`/`l`/`p` verbs, the
+ *  CLI, the approval-gated tool). Re-parses through TeamDef and re-asserts the DEFAULT_WORKER_TOOLS
+ *  floor on write. `lead: null` clears the lead (back to leadless routing). The id is immutable. */
+export function updateTeam(ws: string, id: string, patch: TeamPatch): TeamDef {
+  const cur = loadTeam(ws, id);
+  if (!cur) throw new Error(`no team "${id}"`);
+  const next = TeamDef.parse({
+    ...cur,
+    charter: patch.charter ?? cur.charter,
+    lead: patch.lead === null ? undefined : (patch.lead ?? cur.lead),
+    tools: patch.tools ?? cur.tools,
+    charterBody: patch.charterBody ?? cur.charterBody,
+  });
+  writeTeam(ws, next);
+  return next;
+}
+
+/** Delete a team (the `d` verb / CLI). The default team is protected — every agent belongs to it. Strips
+ *  the team from every member's own `teams:` frontmatter (membership is canon on the agent), then removes
+ *  the team files. Returns the members it detached, for a confirmation line. */
+export async function deleteTeam(ws: string, db: Database, id: string): Promise<string[]> {
+  if (id === DEFAULT_TEAM_ID) throw new Error("the default team cannot be deleted — every agent belongs to it");
+  if (!teamExists(ws, id)) throw new Error(`no team "${id}"`);
+  const members = membersOf(db, id).map((m) => m.id);
+  for (const m of members) {
+    const agent = await loadAgent(ws, m);
+    if (agent.teams.includes(id)) await setAgentTeams(ws, db, m, agent.teams.filter((t) => t !== id));
+  }
+  rmSync(paths.teamDir(ws, id), { recursive: true, force: true });
+  return members;
+}
+
+/** Make a team's membership EXACTLY `memberIds` (the wizard's member picker and the `m` verb). Adds the
+ *  team to newly-selected agents and removes it from de-selected ones — membership is edited on each
+ *  AGENT, the one source of truth. The default team is not settable: everyone is always a member. */
+export async function setTeamMembers(ws: string, db: Database, teamId: string, memberIds: string[]): Promise<void> {
+  if (teamId === DEFAULT_TEAM_ID) throw new Error("every agent is always a member of the default team");
+  if (!teamExists(ws, teamId)) throw new Error(`no team "${teamId}"`);
+  const current = new Set(membersOf(db, teamId).map((m) => m.id));
+  const desired = new Set(memberIds);
+  for (const m of desired)
+    if (!current.has(m)) {
+      const agent = await loadAgent(ws, m); // throws if the id is not an agent
+      if (!agent.teams.includes(teamId)) await setAgentTeams(ws, db, m, [...agent.teams, teamId]);
+    }
+  for (const m of current)
+    if (!desired.has(m)) {
+      const agent = await loadAgent(ws, m);
+      await setAgentTeams(ws, db, m, agent.teams.filter((t) => t !== teamId));
+    }
+}
+
+/** Create a team AND staff it in one call (the Add wizard, the CLI, the approval-gated tool). The team
+ *  file is written first so setTeamMembers' existence check passes. */
+export async function createTeamWithMembers(ws: string, db: Database, draft: NewTeamDraft, memberIds: string[]): Promise<TeamDef> {
+  const team = createTeam(ws, draft);
+  await setTeamMembers(ws, db, team.id, memberIds);
+  return team;
+}
+
+export interface TeamMember { id: string; role: string }
+
+/** A team's roster, derived from the `agent_teams` join (Plan 22) — the many-to-many membership index,
+ *  itself derived from each agent's own `teams:` frontmatter. Ordered by id so routing and rendering are
+ *  deterministic. membersOf(DEFAULT_TEAM_ID) returns the whole squad, since every agent carries the
+ *  implicit default membership. */
+export function membersOf(db: Database, teamId: string): TeamMember[] {
+  return db
+    .query<TeamMember, [string]>(
+      "SELECT r.id, r.role FROM agent_teams at JOIN registry r ON r.id = at.agent_id WHERE at.team_id = ? ORDER BY r.id",
+    )
+    .all(teamId);
+}
+
+export interface TeamProblem { team: string; problem: string }
+
+/** Boot validation. A `lead` that is not an agent, or is an agent sitting on a DIFFERENT team, is an
+ *  inconsistency the captain must see — a lead who isn't on the team it leads would route work out of
+ *  the team silently. Report rather than throw: one bad team must not block boot, and the captain can
+ *  fix the file and restart. Returns the problems found (for a boot notice). */
+export function validateTeams(ws: string, db: Database): TeamProblem[] {
+  const problems: TeamProblem[] = [];
+  const isAgent = db.query<{ id: string }, [string]>("SELECT id FROM registry WHERE id = ?");
+  const isMember = db.query<{ agent_id: string }, [string, string]>("SELECT agent_id FROM agent_teams WHERE agent_id = ? AND team_id = ?");
+  for (const team of listTeams(ws)) {
+    if (!team.lead) continue;
+    // Plan 22: a lead must be an agent AND a member of the team it leads (membership is many-to-many, so
+    // "is a member" is a join lookup, not a single-column compare). A lead who isn't on the team routes
+    // its work out of the team — the inconsistency this reports so the captain can fix the file.
+    if (!isAgent.get(team.lead)) problems.push({ team: team.id, problem: `lead "${team.lead}" is not an agent` });
+    else if (!isMember.get(team.lead, team.id))
+      problems.push({ team: team.id, problem: `lead "${team.lead}" is not a member of the team it leads — add "${team.id}" to its teams` });
+  }
+  return problems;
+}

package/src/store/thread.ts

@@ -0,0 +1,72 @@
+/** Per-agent conversation thread, append-only JSONL at agents/<id>/thread.jsonl.
+ *  Used to persist + resume the root conversation across launches. Tolerant of corrupt lines. */
+import { mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ModelMessage } from "ai";
+import { paths } from "./files";
+
+function threadFile(ws: string, agentId: string): string {
+  return join(paths.agentDir(ws, agentId), "thread.jsonl");
+}
+
+// Must match SUMMARY_MARKER in core/conversation-replay.ts — the first line of a COMPACTED replay cache
+// is a pinned `[CONVERSATION COMPACTION]` summary of the folded (older) turns (Plan 05 Ph3). Defined
+// locally (not imported) to avoid a thread ⇄ conversation-replay import cycle.
+const COMPACTION_HEAD_MARKER = "[CONVERSATION COMPACTION]";
+
+/** Is this raw JSONL line the pinned compaction-summary head? (a `user` message whose text opens with
+ *  the marker) — used so truncation never drops the folded-history summary. */
+function isCompactionHead(line: string): boolean {
+  try {
+    const m = JSON.parse(line) as ModelMessage;
+    return m.role === "user" && typeof m.content === "string" && m.content.startsWith(COMPACTION_HEAD_MARKER);
+  } catch { return false; }
+}
+
+/** Is this raw JSONL line an `assistant` reply? Used to keep the truncated tail on a turn (user+
+ *  assistant PAIR) boundary — a raw-message tail cut can land mid-pair and leave a dangling assistant
+ *  reply (no preceding user turn) as the first replayed message. */
+function isAssistantReply(line: string): boolean {
+  try { return (JSON.parse(line) as ModelMessage).role === "assistant"; }
+  catch { return false; }
+}
+
+export function loadThread(ws: string, agentId: string, maxTurns = 40): ModelMessage[] {
+  const f = threadFile(ws, agentId);
+  if (!existsSync(f)) return [];
+  const lines = readFileSync(f, "utf8").split("\n").filter((l) => l.trim() !== "");
+  // The DERIVED replay cache leads with a pinned `[CONVERSATION COMPACTION]` summary head (Plan 05 Ph3)
+  // whenever older turns were folded. A naive tail-slice (`slice(-maxTurns)`) would DROP that head for a
+  // large replayKeepTurns — silently losing the entire folded-history summary and defeating cross-turn
+  // compaction. PIN the head and truncate from the tail's older end instead.
+  let head: string[] = [];
+  let rest = lines;
+  if (lines.length && isCompactionHead(lines[0])) { head = [lines[0]!]; rest = lines.slice(1); }
+  const budget = Math.max(0, maxTurns - head.length);
+  let kept = budget === 0 ? [] : rest.slice(-budget); // guard: slice(-0) would return the WHOLE array
+  // Slice the tail at a turn (user+assistant PAIR) boundary. When `1 + 2*replayKeepTurns > maxTurns` the
+  // pinned summary head steals a slot and the raw tail cut lands mid-pair — leaving a DANGLING assistant
+  // reply (orphaned from its user turn) as the first replayed message. Drop that orphan so replay opens
+  // on a user turn (or the summary head), never on a bare assistant reply.
+  if (kept.length && isAssistantReply(kept[0]!)) kept = kept.slice(1);
+  const out: ModelMessage[] = [];
+  for (const l of [...head, ...kept]) {
+    try { out.push(JSON.parse(l) as ModelMessage); } catch { /* skip corrupt line */ }
+  }
+  return out;
+}
+
+/** Overwrite thread.jsonl with an exact message list. thread.jsonl is a DERIVED boot-replay cache
+ *  (the ledger is the append-only truth), so it is REBUILT — not appended — each time a completed
+ *  turn is recorded through the audit seam. Plan 05 Ph3 writes the compacted replay (rolling summary
+ *  + recent-K tail) here, so this replaces the old completed-only append. */
+export function writeThread(ws: string, agentId: string, messages: ModelMessage[]): void {
+  mkdirSync(paths.agentDir(ws, agentId), { recursive: true });
+  const body = messages.map((m) => JSON.stringify(m)).join("\n");
+  writeFileSync(threadFile(ws, agentId), body ? body + "\n" : "");
+}
+
+export function clearThread(ws: string, agentId: string): void {
+  const f = threadFile(ws, agentId);
+  if (existsSync(f)) writeFileSync(f, "");
+}

package/src/store/trace.ts

@@ -0,0 +1,98 @@
+/** One JSON file per run under runs/<agent>/<date>-run<n>.json. Files are canon. */
+import { mkdirSync, existsSync, readdirSync, writeFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { paths } from "./files";
+import { RunTrace } from "@taicho-ai/contracts/trace";
+
+function dateStamp(): string { return new Date().toISOString().slice(0, 10); }
+function fileName(id: string): string {
+  const i = id.indexOf("/");
+  if (i < 0) throw new Error("bad run id: " + id);
+  return id.slice(i + 1) + ".json";
+}
+
+export function nextRunId(ws: string, agentId: string): string {
+  const date = dateStamp();
+  const dir = paths.runDir(ws, agentId);
+  let max = 0;
+  if (existsSync(dir)) {
+    const prefix = `${date}-run`;
+    for (const f of readdirSync(dir)) {
+      if (f.startsWith(prefix)) {
+        const n = parseInt(f.slice(prefix.length), 10);
+        if (Number.isFinite(n)) max = Math.max(max, n);
+      }
+    }
+  }
+  return `${agentId}/${date}-run${max + 1}`;
+}
+
+export function writeTrace(ws: string, trace: RunTrace): string {
+  const dir = paths.runDir(ws, trace.agent);
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, fileName(trace.id));
+  writeFileSync(file, JSON.stringify(trace, null, 2));
+  return file;
+}
+
+export function readTrace(ws: string, id: string): RunTrace {
+  const file = join(paths.runDir(ws, id.split("/")[0]), fileName(id));
+  return RunTrace.parse(JSON.parse(readFileSync(file, "utf8")));
+}
+
+export function listTraces(ws: string, agentId?: string): RunTrace[] {
+  const root = join(ws, "runs");
+  if (!existsSync(root)) return [];
+  const agents = agentId
+    ? [agentId]
+    : readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  const out: RunTrace[] = [];
+  for (const a of agents) {
+    const dir = paths.runDir(ws, a);
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir)) {
+      if (!f.endsWith(".json")) continue;
+      try {
+        out.push(RunTrace.parse(JSON.parse(readFileSync(join(dir, f), "utf8"))));
+      } catch {
+        // skip unparseable / in-progress placeholder files so listing never breaks
+      }
+    }
+  }
+  return out.sort((x, y) => x.started.localeCompare(y.started));
+}
+
+/** Atomically reserve a unique run id by exclusively creating its trace file as an
+ *  `interrupted` placeholder. Concurrent reservations for the same agent never collide. */
+export function reserveRunId(ws: string, agentId: string): string {
+  const date = dateStamp();
+  const dir = paths.runDir(ws, agentId);
+  mkdirSync(dir, { recursive: true });
+  let n = 1;
+  const prefix = `${date}-run`;
+  for (const f of readdirSync(dir)) {
+    if (f.startsWith(prefix)) {
+      const m = parseInt(f.slice(prefix.length), 10);
+      if (Number.isFinite(m)) n = Math.max(n, m + 1);
+    }
+  }
+  for (;;) {
+    const id = `${agentId}/${date}-run${n}`;
+    try {
+      writeFileSync(join(dir, `${date}-run${n}.json`), JSON.stringify(placeholderTrace(id, agentId), null, 2), { flag: "wx" });
+      return id;
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException)?.code === "EEXIST") { n++; continue; }
+      throw e;
+    }
+  }
+}
+
+function placeholderTrace(id: string, agent: string): RunTrace {
+  return RunTrace.parse({
+    id, agent, task: "(running)", triggeredBy: "",
+    ledger: { retrieved: [], applied: [], skipped: [] },
+    toolCalls: [], artifacts: [], delegatedOut: [], outcome: "interrupted",
+    tokens: 0, durationMs: 0, started: new Date().toISOString(),
+  });
+}

package/src/store/vectors.ts

@@ -0,0 +1,26 @@
+import type { Database } from "bun:sqlite";
+
+/** v0 recall: embeddings as blobs + brute-force cosine in TS.
+ *  At policy-note scale (hundreds) this is microseconds; sqlite-vec is a later optimization. */
+export function putVector(db: Database, ref: string, kind: string, vec: Float32Array) {
+  db.query("INSERT OR REPLACE INTO embeddings (ref, kind, vec) VALUES (?, ?, ?)")
+    .run(ref, kind, new Uint8Array(vec.buffer.slice(0)));
+}
+
+export function topK(db: Database, kind: string, query: Float32Array, k: number) {
+  const rows = db.query<{ ref: string; vec: Uint8Array }, [string]>(
+    "SELECT ref, vec FROM embeddings WHERE kind = ?").all(kind);
+  const scored = rows.map((r) => {
+    const v = new Float32Array(r.vec.slice().buffer);
+    return { ref: r.ref, score: cosine(query, v) };
+  });
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, k);
+}
+
+function cosine(a: Float32Array, b: Float32Array): number {
+  let dot = 0, na = 0, nb = 0;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
+  return dot / (Math.sqrt(na) * Math.sqrt(nb) || 1);
+}

package/src/store/workflows.ts

@@ -0,0 +1,144 @@
+/** Plan 23: a team's WORKFLOW — how work moves through it, and what each seat does. Optional, captain-
+ *  authored, sits at teams/<id>/workflow.md next to team.md. It is CANON and STABLE: a file, not a
+ *  model-generated plan, so the process is byte-identical on every invocation (the opposite of a Plan 18
+ *  plan, which regenerates per goal). The lead INSTANTIATES it against the input; it never re-invents it.
+ *
+ *  The file is MEMBER-KEYED: markdown headings name the seats. A heading whose text is a member's agent
+ *  id is that member's LANE ("when work reaches you, do this"); the reserved heading `orchestration` is
+ *  the LEAD's slice (the sequence + hand-offs). At run time (run.ts) a member executing UNDER this team
+ *  gets its lane injected as a context-tier section; the lead additionally gets the orchestration slice.
+ *
+ *  SPARSE + OPTIONAL by construction: no workflow.md → the team runs exactly as it did before Plan 23;
+ *  a workflow.md with no section for a given member → that member just runs on the agentic brief (its
+ *  identity + charter + task). Assigning someone to a team can therefore never break — a workflow only
+ *  ADDS structure at the seats you have actually authored. */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { YAML } from "bun";
+import { paths } from "./files";
+import { loadWorkflowDefText, parseWorkflowDef, type WorkflowDef } from "@taicho-ai/graph";
+
+/** The reserved seat name for the lead's orchestration slice. An agent literally named `orchestration`
+ *  would collide with it — deliberately reserved, and documented, so the seat is unambiguous. */
+export const ORCHESTRATION_KEY = "orchestration";
+
+const FRONTMATTER = /^---\n[\s\S]*?\n---\n?([\s\S]*)$/;
+// Seats are LEVEL-2 headings (`## <seat>`). A level-1 `# Title` is a document title (ignored), and
+// deeper `### …` headings live INSIDE a lane as its content — so an author can structure a lane freely.
+const HEADING = /^##\s+(.+?)\s*$/;
+
+export interface TeamWorkflow {
+  /** seat name (lowercased heading text: a member agent id, or `orchestration`) → that section's body. */
+  sections: Map<string, string>;
+}
+
+/** Parse a workflow.md into its seat sections. Any YAML frontmatter is stripped (reserved for a future
+ *  structured `steps:` form — the file stays forward-compatible). Content before the first heading is a
+ *  preamble and is ignored; the format is heading-delimited. */
+export function parseWorkflow(text: string): TeamWorkflow {
+  const body = FRONTMATTER.test(text) ? (FRONTMATTER.exec(text)![1] ?? "") : text;
+  const sections = new Map<string, string>();
+  let key: string | null = null;
+  let buf: string[] = [];
+  const flush = () => { if (key !== null) sections.set(key, buf.join("\n").trim()); };
+  for (const line of body.split("\n")) {
+    const m = HEADING.exec(line);
+    if (m) { flush(); key = m[1].toLowerCase().trim(); buf = []; }
+    else if (key !== null) buf.push(line);
+  }
+  flush();
+  return { sections };
+}
+
+export function loadWorkflow(ws: string, teamId: string): TeamWorkflow | null {
+  const file = paths.teamWorkflowFile(ws, teamId);
+  if (!existsSync(file)) return null;
+  return parseWorkflow(readFileSync(file, "utf8"));
+}
+
+/** Plan 25: the STRUCTURED workflow definition (the `steps:` frontmatter) for a team, or null when the
+ *  team has no workflow.md or the file is a Plan 23 prose-only workflow (no `steps:`). The team id is
+ *  injected from the file location — one source of truth, like membership. */
+export function loadWorkflowDef(ws: string, teamId: string): WorkflowDef | null {
+  const file = paths.teamWorkflowFile(ws, teamId);
+  if (!existsSync(file)) return null;
+  return loadWorkflowDefText(readFileSync(file, "utf8"), teamId);
+}
+
+/** Plan 25: write the structured `steps:` frontmatter into a team's workflow.md. The ENGINE calls this
+ *  (via ctx.proposeWorkflow) only after the captain approves a root proposal — the model never writes
+ *  workflow canon directly (Plan 23's rule). Validates first (an invalid workflow is never written), and
+ *  PRESERVES any existing prose lanes (the markdown body below the frontmatter). Version defaults to the
+ *  next number after any existing structured version, or 1. */
+export function writeWorkflowSteps(
+  ws: string,
+  teamId: string,
+  input: { name: string; version?: number; brief?: string; steps: unknown[] },
+): void {
+  const version = input.version ?? ((loadWorkflowDef(ws, teamId)?.version ?? 0) + 1);
+  // Validate BEFORE writing — a bad workflow must never reach canon.
+  parseWorkflowDef({ id: input.name, team: teamId, version, brief: input.brief, steps: input.steps });
+
+  const file = paths.teamWorkflowFile(ws, teamId);
+  let body = "";
+  if (existsSync(file)) {
+    const text = readFileSync(file, "utf8");
+    const m = /^---\n[\s\S]*?\n---\n?([\s\S]*)$/.exec(text);
+    body = (m ? m[1]! : text).trim(); // keep the lanes (body after any frontmatter, or the whole prose file)
+  }
+  const fm: Record<string, unknown> = { workflow: input.name, version };
+  if (input.brief) fm.brief = input.brief;
+  fm.steps = input.steps;
+  const yaml = YAML.stringify(fm, null, 2).trimEnd();
+
+  mkdirSync(paths.teamDir(ws, teamId), { recursive: true });
+  writeFileSync(file, `---\n${yaml}\n---\n${body ? `\n${body}\n` : "\n"}`);
+}
+
+/** The lane a specific agent plays in this workflow — its own seat section, or undefined if it has none. */
+export function laneFor(wf: TeamWorkflow, agentId: string): string | undefined {
+  const s = wf.sections.get(agentId.toLowerCase());
+  return s ? s : undefined;
+}
+
+/** The orchestration slice — the lead's view of the sequence and hand-offs. Undefined if the file has none. */
+export function orchestrationSlice(wf: TeamWorkflow): string | undefined {
+  const s = wf.sections.get(ORCHESTRATION_KEY);
+  return s ? s : undefined;
+}
+
+/** Does this team have a workflow file at all? Cheap existence check for the Org browser's status line. */
+export function hasWorkflow(ws: string, teamId: string): boolean {
+  return existsSync(paths.teamWorkflowFile(ws, teamId));
+}
+
+/** The seat names a workflow defines, in file order, with `orchestration` marked. For the Org browser's
+ *  summary line and the read_workflow tool. */
+export function seatsOf(wf: TeamWorkflow): string[] {
+  return [...wf.sections.keys()];
+}
+
+/** Write (or overwrite) a team's workflow.md. Captain-owned — the Org browser and hand-edits call this;
+ *  the model never does. Ensures a trailing newline so the file is well-formed. */
+export function writeWorkflow(ws: string, teamId: string, text: string): void {
+  mkdirSync(paths.teamDir(ws, teamId), { recursive: true });
+  writeFileSync(paths.teamWorkflowFile(ws, teamId), text.endsWith("\n") ? text : text + "\n");
+}
+
+/** Scaffold a STARTER workflow.md for a team from its current members — a template the captain then
+ *  hand-edits into a real process. Refuses to clobber an existing file. Returns the text written. The
+ *  header comment explains the two section kinds so an editor knows the shape without leaving the file. */
+export function scaffoldWorkflow(ws: string, teamId: string, members: string[]): string {
+  if (hasWorkflow(ws, teamId)) throw new Error(`team "${teamId}" already has a workflow`);
+  const lanes = (members.length ? members : ["example-member"])
+    .map((m) => `## ${m}\nWhat ${m} does when work reaches it.\n`)
+    .join("\n");
+  const text =
+    `# ${teamId} workflow\n\n` +
+    `<!-- Each "## <agent-id>" heading below is that member's LANE — what it does when work reaches it. -->\n` +
+    `<!-- "## orchestration" is the lead's view: the sequence and the hand-offs. -->\n` +
+    `<!-- Delete a seat you don't want scripted; an unlisted member just runs on the agentic brief. -->\n\n` +
+    `## orchestration\nDescribe the order work moves in, and who hands to whom.\n\n` +
+    lanes;
+  writeWorkflow(ws, teamId, text);
+  return text;
+}