@afokapu/atdd-flow 0.3.16 → 0.3.18

package/conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml

@@ -69,6 +69,19 @@ content:
     messages to their coordinator; they do not directly message the operator or main seat. A receipt
     or result addresses the seat that made the request, not every historical participant in the thread.
 
+    For new project topology, `main@project` is the sole primary-checkout and `main`-branch
+    coordinator. A named `coordinator.stream@project` works only from its own linked
+    `integration/stream` branch and worktree; it integrates bounded driver delivery rather than acting
+    as a hidden feature driver. A driver coordinated by that seat derives its governed base from that
+    exact integration head, while a main-coordinated driver derives from main. Reject nested
+    coordinator lineage, mismatched base/worktree placement, and ambiguous placement rather than
+    guessing. Legacy seat, task, and thread identities remain readable without rename or mutation.
+
+    Drivers hand work back to their named coordinator for integration and validation. The named
+    coordinator hands a reviewed integration candidate to main; only main completes normal
+    integration-to-main gates and publication. No automatic merge executor, branch graph, daemon, or
+    scheduler is introduced by this workflow.
+
     A driver starts only its assigned ready task. Treat the task's done_when criteria as the required
     delivery scope. Prefer existing repository patterns, components, dependencies, contracts, and
     abstractions. When multiple implementations are correct, choose the smallest effective change that

package/extensions/pi/index.ts

@@ -62,6 +62,7 @@ const defaultHeartbeatMs = 15_000;
 const defaultStaleAfterMs = 60_000;
 const defaultActivationIntervalMs = 25;
 const defaultActivationTimeoutMs = 60_000;
