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

package/lib/board/config.ts

@@ -0,0 +1,58 @@
+/**
+ * The `board` section of `bytefly.json`: the two numbers a lane is held to, and the name a
+ * signature has to carry.
+ *
+ * Both are one setting because they are read together, once, when the store opens: a board that
+ * asked the file on every write would spend a stat to answer a question nobody changed, and two
+ * readers of one section are how the settings screen and the gate drift apart. The arithmetic of
+ * a limit stays in `limits.ts` and the signer rule stays in `lead.ts`; this module is the file.
+ *
+ * `extensions/bytefly` imports it too, so `/bytefly settings` shows what the loader keeps rather
+ * than a declared copy of the default. That is allowed because it is `lib/`: a shared body, not
+ * one extension reaching into another.
+ */
+
+import { asRecord, loadConfigSection } from "../config.ts";
+import { type Lead, normalizeLead } from "./lead.ts";
+import { DEFAULT_WIP, normalizeWip, type WipLimits } from "./limits.ts";
+
+/** What one board's `board` section says. */
+export interface BoardConfig {
+	/** How many cards `plan` and `execute` may hold. */
+	wip: WipLimits;
+	/** The team name whose signature satisfies the two gates. */
+	lead: Lead;
+}
+
+/**
+ * The lead when nobody named one.
+ *
+ * A role word rather than a person: the page serves under whatever this is, so the session that
+ * opens `/board` takes it and can sign. A repository renames the lead with `board.lead`, and no
+ * module states a name of its own — `lead.ts` knows the rule, `seat.ts` derives an id from the
+ * name, and this is the one place a default is chosen.
+ */
+export const DEFAULT_LEAD: Lead = "lead";
+
+/** A board's settings when nobody said otherwise: three planning, five in flight, and the lead. */
+export const DEFAULT_BOARD_CONFIG: BoardConfig = { wip: DEFAULT_WIP, lead: DEFAULT_LEAD };
+
+/**
+ * The settings a config section asks for.
+ *
+ * Each key falls back on its own, so a file that sets only `execute` keeps the ordinary `plan`
+ * limit rather than a zero that would freeze the board, and one that sets only `lead` keeps both
+ * numbers. The project's layer is normalized over the global one, so a key the nearer file does
+ * not state keeps the farther file's answer.
+ */
+export function normalizeBoardConfig(
+	raw: Record<string, unknown> | undefined,
+	base: BoardConfig = DEFAULT_BOARD_CONFIG,
+): BoardConfig {
+	return { wip: normalizeWip(asRecord(raw?.wip), base.wip), lead: normalizeLead(raw?.lead, base.lead) };
+}
+
+/** One board's settings: the project's `bytefly.json` over the global one. */
+export function readBoardConfig(cwd: string, options: { agentDir?: string } = {}): BoardConfig {
+	return loadConfigSection(cwd, "board", DEFAULT_BOARD_CONFIG, (raw, base) => normalizeBoardConfig(raw, base), options);
+}

package/lib/board/contract.ts

