agent-coord-mcp 0.19.0 → 0.23.0

package/src/tools/work.ts

@@ -4,16 +4,20 @@ import path from "node:path";
 import { z } from "zod";
 import { WORK_DIR, workFile, readJson } from "../store.js";
 import {
-  type BoardRow,
   type DoneEntry,
   type QueueItem,
   type WorkDoc,
-  boardRowsOf,
   doneEntriesOf,
+  listWorkBoardOf,
   parseWorkDoc,
+  projectV1ToLanes,
   queueItemsOf,
   renderWorkDoc,
+  workDocIssues,
+  workDocLegacyWriteIssues,
+  LANES_V0_WRITE_ISSUE,
 } from "../work.js";
+import { parseFactsDoc, type FactEntry } from "@davidbalzan/groundwork-seam";
 import { loadScopes, ownsDocument } from "./scopes.js";
 import { AGENTS_FILE } from "../store.js";
 import type { AgentRegistry } from "./shared.js";
@@ -42,16 +46,66 @@ export const QUEUE_DOC = "docs/QUEUE.md";
 export const DONE_DOC = "docs/DONE.md";
 export const BOARD_DOC = "docs/WORKSTREAMS.md";
 export const LEGACY_DOC = "docs/BACKLOG.md";
+export const FACTS_DOC = "docs/FACTS.md";
 
-export type WorkFileKind = "queue" | "done" | "board" | "legacy";
+export type WorkFileKind = "queue" | "done" | "board" | "legacy" | "facts";
 
