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

package/lib/board/actions.ts

@@ -0,0 +1,111 @@
+/**
+ * The board's actions and which of them only read it.
+ *
+ * The list and the classification are one table because they were once two: the tool
+ * registered the actions, and `lib/` compared a call's action to a bare string, so
+ * nothing could prove the two agreed — a second read action would have been refused by
+ * plan mode and counted as work by the todo nudge, with every suite green.
+ *
+ * `BOARD_ACTION_KIND` is a `Record<BoardAction, …>`, so an action added to
+ * {@link BOARD_ACTIONS} does not compile until somebody says whether it reads. That is
+ * the whole point: the answer is a type error, not a comment.
+ *
+ * The refusal that names the reads is built here too, beside the table it derives from,
+ * for the same reason `limits.ts` keeps `wipRefusal` beside its limit: a sentence a model
+ * reads is the table said aloud, and a sentence written where it is printed is a second
+ * copy of the answer.
+ */
+
+/** The actions the tool accepts, in the order the description lists them. */
+export const BOARD_ACTIONS = [
+	"list",
+	"add",
+	"claim",
+	"release",
+	"reclaim",
+	"move",
+	"note",
+	"contract",
+	"approve",
+	"review",
+	"edit",
+	"archive",
+	"drop",
+] as const;
+
+/** One action. */
+export type BoardAction = (typeof BOARD_ACTIONS)[number];
+
+/** Whether an action reads the board or writes it. */
+export type BoardActionKind = "read" | "write";
+
+/**
+ * What each action does to the board.
+ *
+ * Exhaustive on purpose: a new action is a compile error here before it can be an
+ * unnoticed assumption in the read-only policy.
+ */
+export const BOARD_ACTION_KIND: Record<BoardAction, BoardActionKind> = {
+	list: "read",
+	add: "write",
+	claim: "write",
+	release: "write",
+	reclaim: "write",
+	move: "write",
+	note: "write",
+	contract: "write",
+	approve: "write",
+	review: "write",
+	edit: "write",
+	archive: "write",
+	drop: "write",
+};
+
+/**
+ * The actions that only read, in the tool's own order.
+ *
+ * Plan mode names them in its refusal, so the sentence a model reads is built from the
+ * table rather than from a second list of what counts as reading.
+ */
+export const BOARD_READ_ACTIONS: readonly BoardAction[] = BOARD_ACTIONS.filter(
+	(action) => BOARD_ACTION_KIND[action] === "read",
+);
+
+/**
+ * The reads as one phrase — `` `list` reads ``, or `` `list` or `archive` read `` — for the
+ * refusal that tells a model which action it may still use.
+ *
+ * The list is a parameter so both branches are testable: today exactly one action reads, so
+ * a sentence that inflected off the exported table could only ever ship its singular half
+ * tested. The phrase stays "or", not a comma list, because the reads are expected to stay
+ * few — one is the common case, and a second is a deliberate change to the policy.
+ */
+export function readActionsText(actions: readonly BoardAction[] = BOARD_READ_ACTIONS): string {
+	const named = actions.map((action) => `\`${action}\``).join(" or ");
+	return `${named} ${actions.length === 1 ? "reads" : "read"}`;
+}
+
+/**
+ * The refusal a board write meets while plan mode is on.
+ *
+ * Plan mode owns the rule and supplies its own exit guidance; the sentence is here because
+ * it is {@link readActionsText}'s sentence, and because the order it names is the board's:
+ * a claim comes before planning, and the plan is recorded once it is approved. Written once
+ * so the refusal and the docs cannot teach two different orders.
+ */
+export function boardWriteRefusal(rawAction: unknown, guidance: string): string {
+	const verb = typeof rawAction === "string" && rawAction.trim() !== "" ? rawAction.trim() : "board";
+	return `Plan mode: \`${verb}\` changes the board — only ${readActionsText()} it; claim the card before you plan, and record its plan once the plan is approved. ${guidance}`;
+}
+
+/**
+ * Whether a value is a board action that only reads.
+ *
+ * A call's `action` is whatever the model sent, so an unknown string is not a read:
+ * the answer has to be safe before the tool has normalized the argument.
+ */
+export function isBoardReadAction(raw: unknown): boolean {
+	if (typeof raw !== "string") return false;
+	if (!BOARD_ACTIONS.includes(raw as BoardAction)) return false;
+	return BOARD_ACTION_KIND[raw as BoardAction] === "read";
+}

