@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/lib/board/links.ts

@@ -36,20 +36,28 @@ export function indexOf(cards: readonly Card[]): BoardIndex {
 export function blockersOf(card: Card, board: BoardIndex): Card[] {
 	return dependsOf(card)
 		.map((id) => board.get(id))
-		.filter((other): other is Card => other !== undefined && other.status !== "done");
+		.filter((other): other is Card => other !== undefined && other.lane !== "done");
 }
 
 /**
- * A list of cards as a reader meets it: `#2 (doing), #3 (blocked)`.
+ * A list of cards as a reader meets it: `#2 (execute), #3 (blocked)`.
  *
  * The lane is what turns ids into a decision — a finished card is about to start, a
- * `doing` one is to leave alone — so it is never left out. One wording serves the
+ * `execute` one is to leave alone — so it is never left out. One formatter serves the
  * refusal sentence, the page's reason line, and the mirror question of what a card is
  * holding up: every one of them is a list of cards read to decide something, so a second
  * formatter would be a second way for the same list to read.
+ *
+ * `titles` adds the card's own title after its lane, for the one audience with the room
+ * and the reason for it: a card's face on the page is where a reader decides what to do
+ * next, and an id alone would send them into the dialog to find out which card it is. A
+ * refusal stays ids and lanes — it is read in a transcript row, and a title there would
+ * push the sentence it belongs to off the line.
  */
-export function lanesText(cards: readonly Card[]): string {
-	return cards.map((card) => `${cardRef(card.id)} (${card.status})`).join(", ");
+export function lanesText(cards: readonly Card[], options: { titles?: boolean } = {}): string {
+	return cards
+		.map((card) => `${cardRef(card.id)} (${card.lane})${options.titles === true ? ` ${card.title}` : ""}`)
+		.join(", ");
 }
 
 /** The cards that wait on `id`, oldest id first, so a report reads in board order. */
@@ -66,7 +74,7 @@ export function dependentsOf(id: string, board: BoardIndex): Card[] {
  * refusal is about a link that would be stranded rather than about work that is held up.
  */
 export function openDependentsOf(id: string, board: BoardIndex): Card[] {
-	return dependentsOf(id, board).filter((card) => card.status !== "done");
+	return dependentsOf(id, board).filter((card) => card.lane !== "done");
 }
 
 /** The sentence a claim, a move, or an assignment is refused with while `card` waits, or undefined. */
@@ -106,21 +114,34 @@ export function wouldCycle(id: string, dependsOn: readonly string[], board: Boar
  *
  * `[]` is a legal answer and means "waits on nothing", so an edit can remove a link
  * — the caller decides whether an absent list means "leave it alone" or "none".
+ *
+ * A link the card already carries is kept even when the card it names has left the board:
+ * `archive` moves a finished card's file rather than deleting its record, the link is inert
+ * (a finished dependency stops blocking), and refusing it would make `edit` unable to
+ * reproduce what the card says. A link the card does not already carry still has to name a
+ * card on the board, so an id nobody can see cannot be added.
  */
-export function normalizeDepends(raw: unknown, id: string, board: BoardIndex): { dependsOn: string[] } | FieldError {
+export function normalizeDepends(
+	raw: unknown,
+	card: Pick<Card, "id" | "dependsOn">,
+	board: BoardIndex,
+): { dependsOn: string[] } | FieldError {
 	if (!Array.isArray(raw)) return { error: "dependsOn must be a list of card ids." };
+	const held = dependsOf(card);
 	const dependsOn: string[] = [];
 	for (const entry of raw) {
 		const parsed = normalizeCardId(entry);
 		// The file name is the canonical spelling of an id, so `#04` and `4` are one card.
 		const dependency = parsed === undefined ? undefined : String(Number(parsed));
 		if (dependency === undefined) return { error: `${JSON.stringify(entry)} is not a card id.` };
-		if (dependency === id) return { error: `${cardRef(id)} cannot wait on itself.` };
-		if (!board.has(dependency)) return { error: `${cardRef(dependency)} does not exist.` };
+		if (dependency === card.id) return { error: `${cardRef(card.id)} cannot wait on itself.` };
+		if (!board.has(dependency) && !held.includes(dependency)) {
+			return { error: `${cardRef(dependency)} does not exist.` };
+		}
 		if (!dependsOn.includes(dependency)) dependsOn.push(dependency);
 	}
 	if (dependsOn.length > MAX_DEPENDS) return { error: `at most ${MAX_DEPENDS} dependencies are allowed.` };
-	const loop = wouldCycle(id, dependsOn, board);
+	const loop = wouldCycle(card.id, dependsOn, board);
 	if (loop !== undefined) return { error: loop };
 	return { dependsOn };
 }

package/lib/board/page-pointer.ts

@@ -66,7 +66,7 @@ export interface PagePointer {
 	port: number;
 	/** The page's one token: every read, and nothing else to authorise. */
 	token: string;
-	/** The seat the page writes as. */
+	/** The seat the page is read as. */
 	seat: { id?: string; label: string };
 	/** When the page started, so a reader can tell a fresh note from a stale one. */
 	startedAt: number;

package/lib/board/read.ts

@@ -0,0 +1,83 @@
+/**
+ * Reading a card file: the one gate a read passes, and the map from an older shape.
+ *
+ * The record itself is `card.ts`; this is what a file on disk becomes. Every version this
+ * build can read passes through {@link readCard}, which maps the names a past build wrote
+ * and stamps the version this one writes — a v1 file says `status`, `plan`, and a
+ * `blockedBy`/`blocker` pair where the record says `lane`, `planPath`, and `blocked`. The
+ * map is read-time only: no file is rewritten, so a board full of older cards reads as a
+ * board rather than as a pile of refusals, and each card takes the new shape on its next
+ * write.
+ *
+ * Pure: no I/O, no clock, no state.
+ */
+
+import { BLOCKERS, type BlockerKind, type Card, type CardBlock, CARD_VERSION, isCard } from "./card.ts";
+import type { Lane } from "./lanes.ts";
+
+/**
+ * The lane words the four-lane board used, as this build's names.
+ *
+ * `todo` was the pool nobody held and `doing` was the work in hand; `blocked` and `done`
+ * kept their names, so they need no row here. A word with no row is not one this build can
+ * place, so the entry is left as it is and {@link isCard} refuses the record — a lane
+ * guessed from an unknown word would put a card somewhere its own history disagrees with.
+ */
+const LEGACY_LANES: Readonly<Record<string, Lane>> = { todo: "backlog", doing: "execute" };
+
+/**
+ * The card as a file on disk holds it, or `undefined` when this build cannot trust it.
+ *
+ * A v1 file is the record before the lane and the block were named: `status` for `lane`,
+ * `plan` for `planPath`, a `blockedBy`/`blocker` pair for `blocked`, and — for a file older
+ * still — log entries whose lane is spelled `status` too. This maps them on read and stamps
+ * `v: 2`; the map is read-time only, so no file is rewritten and a card takes the new shape
+ * on its next write. Everything else is {@link isCard}'s decision; a version above this
+ * build's is the store's refusal to name, not this function's.
+ */
+export function readCard(value: unknown): Card | undefined {
+	const record = migrated(value);
+	return isCard(record) ? record : undefined;
+}
+
+/** A v1 record as this build's shape: the renames, and the version stamp. */
+function migrated(value: unknown): unknown {
+	if (typeof value !== "object" || value === null) return value;
+	const record = value as Record<string, unknown>;
+	if (record.v !== 1) return value;
+	const { status, plan, blockedBy, blocker, log, ...rest } = record;
+	const blocked = blockOf(blockedBy, blocker);
+	return {
+		...rest,
+		v: CARD_VERSION,
+		...(status === undefined || record.lane !== undefined ? {} : { lane: status }),
+		...(plan === undefined ? {} : { planPath: record.planPath ?? plan }),
+		...(blocked === undefined || record.blocked !== undefined ? {} : { blocked }),
+		...(log === undefined ? {} : { log: logEntries(log) }),
+	};
+}
+
+/** The block a v1 pair spells, keeping whichever half the file actually has. */
+function blockOf(rawNote: unknown, rawKind: unknown): CardBlock | undefined {
+	const kind =
+		typeof rawKind === "string" && BLOCKERS.includes(rawKind as BlockerKind) ? (rawKind as BlockerKind) : undefined;
+	const note = typeof rawNote === "string" && rawNote !== "" ? rawNote : undefined;
+	if (kind === undefined && note === undefined) return undefined;
+	return { ...(kind === undefined ? {} : { kind }), ...(note === undefined ? {} : { note }) };
+}
+
+/** A v1 log whose entries spelled the lane `status`, read as this build's entries. */
+function logEntries(raw: unknown): unknown {
+	if (!Array.isArray(raw)) return raw;
+	return raw.map((entry) => {
+		if (typeof entry !== "object" || entry === null) return entry;
+		const record = entry as Record<string, unknown>;
+		if (record.status === undefined || record.lane !== undefined) return entry;
+		const { status, ...rest } = record;
+		// The four-lane board's `todo` and `doing` are this build's `backlog` and `execute`;
+		// a status that is already a lane name passes through, and anything else is left for
+		// `isCard` to refuse rather than mapped onto a lane nobody wrote.
+		const lane = typeof status === "string" ? (LEGACY_LANES[status] ?? status) : status;
+		return { ...rest, lane };
+	});
+}

package/lib/board/reason.ts

@@ -0,0 +1,102 @@
+/**
+ * Why a card sits where it does: one rule, for the card face, the lead's queue, and the
+ * transcript.
+ *
+ * A card's lane says what kind of state it is in; the reason line says the one fact that
+ * decides what happens next — an order it waits on, a block somebody recorded, a contract
+ * nobody approved yet, a spot-check nobody has done. That sentence used to be written
+ * three times (the page's card face, its Team queue, and `board`'s card block), and the
+ * flow this board now runs multiplies the states it has to name, so it is one body.
+ *
+ * It is spliced into the browser bundle as {@link REASON_FOR_JS}, which is why it is
+ * self-contained: it reads the card and a formatter for relative times, and nothing else.
+ * The two callers differ only in whose clock an age is read against — the page's `ago`
+ * against the reader's now, the transcript's against the snapshot's — so the clock is a
+ * parameter rather than an import.
+ *
+ * Pure: no I/O, no clock of its own, no state.
+ */
+
+import type { Card } from "./card.ts";
+
+/** What a reason is about, which is what a row's edge and a dot are coloured by. */
+export const REASON_KINDS = [
+	"waiting",
+	"blocked",
+	"offered",
+	"contract",
+	"approval",
+	"executing",
+	"review",
+	"done",
+	"note",
+] as const;
+
+/** One kind of reason. */
+export type ReasonKind = (typeof REASON_KINDS)[number];
+
+/** One reason line: what it is about, and the sentence a reader gets. */
+export interface Reason {
+	kind: ReasonKind;
+	text: string;
+}
+
+/**
+ * The one line under a card, or `undefined` when the card has nothing to say.
+ *
+ * The order inside a lane is the weight of the fact: an unfinished dependency outranks
+ * everything (a claim would be refused), then the lane's own decision, then the last note.
+ */
+export function reasonFor(card: Card, ago: (at: number) => string): Reason | undefined {
+	const last = card.notes.length > 0 ? card.notes[card.notes.length - 1] : undefined;
+	if (card.lane === "blocked") {
+		// The recorded block is the reason: its sentence if one was written, else the kind,
+		// which is what says where the card goes back to. Only a card with no block at all —
+		// one hand-edited, or released and parked again before this record existed — falls
+		// back to the last note, and then to saying it has nothing.
+		if (card.blocked !== undefined) {
+			const kind = card.blocked.kind;
+			return {
+				kind: "blocked",
+				text: card.blocked.note ?? "blocked on a " + (kind === undefined ? "decision" : kind),
+			};
+		}
+		return { kind: "blocked", text: last === undefined ? "blocked, with nothing recorded" : last.text };
+	}
+	if (card.lane === "backlog") {
+		if (card.offeredAt !== undefined) {
+			return { kind: "offered", text: "offered " + ago(card.offeredAt) + " ago — nobody took it" };
+		}
+		return last === undefined ? undefined : { kind: "note", text: last.text };
+	}
+	if (card.lane === "plan") {
+		// The contract's three lines, read here so the page and the transcript name the same
+		// missing field: this body is spliced, so it cannot call the module that owns them.
+		const missing = [];
+		const fields = ["goal", "acceptance", "scopeOut"];
+		for (let index = 0; index < fields.length; index++) {
+			const value = card.contract === undefined ? undefined : card.contract[fields[index] as "goal"];
+			if (typeof value !== "string" || value === "") missing.push(fields[index]);
+		}
+		if (missing.length > 0) {
+			return { kind: "contract", text: "no contract yet — missing " + missing.join(", ") };
+		}
+		const approved = card.contract === undefined ? undefined : card.contract.approved;
+		if (approved === undefined) return { kind: "approval", text: "contract ready — needs approval" };
+		// A card planned before the plan was required: its contract names no artifact, which
+		// `execute` now refuses, so the line says what is missing rather than who signed.
+		if (card.planPath === undefined) return { kind: "contract", text: "contract approved — no plan recorded" };
+		return { kind: "approval", text: "contract approved by " + approved.by };
+	}
+	if (card.lane === "execute") {
+		if (card.review !== undefined) return { kind: "review", text: "spot-checked by " + card.review.by };
+		if (card.planPath === undefined) return { kind: "contract", text: "no plan recorded" };
+		return { kind: "executing", text: "executing — no spot-check yet" };
+	}
+	const landed = card.landed === undefined ? "" : " · landed " + card.landed.commit;
+	const who = card.owner === undefined ? "" : " by " + card.owner.label;
+	return { kind: "done", text: "✓ done" + who + landed };
+}
+
+/** The same body, as the browser receives it: one rule for the page and the transcript. */
+export const REASON_FOR_JS = String(reasonFor);

package/lib/board/round-text.ts

@@ -6,32 +6,54 @@
  * because a lead in a terminal should not have to open a browser to see what needs a
  * decision. One text, so the two cannot describe one board differently.
  *
- * It reads the cards and the round and nothing else — no clock, no roster, no store — so
- * `plural` and the group lines are pure and a caller supplies what it already read.
+ * It reads the cards, the round, and — when a caller has one — the roster, and never a clock
+ * or a store: the group lines are pure and a caller supplies what it already read. The roster
+ * is what lets an owner who is only history be stated once instead of once per label, and it
+ * is optional because a board works with `session-bus` unloaded.
  */
 
 import { type Card, cardRef } from "./card.ts";
 import type { RoundSummary } from "./round.ts";
 
+/** What the fold needs of a roster row: the page's `ViewTeammate` and the bus's record both answer it. */
+export interface RosterLabel {
+	label: string;
+}
+
 /**
  * The rollup: a headline of what a lead decides on, then one line per group.
  *
  * Groups name their cards by id and state, because the ids are what the next action
  * takes, and an empty group is left out rather than drawn empty.
+ *
+ * `roster` decides which owners are only history: the ones a bus has no record of and that
+ * hold nothing are stated in one line, because a label that ever claimed a card stays an
+ * owner for good. Without a roster nothing is called absent, which is the honest answer for
+ * a machine where the bus has recorded nobody.
  */
-export function formatRound(cards: readonly Card[], round: RoundSummary): string {
+export function formatRound(cards: readonly Card[], round: RoundSummary, roster?: readonly RosterLabel[]): string {
 	const owners = round.owners.length;
 	const headline = [
 		plural(owners, "owner"),
 		plural(cards.length, "feature"),
 		`${round.unassigned.length} unassigned`,
 		`${round.unplanned.length} unplanned`,
+		`${round.unapproved.length} awaiting approval`,
 		`${round.blocked.length} blocked`,
 		`${round.idle.length} idle`,
 		`${round.done.length} done`,
 	].join(" · ");
 	const lines = [headline];
+	// The history is counted as it goes, so its one line can follow the owner lines and the
+	// queue can start where a lead actually decides something.
+	let history = 0;
+	let finished = 0;
 	for (const group of round.owners) {
+		if (isHistoryOwner(group.label, group.cards.length, roster)) {
+			history += 1;
+			finished += group.done.length;
+			continue;
+		}
 		// An owner who finished everything is still listed, with what it finished: the
 		// count says which kind of work is left, and an empty list is a legitimate answer.
 		const counts =
@@ -39,8 +61,10 @@ export function formatRound(cards: readonly Card[], round: RoundSummary): string
 		const listed = group.cards.map((card) => brief(card)).join(", ");
 		lines.push(listed === "" ? `${group.label} (${counts})` : `${group.label} (${counts}): ${listed}`);
 	}
+	if (history > 0) lines.push(historyLine(history, finished));
 	lines.push(...group("unassigned", round.unassigned));
 	lines.push(...group("unplanned", round.unplanned));
+	lines.push(...group("unapproved", round.unapproved));
 	lines.push(...group("blocked", round.blocked, true));
 	lines.push(...group("idle", round.idle));
 	lines.push(...group("done", round.done));
@@ -61,10 +85,48 @@ export function plural(count: number, noun: string): string {
 /** The same body, as the browser receives it: one wording for `1 card`, not two. */
 export const PLURAL_JS = String(plural);
 
-/** `#4 doing planned`, the brief a rollup group needs. */
+/**
+ * Whether an owner is only history: the bus has no record of it, and it holds nothing.
+ *
+ * The Team tab and this text answer one question — which owners a board still has to show —
+ * so they ask it here. A label that ever claimed a card stays an owner for good, which is why
+ * the set only grows and why it is stated once.
+ *
+ * `roster` absent is "no bus here", not "no record": a machine that has recorded nobody
+ * cannot call an owner absent, and the page says `—` for the same reason.
+ */
+export function isHistoryOwner(label: string, held: number, roster: readonly RosterLabel[] | undefined): boolean {
+	if (roster === undefined || held > 0) return false;
+	const key = label.toLowerCase();
+	for (const session of roster) {
+		if (session.label.toLowerCase() === key) return false;
+	}
+	return true;
+}
+
+/** The same body, as the browser receives it. */
+export const HISTORY_OWNER_JS = String(isHistoryOwner);
+
+/**
+ * The one line the fold prints: `18 owners with no record · 71 done`.
+ *
+ * The page's history row and this line are one sentence, so the count of owners and the work
+ * they finished read the same on both surfaces.
+ */
+export function historyLine(owners: number, done: number): string {
+	return plural(owners, "owner") + " with no record · " + done + " done";
+}
+
+/** The same body, as the browser receives it: it calls `plural`, which the fragment holds. */
+export const HISTORY_LINE_JS = String(historyLine);
+
+/** `#4 execute planned`, the brief a rollup group needs. */
 function brief(card: Card): string {
-	const planned = card.status === "doing" ? (card.plan === undefined ? " unplanned" : " planned") : "";
-	return `${cardRef(card.id)} ${card.status}${planned}`;
+	// Only the two lanes a card is worked in say whether it was planned first: the pool has
+	// no plan yet, and a finished card is history.
+	const planned =
+		card.lane === "plan" || card.lane === "execute" ? (card.planPath === undefined ? " unplanned" : " planned") : "";
+	return `${cardRef(card.id)} ${card.lane}${planned}`;
 }
 
 /** One rollup group, or nothing when it is empty. */

package/lib/board/round.ts

@@ -8,16 +8,17 @@
  * know — nobody has touched it in half an hour — not that its owner's process is
  * gone.
  *
- * The groups overlap on purpose. A `doing` card with no plan and no touch for half
- * an hour is both `unplanned` and `idle`, and hiding it in one of the two would lose
- * half the reason a lead should look at it.
+ * The groups overlap on purpose. A `plan` card with no contract and no touch for half
+ * an hour is both `unplanned` and, once it is executing, `idle`; hiding it in one of the
+ * two would lose half the reason a lead should look at it.
  *
  * Pure: no I/O and no clock of its own.
  */
 
 import type { Card } from "./card.ts";
+import { contractApproved, missingContractFields } from "./contract.ts";
 
-/** How long a `doing` card may go untouched before the rollup calls it idle. */
+/** How long an `execute` card may go untouched before the rollup calls it idle. */
 export const IDLE_MS = 30 * 60 * 1_000;
 
 /**
@@ -35,17 +36,22 @@ export interface RoundGroup<T extends Card = Card> {
 
 /** The lead's rollup of one board. */
 export interface RoundSummary<T extends Card = Card> {
-	/** Every owner with at least one unfinished card, ordered by label. */
+	/** Every owner the board names, ordered by label, with its live cards and the ones it finished. */
 	owners: RoundGroup<T>[];
-	/** `todo` cards: nobody has taken them yet. */
+	/** `backlog` cards: nobody has taken them yet. */
 	unassigned: T[];
-	/** `doing` cards with no plan recorded: work started before it was planned. */
+	/**
+	 * `plan` cards whose contract is still missing a line, or whose plan was never recorded:
+	 * work started before it was agreed, and either one refuses `execute`.
+	 */
 	unplanned: T[];
+	/** `plan` cards whose contract is complete and nobody has approved: the lead's queue. */
+	unapproved: T[];
 	/** `blocked` cards, and the note that says why. */
 	blocked: T[];
-	/** `doing` cards untouched for {@link IDLE_MS}: possibly a dead owner. */
+	/** `execute` cards untouched for {@link IDLE_MS}: possibly a dead owner. */
 	idle: T[];
-	/** Finished cards, oldest first, kept as history. */
+	/** Finished cards, in the board's own order — priority, then age — kept as history. */
 	done: T[];
 }
 
@@ -64,21 +70,30 @@ export function buildRound<T extends Card = Card>(cards: readonly T[], now: numb
 	const groups = new Map<string, RoundGroup<T>>();
 	const unassigned: T[] = [];
 	const unplanned: T[] = [];
+	const unapproved: T[] = [];
 	const blocked: T[] = [];
 	const idle: T[] = [];
 	const done: T[] = [];
 
 	for (const card of cards) {
-		if (card.status === "todo") unassigned.push(card);
-		if (card.status === "done") done.push(card);
-		if (card.status === "blocked") blocked.push(card);
-		if (card.status === "doing" && card.plan === undefined) unplanned.push(card);
-		if (card.status === "doing" && now - card.updatedAt >= IDLE_MS) idle.push(card);
+		// The pool is what nobody holds, and the two lanes a lead watches are the two a card
+		// is worked in: a plan with a contract still missing is work started before it was
+		// agreed, and an execute nothing has touched is work that may have stopped.
+		if (card.lane === "backlog") unassigned.push(card);
+		if (card.lane === "done") done.push(card);
+		if (card.lane === "blocked") blocked.push(card);
+		if (card.lane === "plan") {
+			// A complete contract still needs a file to execute against: a card planned before
+			// the artifact rule has neither, and it belongs in the queue that leads somewhere.
+			if (missingContractFields(card.contract).length > 0 || card.planPath === undefined) unplanned.push(card);
+			else if (!contractApproved(card.contract)) unapproved.push(card);
+		}
+		if (card.lane === "execute" && now - card.updatedAt >= IDLE_MS) idle.push(card);
 
 		if (card.owner === undefined) continue;
 		const key = card.owner.label.toLowerCase();
 		const group = groups.get(key) ?? { label: card.owner.label, cards: [], done: [] };
-		if (card.status === "done") group.done.push(card);
+		if (card.lane === "done") group.done.push(card);
 		else group.cards.push(card);
 		groups.set(key, group);
 	}
@@ -87,6 +102,7 @@ export function buildRound<T extends Card = Card>(cards: readonly T[], now: numb
 		owners: [...groups.values()].sort((a, b) => a.label.localeCompare(b.label)),
 		unassigned,
 		unplanned,
+		unapproved,
 		blocked,
 		idle,
 		done,