@@ -0,0 +1,113 @@
+/**
+ * The contract: the three lines a card must state before it may be executed.
+ *
+ * A card is one feature, and the board's job in the PLAN lane is to say what "done" means
+ * *before* anybody starts — goal, acceptance, and what is deliberately out of scope — so a
+ * session that picks the card up does not renegotiate it, and a session that finishes it
+ * can be checked against something it did not write. The contract is three one-line fields
+ * on the card file: the plan file says how, the contract says what and why.
+ *
+ * The approval is part of the contract because it is a statement about *this* wording: a
+ * changed line is an unapproved one, and every write here drops the sign. A {@link Sign}
+ * records who read it and when, which is all a file can say about a person.
+ *
+ * Value-only: the field caps, the boundary the model's arguments pass, and the shapes
+ * `isCard` validates. No I/O, no clock, and no card — a caller that has one reads
+ * `card.contract`.
+ */
+
+import { sanitizeLine } from "../format.ts";
+
+/** The three lines of a contract, in the order a reader and a refusal name them. */
+export const CONTRACT_FIELDS = ["goal", "acceptance", "scopeOut"] as const;
+
+/** One line of a contract. */
+export type ContractField = (typeof CONTRACT_FIELDS)[number];
+
+/** Longest single contract line, in characters. One line, so it fits a row and a dialog rung. */
+export const MAX_CONTRACT = 400;
+
+/** Who read something and when: an approval of a contract, or a spot-check of finished work. */
+export interface Sign {
+	/** The session that signed, as the label a card records. */
+	by: string;
+	/** When it signed. */
+	at: number;
+}
+
+/** What a card promises before it may be executed. */
+export interface Contract {
+	/** What the feature is for, in one line. */
+	goal: string;
+	/** How a reader can tell it is done, in one line. */
+	acceptance: string;
+	/** What this deliberately does not do, so a reviewer does not ask for it. */
+	scopeOut: string;
+	/** Who approved this wording, and when. Absent until somebody who does not hold the card reads it. */
+	approved?: Sign;
+}
+
+/** A rejected field, phrased for the model: what was wrong, not that something was. */
+export type FieldError = { error: string };
+
+/** One contract line as stored: one sanitized line, or the reason it cannot be one. */
+export function normalizeContractField(field: ContractField, raw: unknown): { text: string } | FieldError {
+	if (typeof raw !== "string") return { error: `${field} is required.` };
+	const text = sanitizeLine(raw).trim();
+	if (text === "") return { error: `${field} is required.` };
+	if (text.length > MAX_CONTRACT) return { error: `${field} must be at most ${MAX_CONTRACT} characters.` };
+	return { text };
+}
+
+/** The fields a contract still needs, in {@link CONTRACT_FIELDS} order. */
+export function missingContractFields(contract: Contract | undefined): ContractField[] {
+	if (contract === undefined) return [...CONTRACT_FIELDS];
+	return CONTRACT_FIELDS.filter((field) => contract[field].trim() === "");
+}
+
+/** Whether a contract is complete enough to be approved. */
+export function contractComplete(contract: Contract | undefined): boolean {
+	return missingContractFields(contract).length === 0;
+}
+
+/** Whether a contract has been approved, by anybody at all. */
+export function contractApproved(contract: Contract | undefined): boolean {
+	return contract?.approved !== undefined;
+}
+
+/**
+ * The contract with `changed` applied, and no approval on it.
+ *
+ * A changed line is an unapproved one: the sign names a wording, so keeping it across an
+ * edit would let a session approve one contract and execute another. A caller that changed
+ * nothing does not call this.
+ */
+export function mergedContract(
+	contract: Contract | undefined,
+	changed: Partial<Record<ContractField, string>>,
+): Contract {
+	const next: Contract = {
+		goal: changed.goal ?? contract?.goal ?? "",
+		acceptance: changed.acceptance ?? contract?.acceptance ?? "",
+		scopeOut: changed.scopeOut ?? contract?.scopeOut ?? "",
+	};
+	return next;
+}
+
+/** Whether `value` is a sign this build can trust: a name and a whole moment. */
+export function isSign(value: unknown): value is Sign {
+	if (typeof value !== "object" || value === null) return false;
+	const sign = value as Record<string, unknown>;
+	return typeof sign.by === "string" && sign.by !== "" && typeof sign.at === "number" && Number.isInteger(sign.at);
+}
+
+/** Whether `value` is a contract this build can trust. */
+export function isContract(value: unknown): value is Contract {
+	if (typeof value !== "object" || value === null) return false;
+	const contract = value as Record<string, unknown>;
+	for (const field of CONTRACT_FIELDS) {
+		const line = contract[field];
+		if (typeof line !== "string" || line === "" || line.length > MAX_CONTRACT) return false;
+	}
+	return contract.approved === undefined || isSign(contract.approved);
+}

