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

package/extensions/board/tools.ts

@@ -14,12 +14,16 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Static } from "typebox";
-import { type Card, cardRef, matchesQuery, normalizeCardId } from "../../lib/board/card.ts";
+import { type ArtifactCheck, planForContract, planForExecute } from "../../lib/board/artifact.ts";
+import { type Card, cardRef, holds, matchesQuery, normalizeCardId } from "../../lib/board/card.ts";
+import { movableLanes } from "../../lib/board/lanes.ts";
 import { indexOf } from "../../lib/board/links.ts";
-import { type CardOp, holds } from "../../lib/board/rules.ts";
+import type { CardOp } from "../../lib/board/rules.ts";
 import { buildRound } from "../../lib/board/round.ts";
+import { readRoster, type RosterSession } from "../../lib/session-roster.ts";
 import type { BoardStore } from "../../lib/board/store.ts";
 import { messageOf } from "../../lib/errors.ts";
+import { listOf } from "../../lib/format.ts";
 import { revParse } from "../../lib/git/read.ts";
 import { strayField } from "../../lib/stray-fields.ts";
 import { createExecRunner } from "../../lib/git/runner.ts";
@@ -27,17 +31,17 @@ import { failedResult, textResult } from "../../lib/tool-result.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { callLine, detailsOrLine, isTailResult, TailResult } from "../../lib/tui/tool.ts";
 import { formatRound } from "../../lib/board/round-text.ts";
+import { skippedText } from "../../lib/board/skipped.ts";
 import {
 	archiveNote,
+	CLAIM_NEXT,
 	formatArchive,
 	formatArchived,
 	formatBoard,
 	formatCard,
 	formatDropped,
-	formatSkipped,
 } from "./format.ts";
 import { createTeamJoin, type TeamJoin } from "../../lib/session-tool.ts";
-import { joinOnClaim } from "./join.ts";
 import { collapsedLine, resultInput } from "./result.ts";
 import { createInput } from "./input.ts";
 import type { BoardSession } from "../../lib/board/session.ts";
@@ -76,14 +80,14 @@ function callSubject(action: BoardAction, args: Record<string, unknown>): string
 	if (action === "list") {
 		const parts = ["list"];
 		if (args.round === true) parts.push("round");
-		if (typeof args.status === "string") parts.push(args.status);
+		if (typeof args.lane === "string") parts.push(args.lane);
 		if (typeof args.query === "string" && args.query.trim() !== "") parts.push(`"${args.query.trim()}"`);
 		if (card !== "") parts.push(card);
 		return parts.join(" ");
 	}
 	if (card === "") return action;
-	const status = typeof args.status === "string" ? ` ${args.status}` : "";
-	return `${action} ${card}${status}`;
+	const lane = typeof args.lane === "string" ? ` ${args.lane}` : "";
+	return `${action} ${card}${lane}`;
 }
 
 /** One refusal: the reason for the model, the state for the renderer. */