+const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
 function participants(thread: Thread) {
   return Array.isArray(thread.participants) && thread.participants.every((entry) => typeof entry === "string") ? thread.participants as string[] : [];
@@ -342,7 +343,7 @@ export default function (pi: ExtensionAPI) {
       root, seat, piSession, herdrSession, pane,
       activate: async () => {
         if (!await current.activate()) return;
-        pi.sendMessage({ customType: "atdd-flow-start", content: `SYSTEM: you are ${seat}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
+        pi.sendMessage({ customType: "atdd-flow-start", content: `SYSTEM: you are ${seat}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Convention: ${lifecycleConventionPath}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
         if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
       },
     }).catch(() => undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -37,6 +37,8 @@ Usage:
   atdd-flow task start|review|return <project> <task-id> --by <address>
   atdd-flow task done <project> <task-id> --by <address> [--retire-assignee]
   atdd-flow task prove <project> <task-id> --by <address> --item <number> --proof <reference>
+  atdd-flow task handoff <project> <task-id> --by <assignee> --phase <plan|red|green|refactor> --evidence <message-or-reference>
+  atdd-flow task respond <project> <task-id> --by <coordinator> --outcome <accept|return> --phase <plan|red|green|refactor>
   atdd-flow task block <project> <task-id> --by <address> --reason <text>
   atdd-flow task unblock <project> <task-id> --by <coordinator-address>
   atdd-flow task list <project> [--coordinator <address>] [--assignee <address>]
@@ -112,11 +114,13 @@ async function main() {
       if (subcommand === "done") return tasks.done(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "return") return tasks.returnToWork(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "prove") return tasks.prove(root, required(projectName, "project"), required(taskId, "task id"), tail);
+      if (subcommand === "handoff") return tasks.submitHandoff(root, required(projectName, "project"), required(taskId, "task id"), tail);
+      if (subcommand === "respond") return tasks.respondToHandoff(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "block") return tasks.block(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "unblock") return tasks.unblock(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "list") return tasks.list(root, required(projectName, "project"), rest.slice(2));
       if (subcommand === "open") return tasks.open(root, required(projectName, "project"), required(taskId, "task id"));
-      throw new Error("Use `atdd-flow task add|assign|amend|import|start|prove|review|return|done|block|unblock|list|open`.");
+      throw new Error("Use `atdd-flow task add|assign|amend|import|start|prove|handoff|respond|review|return|done|block|unblock|list|open`.");
     },
     cleanup: async () => {
       const [subcommand, projectName, taskId] = rest;

package/src/multiplexer.ts

@@ -89,6 +89,28 @@ async function projectSeats(root: string, projectName: string) {
   return seats.filter((entry): entry is Seat => Boolean(entry && entry.schema === "atdd-workflow/seat/v2" && !entry.retired));
 }
 
+function assertNewTopologyPlacement(config: Project, entry: Seat, primary: string) {
+  const coordinator = config.roles.coordinator;
+  const namedCoordinatorDefaults = coordinator?.address === "coordinator.{name}@{project}" && coordinator.branch === "integration/{name}";
+  const mainDefaults = config.roles.main?.address === "main@{project}" && config.roles.main.branch === "main";
+  if (entry.role === "main" && mainDefaults && (entry.address !== `main@${config.project}` || entry.branch !== "main" || resolve(entry.worktree) !== primary)) {
+    throw new Error(`Main seat ${entry.address} must use the primary main worktree and branch.`);
+  }
+  if (entry.role !== "coordinator" || !namedCoordinatorDefaults) return;
+  // coordinator@project remains the preserved historical primary identity;
+  // every newly named coordinator must be a single linked integration stream.
+  if (entry.address === `coordinator@${config.project}`) {
+    if (entry.branch !== "main" || resolve(entry.worktree) !== primary) throw new Error(`Legacy primary coordinator ${entry.address} has mismatched placement.`);
+    return;
+  }
+  const suffix = `@${config.project}`;
+  const local = entry.address.endsWith(suffix) ? entry.address.slice(0, -suffix.length) : "";
+  const match = local.match(/^coordinator\.([a-z0-9_-]+)$/);
+  if (!match || entry.branch !== `integration/${match[1]}` || resolve(entry.worktree) === primary) {
+    throw new Error(`Named coordinator ${entry.address} must use one linked integration/<stream> worktree and branch.`);
+  }
+}
+
 async function targets(root: string): Promise<Target[]> {
   let projects: string[];
   try { projects = await readdir(paths(root).work); }
@@ -102,6 +124,7 @@ async function targets(root: string): Promise<Target[]> {
     const primary = resolve(config.repository);
     result.push({ project: name, worktree: primary, workspaceLabel: name });
     for (const entry of await projectSeats(root, name)) {
+      assertNewTopologyPlacement(config, entry, primary);
       if ((entry.role === "main" || entry.role === "coordinator") && resolve(entry.worktree) === primary) {
         result.push({ project: name, worktree: primary, workspaceLabel: name, seat: entry });
         continue;
@@ -148,7 +171,7 @@ async function ensureWorkspace(session: string, target: Target, workspaces: Work
   if (!current) {
     const args = target.workspaceLabel === target.project
       ? ["workspace", "create", "--cwd", target.worktree, "--label", target.workspaceLabel, "--no-focus"]
-      : ["worktree", "open", "--workspace", primary?.id ?? "", "--cwd", primary?.worktree ?? "", "--path", target.worktree, "--label", target.workspaceLabel, "--no-focus"];
+      : ["worktree", "open", "--workspace", primary?.id ?? "", "--path", target.worktree, "--label", target.workspaceLabel, "--no-focus"];
     if (args.includes("")) throw new Error(`Project primary workspace is required to open linked worktree ${target.worktree}.`);
     const created = json(await command(["herdr", "--session", session, ...args]));
     current = { workspace_id: workspaceId(created), label: target.workspaceLabel, worktree: { checkout_path: target.worktree } };

package/src/overview.ts

@@ -1,6 +1,6 @@
 import { readdir } from "node:fs/promises";
 import { canonicalAddress, desk, exists, paths, readYaml, type Checkpoint, type Seat } from "./core";
-import { type Task, type TaskStatus } from "./tasks";
+import { type Task, type TaskHandoff, type TaskStatus } from "./tasks";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { type Message, type Thread } from "./threads";
 
@@ -108,6 +108,10 @@ function taskPhase(entry: ListedTask) {
   return stateName(entry.task.status);
 }
 
+function handoffStateName(value: TaskHandoff["state"]) {
+  return value.replaceAll("_", "-").toUpperCase();
+}
+
 function attentionForTask(entry: ListedTask, checkpointBySeat: Map<string, Checkpoint | undefined>): Attention | undefined {
   const { task } = entry;
   const inspect = `atdd-flow task open ${entry.project} ${entry.id}`;
@@ -261,11 +265,24 @@ async function taskDashboard(root: string, projectName: string, taskId: string)
   const record = await desk(root);
   const threadList = (await threads(root)).filter((item) => item.record.task === `${projectName}/${taskId}`);
   const proof = `${entry.task.done_when.filter((item) => item.proof).length}/${entry.task.done_when.length} proof`;
-  header(`TASK / ${projectName}/${taskId}`, record.desk, `${taskPhase(entry)}${dot}${proof}`, record.application);
+  const runtime = entry.task.assignee ? await readRuntimeState(root, entry.task.assignee) : undefined;
+  const runtimeState = runtime && !isRuntimeStateStale(runtime, 60_000) ? "ONLINE" : "OFFLINE";
+  const handoff = entry.task.handoff ? handoffStateName(entry.task.handoff.state) : undefined;
+  header(`TASK / ${projectName}/${taskId}`, record.desk, `${taskPhase(entry)}${entry.task.phase ? `${dot}${entry.task.phase.toUpperCase()}` : ""}${handoff ? `${dot}${handoff}` : ""}${dot}${proof}${dot}RUNTIME ${runtimeState}`, record.application);
   console.log(`\n  ${strong(entry.task.title)}`);
   rule("OWNERSHIP");
   console.log(`  coordinator  ${entry.task.coordinator}`);
   console.log(`  assignee     ${entry.task.assignee ?? muted("unassigned")}`);
+  rule("PHASE / HANDOFF");
+  if (!entry.task.phase && !entry.task.handoff) console.log(`  ${muted("No optional phase or handoff projection has been recorded.")}`);
+  if (entry.task.phase) console.log(`  phase     ${entry.task.phase.toUpperCase()}`);
+  if (entry.task.handoff) {
+    console.log(`  handoff   ${handoffStateName(entry.task.handoff.state)}`);
+    console.log(`  evidence  ${entry.task.handoff.evidence}`);
+    console.log(`  updated   ${entry.task.handoff.updated_at}`);
+  }
+  rule("RUNTIME OBSERVATION", runtimeState);
+  console.log(`  assignee runtime  ${runtimeState}${runtime ? ` · ${runtime.model} · heartbeat ${runtime.heartbeat_at}` : " · no current advisory observation"}`);
   rule("DEPENDENCIES", String((entry.task.depends_on ?? []).length));
   if (!entry.task.depends_on?.length) console.log(`  ${muted("Independent; it may proceed in parallel.")}`);
   for (const dependency of entry.task.depends_on ?? []) console.log(`  ${entry.waiting.includes(dependency) ? tone("○", "WAITING") : tone("✓", "DONE")} ${dependency}${entry.waiting.includes(dependency) ? `  ${tone("WAITING", "WAITING")}` : ""}`);

package/src/seats.ts

@@ -10,10 +10,17 @@ import {
 import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
 import { seatTasks } from "./tasks";
 import { projectHerdrSeat } from "./multiplexer";
+import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
+
+const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
 const defaultRoles = (dynamicModels = true): Record<string, Role> => ({
+  main: {
+    address: "main@{project}", branch: "main", worktree: "{repository}",
+    ...(dynamicModels ? {} : { agent: "pi" }),
+  },
   coordinator: {
-    address: "coordinator@{project}", branch: "main", worktree: "{repository}",
+    address: "coordinator.{name}@{project}", branch: "integration/{name}", base: "main", worktree: "{worktree_root}/{name}",
     ...(dynamicModels ? {} : { agent: "pi" }),
   },
   driver: {
@@ -75,10 +82,27 @@ export async function spawn(root: string, projectName: string, roleName: string,
   const config = await project(root, projectName);
   const role = required(config.roles[roleName], `role ${roleName}`);
   const entries = { project: config.project, name, worktree_root: config.worktree_root ?? "" };
-  const address = fill(role.address, entries);
-  const configuredPath = role.worktree ? fill(role.worktree, { ...entries, repository: config.repository ?? "" }) : undefined;
+  // Retain the historical primary coordinator command for existing Desks while
+  // new defaults make main@project the only new primary identity.
+  const legacyPrimaryCoordinator = roleName === "coordinator" && name === "main"
+    && role.address === "coordinator.{name}@{project}" && role.branch === "integration/{name}";
+  const address = legacyPrimaryCoordinator ? `coordinator@${config.project}` : fill(role.address, entries);
+  const configuredPath = legacyPrimaryCoordinator ? config.repository : role.worktree ? fill(role.worktree, { ...entries, repository: config.repository ?? "" }) : undefined;
   const worktree = resolve(required(words(args, "--worktree") ?? configuredPath, "--worktree or role worktree template"));
-  const branch = words(args, "--branch") ?? fill(role.branch, { project: config.project, name });
+  const branch = words(args, "--branch") ?? (legacyPrimaryCoordinator ? "main" : fill(role.branch, { project: config.project, name }));
+  const newMainDefaults = roleName === "main" && role.address === "main@{project}" && role.branch === "main";
+  const newNamedCoordinatorDefaults = roleName === "coordinator" && !legacyPrimaryCoordinator
+    && role.address === "coordinator.{name}@{project}" && role.branch === "integration/{name}";
+  if (newMainDefaults && (branch !== "main" || (config.repository && worktree !== resolve(config.repository)))) {
+    throw new Error(`Main seat main@${config.project} must use the declared primary main worktree and branch.`);
+  }
+  if (newNamedCoordinatorDefaults) {
+    if (!/^[a-z0-9_-]+$/.test(name)) throw new Error("Named coordinator must use one single stream name.");
+    const expectedWorktree = resolve(fill(required(role.worktree, "named coordinator worktree template"), { ...entries, repository: config.repository ?? "" }));
+    if (branch !== `integration/${name}` || worktree !== expectedWorktree) {
+      throw new Error(`Named coordinator ${address} must use its declared integration/${name} branch and linked worktree.`);
+    }
+  }
   await ensureWorktree(config, role, worktree, branch);
   const purpose = words(args, "--purpose") ?? (role.purpose ? fill(role.purpose, entries) : undefined);
   const portfolio = await modelPortfolio(root);
@@ -360,6 +384,17 @@ export async function openSeat(root: string, address: string) {
   // legacy scalar form while the durable record now carries its session too.
   const herdr = record.runtime?.addresses.herdr;
   if (herdr && typeof herdr !== "string") console.log(`herdr: ${herdr.pane} (session: ${herdr.session})`);
+  if (typeof herdr === "string") console.log(`herdr: ${herdr} (unscoped; unverified)`);
+  if (record.runtime?.application === "herdr") {
+    const advisory = await readRuntimeState(root, resolved);
+    const missing = [
+      typeof herdr === "string" || !herdr ? "Herdr session" : undefined,
+      !record.runtime.pi_session || !record.runtime.pi_session_path ? "Pi session/path" : undefined,
+      !record.runtime.launch_receipt || !await exists(record.runtime.launch_receipt) ? "launch receipt" : undefined,
+      !advisory || isRuntimeStateStale(advisory, 60_000) ? "advisory heartbeat" : undefined,
+    ].filter((entry): entry is string => Boolean(entry));
+    console.log(`runtime verification: ${missing.length ? `unverified (${missing.join(", ")})` : "bounded metadata and fresh advisory heartbeat"}`);
+  }
   const checkpointFile = paths(root).checkpointFile(resolved);
   if (await exists(checkpointFile)) console.log(yaml.print(await readYaml<Checkpoint>(checkpointFile)));
   const threadIds = await readdir(paths(root).threads);
@@ -369,4 +404,5 @@ export async function openSeat(root: string, address: string) {
     const entry = await readYaml<{ participants: string[]; state: string; subject: string }>(file);
     if (entry.participants.includes(resolved)) console.log(`${threadId}  ${entry.state}  ${entry.subject}`);
   }
+  console.log(`Convention: ${lifecycleConventionPath}`);
 }

package/src/tasks.ts

@@ -1,10 +1,17 @@
 import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
 import {
   type Checkpoint, atomicYaml, canonicalAddress, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
 } from "./core";
 
 export type TaskStatus = "todo" | "in_progress" | "review" | "done";
+/** An optional, descriptive implementation phase; task status remains the lifecycle authority. */
+export type TaskPhase = "plan" | "red" | "green" | "refactor";
+export type HandoffState = "executing" | "awaiting_coordinator" | "awaiting_assignee";
+/** A mutable projection of an immutable evidence message/reference, not a second task lifecycle. */
+export type TaskHandoff = { state: HandoffState; evidence: string; updated_at: string };
 export type DoneWhen = { text: string; proof?: string };
+export type GovernedBase = { coordinator: string; branch: string; commit: string };
 export type Task = {
   schema: "atdd-workflow/task/v1";
   title: string;
@@ -15,6 +22,12 @@ export type Task = {
   source?: string;
   depends_on?: string[];
   blocker?: string;
+  /** Absent on legacy tasks. */
+  phase?: TaskPhase;
+  /** Absent on legacy tasks; evidence remains an opaque immutable message/reference. */
+  handoff?: TaskHandoff;
+  /** Exact named-coordinator or main head from which an assigned driver is governed. */
+  governed_base?: GovernedBase;
   done_when: DoneWhen[];
 };
 
@@ -60,6 +73,42 @@ async function writeTask(root: string, projectName: string, id: string, task: Ta
   await atomicYaml(paths(root).taskFile(projectName, id), task);
 }
 
+/** Records the exact parent head for new bounded topology without rewriting legacy tasks. */
+async function governedBase(root: string, projectName: string, coordinatorAddress: string, assignee?: string): Promise<GovernedBase | undefined> {
+  if (!assignee) return undefined;
+  const config = await project(root, projectName);
+  if (!config.repository) return undefined;
+  const coordinator = await seat(root, coordinatorAddress);
+  const driver = await seat(root, assignee);
+  if (driver.role !== "driver") throw new Error(`${assignee} is not a driver seat.`);
+  const primary = resolve(config.repository);
+  let branch: string;
+  if (coordinator.role === "main") {
+    if (coordinator.address !== `main@${config.project}` || coordinator.branch !== "main" || resolve(coordinator.worktree) !== primary) {
+      throw new Error(`Main coordinator ${coordinator.address} has mismatched primary lineage.`);
+    }
+    branch = "main";
+  } else if (coordinator.role === "coordinator") {
+    const configured = config.roles.coordinator;
+    // Existing coordinator role templates and coordinator@project records
+    // predate bounded integration lineage and remain readable unchanged.
+    if (configured?.address !== "coordinator.{name}@{project}" || configured.branch !== "integration/{name}" || coordinator.address === `coordinator@${config.project}`) return undefined;
+    const suffix = `@${config.project}`;
+    const local = coordinator.address.endsWith(suffix) ? coordinator.address.slice(0, -suffix.length) : "";
+    const match = local.match(/^coordinator\.([a-z0-9_-]+)$/);
+    if (!match || coordinator.branch !== `integration/${match[1]}` || resolve(coordinator.worktree) === primary) {
+      throw new Error(`Coordinator ${coordinator.address} has mismatched or nested integration lineage.`);
+    }
+    branch = coordinator.branch;
+  } else {
+    throw new Error(`Task coordinator ${coordinator.address} must be main or a named coordinator.`);
+  }
+  const commit = await runOutput(["git", "-C", coordinator.worktree, "rev-parse", branch]);
+  const common = await runOutput(["git", "-C", driver.worktree, "merge-base", commit, driver.branch]);
+  if (common !== commit) throw new Error(`Driver ${driver.address} is not based on the exact coordinator head ${commit}.`);
+  return { coordinator: coordinator.address, branch, commit };
+}
+
 async function retireAssignee(root: string, projectName: string, id: string, task: Task) {
   const assignee = required(task.assignee, `an assignee for task ${id}`);
   const unfinished = (await allTasks(root, projectName))
@@ -98,6 +147,7 @@ export async function add(root: string, projectName: string, id: string, args: s
   const assignee = assigneeValue ? await canonicalAddress(root, assigneeValue) : undefined;
   await seat(root, coordinator);
   if (assignee) await seat(root, assignee);
+  const base = await governedBase(root, projectName, coordinator, assignee);
   const doneWhen = values(args, "--done-when").map((text) => ({ text }));
   if (!doneWhen.length) throw new Error("A task needs at least one --done-when criterion.");
   const dependsOn = words(args, "--depends-on")?.split(",").filter(Boolean).map(taskId);
@@ -107,6 +157,7 @@ export async function add(root: string, projectName: string, id: string, args: s
     status: "todo",
     coordinator,
     ...(assignee ? { assignee } : {}),
+    ...(base ? { governed_base: base } : {}),
     ...(words(args, "--body") ? { body: words(args, "--body") } : {}),
     ...(words(args, "--source") ? { source: words(args, "--source") } : {}),
     ...(dependsOn?.length ? { depends_on: dependsOn } : {}),
@@ -124,7 +175,9 @@ export async function assign(root: string, projectName: string, id: string, args
   if (task.assignee) throw new Error(`Task ${id} is already assigned to ${task.assignee}.`);
   const assignee = await canonicalAddress(root, required(words(args, "--assignee"), "--assignee"));
   await seat(root, assignee);
+  const base = await governedBase(root, projectName, task.coordinator, assignee);
   task.assignee = assignee;
+  if (base) task.governed_base = base;
   await writeTask(root, projectName, id, task);
   console.log(`${id}  assigned  ${assignee}`);
 }
@@ -220,6 +273,62 @@ export async function returnToWork(root: string, projectName: string, id: string
   return transition(root, projectName, taskId(id), "in_progress", required(words(args, "--by"), "--by"));
 }
 
+const phases: TaskPhase[] = ["plan", "red", "green", "refactor"];
+const handoffOutcomes = ["accept", "return"] as const;
+
+type HandoffOutcome = typeof handoffOutcomes[number];
+
+function phase(value: string | undefined): TaskPhase {
+  const selected = required(value, "--phase");
+  if (!phases.includes(selected as TaskPhase)) throw new Error(`--phase must be one of: ${phases.join(", ")}.`);
+  return selected as TaskPhase;
+}
+
+function handoffOutcome(value: string | undefined): HandoffOutcome {
+  const selected = required(value, "--outcome");
+  if (!(handoffOutcomes as readonly string[]).includes(selected)) throw new Error("--outcome must be accept or return.");
+  return selected as HandoffOutcome;
+}
+
+/**
+ * The assignee records work as ready for a coordinator decision. The evidence
+ * value is deliberately opaque: it links an immutable message/reference but
+ * never parses message prose or changes the task lifecycle.
+ */
+export async function submitHandoff(root: string, projectName: string, id: string, args: string[]) {
+  const task = await readTask(root, projectName, taskId(id));
+  const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
+  if (!task.assignee || actor !== task.assignee) throw new Error(`Only ${task.assignee ?? "the assignee"} may submit a handoff for task ${id}.`);
+  if (task.status !== "in_progress") throw new Error(`Task ${id} must be in_progress before a handoff is submitted.`);
+  if (task.handoff?.state === "awaiting_coordinator") throw new Error(`Task ${id} is already awaiting coordinator handoff response.`);
+  const evidence = required(words(args, "--evidence"), "--evidence");
+  task.phase = phase(words(args, "--phase"));
+  task.handoff = { state: "awaiting_coordinator", evidence, updated_at: now() };
+  await writeTask(root, projectName, taskId(id), task);
+  console.log(`${id}  handoff awaiting_coordinator`);
+}
+
+/**
+ * The coordinator accepts a handoff for the assignee's next phase or returns
+ * it to active execution. This only updates the optional projection.
+ */
+export async function respondToHandoff(root: string, projectName: string, id: string, args: string[]) {
+  const task = await readTask(root, projectName, taskId(id));
+  const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
+  if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may respond to task ${id} handoff.`);
+  if (task.status !== "in_progress") throw new Error(`Task ${id} must be in_progress before a handoff is answered.`);
+  if (task.handoff?.state !== "awaiting_coordinator") throw new Error(`Task ${id} is not awaiting coordinator handoff response.`);
+  const outcome = handoffOutcome(words(args, "--outcome"));
+  task.phase = phase(words(args, "--phase"));
+  task.handoff = {
+    ...task.handoff,
+    state: outcome === "accept" ? "awaiting_assignee" : "executing",
+    updated_at: now(),
+  };
+  await writeTask(root, projectName, taskId(id), task);
+  console.log(`${id}  handoff ${task.handoff.state}`);
+}
+
 export async function prove(root: string, projectName: string, id: string, args: string[]) {
   const task = await readTask(root, projectName, taskId(id));
   const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));