package/lib/board/join.ts

@@ -0,0 +1,38 @@
+/**
+ * The one join both surfaces ask for: the ask-once rule, and what a failure means.
+ *
+ * `board` joins when the page opens and when a card is claimed; `team` joins when a card
+ * is claimed through the round, and `/team join` asks the bus directly. The asking is
+ * shared because the rule around it is easy to get different in two places: ask only
+ * while the standing does not say this session is on the team, so a card write costs one
+ * request per session rather than one per card, and never let the join undo a card that
+ * was already written — a bus that is not loaded is a sentence, not an exception.
+ *
+ * `lib/` is value-only, so the join and the standing arrive as parameters, exactly as the
+ * store does for the tools.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "../errors.ts";
+import type { TeamJoin } from "../session-tool.ts";
+import type { TeamStanding } from "./session.ts";
+
+/**
+ * Put this session on the team, once.
+ *
+ * A failure is recorded and asked again by the next claim; a join that threw is
+ * swallowed here for the same reason, because the card it came after is already true.
+ */
+export async function joinOnce(
+	standing: TeamStanding,
+	team: TeamJoin,
+	ctx: ExtensionContext,
+	label: string,
+): Promise<void> {
+	if (standing.last()?.ok === true) return;
+	try {
+		standing.record(await team.join(ctx, { label }));
+	} catch (error) {
+		standing.record({ ok: false, error: messageOf(error) });
+	}
+}

package/lib/board/lanes.ts