package/lib/board/artifact.ts

@@ -0,0 +1,149 @@
+/**
+ * Whether a path is a plan of this repository: the board's half of the plan store.
+ *
+ * The board records the file a card is executed against, and that record is only worth
+ * something if the file is the one `plan` wrote. The board does not parse a plan — it
+ * resolves the path the model passed, requires it to be inside this repository's plan
+ * store, and requires it to be there. So a contract cannot name a path to nothing, and a
+ * card cannot enter `execute` on a plan somebody deleted after recording it.
+ *
+ * Two sentences per refusal, because the two moments ask different questions. At `contract`
+ * the question is "may this be recorded", and the way out is "write the plan, then pass the
+ * path it returned". At `execute` or `done` the question is "is the plan it recorded still
+ * there", and the way out follows the card's lane — a card in `plan` can record again, and
+ * one already executing has to come back to `plan` first, which is why {@link contractRoute}
+ * is here rather than in each caller. One resolution body answers both: the store's rules
+ * come from `plans/paths.ts`, so the board and the plan tool cannot disagree about what a
+ * plan path is.
+ *
+ * The board still never reads a plan. A `stat` is the whole check, which is why this module
+ * is the only place the board touches the plan store.
+ */
+
+import { statSync } from "node:fs";
+import { sanitizeLine, shortenPath } from "../format.ts";
+import { isInside } from "../path.ts";
+import { isContainedPlan, isPlanFileName, resolvePlanArg } from "../plans/paths.ts";
+import type { Card } from "./card.ts";
+import { cardRef } from "./card.ts";
+
+/** The plan a card is executed against, resolved and proved to exist. */
+export interface PlanArtifact {
+	/** The absolute path that was proved. */
+	path: string;
+	/**
+	 * The stored plan path the proof was computed for.
+	 *
+	 * Only a re-check of a record carries it, and the gate compares it: a fact proved for
+	 * one path cannot open a card whose recorded path is another, and a card whose path
+	 * changed between the read and the write is refused rather than forced.
+	 */
+	recorded?: string;
+}
+
+/**
+ * The resolved path, or the sentence refusing it.
+ *
+ * A union rather than two fields, so the tool hands the state machine one fact and the
+ * state machine decides which refusal a caller hears first — an owner-check that fails
+ * should be heard before a path that does not resolve.
+ */
+export type ArtifactCheck = PlanArtifact | { error: string };
+
+/** What is inside the store at a resolved path. */
+type Located =
+	/** Not inside the store at all, or reached through a link that leaves it. */
+	| { kind: "outside"; path: string }
+	/** Inside the store, but not a markdown plan file. */
+	| { kind: "named"; path: string }
+	/** A plan name; what is at it, if anything. */
+	| { kind: "plan"; path: string; file: boolean; present: boolean };
+
+/** Resolve `rawPath` against `planDir`, and say what the store holds there. */
+function locate(planDir: string, rawPath: string): Located {
+	const path = resolvePlanArg(planDir, rawPath);
+	if (!isContainedPlan(planDir, path)) {
+		// `isContainedPlan` answers both questions at once, so the name rule is asked again
+		// here: a `.txt` in the store deserves the sentence about its name, not about a link.
+		return isInside(planDir, path) && !isPlanFileName(path) ? { kind: "named", path } : { kind: "outside", path };
+	}
+	try {
+		const info = statSync(path);
+		return { kind: "plan", path, present: true, file: info.isFile() };
+	} catch {
+		return { kind: "plan", path, present: false, file: false };
+	}
+}
+
+/** One path as a refusal prints it: shortened, and never more than one line. */
+function at(path: string): string {
+	return sanitizeLine(shortenPath(path));
+}
+
+/**
+ * How a card records the plan again, which depends on the lane it is in.
+ *
+ * `contract` is written in `plan` and nowhere else, so a refusal that names it from
+ * `execute` would send a reader into another refusal — and from the pool the missing step is
+ * the claim. A finished card cannot be re-planned at all; that branch is unreachable through
+ * a gate, and says the fact rather than a route so the table is complete for its type.
+ */
+export function contractRoute(card: Pick<Card, "lane">): string {
+	switch (card.lane) {
+		case "plan":
+			return "record it with `contract`.";
+		case "backlog":
+			return "claim it, then record it with `contract`.";
+		case "blocked":
+		case "execute":
+			return "move it back to plan, then record it with `contract`.";
+		case "done":
+			return "a finished card's plan cannot change.";
+	}
+}
+
+/** What `contract` may record: a plan of this repository, already written. */
+export function planForContract(planDir: string, rawPath: string): ArtifactCheck {
+	const found = locate(planDir, rawPath);
+	if (found.kind === "outside") {
+		return {
+			error: `${at(found.path)} is not in this repository's plan store; \`plan\` action \`write\` saves into ${at(planDir)}.`,
+		};
+	}
+	if (found.kind === "named") {
+		return { error: `${at(found.path)} is not a markdown plan; \`plan\` action \`write\` saves into ${at(planDir)}.` };
+	}
+	if (!found.present) {
+		return {
+			error: `${at(found.path)} does not exist; \`plan\` action \`write\` saves the plan, and \`contract\` records the path it returns.`,
+		};
+	}
+	if (!found.file)
+		return { error: `${at(found.path)} is not a file; record the markdown file \`plan\` action \`write\` saves.` };
+	return { path: found.path };
+}
+
+/**
+ * What a card may enter `execute` or `done` on: the plan it recorded, still in the store.
+ *
+ * The recorded path may predate this rule — a card written when any string was accepted —
+ * which is why an outside path refuses here with the same route out as a missing file.
+ */
+export function planForExecute(planDir: string, card: Pick<Card, "id" | "lane" | "planPath">): ArtifactCheck {
+	const rawPath = card.planPath ?? "";
+	const found = locate(planDir, rawPath);
+	const route = ` ${contractRoute(card)}`;
+	if (found.kind === "outside") {
+		return { error: `${cardRef(card.id)}'s plan is outside this repository's plan store (${at(rawPath)});${route}` };
+	}
+	if (found.kind === "named") {
+		return { error: `${cardRef(card.id)}'s recorded plan is not a markdown file (${at(rawPath)});${route}` };
+	}
+	if (!found.present) {
+		return { error: `the plan recorded for ${cardRef(card.id)} is gone (${at(found.path)});${route}` };
+	}
+	if (!found.file) {
+		return { error: `the plan recorded for ${cardRef(card.id)} is not a file (${at(found.path)});${route}` };
+	}
+	return { path: found.path, recorded: rawPath };
+}