@@ -127,14 +131,16 @@ export function registerTools(pi: ExtensionAPI, runtime: BoardSession, deps: { t
 		label: "Board",
 		description:
 			"The shared feature list for this repository: one card per feature, which any session reads and writes. " +
-			"A card carries the feature's outcome, the session that holds it, path hints, the plan it is executing, " +
-			`its priority, what it waits for, and its notes. ${verbHelp()} A card's steps do not belong on the ` +
-			"board - they belong in the plan and in `todo`.",
+			"A card moves through five lanes - backlog, plan, execute, blocked, done - and carries the feature's " +
+			"outcome, the session that holds it, the contract it promises (goal, acceptance, scopeOut), the plan it " +
+			`is executed against, its priority, what it waits for, and its notes. ${verbHelp()} A card's steps do not ` +
+			"belong on the board - they belong in the plan and in `todo`.",
 		promptSnippet: `The shared feature list for this repository: ${BOARD_ACTIONS.join(", ")}.`,
 		promptGuidelines: [
-			"Claim a card before working on it; release or finish it when you stop, and reclaim a card whose owner is gone.",
-			"Record the plan file with `board` action `plan` once the plan is approved, then execute it.",
-			"Note each phase of the work, and move the card to `done` or `blocked` when it changes state.",
+			"Claim a card to pull it from backlog into plan, design it in plan mode, then record the contract with `contract`: goal, acceptance, scopeOut, and the plan file `plan` action `write` returned — a path outside this repository's plan store is refused. Move it to execute only once the lead (`board.lead` in `bytefly.json`, `lead` by default, the name the page serves as) has approved that contract, or the person has signed with `/board approve` — a lead releases a card before signing it.",
+			"Before a card is done, the lead records a spot-check with `review`, or the person signs with `/board review`; the plan it recorded must still be in the store, and `contract` is how it is re-recorded.",
+			"Move a card to `blocked` with a `blocker` kind and one line about what is waited on: it resumes in `plan`, or in `execute` once its contract is approved.",
+			"Note each phase of the work, and release or reclaim a card you stop holding, so the lane count means what it says.",
 			"A card that waits on another is linked with `edit` and `dependsOn`, so the order is on the board instead of in a refusal.",
 			"A feature's steps belong in `todo`, not on the board: one card is one feature, whatever it takes.",
 			"A `handoff` in your inbox is work you now own: read it with `session inbox`, record the plan, and start it.",
@@ -154,27 +160,35 @@ export function registerTools(pi: ExtensionAPI, runtime: BoardSession, deps: { t
 					`unknown action "${String(args.action)}"; use ${BOARD_ACTIONS.join(", ")}.`,
 				);
 			}
-			const me = runtime.who(ctx, ctx.cwd);
+			const me = await runtime.who(ctx, ctx.cwd);
 			try {
-				// Before the join and the store: a refused call has done nothing, so it cannot
-				// have enlisted this session as a teammate on its way to the refusal.
+				// Before the join and before a card is read: a refused call has written nothing, so it
+				// cannot have enlisted this session as a teammate on its way to the refusal.
 				const stray = strayField(action, args, ACTION_FIELDS);
 				if (stray !== undefined) return refusal(action, me, stray);
 				const store = await runtime.store(ctx.cwd);
 				const now = runtime.now();
 				switch (action) {
 					case "list":
-						return await read(store, action, me, args, now);
+						// The round folds the owners a bus has no record of, and the rollup is the only read
+						// that needs the bus for its own sake: a plain `list` reads no bus file beyond the
+						// record that names whoever is calling.
+						return await read(store, action, me, args, now, async () => readRoster(await runtime.busDir(ctx.cwd)));
 					case "add":
 						return await add(store, me, args, now);
 					case "claim": {
-						const claimed = await mutate(store, action, me, now, args, { kind: "claim" });
+						const claimed = await mutate(store, action, me, now, args, { kind: "claim" }, CLAIM_NEXT);
 						// Taking a card is what makes this session a teammate. It is the one action here
 						// worth being addressed about, and the board is the user's surface for the team, so
 						// nobody has to know the bus exists. A refused claim wrote nothing and enlists
 						// nobody; a refused join is not a failed claim, so the card stands and the next
 						// claim asks again.
-						if (!refused(claimed)) await joinOnClaim(runtime.team, team, ctx, me.label);
+						if (!refused(claimed)) {
+							// Loaded here, not at registration: the join is the claim's side effect, so a
+							// session that never claims pays nothing for it.
+							const { joinOnce } = await import("../../lib/board/join.ts");
+							await joinOnce(runtime.team, team, ctx, me.label);
+						}
 						return claimed;
 					}
 					case "release":
@@ -183,29 +197,47 @@ export function registerTools(pi: ExtensionAPI, runtime: BoardSession, deps: { t
 						return await mutate(store, action, me, now, args, { kind: "reclaim" });
 					case "move": {
 						if (args.card === undefined) return refusal(action, me, 'card is required: pass the id, e.g. "4".');
-						const status = args.status;
-						if (status === undefined || status === "todo") {
-							return refusal(
-								action,
-								me,
-								'move needs a target lane: "doing", "blocked", or "done". Use release to return a card to todo.',
-							);
+						const lane = args.lane;
+						if (lane === undefined) {
+							return refusal(action, me, `move needs a target lane: ${listOf(movableLanes())}.`);
 						}
-						// Only the lane that has something to say reads for it: a move to `done`
-						// records the commit that closed the card, and a board outside a
-						// repository simply has none to record.
-						const landed = status === "done" ? await headCommit(pi, ctx.cwd) : undefined;
+						// Only the lanes that have something to say read for it: a move to `done`
+						// records the commit that closed the card, and both `execute` and `done` carry
+						// the proof that the plan the card recorded is still there. A board outside a
+						// repository simply has no commit to record.
+						const landed = lane === "done" ? await headCommit(pi, ctx.cwd) : undefined;
+						const proved =
+							lane === "execute" || lane === "done"
+								? await recordedPlan(runtime, ctx.cwd, store, args.card)
+								: undefined;
 						return await mutate(store, action, me, now, args, {
 							kind: "move",
-							status,
+							lane,
 							...(args.blockedBy === undefined ? {} : { blockedBy: args.blockedBy }),
+							...(args.blocker === undefined ? {} : { blocker: args.blocker }),
 							...(landed === undefined ? {} : { landed }),
+							...(proved === undefined ? {} : { artifact: proved }),
 						});
 					}
 					case "note":
 						return await mutate(store, action, me, now, args, { kind: "note", text: args.text });
-					case "plan":
-						return await mutate(store, action, me, now, args, { kind: "plan", path: args.path });
+					case "contract": {
+						// The plan is proved here, at the boundary: the state machine decides, but only
+						// a caller holding the working directory can answer whether the file is there.
+						const plan =
+							args.path === undefined ? undefined : planForContract(await runtime.planDir(ctx.cwd), args.path);
+						return await mutate(store, action, me, now, args, {
+							kind: "contract",
+							...(plan === undefined ? {} : { artifact: plan }),
+							goal: args.goal,
+							acceptance: args.acceptance,
+							scopeOut: args.scopeOut,
+						});
+					}
+					case "approve":
+						return await mutate(store, action, me, now, args, { kind: "approve", text: args.text });
+					case "review":
+						return await mutate(store, action, me, now, args, { kind: "review", text: args.text });
 					case "edit": {
 						if (
 							args.title === undefined &&
@@ -259,6 +291,42 @@ export function registerTools(pi: ExtensionAPI, runtime: BoardSession, deps: { t
 	});
 }
 
+/**
+ * The plan file a card entering `execute` recorded, proved to be there.
+ *
+ * A `move` names the card, not its plan, so the tool reads the card — one read, on the one
+ * lane whose gate needs it — and hands `steps.ts` the fact. A card with no plan recorded
+ * gets no fact and the state machine refuses it; a recorded plan that is gone, or outside
+ * this repository's store, is refused here with the sentence that names the card and the
+ * way out.
+ */
+async function recordedPlan(
+	runtime: BoardSession,
+	cwd: string,
+	store: BoardStore,
+	rawCard: string | undefined,
+): Promise<ArtifactCheck | undefined> {
+	const id = rawCard === undefined ? undefined : normalizeCardId(rawCard);
+	const card = id === undefined ? undefined : await store.read(id);
+	if (card?.planPath === undefined) return undefined;
+	return planForExecute(await runtime.planDir(cwd), card);
+}
+
+/** The `list` fields that narrow a listing, in the order a refusal names them. */
+const CARD_FILTERS = ["lane", "query", "mine", "round"] as const;
+
+/**
+ * The refusal for the filters a `list` that names a card would otherwise drop.
+ *
+ * `card` answers for that one card, so a filter beside it changes nothing — and a call that
+ * sent both meant one of them. A dropped field is what `strayField` exists to prevent one
+ * level up, so it is refused here in the same voice the archive's own reader uses.
+ */
+function cardFiltersRefusal(args: BoardArgs, fields: readonly (keyof BoardArgs)[] = CARD_FILTERS): string | undefined {
+	const given = fields.filter((field) => args[field] !== undefined);
+	return given.length === 0 ? undefined : `card does not read ${given.join(", ")}: it answers for that one card.`;
+}
+
 /** `list`: the board, one card, the lead's rollup, or the archive. */
 async function read(
 	store: BoardStore,
@@ -266,6 +334,7 @@ async function read(
 	me: BoardDetails["me"],
 	args: BoardArgs,
 	now: number,
+	roster: () => Promise<readonly RosterSession[] | undefined>,
 ): Promise<ReturnType<typeof textResult<BoardDetails>>> {
 	if (args.archived === true) return readArchive(store, action, me, args, now);
 	const cards = await store.list();
@@ -275,6 +344,8 @@ async function read(
 	// A directory listing, not a read: a listing says what it left aside without opening one.
 	const archived = await store.archivedCount();
 	if (args.card !== undefined) {
+		const ignored = cardFiltersRefusal(args);
+		if (ignored !== undefined) return refusal(action, me, ignored);
 		const id = normalizeCardId(args.card);
 		if (id === undefined) return refusal(action, me, `"${args.card}" is not a card id.`);
 		const card = cards.find((entry) => entry.id === id);
@@ -296,7 +367,7 @@ async function read(
 	}
 	const listed = cards.filter(
 		(card) =>
-			(args.status === undefined || card.status === args.status) &&
+			(args.lane === undefined || card.lane === args.lane) &&
 			(args.query === undefined || matchesQuery(card, args.query)) &&
 			// The same rule a claim is checked against, so "mine" cannot list a card this
 			// session could not release.
@@ -306,18 +377,23 @@ async function read(
 	// repository's own board is mostly finished cards — so a listing that names no lane
 	// leaves them out and says how many. A named lane, `card`, and `round` are unchanged;
 	// the rollup counts the whole board, which is what makes it a rollup.
-	const hiddenDone = args.status === undefined ? listed.filter((card) => card.status === "done").length : 0;
-	const shown = hiddenDone === 0 ? listed : listed.filter((card) => card.status !== "done");
+	const hiddenDone = args.lane === undefined ? listed.filter((card) => card.lane === "done").length : 0;
+	const shown = hiddenDone === 0 ? listed : listed.filter((card) => card.lane !== "done");
 	if (args.round !== true) {
-		return textResult(formatBoard(shown, { hiddenDone, archived, skipped }), { action, me, cards: shown });
+		return textResult(formatBoard(shown, { hiddenDone, archived, skipped }), {
+			action,
+			me,
+			cards: shown,
+			...(args.mine === true ? { mine: true } : {}),
+		});
 	}
 	const round = buildRound(cards, now);
 	// One line under the rollup, because a reader who cannot see a card file should know why,
 	// and one for the archive, because a rollup that silently left it out would be a board
 	// smaller than the one on disk.
-	const notes = [formatSkipped(skipped), archiveNote(archived)].filter((line) => line !== "");
-	const text = [formatRound(cards, round), ...notes].join("\n");
-	return textResult(text, { action, me, cards: listed, round });
+	const notes = [skippedText(skipped), archiveNote(archived)].filter((line) => line !== "");
+	const text = [formatRound(cards, round, await roster()), ...notes].join("\n");
+	return textResult(text, { action, me, cards: listed, round, ...(args.mine === true ? { mine: true } : {}) });
 }
 
 /**
@@ -334,7 +410,7 @@ async function readArchive(
 	args: BoardArgs,
 	now: number,
 ): Promise<ReturnType<typeof textResult<BoardDetails>>> {
-	const wrong = (["status", "round"] as const).filter((field) => args[field] !== undefined);
+	const wrong = (["lane", "round"] as const).filter((field) => args[field] !== undefined);
 	if (wrong.length > 0) {
 		return refusal(
 			action,
@@ -344,6 +420,9 @@ async function readArchive(
 	}
 	const pile = await store.archived();
 	if (args.card !== undefined) {
+		// `query` and `mine` narrow the pile, not the one card it would answer for.
+		const ignored = cardFiltersRefusal(args, ["query", "mine"]);
+		if (ignored !== undefined) return refusal(action, me, ignored);
 		const id = normalizeCardId(args.card);
 		if (id === undefined) return refusal(action, me, `"${args.card}" is not a card id.`);
 		const card = pile.cards.find((entry) => entry.id === id);
@@ -360,7 +439,12 @@ async function readArchive(
 	const shown = pile.cards.filter(
 		(card) => (args.query === undefined || matchesQuery(card, args.query)) && (args.mine !== true || holds(card, me)),
 	);
-	return textResult(formatArchive(shown, pile.skipped), { action, me, cards: shown });
+	return textResult(formatArchive(shown, pile.skipped), {
+		action,
+		me,
+		cards: shown,
+		...(args.mine === true ? { mine: true } : {}),
+	});
 }
 
 /** `add`: the only action that creates a card. */
@@ -384,13 +468,16 @@ async function mutate(
 	now: number,
 	args: BoardArgs,
 	op: CardOp,
+	/** One line a card's own text does not carry, for the action that has a next step. */
+	next?: string,
 ): Promise<ReturnType<typeof textResult<BoardDetails>>> {
 	if (args.card === undefined) return refusal(action, me, 'card is required: pass the id, e.g. "4".');
 	const id = normalizeCardId(args.card);
 	if (id === undefined) return refusal(action, me, `"${args.card}" is not a card id.`);
 	const result = await store.mutate(id, op, me, now);
 	if (!result.ok) return refusal(action, me, result.error, result.card);
-	return textResult(formatCard(result.card), { action, me, card: result.card });
+	const lines = [formatCard(result.card), ...(next === undefined ? [] : [next])];
+	return textResult(lines.join("\n"), { action, me, card: result.card });
 }
 
 /**
@@ -415,7 +502,7 @@ async function archiveCards(
 		if (!result.changed) return textResult(`${cardRef(id)} is already archived.`, { action: "archive", me });
 		return textResult(formatArchived([id]), { action: "archive", me, card: result.card, archived: [id] });
 	}
-	const finished = (await store.list()).filter((card) => card.status === "done");
+	const finished = (await store.list()).filter((card) => card.lane === "done");
 	const moved: string[] = [];
 	const failed: Array<{ card: string; error: string }> = [];
 	for (const card of finished) {

package/extensions/board/types.ts

@@ -10,53 +10,47 @@
 import type { Card } from "../../lib/board/card.ts";
 import type { Actor } from "../../lib/board/rules.ts";
 import type { RoundSummary } from "../../lib/board/round.ts";
+import { BOARD_ACTIONS, type BoardAction } from "../../lib/board/actions.ts";
 
 /** The tool's name. One extension registers it, so it stays here. */
 export const BOARD_TOOL = "board";
 
-/** The actions the tool accepts, in the order the description lists them. */
-export const BOARD_ACTIONS = [
-	"list",
-	"add",
-	"claim",
-	"release",
-	"reclaim",
-	"move",
-	"note",
-	"plan",
-	"edit",
-	"archive",
-	"drop",
-] as const;
-
-/** One action. */
-export type BoardAction = (typeof BOARD_ACTIONS)[number];
+// The actions are the board's, not the tool's: plan mode's read-only policy and the todo
+// nudge classify a call by the same table, and nothing under `lib/` may import this
+// file. Re-exported here so the schema, the description, and the suites keep one import
+// for the tool's own vocabulary.
+export { BOARD_ACTIONS, type BoardAction };
 
 /**
- * What each verb does, in one sentence.
+ * What each action does, in one sentence.
  *
  * The tool description is built from this table and the parameter's `action`
- * description points at that sentence, so the verbs are stated once. A new action is
+ * description points at that sentence, so the actions are stated once. A new action is
  * a row here and an entry in {@link BOARD_ACTIONS}; `test` holds the two together.
  */
 export const BOARD_ACTION_DOCS: Record<BoardAction, string> = {
 	list:
-		"shows the board — `status` filters one lane, `mine` only what this session holds, " +
+		"shows the board — `lane` filters one lane, `mine` only what this session holds, " +
 		"`query` matches a title, a holder, a path hint, the plan, or a note's text, `card` reads that one card " +
-		"instead of the board, and `round` adds the lead's rollup of owners, unassigned, unplanned, blocked, and " +
-		"idle, which always covers the whole board — and a listing that names no lane leaves out the `done` cards, " +
+		"instead of the board, which refuses the fields that narrow a listing beside it, and `round` adds the lead's rollup of owners, unassigned, unplanned, awaiting approval, " +
+		"blocked, idle, and done, which always covers the whole board — and a listing that names no lane leaves out the `done` cards, " +
 		"saying how many it left out",
-	add: "creates a `todo` card",
-	claim: "takes one for this session",
-	release: "gives it back",
-	reclaim: "takes it from whoever holds it",
-	move: "changes lane",
+	add: "creates a `backlog` card",
+	claim: "pulls one into `plan` for this session, when `plan` has room",
+	release: "gives it back to `backlog`",
+	reclaim: "takes it from whoever holds it, back to `backlog`",
+	move: "changes lane, through the one transition the board allows from where the card is; a card enters `execute` or `done` only while the plan it recorded is still in the store",
 	note: "appends to its history",
-	plan: "records the plan file being executed",
+	contract:
+		"records the plan file and the three lines a card promises — `goal`, `acceptance`, `scopeOut` — and drops any approval, because the wording changed; `path` is required and must be the plan `plan` action `write` saved in this repository's plan store",
+	approve:
+		"approves the contract: the lead (`board.lead`, `lead` by default, the name the page serves as), who does not hold the card, says the wording is right, which is what `plan` to `execute` requires, and `text` records what the signer saw",
+	review:
+		"records a spot-check of the finished work: the lead, who does not hold the card, in `execute`, which is what `done` requires, and `text` records what the signer saw",
 	edit: "fixes what the card says — title, path hints, priority, and what it waits for",
 	archive:
 		"sets a finished card aside, out of the board and still readable, or every finished card when no `card` is named",
-	drop: "deletes a `todo`, a `done`, or one you hold",
+	drop: "deletes a `backlog` or a `done` card, or one you hold",
 };
 
 /**
@@ -71,14 +65,16 @@ export const BOARD_ACTION_DOCS: Record<BoardAction, string> = {
  * a new field cannot be published without an action that acts on it.
  */
 export const ACTION_FIELDS: Record<BoardAction, readonly string[]> = {
-	list: ["card", "status", "mine", "query", "round", "archived"],
+	list: ["card", "lane", "mine", "query", "round", "archived"],
 	add: ["title", "paths", "priority", "note"],
 	claim: ["card"],
 	release: ["card"],
 	reclaim: ["card"],
-	move: ["card", "status", "blockedBy"],
+	move: ["card", "lane", "blockedBy", "blocker"],
 	note: ["card", "text"],
-	plan: ["card", "path"],
+	contract: ["card", "path", "goal", "acceptance", "scopeOut"],
+	approve: ["card", "text"],
+	review: ["card", "text"],
 	edit: ["card", "title", "paths", "priority", "dependsOn"],
 	archive: ["card"],
 	drop: ["card"],
@@ -89,6 +85,14 @@ export interface BoardDetails {
 	action: BoardAction;
 	/** The serving session: the id Pi knows, and the label a card records. */
 	me: Actor;
+	/**
+	 * Whether the read was narrowed to this session's own cards.
+	 *
+	 * Kept because the transcript says so: a listing that answers "what am I holding" draws
+	 * those rows in the accent, and a listing that answers "what is on the board" does not
+	 * pretend every row is the reader's.
+	 */
+	mine?: boolean;
 	/** The board a `list` read, in lane order. */
 	cards?: Card[];
 	/** The card an action produced, or the one a refusal left untouched. */