@@ -0,0 +1,182 @@
+/**
+ * The board's lane vocabulary, and the one table that decides what each lane means.
+ *
+ * Five lanes, and a card is in exactly one of them: `backlog` is the pool nobody holds,
+ * `plan` is where a contract is written and approved, `execute` is where the work happens,
+ * `blocked` is a card waiting on a person, and `done` is closed. A lane is not a status
+ * among others — an approval and a review are facts about a card, not places it can be —
+ * so every surface reads this table rather than spelling a label, a colour, or a rule of
+ * its own. The page receives it in the snapshot, the tool's schema is generated from
+ * {@link LANES}, and `card.ts` reads the ownership invariant off `ownerless`.
+ *
+ * {@link TRANSITIONS} is the other half: the lanes a move may join, and what that move
+ * requires first. `rules.ts` enforces the requirements and the tool stops carrying a
+ * second copy of the list, which is how one surface came to offer a move another refused.
+ *
+ * Value-only: no I/O, no clock, no card. A caller that has a card reads `card.lane`.
+ */
+
+/** The lanes, in the order the page, the rollup, and the transcript read them. */
+export const LANES = ["backlog", "plan", "execute", "blocked", "done"] as const;
+
+/** One lane a card can sit in. */
+export type Lane = (typeof LANES)[number];
+
+/**
+ * The colours a lane may wear: the page's kit names them as properties, and
+ * `extensions/board/tone.ts` bridges them to the terminal's own roles — the two
+ * vocabularies are not shared, which is what that bridge exists for.
+ */
+export type LaneRole = "muted" | "warn" | "accent" | "danger" | "success";
+
+/** What one lane means, in the words every surface uses. */
+export interface LaneRule {
+	/** The word a head, a row, and a sentence print: one name for one lane. */
+	label: string;
+	/** What an empty tray says, so a lane with no work reads as a fact rather than a blank. */
+	empty: string;
+	/** The colour the lane's dot, its reason line, and its dialog state take. */
+	role: LaneRole;
+	/**
+	 * Whether a card in this lane has no owner.
+	 *
+	 * `backlog` is the pool, so a card nobody has taken belongs there; every other lane is
+	 * somebody's, which is what a claim, a release, and `isCard`'s invariant turn on.
+	 */
+	ownerless: boolean;
+	/** Whether the lane is the end of the line: nothing moves out of it. */
+	terminal: boolean;
+	/** Whether the lane admits cards by pull, and so is held to a WIP limit. */
+	pulled: boolean;
+}
+
+/** One rule per lane, keyed by the lane itself so a lane cannot arrive without one. */
+export const LANE_RULES: Record<Lane, LaneRule> = {
+	backlog: {
+		label: "Backlog",
+		empty: "the pool is empty",
+		role: "muted",
+		ownerless: true,
+		terminal: false,
+		pulled: false,
+	},
+	plan: {
+		label: "Plan",
+		empty: "nothing being planned",
+		role: "warn",
+		ownerless: false,
+		terminal: false,
+		pulled: true,
+	},
+	execute: {
+		label: "Execute",
+		empty: "nothing in flight",
+		role: "accent",
+		ownerless: false,
+		terminal: false,
+		pulled: true,
+	},
+	blocked: {
+		label: "Blocked",
+		empty: "nothing blocked",
+		role: "danger",
+		ownerless: false,
+		terminal: false,
+		pulled: false,
+	},
+	done: {
+		label: "Done",
+		empty: "nothing finished yet",
+		role: "success",
+		ownerless: false,
+		terminal: true,
+		pulled: false,
+	},
+};
+
+/**
+ * What a move must satisfy before it is allowed.
+ *
+ * Each name is one gate `rules.ts` can answer from the card, the board, and the fact the
+ * caller handed in: `contract` is the three lines being present, `approval` is somebody who
+ * does not hold the card having read them, `review` is the same for the finished work,
+ * `artifact` is the plan file the card is executed against — recorded, and proved to be in
+ * this repository's plan store — `blocker` is the recorded reason and kind, and `waiting` is
+ * no unfinished dependency. The blocker's own kind is a label: where a blocked card may go is
+ * decided by what it has, not by what it was parked on.
+ */
+export const REQUIREMENTS = ["contract", "approval", "review", "artifact", "blocker", "waiting"] as const;
+
+/** One requirement a transition may carry. */
+export type Requirement = (typeof REQUIREMENTS)[number];
+
+/** One lane change a `move` may make, and the gates in front of it. */
+export interface Transition {
+	from: Lane;
+	to: Lane;
+	/** Checked in this order, so a card missing two things hears about the first. */
+	needs: readonly Requirement[];
+}
+
+/**
+ * The lane changes a `move` may make.
+ *
+ * Absent pairs are refused, and the two absences that matter are deliberate: nothing moves
+ * *into* `backlog` (a card nobody holds is `release`'s or `reclaim`'s decision, not a
+ * move's), and nothing moves *out of* `done` (finished work is history). Re-planning is
+ * `execute → plan`, and a blocked card goes back to `plan` or resumes in `execute` — either
+ * one into a lane that has room for it, since a park frees a slot rather than reserving one.
+ *
+ * The dependency gate is not one of these: it belongs to the pull out of the pool, which
+ * `claim` asks itself, and to `execute` and `done`. Planning is where a wait is read against
+ * the contract, so a card may be planned before the work it waits on is finishable.
+ *
+ * `execute` has two doors and asks the same gates at both: no unfinished dependency, the
+ * contract's three lines, the plan file the card is executed against, and the approval a
+ * session that does not hold the card gave. The plan joins the contract rather than `done`
+ * because a plan recorded after the work began is a note about what happened, not the
+ * agreement the work was done against. So the way out of a block follows the card's state
+ * rather than the block's kind — a card parked from `plan` cannot enter `execute` until it
+ * has been planned, proved, and approved, and one parked from `execute` already carries all
+ * three and resumes.
+ */
+export const TRANSITIONS: readonly Transition[] = [
+	{ from: "backlog", to: "plan", needs: [] },
+	{ from: "plan", to: "execute", needs: ["waiting", "contract", "artifact", "approval"] },
+	{ from: "plan", to: "blocked", needs: ["blocker"] },
+	{ from: "execute", to: "plan", needs: [] },
+	{ from: "execute", to: "blocked", needs: ["blocker"] },
+	{ from: "execute", to: "done", needs: ["waiting", "review", "artifact"] },
+	{ from: "blocked", to: "plan", needs: [] },
+	{ from: "blocked", to: "execute", needs: ["waiting", "contract", "artifact", "approval"] },
+];
+
+/** The one transition from `from` to `to`, or `undefined` when a move may not make it. */
+export function transitionOf(from: Lane, to: Lane): Transition | undefined {
+	return TRANSITIONS.find((transition) => transition.from === from && transition.to === to);
+}
+
+/** Where a lane sits in {@link LANES}: the order a listing, a tray, and a rollup share. */
+export function laneIndex(lane: Lane): number {
+	return LANES.indexOf(lane);
+}
+
+/** Whether `value` is one of the lanes, so an untrusted lane is a refusal and not a crash. */
+export function isLane(value: unknown): value is Lane {
+	return typeof value === "string" && LANES.includes(value as Lane);
+}
+
+/** The lanes a `move` may name, in lane order: everything but `backlog`, which `release` reaches. */
+export function movableLanes(): Lane[] {
+	return LANES.filter((lane) => lane !== "backlog");
+}
+
+/**
+ * The lanes a `move` from `lane` may reach, in lane order.
+ *
+ * A tool description and a refusal both read this: the alternative is the hand-written list
+ * that drifted from `rules.ts` and offered a target the rule then refused.
+ */
+export function targetsFrom(lane: Lane): Lane[] {
+	return LANES.filter((to) => transitionOf(lane, to) !== undefined);
+}