package/lib/board/card.ts

@@ -9,14 +9,36 @@
  *
  * The record is untrusted when it comes back off disk: a file may be half-written
  * by a process that died, hand-edited, or left by an older version. {@link isCard}
- * is the one gate every read passes, so the router, the tool, and the page see
- * the same record or none. Value-only: no I/O, no state.
+ * is the shape every read is held to; the reader that maps an older shape onto this
+ * one is `read.ts`, so the router, the tool, and the page see the same record or none.
+ * Value-only: no I/O, no state.
  */
 
 import { sanitizeLine } from "../format.ts";
+import { type Contract, isContract, isSign, type Sign } from "./contract.ts";
+import { LANE_RULES, LANES, type Lane } from "./lanes.ts";
 
 /** The schema version this build writes. A file with another value is refused, never migrated in place. */
-export const CARD_VERSION = 1;
+export const CARD_VERSION = 2;
+
+/**
+ * The card versions this build can read.
+ *
+ * A v1 file is the record before the lane and the block were renamed: `readCard` maps it
+ * and hands back a v2 card, and the file itself is rewritten only when the card is next
+ * written. A version above {@link CARD_VERSION} is a newer build's record, which this one
+ * names rather than guesses at.
+ */
+export const SUPPORTED_VERSIONS = [1, CARD_VERSION] as const;
+
+/**
+ * The ended-card record's own version.
+ *
+ * The ledger is not the card: it is written once, never read back, and must not move when
+ * the card record does, or every record a past build wrote would disagree with its own
+ * validator.
+ */
+export const ENDED_VERSION = 1;
 
 /** Longest title, in characters. One line, so it cannot wrap a lane row. */
 export const MAX_TITLE = 120;