-export type StoredDoc = {
-  kind: WorkFileKind;
-  // Repo-relative, exactly as it will be written back.
+export type StoredWorkDoc = {
+  kind: "queue" | "done" | "board" | "legacy";
   path: string;
   doc: WorkDoc;
 };
 
+export type StoredFactsDoc = {
+  kind: "facts";
+  path: string;
+  source: string;
+  entries: FactEntry[];
+  issues: string[];
+};
+
+export type StoredDoc = StoredWorkDoc | StoredFactsDoc;
+
+function isFactsDoc(d: StoredDoc): d is StoredFactsDoc {
+  return d.kind === "facts";
+}
+
+async function loadDoc(repo: string, f: { kind: WorkFileKind; path: string }): Promise<StoredDoc> {
+  const source = await fsp.readFile(path.join(repo, f.path), "utf8");
+  if (f.kind === "facts") {
+    const parsed = parseFactsDoc(source);
+    return { kind: "facts", path: f.path, source, entries: parsed.entries, issues: parsed.issues };
+  }
+  return { kind: f.kind, path: f.path, doc: parseWorkDoc(source) };
+}
+
+function docIssues(d: StoredDoc): string[] {
+  if (isFactsDoc(d)) return d.issues.map((issue) => `${d.path}: ${issue}`);
+  return [...workDocIssues(d.doc), ...workDocLegacyWriteIssues(d.doc)].map(
+    (issue) => `${d.path}: ${issue}`,
+  );
+}
+
+function importedSummary(d: StoredDoc) {
+  if (isFactsDoc(d)) {
+    return {
+      path: d.path,
+      kind: d.kind,
+      facts: d.entries.length,
+      ...(d.issues.length ? { issues: d.issues } : {}),
+    };
+  }
+  const issues = [...workDocIssues(d.doc), ...workDocLegacyWriteIssues(d.doc)];
+  return {
+    path: d.path,
+    kind: d.kind,
+    queue: queueItemsOf(d.doc).length,
+    done: doneEntriesOf(d.doc).length,
+    board: listWorkBoardOf(d.doc).length,
+    ...(issues.length ? { issues } : {}),
+  };
+}
+
 export type WorkState = {
   project: string;
   repo: string;
@@ -72,6 +126,7 @@ function resolveDocs(repo: string): { kind: WorkFileKind; path: string }[] {
     out.push({ kind: "legacy", path: LEGACY_DOC });
   }
   if (has(BOARD_DOC)) out.push({ kind: "board", path: BOARD_DOC });
+  if (has(FACTS_DOC)) out.push({ kind: "facts", path: FACTS_DOC });
   return out;
 }
 
@@ -98,30 +153,27 @@ export async function importWorkTool(args: { project: string; repo?: string }) {
   if (!found.length) {
     return {
       ok: false as const,
-      error: `no work documents under '${repo}' — expected ${QUEUE_DOC}/${DONE_DOC} or the legacy ${LEGACY_DOC}`,
+      error: `no work documents under '${repo}' — expected ${QUEUE_DOC}/${DONE_DOC} or the legacy ${LEGACY_DOC} (optional ${FACTS_DOC})`,
     };
   }
 
   const docs: StoredDoc[] = [];
-  for (const f of found) {
-    const source = await fsp.readFile(path.join(repo, f.path), "utf8");
-    docs.push({ kind: f.kind, path: f.path, doc: parseWorkDoc(source) });
-  }
+  for (const f of found) docs.push(await loadDoc(repo, f));
   const state: WorkState = { project: args.project, repo, importedAt: Date.now(), docs };
   await saveState(state);
 
+  const allIssues = docs.flatMap(docIssues);
   return {
     ok: true as const,
     project: args.project,
     repo,
     file: workFile(args.project),
-    imported: docs.map((d) => ({
-      path: d.path,
-      kind: d.kind,
-      queue: queueItemsOf(d.doc).length,
-      done: doneEntriesOf(d.doc).length,
-      board: boardRowsOf(d.doc).length,
-    })),
+    imported: docs.map(importedSummary),
+    ...(allIssues.length
+      ? {
+          warning: `${allIssues.length} issue(s) (board arity / unknown grammar / facts) — documents round-trip unchanged. See imported[].issues.`,
+        }
+      : {}),
     note: "the markdown remains authoritative — this store is a derived index",
   };
 }
@@ -130,18 +182,21 @@ export async function importWorkTool(args: { project: string; repo?: string }) {
 
 export const listWorkSchema = {
   project: z.string().min(1),
-  kind: z.enum(["queue", "done", "board"]).optional(),
+  kind: z.enum(["queue", "done", "board", "facts"]).optional(),
   priority: z.enum(["P1", "P2", "P3"]).optional(),
   // Include queue items already ticked off (default false).
   includeDone: z.boolean().optional(),
+  // native (default): discriminated v1 | lanes-v0. lanes: lossy projection of v1.
+  view: z.enum(["native", "lanes"]).optional(),
   repo: z.string().optional(),
 };
 
 export async function listWorkTool(args: {
   project: string;
-  kind?: "queue" | "done" | "board";
+  kind?: "queue" | "done" | "board" | "facts";
   priority?: "P1" | "P2" | "P3";
   includeDone?: boolean;
+  view?: "native" | "lanes";
   repo?: string;
 }) {
   // No import yet (or the store was deleted) → read the documents directly.
@@ -160,12 +215,21 @@ export async function listWorkTool(args: {
 
   const queue: QueueItem[] = [];
   const done: DoneEntry[] = [];
-  const board: BoardRow[] = [];
+  const facts: FactEntry[] = [];
+  let board = [];
+  const issues: string[] = [];
   for (const d of state.docs) {
+    if (isFactsDoc(d)) {
+      facts.push(...d.entries);
+      issues.push(...docIssues(d));
+      continue;
+    }
     queue.push(...queueItemsOf(d.doc));
     done.push(...doneEntriesOf(d.doc));
-    board.push(...boardRowsOf(d.doc));
+    board.push(...listWorkBoardOf(d.doc));
+    issues.push(...docIssues(d));
   }
+  if (args.view === "lanes") board = board.map(projectV1ToLanes);
 
   const openQueue = args.includeDone ? queue : queue.filter((q) => !q.done);
   const filtered = args.priority ? openQueue.filter((q) => q.priority === args.priority) : openQueue;
@@ -178,6 +242,8 @@ export async function listWorkTool(args: {
     ...(args.kind === "queue" || args.kind === undefined ? { queue: filtered } : {}),
     ...(args.kind === "done" || args.kind === undefined ? { done } : {}),
     ...(args.kind === "board" || args.kind === undefined ? { board } : {}),
+    ...(args.kind === "facts" || args.kind === undefined ? { facts } : {}),
+    ...(issues.length ? { issues } : {}),
   };
 }
 
@@ -187,10 +253,7 @@ async function importFromDisk(project: string, repo: string): Promise<WorkState
   const found = resolveDocs(repo);
   if (!found.length) return null;
   const docs: StoredDoc[] = [];
-  for (const f of found) {
-    const src = await fsp.readFile(path.join(repo, f.path), "utf8");
-    docs.push({ kind: f.kind, path: f.path, doc: parseWorkDoc(src) });
-  }
+  for (const f of found) docs.push(await loadDoc(repo, f));
   return { project, repo, importedAt: Date.now(), docs };
 }
 
@@ -231,6 +294,19 @@ export async function exportWorkTool(args: {
   const files = [];
   for (const d of state.docs) {
     const target = path.join(repo, d.path);
+    if (isFactsDoc(d)) {
+      // FACTS is not an export write target — set-fact.mjs owns the file.
+      const current = existsSync(target) ? await fsp.readFile(target, "utf8") : null;
+      files.push({
+        path: d.path,
+        bytes: Buffer.byteLength(d.source, "utf8"),
+        identical: current === d.source,
+        written: false,
+        note: "facts is not an export write target (set-fact.mjs owns the file)",
+        ...(d.issues.length ? { issues: d.issues } : {}),
+      });
+      continue;
+    }
     const rendered = renderWorkDoc(d.doc);
     const current = existsSync(target) ? await fsp.readFile(target, "utf8") : null;
     const declared = scopes.documents.find((s) => s.path === d.path);
@@ -244,22 +320,34 @@ export async function exportWorkTool(args: {
         }
       : undefined;
 
-    if (write && rendered !== current) await fsp.writeFile(target, rendered, "utf8");
+    const issues = [...workDocIssues(d.doc), ...workDocLegacyWriteIssues(d.doc)];
+    const wouldWrite = write && rendered !== current;
+    const refuseLegacyWrite = wouldWrite && workDocLegacyWriteIssues(d.doc).length > 0;
+    if (wouldWrite && !refuseLegacyWrite) await fsp.writeFile(target, rendered, "utf8");
     files.push({
       path: d.path,
       bytes: Buffer.byteLength(rendered, "utf8"),
       identical: rendered === current,
-      written: write && rendered !== current,
+      written: wouldWrite && !refuseLegacyWrite,
+      // Refused rows replay verbatim — the write is byte-faithful — but a
+      // caller rewriting a document should hear that some rows carry no
+      // record, rather than infer health from `identical:true`.
+      ...(refuseLegacyWrite ? { error: LANES_V0_WRITE_ISSUE } : {}),
+      ...(issues.length ? { issues } : {}),
       ...(scope ? { scope } : {}),
     });
   }
 
+  const refused = files.filter((f) => "error" in f);
   return {
-    ok: true as const,
-    project: state.project,
+    ok: refused.length === 0,
+    project: args.project,
     repo,
     write,
     files,
+    ...(refused.length
+      ? { error: `refused ${refused.length} new lanes-v0 write(s) — ${LANES_V0_WRITE_ISSUE}` }
+      : {}),
     ...(write ? {} : { note: "dry run — pass write:true to rewrite the documents" }),
   };
 }

package/src/work.ts

@@ -1,329 +1,31 @@
-// Work state as data (Phase 8 Task 5): queue items, done entries and board
-// rows as typed records, with markdown as a first-class EXPORT rather than the
-// datastore.
-//
-// WHY THIS SHAPE. `docs/QUEUE.md` / `docs/DONE.md` were parsed under a contract
-// requiring exact `—` (U+2014) and ` · ` (U+00B7). A parser once returned ZERO
-// items on the real file while passing every synthetic test, and the consuming
-// UI rendered an empty panel — no error, no signal. The files themselves are
-// good: David edits them, git diffs them, they grep. So markdown stays the
-// INTERFACE and stops being the DATASTORE.
-//
-// MARKDOWN REMAINS AUTHORITATIVE. Delete the store and the documents still
-// stand alone: every field here is recoverable from the file it came from, the
-// exporter is byte-exact, and nothing downstream is required to read records.
-// The store is a derived index until a consumer chooses otherwise.
-//
-// The round-trip guarantee is structural, not incidental: everything this
-// module does NOT model — prose, the write-rule paragraphs, the Cross-project
-// section, fenced examples — is captured verbatim as a `text` block and
-// replayed in place. Only lines it genuinely understands are re-rendered, so
-// an unmodelled construct can never be silently dropped.
-
-import { createHash } from "node:crypto";
-
-// ---------- record shapes ----------
-
-export type Priority = "P1" | "P2" | "P3";
-
-// Fields taken from what the pre-existing parser extracted, no more.
-export type QueueItem = {
-  id: string;
-  priority: Priority;
-  text: string;
-  done: boolean;
-  // The `### Subsection` this item sits under, when the document groups them.
-  section?: string;
-};
-
-// `ref` and `date` are parsed separately today and stay separate fields — a
-// reassembled "ref · date" string would put the glyph contract right back into
-// the data model, which is the bug this task exists to delete.
-export type DoneEntry = {
-  id: string;
-  text: string;
-  ref?: string;
-  date?: string;
-  section?: string;
-};
-
-// WORKSTREAMS.md's Lanes table, as it genuinely exists: a 5-column markdown
-// table. Column headers are carried so a renamed column round-trips.
-export type BoardRow = {
-  id: string;
-  lane: string;
-  owner: string;
-  state: string;
-  currentSlice: string;
-  nextGo: string;
-  // The line this row was read from. Markdown tables are hand-aligned and
-  // there is no canonical spacing, so an UNCHANGED row replays its original
-  // bytes; edit any field and the renderer notices the mismatch and re-renders
-  // in the normalized form. Absent on rows built from scratch.
-  raw?: string;
-};
-
-// A parsed document: an ordered block list. `text` blocks are verbatim lines
-// (never interpreted); the others carry records rendered back in place.
-export type Block =
-  | { kind: "text"; lines: string[] }
-  | { kind: "queue"; items: QueueItem[] }
-  | { kind: "done"; entries: DoneEntry[] }
-  // `header` and `align` are kept as raw lines for the same reason as
-  // BoardRow.raw — the alignment row (`|---|---|`) has no canonical form.
-  | { kind: "board"; header: string; align: string; rows: BoardRow[] };
-
-export type WorkDoc = {
-  // Kept so an export can be written back with the exact byte tail it had.
-  trailingNewline: boolean;
-  blocks: Block[];
-};
-
-// ---------- the glyph contract ----------
-//
-// Pinned in docs/DONE.md and consumed by external parsers: the ref splits on
-// the LAST ` — ` (space, U+2014, space) and the date is a trailing ` · `
-// (space, U+00B7, space) + ISO date. Written as explicit escapes so a source
-// file normalization or a copy-paste through an ASCII-mangling tool can never
-// change them silently — the constants are the contract.
-export const EM_DASH_SEP = " — ";
-export const MIDDOT_SEP = " · ";
-const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
-
-// Deterministic ids: same content in → same id out, so import→export→import is
-// stable and no id has to be written into the markdown (which would change the
-// bytes the round trip is measured on).
-function idFor(kind: string, seed: string): string {
-  return `${kind}-${createHash("sha1").update(seed).digest("hex").slice(0, 8)}`;
-}
-
-// ---------- line-level recognizers ----------
-
-const QUEUE_LINE = /^- \[( |x)\] \((P1|P2|P3)\) (.*)$/;
-const DONE_LINE = /^- \[( |x)\] (.*)$/;
-
-export function parseQueueLine(line: string, section?: string): QueueItem | null {
-  const m = QUEUE_LINE.exec(line);
-  if (!m) return null;
-  const [, mark, priority, text] = m;
-  return {
-    id: idFor("q", text ?? ""),
-    priority: priority as Priority,
-    text: text ?? "",
-    done: mark === "x",
-    ...(section ? { section } : {}),
-  };
-}
-
-// Split on the LAST ` — `, then peel a trailing ` · YYYY-MM-DD`. Both parts are
-// optional: an entry with neither is still a done entry, it just carries no
-// verifiable ref — which is a fact about the entry, not a parse failure. The
-// old parser treated the same line as nothing at all.
-export function parseDoneLine(line: string, section?: string): DoneEntry | null {
-  const m = DONE_LINE.exec(line);
-  if (!m) return null;
-  let body = m[2] ?? "";
-  let ref: string | undefined;
-  let date: string | undefined;
-
-  const cut = body.lastIndexOf(EM_DASH_SEP);
-  if (cut !== -1) {
-    const tail = body.slice(cut + EM_DASH_SEP.length);
-    const dot = tail.lastIndexOf(MIDDOT_SEP);
-    if (dot !== -1) {
-      const maybeDate = tail.slice(dot + MIDDOT_SEP.length);
-      if (ISO_DATE.test(maybeDate)) {
-        date = maybeDate;
-        ref = tail.slice(0, dot);
-      }
-    }
-    // A tail with no date is still a ref, as long as it isn't prose with
-    // spaces — refs are `owner/repo#N` or `owner/repo@sha`.
-    if (date === undefined && /^\S+$/.test(tail)) ref = tail;
-    if (ref !== undefined) body = body.slice(0, cut);
-  }
-  return {
-    id: idFor("d", `${body}|${ref ?? ""}|${date ?? ""}`),
-    text: body,
-    ...(ref !== undefined ? { ref } : {}),
-    ...(date !== undefined ? { date } : {}),
-    ...(section ? { section } : {}),
-  };
-}
-
-export function renderQueueLine(item: QueueItem): string {
-  return `- [${item.done ? "x" : " "}] (${item.priority}) ${item.text}`;
-}
-
-export function renderDoneLine(entry: DoneEntry): string {
-  let line = `- [x] ${entry.text}`;
-  if (entry.ref !== undefined) line += `${EM_DASH_SEP}${entry.ref}`;
-  if (entry.date !== undefined) line += `${MIDDOT_SEP}${entry.date}`;
-  return line;
-}
-
-// ---------- board table ----------
-
-const TABLE_ROW = /^\|(.*)\|\s*$/;
-const TABLE_ALIGN = /^\|[\s:|-]+\|\s*$/;
-
-function splitRow(line: string): string[] {
-  const m = TABLE_ROW.exec(line);
-  if (!m) return [];
-  return (m[1] ?? "").split("|").map((c) => c.trim());
-}
-
-function renderRow(cells: string[]): string {
-  return `| ${cells.join(" | ")} |`;
-}
-
-function boardCells(r: BoardRow): string[] {
-  return [r.lane, r.owner, r.state, r.currentSlice, r.nextGo];
-}
-
-// Replay the original line when the fields still say what it said; re-render
-// once anything actually changed.
-export function renderBoardRow(r: BoardRow): string {
-  if (r.raw !== undefined) {
-    const cells = splitRow(r.raw);
-    if (cells.length === 5 && cells.every((c, i) => c === boardCells(r)[i])) return r.raw;
-  }
-  return renderRow(boardCells(r));
-}
-
-// ---------- document parsing ----------
-
-type SectionKind = "queue" | "done" | "none";
-
-// Which record kind a `## Heading` opens. `## Queue` → queue items,
-// `## Done` → done entries; anything else closes the record region, so the
-// Cross-project section's bullets stay verbatim prose.
-function sectionKindOf(heading: string): SectionKind {
-  const h = heading.replace(/^#+\s*/, "").trim().toLowerCase();
-  if (h === "queue") return "queue";
-  if (h === "done") return "done";
-  return "none";
-}
-
-export function parseWorkDoc(source: string): WorkDoc {
-  const trailingNewline = source.endsWith("\n");
-  const lines = source.split("\n");
-  if (trailingNewline) lines.pop(); // the split's empty tail, restored on render
-
-  const blocks: Block[] = [];
-  let text: string[] = [];
-  let kind: SectionKind = "none";
-  let subsection: string | undefined;
-  let inFence = false;
-
-  const flushText = () => {
-    if (text.length) blocks.push({ kind: "text", lines: text });
-    text = [];
-  };
-  // Consecutive item lines coalesce into one block; anything in between (a
-  // blank line, a subsection heading) flushes as text first and therefore
-  // starts a new one, which is what keeps rendering order faithful.
-  const pushItem = (item: QueueItem) => {
-    flushText();
-    const last = blocks[blocks.length - 1];
-    if (last?.kind === "queue") last.items.push(item);
-    else blocks.push({ kind: "queue", items: [item] });
-  };
-  const pushEntry = (entry: DoneEntry) => {
-    flushText();
-    const last = blocks[blocks.length - 1];
-    if (last?.kind === "done") last.entries.push(entry);
-    else blocks.push({ kind: "done", entries: [entry] });
-  };
-
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i] ?? "";
-
-    // Fenced blocks are never interpreted — docs/DONE.md pins the done-line
-    // FORMAT inside a fence, and parsing that example as an entry would
-    // invent a record out of documentation.
-    if (/^\s*```/.test(line)) {
-      inFence = !inFence;
-      text.push(line);
-      continue;
-    }
-    if (inFence) {
-      text.push(line);
-      continue;
-    }
-
-    if (/^#{1,6}\s/.test(line)) {
-      const level = (line.match(/^#+/) ?? [""])[0].length;
-      if (level <= 2) {
-        kind = sectionKindOf(line);
-        subsection = undefined;
-      } else if (kind !== "none") {
-        subsection = line.replace(/^#+\s*/, "").trim();
-      }
-      text.push(line);
-      continue;
-    }
-
-    if (kind === "queue") {
-      const item = parseQueueLine(line, subsection);
-      if (item) {
-        pushItem(item);
-        continue;
-      }
-    } else if (kind === "done") {
-      const entry = parseDoneLine(line, subsection);
-      if (entry) {
-        pushEntry(entry);
-        continue;
-      }
-    }
-
-    // Lanes table: a header row followed by an alignment row.
-    if (TABLE_ROW.test(line) && TABLE_ALIGN.test(lines[i + 1] ?? "")) {
-      const rows: BoardRow[] = [];
-      let j = i + 2;
-      for (; j < lines.length && TABLE_ROW.test(lines[j] ?? ""); j++) {
-        const raw = lines[j] ?? "";
-        const [lane = "", owner = "", state = "", currentSlice = "", nextGo = ""] = splitRow(raw);
-        rows.push({ id: idFor("b", lane), lane, owner, state, currentSlice, nextGo, raw });
-      }
-      flushText();
-      blocks.push({ kind: "board", header: line, align: lines[i + 1] ?? "", rows });
-      i = j - 1;
-      continue;
-    }
-
-    text.push(line);
-  }
-  flushText();
-  return { trailingNewline, blocks };
-}
-
-export function renderWorkDoc(doc: WorkDoc): string {
-  const out: string[] = [];
-  for (const block of doc.blocks) {
-    if (block.kind === "text") out.push(...block.lines);
-    else if (block.kind === "queue") out.push(...block.items.map(renderQueueLine));
-    else if (block.kind === "done") out.push(...block.entries.map(renderDoneLine));
-    else {
-      out.push(block.header);
-      out.push(block.align);
-      for (const r of block.rows) out.push(renderBoardRow(r));
-    }
-  }
-  return out.join("\n") + (doc.trailingNewline ? "\n" : "");
-}
-
-// ---------- record extraction ----------
-
-export function queueItemsOf(doc: WorkDoc): QueueItem[] {
-  return doc.blocks.flatMap((b) => (b.kind === "queue" ? b.items : []));
-}
-
-export function doneEntriesOf(doc: WorkDoc): DoneEntry[] {
-  return doc.blocks.flatMap((b) => (b.kind === "done" ? b.entries : []));
-}
-
-export function boardRowsOf(doc: WorkDoc): BoardRow[] {
-  return doc.blocks.flatMap((b) => (b.kind === "board" ? b.rows : []));
-}
+export {
+  type Priority,
+  type QueueItem,
+  type DoneEntry,
+  type BoardRow,
+  BOARD_ARITY,
+  type MalformedRow,
+  isMalformedRow,
+  type Block,
+  type WorkDoc,
+  EM_DASH_SEP,
+  MIDDOT_SEP,
+  parseQueueLine,
+  parseDoneLine,
+  renderQueueLine,
+  renderDoneLine,
+  renderBoardRow,
+  parseWorkDoc,
+  renderWorkDoc,
+  queueItemsOf,
+  doneEntriesOf,
+  boardRowsOf,
+  workstreamsV1RowsOf,
+  listWorkBoardOf,
+  projectV1ToLanes,
+  workDocIssues,
+  workDocLegacyWriteIssues,
+  LANES_V0_WRITE_ISSUE,
+  type WorkstreamsV1Row,
+  type ListWorkBoardRow,
+} from "@davidbalzan/groundwork-seam/docs";