package/lib/board/lead.ts

@@ -0,0 +1,130 @@
+/**
+ * Who may sign a card's two gates: the lead, and the person at the keyboard.
+ *
+ * `approve` and `review` are the board's one human judgement — a contract somebody read and a
+ * piece of work somebody looked at — so the signature has to belong to somebody accountable
+ * rather than to whichever peer answered first. The lead is a team name in `bytefly.json`
+ * (`board.lead`, defaulting to the page's seat — `board/seat.ts` — in `config.ts`), because that is
+ * the one identity a pure rule can be handed and a card file can record; the person is the one
+ * actor a file can name that is not a holder, which is what keeps a repository worked by one
+ * session able to close a card at all.
+ *
+ * The signer is refused in two shapes and this module owns both: a session that is not the lead
+ * (`signRefusal`), and a lead that holds the card it means to sign (`holderRefusal` — release it
+ * first, since a session signing its own wording is the gate approving itself). The words of each
+ * sign live in one table here, so the two gates and the lane requirements that ask for a
+ * signature cannot drift into four slightly different sentences.
+ *
+ * Pure: a name compare and a sentence, no clock and no file.
+ */
+
+import { normalizeLabel } from "../session-label.ts";
+import { cardRef, type Card } from "./card.ts";
+import type { Actor } from "./rules.ts";
+
+/** The lead's team name: the label a signature has to carry. */
+export type Lead = string;
+
+/**
+ * The person at the keyboard, as a write is made.
+ *
+ * `/board approve` and `/board review` write as this label, so a repository worked by one
+ * session is not stuck behind its own holder rule, and the record says who signed.
+ */
+export const PERSON_LABEL = "you";
+
+/** The id the person's actor carries: a prefix no session id uses, so a label cannot stand in. */
+export const PERSON_ID = "person:you";
+
+/** The actor a command writes as: the person's label, and an id a session cannot have. */
+export function personActor(): Actor {
+	return { id: PERSON_ID, label: PERSON_LABEL };
+}
+
+/** Whether `actor` is the person at the keyboard rather than a session. */
+export function isPerson(actor: Pick<Actor, "id">): boolean {
+	return actor.id === PERSON_ID;
+}
+
+/**
+ * The lead's name as a config file says it, or the running one when it says nothing usable.
+ *
+ * A blank string is not a lead called nothing: it is a file that said nothing, so the layer
+ * below keeps its answer, and a name is flattened and capped by the same rule every label is.
+ */
+export function normalizeLead(raw: unknown, base: Lead): Lead {
+	return typeof raw === "string" ? normalizeLabel(raw, base) : base;
+}
+
+/**
+ * Whether `actor` is the lead.
+ *
+ * A label compare, the way a teammate is addressed — not `holds`, which asks whether a session
+ * owns a card and prefers the ids when both sides have one.
+ */
+export function isLead(actor: Pick<Actor, "label">, lead: Lead): boolean {
+	return actor.label.toLowerCase() === lead.toLowerCase();
+}
+
+/** The two signs a card carries. */
+export type Sign = "approve" | "review";
+
+/** The two signs, in the order a person is likely to want them. */
+export const SIGN_KINDS: readonly Sign[] = ["approve", "review"];
+
+/** `word` as one of the two signs, or `undefined` when it is not one. */
+export function signOf(word: string): Sign | undefined {
+	return SIGN_KINDS.find((sign) => sign === word);
+}
+
+/** The words one sign is refused with, wherever the refusal is written. */
+interface SignWords {
+	/** What a session that is not the lead is told. */
+	readonly notSigner: (card: Card, actor: Actor, lead: Lead) => string;
+	/** What a holder that is not the lead is told. */
+	readonly holder: string;
+	/** What a holder that is the lead has to do first. */
+	readonly release: string;
+	/** What the move gate says when nobody has signed: the way out, naming the lead. */
+	readonly missing: (card: Card, lead: Lead) => string;
+}
+
+const SIGN_WORDS: Record<Sign, SignWords> = {
+	approve: {
+		notSigner: (card, actor, lead) =>
+			`${cardRef(card.id)}'s contract is signed by the lead (${lead}); this session is ${actor.label}. The person signs it with \`/board approve ${card.id}\`.`,
+		holder: "Its contract is signed by the lead, who does not hold it.",
+		release: "A lead releases a card before signing it.",
+		missing: (card, lead) =>
+			`${cardRef(card.id)} is in plan; its contract is not approved yet. The lead (${lead}) approves with \`approve\`, or the person with \`/board approve ${card.id}\`.`,
+	},
+	review: {
+		notSigner: (card, actor, lead) =>
+			`${cardRef(card.id)} is spot-checked by the lead (${lead}); this session is ${actor.label}. The person signs with \`/board review ${card.id}\`.`,
+		holder: "A card is spot-checked by the lead, who does not hold it.",
+		release: "A lead releases a card before spot-checking it.",
+		missing: (card, lead) =>
+			`${cardRef(card.id)} has no spot-check recorded. The lead (${lead}) records one with \`review\`, or the person with \`/board review ${card.id}\`.`,
+	},
+};
+
+/**
+ * Why `actor` may not sign `card`, or `undefined` when it may.
+ *
+ * The holder is the caller's own check: this asks only whether the actor is the person or the
+ * lead, because those are the two answers the gate accepts.
+ */
+export function signRefusal(card: Card, actor: Actor, lead: Lead, sign: Sign): string | undefined {
+	if (isPerson(actor) || isLead(actor, lead)) return undefined;
+	return SIGN_WORDS[sign].notSigner(card, actor, lead);
+}
+
+/** What a holder is told when it means to sign its own card: what the lead does, or what it is. */
+export function holderRefusal(actor: Actor, lead: Lead, sign: Sign): string {
+	return isLead(actor, lead) ? SIGN_WORDS[sign].release : SIGN_WORDS[sign].holder;
+}
+
+/** What a lane that needs a sign nobody gave says: the lead approves it, or the person signs. */
+export function missingSign(card: Card, lead: Lead, sign: Sign): string {
+	return SIGN_WORDS[sign].missing(card, lead);
+}