@@ -27,12 +49,32 @@ export const MAX_PATHS = 12;
 /** Longest path hint, in characters. */
 export const MAX_PATH = 200;
 
-/** Longest recorded plan path, in characters. */
-export const MAX_PLAN = 300;
+/**
+ * Longest recorded plan path, in characters.
+ *
+ * The board records the *resolved* absolute path (a `~/…` form is expanded before it is
+ * stored), so this cap holds a machine path rather than a caller's shorthand: a deep agent
+ * directory plus a stamped plan name, with room for a platform's own limit.
+ */
+export const MAX_PLAN = 1024;
 
 /** Longest sentence saying what a blocked card is waiting on: one line, so it fits a row. */
 export const MAX_BLOCKED = 200;
 
+/**
+ * Why a card is blocked: what a person has to read before it moves again.
+ *
+ * A block is not one thing: a contract that turned out wrong, a dependency, and a decision
+ * a person owes the card are different errands. The kind is the card's own claim — the board
+ * records it and draws it, and nothing here can verify that a "contract" block really is
+ * one — so it explains the card rather than routing it: where a blocked card may go is
+ * decided by what it has, not by what it was parked on.
+ */
+export const BLOCKERS = ["contract", "dependency", "decision"] as const;
+
+/** One kind of block. */
+export type BlockerKind = (typeof BLOCKERS)[number];
+
 /** Longest single note, in characters. */
 export const MAX_NOTE = 1000;
 
@@ -61,12 +103,6 @@ export type Priority = (typeof PRIORITIES)[number];
 /** What an absent priority means: a card is ordinary until somebody says otherwise. */
 export const DEFAULT_PRIORITY: Priority = "normal";
 
-/** The lanes, in the order the page and the rollup read them. */
-export const CARD_STATUSES = ["todo", "doing", "blocked", "done"] as const;
-
-/** One lane a card can sit in. */
-export type CardStatus = (typeof CARD_STATUSES)[number];
-
 /** Who holds a card: the session id when it is known, and always the label it is addressed by. */
 export interface CardOwner {
 	/** Session id, when the claim came from a live session. */
@@ -75,6 +111,22 @@ export interface CardOwner {
 	label: string;
 }
 
+/**
+ * Why a card is blocked: the kind, and the sentence a person reads.
+ *
+ * One record rather than two sibling keys, because one fact deserves one key. The kind is
+ * absent only on a card written before it existed — a v1 block may hold the sentence alone
+ * — and every block this build writes carries one, because the move into `blocked`
+ * requires it. It says what kind of errand parked the card, and it is not a route: the way
+ * out is the lane the card's contract lets it resume in.
+ */
+export interface CardBlock {
+	/** Why it is blocked, when it was recorded. */
+	kind?: BlockerKind;
+	/** What it waits on, in one line; absent means the block was recorded without a sentence. */
+	note?: string;
+}
+
 /** One note: who wrote it, when, and what it says. */
 export interface CardNote {
 	by: string;
@@ -91,9 +143,17 @@ export interface CardNote {
  * page needs and the one a reader has no way to reconstruct.
  */
 export interface CardTransition {
-	status: CardStatus;
+	lane: Lane;
 	at: number;
 	by: string;
+	/**
+	 * What the card was parked on, when the lane entered is `blocked`.
+	 *
+	 * The present block is deleted when the card leaves `blocked`, so without this the
+	 * answer to "why did this sit for two days" dies with the resume. The log keeps it for
+	 * as long as the transition lives, which is the same bounded history as every other transition.
+	 */
+	block?: CardBlock;
 }
 
 /**
@@ -112,25 +172,29 @@ export interface CardLanded {
 /** One feature on the board. */
 export interface Card {
 	/** Schema version; an unknown value is refused rather than guessed at. */
-	v: 1;
+	v: 2;
 	/** `"4"`, shown as `#4`. Allocated by the store, never by a caller. */
 	id: string;
 	/** One line, ≤ {@link MAX_TITLE} — the feature's outcome. */
 	title: string;
-	status: CardStatus;
+	lane: Lane;
 	owner?: CardOwner;
 	/** Repository-relative hints, never claims. */
 	paths: string[];
-	/** The plan file being executed, once one is recorded. */
-	plan?: string;
+	/** The plan file the work is done against, once one is recorded. */
+	planPath?: string;
+	/** What the card promises before it may be executed, and who approved that wording. */
+	contract?: Contract;
+	/** Who spot-checked the finished work, and when: what a move to `done` requires. */
+	review?: Sign;
 	/**
-	 * What a blocked card is waiting on: the decision, in one line.
+	 * What the card is blocked on, while it is in `blocked`.
 	 *
-	 * `blocked` exists to say a human has to decide something — a dependency is a
-	 * different thing, and `waits` is what refuses a claim. Absent means the card was
-	 * blocked without saying why, which is a state the tool allows and the page names.
+	 * A dependency is a different thing, and `waits` is what refuses a claim; this is the
+	 * human decision a card was parked on. Absent unless the card is blocked, and deleted
+	 * when it leaves — the transition log keeps what it was.
 	 */
-	blockedBy?: string;
+	blocked?: CardBlock;
 	/** What closed a finished card: the commit at the move to `done`, and when. */
 	landed?: CardLanded;
 	/**
@@ -174,16 +238,22 @@ export interface Card {
  * that comes back is worse than an id that is gone — the same number would answer for
  * two different features. The store keeps one of these per ended card, writes it
  * before the card file goes, and never allocates its id again.
+ *
+ * The pile is a ledger, and this build never reads it back: the spent ids are the file
+ * names the allocator skips, and the record itself is for a person opening the directory.
+ * {@link isEndedCard} is the shape a reader would have to hold one to, and it is why the
+ * field is `lane` rather than the `status` an older record spells — nothing migrates a
+ * record no code path opens.
  */
 export interface EndedCard {
-	/** Schema version for the record itself; a reader refuses what it does not know. */
+	/** Schema version for the record itself; it moves with neither the card record nor time. */
 	v: 1;
 	/** The id that is now spent, without padding. */
 	id: string;
 	/** What the card was called, so a note that names its id still reads. */
 	title: string;
 	/** The lane it was in when it ended. */
-	status: CardStatus;
+	lane: Lane;
 	/** Who ended it. */
 	by: string;
 	/** The owner it had, when it had one. */
@@ -198,10 +268,10 @@ export interface EndedCard {
 export function isEndedCard(value: unknown): value is EndedCard {
 	if (typeof value !== "object" || value === null) return false;
 	const ended = value as Record<string, unknown>;
-	if (ended.v !== CARD_VERSION) return false;
+	if (ended.v !== ENDED_VERSION) return false;
 	if (typeof ended.id !== "string" || !/^[0-9]+$/.test(ended.id)) return false;
 	if (typeof ended.title !== "string" || ended.title === "") return false;
-	if (!CARD_STATUSES.includes(ended.status as CardStatus)) return false;
+	if (!LANES.includes(ended.lane as Lane)) return false;
 	if (typeof ended.by !== "string" || ended.by === "") return false;
 	if (!isOwner(ended.owner)) return false;
 	if (typeof ended.at !== "number" || !Number.isInteger(ended.at)) return false;
@@ -268,7 +338,7 @@ export function priorityOf(card: Card): Priority {
 }
 
 /** A card's dependencies, with the absent field read as its meaning. */
-export function dependsOf(card: Card): readonly string[] {
+export function dependsOf(card: Pick<Card, "dependsOn">): readonly string[] {
 	return card.dependsOn ?? [];
 }
 
@@ -283,7 +353,7 @@ export function dependsOf(card: Card): readonly string[] {
  */
 export function laneSince(card: Card): number | undefined {
 	const last = card.log?.at(-1);
-	return last !== undefined && last.status === card.status ? last.at : undefined;
+	return last !== undefined && last.lane === card.lane ? last.at : undefined;
 }
 
 /** Where a card's priority sits in {@link PRIORITIES}: the lane sort's first key after the lane. */
@@ -309,7 +379,7 @@ export function matchesQuery(card: Card, query: string): boolean {
 	if (card.title.toLowerCase().includes(needle)) return true;
 	if (card.owner !== undefined && card.owner.label.toLowerCase().includes(needle)) return true;
 	if (card.paths.some((path) => path.toLowerCase().includes(needle))) return true;
-	if (card.plan !== undefined && card.plan.toLowerCase().includes(needle)) return true;
+	if (card.planPath !== undefined && card.planPath.toLowerCase().includes(needle)) return true;
 	return card.notes.some((note) => note.text.toLowerCase().includes(needle));
 }
 
@@ -328,8 +398,10 @@ export function normalizeNote(raw: unknown): { text: string } | FieldError {
 /**
  * The recorded plan path: one line, and nothing more.
  *
- * The board never reads the plan, so it does not resolve or check the path — this
- * is a note to the reader about which plan the card is executing.
+ * The board never reads the plan: `artifact.ts` resolves the caller's path against this
+ * repository's plan store and proves it is there, and `contract` stores what came back, so
+ * what arrives here is already an absolute path. This only holds it to one line and
+ * {@link MAX_PLAN}.
  */
 export function normalizePlanPath(raw: unknown): { path: string } | FieldError {
 	if (typeof raw !== "string") return { error: "path is required." };
@@ -340,19 +412,26 @@ export function normalizePlanPath(raw: unknown): { path: string } | FieldError {
 }
 
 /**
- * The sentence a block records: one line, and nothing more.
+ * The block a move records: one kind, and the sentence when one is given.
  *
- * The board never resolves it against anything — it is the reader's explanation of what
- * a person has to decide — so this only keeps it to a length a row can hold.
+ * The refusals name the tool's parameters (`blocker`, `blockedBy`) rather than the record's
+ * fields, because this is the boundary the model's arguments pass, and the model wrote a
+ * parameter. The kind is required here — a block this build writes always says what kind it
+ * is — and the sentence is not: a card may be parked with nothing written down.
  */
-export function normalizeBlockedBy(raw: unknown): { blockedBy: string } | FieldError {
-	if (typeof raw !== "string") return { error: "blockedBy must be text." };
-	const blockedBy = sanitizeLine(raw).trim();
-	if (blockedBy === "") return { error: "blockedBy must say what the card waits on." };
-	if (blockedBy.length > MAX_BLOCKED) {
+export function normalizeBlock(rawKind: unknown, rawNote: unknown): { blocked: CardBlock } | FieldError {
+	const allowed = BLOCKERS.join(", ");
+	const kind = typeof rawKind === "string" ? sanitizeLine(rawKind).trim().toLowerCase() : "";
+	const known = BLOCKERS.find((entry) => entry === kind);
+	if (known === undefined) return { error: `blocker must be one of ${allowed}.` };
+	if (rawNote === undefined) return { blocked: { kind: known } };
+	if (typeof rawNote !== "string") return { error: "blockedBy must be text." };
+	const note = sanitizeLine(rawNote).trim();
+	if (note === "") return { error: "blockedBy must say what the card waits on." };
+	if (note.length > MAX_BLOCKED) {
 		return { error: `blockedBy must be at most ${MAX_BLOCKED} characters.` };
 	}
-	return { blockedBy };
+	return { blocked: { kind: known, note } };
 }
 
 /** A card id as a caller writes it (`4`, `#4`), or undefined when it is not one. */
@@ -381,13 +460,28 @@ export function signatureOf(cards: readonly Card[]): string {
 		.join(",");
 }
 
+/**
+ * Whether `actor` is the owner of `card`.
+ *
+ * The id decides when both sides have one — a session that renamed itself is still the same
+ * holder — and the label decides otherwise, case-insensitively, the way the bus resolves a
+ * target. A signature that takes the actor structurally is what lets the record own this
+ * rule while `rules.ts` and `steps.ts` share it without importing each other.
+ */
+export function holds(card: Card, actor: { id?: string; label: string }): boolean {
+	const owner = card.owner;
+	if (owner === undefined) return false;
+	if (owner.id !== undefined && actor.id !== undefined) return owner.id === actor.id;
+	return owner.label.toLowerCase() === actor.label.toLowerCase();
+}
+
 /**
  * Whether `value` is a card this build can trust.
  *
- * Shape *and* the two invariants a bug could otherwise smuggle past the rules: a
- * `todo` card has no owner, and the other three lanes always have one. A card that
- * fails here is dropped by the reader rather than repaired, because a repair would
- * guess at which half of the record was meant.
+ * Shape *and* the invariants a bug could otherwise smuggle past the rules: the one
+ * ownerless lane really has no owner, and the others always have one. A card that fails
+ * here is dropped by the reader rather than repaired, because a repair would guess at
+ * which half of the record was meant.
  */
 export function isCard(value: unknown): value is Card {
 	if (typeof value !== "object" || value === null) return false;
@@ -395,12 +489,17 @@ export function isCard(value: unknown): value is Card {
 	if (card.v !== CARD_VERSION) return false;
 	if (typeof card.id !== "string" || !/^[0-9]+$/.test(card.id)) return false;
 	if (typeof card.title !== "string" || card.title === "") return false;
-	if (!CARD_STATUSES.includes(card.status as CardStatus)) return false;
+	if (!LANES.includes(card.lane as Lane)) return false;
+	// The lane was just proved to be one of `LANES`, which is the whole guarantee the cast
+	// names: from here the table can be addressed by it.
+	const lane = card.lane as Lane;
 	if (!isOwner(card.owner)) return false;
 	if (!Array.isArray(card.paths) || card.paths.length > MAX_PATHS) return false;
 	if (!card.paths.every((path) => typeof path === "string")) return false;
-	if (card.plan !== undefined && typeof card.plan !== "string") return false;
-	if (card.blockedBy !== undefined && !isBlockedBy(card.blockedBy)) return false;
+	if (card.planPath !== undefined && typeof card.planPath !== "string") return false;
+	if (card.contract !== undefined && !isContract(card.contract)) return false;
+	if (card.review !== undefined && !isSign(card.review)) return false;
+	if (card.blocked !== undefined && !isBlock(card.blocked)) return false;
 	if (card.landed !== undefined && !isLanded(card.landed)) return false;
 	if (card.offeredAt !== undefined && (typeof card.offeredAt !== "number" || !Number.isInteger(card.offeredAt))) {
 		return false;
@@ -416,12 +515,23 @@ export function isCard(value: unknown): value is Card {
 	if (typeof card.rev !== "number" || !Number.isInteger(card.rev) || card.rev < 1) return false;
 	if (typeof card.createdAt !== "number" || typeof card.updatedAt !== "number") return false;
 	if (typeof card.by !== "string") return false;
-	return (card.status === "todo") === (card.owner === undefined);
+	// One ownerless lane, and the table says which: a pool card has no holder, and every
+	// card that is somebody's work has one.
+	return LANE_RULES[lane].ownerless === (card.owner === undefined);
 }
 
-/** A recorded block: one line the reader can hold, within the cap this build writes. */
-function isBlockedBy(value: unknown): value is string {
-	return typeof value === "string" && value !== "" && value.length <= MAX_BLOCKED;
+/**
+ * A recorded block: a kind this build knows when one is there, and a sentence a row can
+ * hold when one is there — at least one of the two, because an empty block says nothing.
+ */
+function isBlock(value: unknown): value is CardBlock {
+	if (typeof value !== "object" || value === null) return false;
+	const block = value as Record<string, unknown>;
+	if (block.kind !== undefined && !BLOCKERS.includes(block.kind as BlockerKind)) return false;
+	if (block.note !== undefined) {
+		if (typeof block.note !== "string" || block.note === "" || block.note.length > MAX_BLOCKED) return false;
+	}
+	return block.kind !== undefined || block.note !== undefined;
 }
 
 /** A recorded landing: a commit id and the moment it closed the card. */
@@ -454,12 +564,13 @@ function isDepends(value: unknown): boolean {
 	return true;
 }
 
-/** A recorded lane change: a lane, a moment, and who moved it. */
+/** A recorded lane change: a lane, a moment, and who moved it, and what it parked on. */
 function isTransition(value: unknown): value is CardTransition {
 	if (typeof value !== "object" || value === null) return false;
 	const entry = value as Record<string, unknown>;
+	if (entry.block !== undefined && !isBlock(entry.block)) return false;
 	return (
-		CARD_STATUSES.includes(entry.status as CardStatus) &&
+		LANES.includes(entry.lane as Lane) &&
 		typeof entry.at === "number" &&
 		Number.isInteger(entry.at) &&
 		typeof entry.by === "string" &&