package/lib/board/limits.ts

@@ -0,0 +1,78 @@
+/**
+ * How many cards a pulled lane may hold, and the sentence that refuses the next one.
+ *
+ * The board is a pull system: a session takes a backlog card into `plan`, and from there
+ * into `execute`. Both lanes are limited, because the binding constraint in this flow is
+ * the person who approves a contract and spot-checks the work, not the number of cards a
+ * session can start. The limit is a hard gate rather than a hint — a lane that is over its
+ * limit is a queue nobody is reviewing, and a warning nobody reads is the same as no limit.
+ *
+ * The two numbers are turned into a {@link WipLimits} here and clamped to `1..MAX_WIP`, so a
+ * typo cannot stop a board; where they are read from is `config.ts`, which reads the whole
+ * `board` section once per store and hands it to `applyOp`. That keeps `rules.ts` pure: the
+ * rule decides, the owner of the setting supplies the number, and this module is only the
+ * arithmetic and the sentence.
+ */
+
+import { clampInteger } from "../config.ts";
+import { LANE_RULES, type Lane } from "./lanes.ts";
+
+/** The lanes a limit applies to: the two a card is pulled into. */
+export type LimitedLane = "plan" | "execute";
+
+/** The limits one board enforces. */
+export type WipLimits = Record<LimitedLane, number>;
+
+/** A board's limits when nobody said otherwise: three being planned, five in flight. */
+export const DEFAULT_WIP: WipLimits = { plan: 3, execute: 5 };
+
+/** The largest limit a misconfigured file may ask for. */
+export const MAX_WIP = 20;
+
+/**
+ * The limits a config section asks for, each clamped into range.
+ *
+ * A missing key keeps the default, so a user who sets only `execute` keeps the ordinary
+ * `plan` limit rather than a zero that would freeze the board.
+ */
+export function normalizeWip(raw: Record<string, unknown> | undefined, base: WipLimits = DEFAULT_WIP): WipLimits {
+	return {
+		plan: clampInteger(raw?.plan, base.plan, 1, MAX_WIP),
+		execute: clampInteger(raw?.execute, base.execute, 1, MAX_WIP),
+	};
+}
+
+/** The limit a lane is held to, or `undefined` when the lane is not pulled. */
+export function limitOf(lane: Lane, limits: WipLimits): number | undefined {
+	return LANE_RULES[lane].pulled ? limits[lane as LimitedLane] : undefined;
+}
+
+/** How many cards the board holds in `lane`. */
+export function countIn(lane: Lane, cards: readonly { lane: Lane }[]): number {
+	return cards.filter((card) => card.lane === lane).length;
+}
+
+/**
+ * Why the next card may not enter `lane`, or `undefined` when it may.
+ *
+ * The sentence names the lane, the number, the limit, and the ways out, because a refusal
+ * that only says "full" sends the reader looking for a setting they were never shown.
+ *
+ * `from` is the lane the card is leaving, and the one case that changes the advice is a
+ * resume out of `blocked`: that card cannot finish, and it is already parked, so the two
+ * exits the ordinary sentence offers are the two it does not have.
+ */
+export function wipRefusal(
+	lane: LimitedLane,
+	cards: readonly { lane: Lane }[],
+	limits: WipLimits,
+	from?: Lane,
+): string | undefined {
+	const limit = limitOf(lane, limits) ?? DEFAULT_WIP[lane];
+	const held = countIn(lane, cards);
+	if (held < limit) return undefined;
+	const what = lane === "plan" ? "being planned" : "executing";
+	const waysOut =
+		from === "blocked" ? "wait for a slot, or release it back to the pool" : "finish, block, or release one first";
+	return `${held} cards are already ${what} (the limit is ${limit}); ${waysOut}.`;
+}