@afokapu/atdd-flow 0.3.39 → 0.3.41

package/README.md

@@ -130,7 +130,7 @@ atdd-flow task review example-app runtime-rollout --by driver.runtime@example-ap
 atdd-flow task done example-app runtime-rollout --by coordinator@example-app
 ```
 
-Proof is a compact PR, CI run, report, commit range, deployment, or thread reference. Dependencies gate prerequisites; independent tasks are parallel-ready. A coordinator can staff an unassigned ready task with `atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address>`; assignment is allowed only once while the task is `todo`. Use `task block` only for a real external blocker, then checkpoint exact state and next action. Once the blocker is resolved, only that coordinator can clear it with `atdd-flow task unblock <project> <task-id> --by <coordinator-address>` while the task remains `in_progress`. For deliveries explicitly governed by the `workflow` ATDD Bun profile, `review → done` additionally requires a durable final behavioral-review result with decision `APPROVE` for the current clean delivery commit. For an idle driver’s final task, `task done ... --retire-assignee` delegates clean-and-merged worktree retirement to ATDD Bun. A driver whose assigned tasks are all already `done` is retired with `atdd-flow seat retire <address> --by <coordinator-or-main>`, using the same checks. When every assigned task is `done` and the recorded worktree is absent from disk and from `git worktree list`, `seat retire` records the retirement without running worktree finish, deleting the branch, or recreating the worktree; a missing worktree that Git still registers fails closed. Both paths fail closed on unfinished tasks or a dirty or unmerged worktree; on success they record `retired` and a checkpoint, then close the driver's Herdr workspace when `close_inactive` is enabled.
+Proof is a compact PR, CI run, report, commit range, deployment, or thread reference. Dependencies gate prerequisites; independent tasks are parallel-ready. A coordinator can staff an unassigned ready task with `atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address>`; assignment is allowed only once while the task is `todo`. Use `task block` only for a real external blocker, then checkpoint exact state and next action. Once the blocker is resolved, only that coordinator can clear it with `atdd-flow task unblock <project> <task-id> --by <coordinator-address>` while the task remains `in_progress`. For deliveries explicitly governed by the `workflow` ATDD Bun profile, `review → done` additionally requires a durable final behavioral-review result with decision `APPROVE` for the current clean delivery commit. For an idle driver’s final task, `task done ... --retire-assignee` delegates clean-and-merged worktree retirement to ATDD Bun. A driver whose assigned tasks are all already `done` is retired with `atdd-flow seat retire <address> --by <coordinator-or-main>`, using the same checks. When every assigned task is `done` and the recorded worktree is absent from disk and from `git worktree list`, `seat retire` records the retirement without running worktree finish, deleting the branch, or recreating the worktree; a missing worktree that Git still registers fails closed. Both paths fail closed on unfinished tasks or a dirty or unmerged worktree; on success they record `retired` and a checkpoint, then close the driver's Herdr workspace when `close_inactive` is enabled. `main@<project>` may likewise retire a coordinator seat (never main, the operator, or a seat on the primary checkout) once every task it coordinates or is assigned is `done`, through the same worktree-finish, absent-and-unregistered, and fail-closed paths. Retirement runs in the seat worktree with ATDD Bun from the primary checkout's `node_modules/.bin`, else the primary checkout's own source when it is the ATDD Bun package, else `PATH`; never the seat worktree's copy, which may pin an older toolkit.
 
 At 80% context usage a seat writes a structured handover (template and process rules in the lifecycle convention), checks it with `atdd-flow handover <address> --check --file <path>`, and records it with `atdd-flow handover <address> --file <path>`. The seat keeps one durable `handover.yaml` beside its unchanged checkpoint. Recording rejects a missing header, Runtime line, or section, sections out of order, more than 150 lines, vague references such as `latest` or `that PR` without an exact ID, and a `supersedes` value that does not match the recorded handover id. A fresh session bound to the same seat reads it with `atdd-flow handover show <address>`.
 

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

@@ -246,8 +246,9 @@ content:
     review and writes a blocked checkpoint for investigation.
 
     Before working in or retiring a driver worktree, install that repository's local dependencies there.
-    Retirement resolves ATDD Bun from the worktree's local node_modules/.bin so it does not depend on a
-    developer's global executable installation.
+    Retirement runs in the seat worktree but resolves ATDD Bun from the primary checkout's local
+    node_modules/.bin, then the primary checkout's own source when it is the ATDD Bun package, then PATH.
+    It never uses the seat worktree's copy, which may pin an older toolkit that refuses its own retirement.
 
     Use the atdd-flow CLI to mutate workflow records. Read task, seat, checkpoint, and thread YAML
     before acting; do not treat terminal pane history, a multiplexer, an optional judgment helper, or an

package/package.json

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

package/src/cli.ts

@@ -49,6 +49,8 @@ Usage:
   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 supersede|reject <project> <task-id> --by <coordinator-address> --reason <text>
+  atdd-flow task defer <project> <task-id> --by <coordinator-address> --reason <text> --owner <address> --trigger <text> --review-at <ISO-8601>
   atdd-flow task unblock <project> <task-id> --by <coordinator-address>
   atdd-flow task list <project> [--coordinator <address>] [--assignee <address>]
   atdd-flow task open <project> <task-id>
@@ -132,10 +134,13 @@ async function main() {
       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 === "supersede") return tasks.disposition(root, required(projectName, "project"), required(taskId, "task id"), "superseded", tail);
+      if (subcommand === "reject") return tasks.disposition(root, required(projectName, "project"), required(taskId, "task id"), "rejected", tail);
+      if (subcommand === "defer") return tasks.defer(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|transfer|amend|import|start|prove|handoff|respond|review|return|done|block|unblock|list|open`.");
+      throw new Error("Use `atdd-flow task add|assign|transfer|amend|import|start|prove|handoff|respond|review|return|done|block|supersede|reject|defer|unblock|list|open`.");
     },
     seat: async () => {
       if (rest[0] === "retire") return tasks.retireSeat(root, required(rest[1], "address"), rest.slice(2));

package/src/multiplexer.ts

@@ -1,7 +1,7 @@
 import { readdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { desk, exists, paths, project, readYaml, runOutput, type Project, type Seat } from "./core";
-import { seatTasks } from "./tasks";
+import { seatTasks, terminal } from "./tasks";
 
 export type HerdrPolicy = {
   schema: "atdd-workflow/multiplexer/herdr/v1";
@@ -179,7 +179,7 @@ async function targets(root: string, options: { strict?: string; unprojected?: U
       if (entry.role === "driver") {
         // An explicit per-seat projection keeps the established assigned-work rule.
         linked = entry.address === options.strict
-          ? (await seatTasks(root, name, entry.address)).some(({ task }) => task.assignee === entry.address && task.status !== "done")
+          ? (await seatTasks(root, name, entry.address)).some(({ task }) => task.assignee === entry.address && !terminal(task))
           : await activeDriver(root, name, entry, options.live);
         if (linked) options.activeDrivers?.add(entry.address);
       }

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 TaskHandoff, type TaskStatus } from "./tasks";
+import { type Task, type TaskHandoff, type TaskStatus, terminal } from "./tasks";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { type Message, type Thread } from "./threads";
 
@@ -14,7 +14,7 @@ const useColor = Boolean(process.stdout.isTTY && !process.env.NO_COLOR && proces
 const paint = (text: string, code: number) => useColor ? `\u001B[${code}m${text}\u001B[0m` : text;
 const muted = (text: string) => paint(text, 2);
 const strong = (text: string) => paint(text, 1);
-const tone = (text: string, state: string) => paint(text, ({ BLOCKED: 31, RE_SEAT: 31, REVIEW: 33, WAITING: 33, ASSIGN: 36, VERIFY: 35, ACTIVE: 36, DONE: 32 } as Record<string, number>)[state] ?? 37);
+const tone = (text: string, state: string) => paint(text, ({ SUPERSEDED: 90, REJECTED: 90, BLOCKED: 31, RE_SEAT: 31, REVIEW: 33, WAITING: 33, ASSIGN: 36, VERIFY: 35, ACTIVE: 36, DONE: 32 } as Record<string, number>)[state] ?? 37);
 const truncate = (value: string, width: number) => value.length <= width ? value : `${value.slice(0, Math.max(1, width - 1))}…`;
 const dot = " · ";
 
@@ -55,7 +55,7 @@ async function tasks(root: string, project: string): Promise<ListedTask[]> {
   const byId = new Map(entries.map((entry) => [entry.id, entry.task]));
   return entries.map((entry) => ({
     ...entry,
-    waiting: (entry.task.depends_on ?? []).filter((dependency) => byId.get(dependency)?.status !== "done"),
+    waiting: (entry.task.depends_on ?? []).filter((dependency) => !(byId.get(dependency) && terminal(byId.get(dependency)!))),
   }));
 }
 
@@ -99,10 +99,11 @@ function bar(done: number, total: number, width = 16) {
 }
 
 function stateName(status: TaskStatus) {
-  return ({ todo: "READY", in_progress: "ACTIVE", review: "REVIEW", done: "DONE" } as Record<TaskStatus, string>)[status];
+  return ({ todo: "READY", in_progress: "ACTIVE", review: "REVIEW", done: "DONE", superseded: "SUPERSEDED", rejected: "REJECTED" } as Record<TaskStatus, string>)[status];
 }
 
 function taskPhase(entry: ListedTask) {
+  if (terminal(entry.task)) return stateName(entry.task.status);
   if (entry.task.blocker) return "BLOCKED";
   if (entry.waiting.length) return "WAITING";
   return stateName(entry.task.status);
@@ -115,7 +116,7 @@ function handoffStateName(value: TaskHandoff["state"]) {
 function attentionForTask(entry: ListedTask, checkpointBySeat: Map<string, Checkpoint | undefined>): Attention | undefined {
   const { task } = entry;
   const inspect = `atdd-flow task open ${entry.project} ${entry.id}`;
-  if (task.status === "done") return undefined;
+  if (terminal(task)) return undefined;
   if (task.blocker) return {
     project: entry.project, id: entry.id, label: task.title, state: "BLOCKED", detail: task.blocker,
     command: inspect, priority: 0,
@@ -174,11 +175,12 @@ function printProjects(projects: string[], allTasks: ListedTask[], allSeats: Lis
     const tasks = allTasks.filter((entry) => entry.project === project);
     const seats = allSeats.filter((entry) => entry.project === project);
     const done = tasks.filter((entry) => entry.task.status === "done").length;
+    const closed = tasks.filter((entry) => terminal(entry.task)).length;
     const active = seats.filter((entry) => entry.checkpoint?.status === "active").length;
     const blocked = seats.filter((entry) => entry.checkpoint?.status === "blocked").length;
     const nameWidth = Math.min(22, Math.max(14, Math.floor(width / 4)));
-    const counts = `${done}/${tasks.length} done${active ? `${dot}${active} active` : ""}${blocked ? `${dot}${blocked} blocked` : ""}`;
-    console.log(`  ${strong(truncate(project, nameWidth).padEnd(nameWidth))} ${bar(done, tasks.length)}  ${counts}`);
+    const counts = `${done}/${tasks.length} done${closed > done ? `${dot}${closed - done} closed without delivery` : ""}${active ? `${dot}${active} active` : ""}${blocked ? `${dot}${blocked} blocked` : ""}`;
+    console.log(`  ${strong(truncate(project, nameWidth).padEnd(nameWidth))} ${bar(closed, tasks.length)}  ${counts}`);
   }
 }
 
@@ -311,7 +313,8 @@ async function taskDashboard(root: string, projectName: string, taskId: string)
 
   rule("NEXT");
   let next: string;
-  if (entry.task.blocker) next = "Resolve the recorded blocker before changing state.";
+  if (terminal(entry.task)) next = `Closed by terminal disposition (${entry.task.status}); no further action.`;
+  else if (entry.task.blocker) next = "Resolve the recorded blocker before changing state.";
   else if (entry.waiting.length) next = "Complete the unmet dependencies first.";
   else if (entry.task.status === "review" && reviewRequired && !latestReview) next = `Coordinator: launch final review with \`atdd-flow behavioral-review launch ${projectName} ${taskId} --by ${entry.task.coordinator} --application <application> --placement <container>.\``;
   else if (entry.task.status === "review" && latestReview?.status === "pending") next = `Await reviewer ${latestReview.reviewer.address}; inspect with \`atdd-flow behavioral-review open ${projectName} ${taskId}.\``;

package/src/owner-escalations.ts

@@ -2,7 +2,7 @@ import { createHash } from "node:crypto";
 import { readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { atomicYaml, exists, now as workflowNow, paths, readYaml, required, seat } from "./core";
-import { type Task } from "./tasks";
+import { type Task, terminal } from "./tasks";
 import { post, startThread } from "./threads";
 
 type Option = "authorize-safe-fallback" | "provide-cross-project-decision" | "hold-or-resolve";
@@ -70,7 +70,7 @@ async function independent(root: string, entry: { project: string; id: string },
   return false;
 }
 function candidate(entry: { project: string; id: string; task: Task }): Candidate | undefined {
-  if (entry.task.status === "done" || !entry.task.blocker) return;
+  if (terminal(entry.task) || !entry.task.blocker) return;
   const material = classification(entry.task.blocker); if (!material) return;
   return { schema: "atdd-workflow/owner-alert/v1", state: "blocked", material_class: material, affected_tasks: [`${entry.project}/${entry.id}`], evidence: redactOwnerEvidence(entry.task.blocker),
     fallback: { state: "absent", evidence: "No independent checkpoint-active task is visibly executing in the affected project.", safe_automatic_action: "none" }, owner_options: options,

package/src/seats.ts

@@ -9,7 +9,7 @@ import {
   required, run, runOutput, runtimeAddress, seat, taskId, words, yaml,
 } from "./core";
 import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
-import { type Task, seatTasks } from "./tasks";
+import { type Task, seatTasks, terminal } from "./tasks";
 import { misplacedSeats, projectHerdrSeat } from "./multiplexer";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
@@ -344,7 +344,7 @@ async function launchEligibleTasks(root: string, record: Seat, address: string)
     if (entry.task.status === "in_progress") return entry;
     if (entry.task.status !== "todo") return undefined;
     const dependencies = await Promise.all((entry.task.depends_on ?? []).map(async (id) => {
-      try { return (await readYaml<{ status?: string }>(paths(root).taskFile(record.project, id))).status === "done"; }
+      try { return terminal(await readYaml<{ status: Task["status"] }>(paths(root).taskFile(record.project, id))); }
       catch { return false; }
     }));
     return dependencies.every(Boolean) ? entry : undefined;
@@ -355,7 +355,7 @@ async function launchEligibleTasks(root: string, record: Seat, address: string)
 async function chooseLaunchModel(root: string, config: Desk, record: Seat, portfolio: ModelPortfolio, select: (input: ModelSelectionInput) => Promise<ModelSelectionResponse> = selectModel) {
   const candidates = availableModelCandidates(config, portfolio);
   if (!candidates.length) throw new Error("No enabled model in models.yaml has an available executable.");
-  const work = (await seatTasks(root, record.project, record.address)).filter((entry) => entry.task.status !== "done");
+  const work = (await seatTasks(root, record.project, record.address)).filter((entry) => !terminal(entry.task));
   const selection = await select({
     seat: { address: record.address, role: record.role, ...(record.purpose ? { purpose: record.purpose } : {}) },
     tasks: work.map((entry) => ({

package/src/tasks.ts

@@ -4,7 +4,7 @@ import {
   type Checkpoint, type Seat, atomicYaml, canonicalAddress, exists, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
 } from "./core";
 
-export type TaskStatus = "todo" | "in_progress" | "review" | "done";
+export type TaskStatus = "todo" | "in_progress" | "review" | "done" | "superseded" | "rejected";
 /** 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";
@@ -22,6 +22,8 @@ export type CoordinatorTransfer = {
   exact_head: { branch: string; commit: string };
   effective_at: string;
 };
+export type TerminalDisposition = { kind: "superseded" | "rejected"; by: string; at: string; reason: string };
+export type DeferredDisposition = { by: string; at: string; reason: string; owner: string; trigger: string; review_at: string };
 export type Task = {
   schema: "atdd-workflow/task/v1";
   title: string;
@@ -36,20 +38,27 @@ export type Task = {
   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. */
+  /** Legacy topology evidence is preserved but is not created for role-neutral assignments. */
   governed_base?: GovernedBase;
   /** Absent on legacy tasks; later entries never rewrite earlier coordinator evidence. */
   coordinator_transfers?: CoordinatorTransfer[];
+  /** Immutable terminal coordinator decision. */
+  disposition?: TerminalDisposition;
+  /** Bounded hold with an accountable owner, trigger, and review point. */
+  deferred?: DeferredDisposition;
   done_when: DoneWhen[];
 };
 
 export type ListedTask = { id: string; task: Task };
+export const terminal = (task: Pick<Task, "status">) => task.status === "done" || task.status === "superseded" || task.status === "rejected";
 
 const transitions: Record<TaskStatus, TaskStatus[]> = {
   todo: ["in_progress"],
   in_progress: ["review"],
   review: ["in_progress", "done"],
   done: [],
+  superseded: [],
+  rejected: [],
 };
 
 function assertCoordinatorIntegrity(task: Task, id: string) {
@@ -94,7 +103,7 @@ export async function seatTasks(root: string, projectName: string, address: stri
 
 async function ready(root: string, projectName: string, task: Task) {
   const dependencies = await Promise.all((task.depends_on ?? []).map(async (id) => ({ id, task: await readTask(root, projectName, id) })));
-  return dependencies.filter((entry) => entry.task.status !== "done").map((entry) => entry.id);
+  return dependencies.filter((entry) => !terminal(entry.task)).map((entry) => entry.id);
 }
 
 function allProofs(task: Task) {
@@ -141,6 +150,24 @@ async function governedBase(root: string, projectName: string, coordinatorAddres
   return { coordinator: coordinator.address, branch, commit };
 }
 
+/**
+ * Assignment is accountability only: any existing, non-retired seat of the same project is eligible
+ * regardless of role. Validation happens before any task write, so a rejection leaves no partial record.
+ */
+async function eligibleAssignee(root: string, projectName: string, address: string) {
+  const candidate = await seat(root, address);
+  if (candidate.project !== projectName) throw new Error(`Task assignee ${candidate.address} does not belong to project ${projectName}.`);
+  if (candidate.retired) throw new Error(`Task assignee ${candidate.address} is retired.`);
+  return candidate;
+}
+
+/** Legacy topology evidence is recorded only when it is exactly provable; it never gates assignment. */
+async function evidenceBase(root: string, projectName: string, coordinator: string, assignee: Seat): Promise<GovernedBase | undefined> {
+  if (assignee.role !== "driver") return undefined;
+  try { return await governedBase(root, projectName, coordinator, assignee.address); }
+  catch { return undefined; }
+}
+
 async function retireAssignee(root: string, projectName: string, id: string, task: Task) {
   return retireDriver(root, projectName, required(task.assignee, `an assignee for task ${id}`), id);
 }
@@ -172,9 +199,26 @@ async function absentUnregisteredWorktree(root: string, projectName: string, own
   return `Worktree ${owner.worktree} is absent and unregistered; retired without worktree finish; branch ${owner.branch} retained.`;
 }
 
+/**
+ * Resolves the ATDD Bun that retires a seat: the primary checkout's local copy, then the primary
+ * checkout's package source when it is ATDD Bun itself, then PATH. A seat worktree copy is never used:
+ * a finished branch may pin an older toolkit that refuses the seat being retired.
+ */
+async function retirementBun(root: string, projectName: string) {
+  const primary = resolve(required((await project(root, projectName)).repository, `a repository for project ${projectName}`));
+  const local = join(primary, "node_modules", ".bin", "atdd-bun");
+  if (await exists(local)) return [local];
+  const source = join(primary, "src", "cli.ts");
+  try {
+    if ((await Bun.file(join(primary, "package.json")).json()).name === "@afokapu/atdd-bun" && await exists(source)) return [process.execPath, source];
+  } catch { /* no readable package manifest; fall through to PATH */ }
+  // Absolute so command execution never substitutes the seat worktree's local copy.
+  return [required(Bun.which("atdd-bun") ?? undefined, "atdd-bun in the primary checkout node_modules/.bin or on PATH")];
+}
+
 async function retireDriver(root: string, projectName: string, assignee: string, id: string, allowAbsentWorktree = false) {
   const unfinished = (await allTasks(root, projectName))
-    .filter((entry) => entry.id !== id && entry.task.assignee === assignee && entry.task.status !== "done")
+    .filter((entry) => entry.id !== id && (entry.task.assignee === assignee || entry.task.coordinator === assignee) && !terminal(entry.task))
     .map((entry) => entry.id);
   if (unfinished.length) throw new Error(`Cannot retire ${assignee}; it still owns unfinished tasks: ${unfinished.join(", ")}.`);
 
@@ -182,7 +226,7 @@ async function retireDriver(root: string, projectName: string, assignee: string,
   if (owner.retired) throw new Error(`Seat ${assignee} is already retired.`);
   try {
     const summary = (allowAbsentWorktree ? await absentUnregisteredWorktree(root, projectName, owner) : undefined)
-      ?? await runOutput(["atdd-bun", "worktree", "finish", "--delete-branch"], owner.worktree);
+      ?? await runOutput([...await retirementBun(root, projectName), "worktree", "finish", "--delete-branch"], owner.worktree);
     owner.retired = { task: `${projectName}/${id}`, completed_at: now(), summary };
     await atomicYaml(paths(root).seatFile(assignee), owner);
     const checkpoint: Checkpoint = {
@@ -206,32 +250,53 @@ async function retireDriver(root: string, projectName: string, assignee: string,
   await closeRetiredDriverWorkspace(root, owner);
 }
 
-/** Retires a driver whose assigned tasks are all already done. */
+/**
+ * Only main retires a coordinator, and never one seated on the primary checkout; a driver may also be
+ * retired by the coordinator of every task assigned to it.
+ */
+async function assertRetireAuthority(root: string, owner: Seat, actor: string, owned: ListedTask[]) {
+  const main = `main@${owner.project}`;
+  if (owner.role === "coordinator") {
+    if (actor !== main) throw new Error(`Only ${main} may retire coordinator ${owner.address}.`);
+    const primary = (await project(root, owner.project)).repository;
+    if (primary && await canonicalPath(owner.worktree) === await canonicalPath(primary)) {
+      throw new Error(`Cannot retire ${owner.address}; its worktree is the primary checkout.`);
+    }
+  } else if (actor !== main && owned.some((entry) => entry.task.coordinator !== actor)) {
+    throw new Error(`Only ${main} or the coordinator of every task assigned to ${owner.address} may retire it.`);
+  }
+}
+
+/**
+ * Retires a driver whose assigned tasks are all terminal (done, superseded, or rejected), or, for main only, a coordinator
+ * (never main or the primary checkout) whose coordinated and assigned tasks are all terminal.
+ */
 export async function retireSeat(root: string, address: string, args: string[]) {
   const resolved = await canonicalAddress(root, address);
   const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
   const owner = await seat(root, resolved);
-  if (owner.role !== "driver") throw new Error(`Only driver seats can be retired; ${resolved} is ${owner.role}.`);
+  const coordinator = owner.role === "coordinator";
+  if (owner.role !== "driver" && !coordinator) throw new Error(`Only driver or coordinator seats can be retired; ${resolved} is ${owner.role}.`);
   if (owner.retired) throw new Error(`Seat ${resolved} is already retired.`);
-  const owned = (await allTasks(root, owner.project)).filter((entry) => entry.task.assignee === resolved);
-  if (!owned.length) throw new Error(`Cannot retire ${resolved}; it has no assigned tasks.`);
-  const unfinished = owned.filter((entry) => entry.task.status !== "done").map((entry) => entry.id);
+  const owned = (await allTasks(root, owner.project))
+    .filter((entry) => entry.task.assignee === resolved || (coordinator && entry.task.coordinator === resolved));
+  if (!owned.length) throw new Error(`Cannot retire ${resolved}; it has no ${coordinator ? "coordinated or " : ""}assigned tasks.`);
+  const unfinished = owned.filter((entry) => !terminal(entry.task)).map((entry) => entry.id);
   if (unfinished.length) throw new Error(`Cannot retire ${resolved}; it still owns unfinished tasks: ${unfinished.join(", ")}.`);
-  if (actor !== `main@${owner.project}` && owned.some((entry) => entry.task.coordinator !== actor)) {
-    throw new Error(`Only main@${owner.project} or the coordinator of every task assigned to ${resolved} may retire it.`);
-  }
+  await assertRetireAuthority(root, owner, actor, owned);
   await retireDriver(root, owner.project, resolved, owned.at(-1)!.id, true);
   console.log(`${resolved}  retired`);
 }
 
 export async function add(root: string, projectName: string, id: string, args: string[]) {
+  const normalizedId = taskId(id);
   await project(root, projectName);
+  if (await exists(paths(root).taskFile(projectName, normalizedId))) throw new Error(`Task ${normalizedId} already exists and cannot be replaced.`);
   const coordinator = await canonicalAddress(root, required(words(args, "--coordinator"), "--coordinator"));
   const assigneeValue = words(args, "--assignee");
   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 base = assignee ? await evidenceBase(root, projectName, coordinator, await eligibleAssignee(root, projectName, assignee)) : undefined;
   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);
@@ -247,8 +312,8 @@ export async function add(root: string, projectName: string, id: string, args: s
     ...(dependsOn?.length ? { depends_on: dependsOn } : {}),
     done_when: doneWhen,
   };
-  await writeTask(root, projectName, taskId(id), task);
-  console.log(id);
+  await writeTask(root, projectName, normalizedId, task);
+  console.log(normalizedId);
 }
 
 export async function assign(root: string, projectName: string, id: string, args: string[]) {
@@ -258,8 +323,7 @@ export async function assign(root: string, projectName: string, id: string, args
   if (task.status !== "todo") throw new Error(`Task ${id} can only be assigned while todo.`);
   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);
+  const base = await evidenceBase(root, projectName, task.coordinator, await eligibleAssignee(root, projectName, assignee));
   task.assignee = assignee;
   if (base) task.governed_base = base;
   await writeTask(root, projectName, id, task);
@@ -354,6 +418,7 @@ export async function transfer(root: string, projectName: string, id: string, ar
 
 export async function amend(root: string, projectName: string, id: string, args: string[]) {
   const task = await readTask(root, projectName, taskId(id));
+  if (task.disposition) throw new Error(`Task ${id} has a terminal disposition and cannot be amended.`);
   const title = words(args, "--title");
   const body = words(args, "--body");
   const source = words(args, "--source");
@@ -376,6 +441,7 @@ export async function amend(root: string, projectName: string, id: string, args:
  */
 export async function importCompleted(root: string, projectName: string, id: string, args: string[]) {
   const task = await readTask(root, projectName, taskId(id));
+  if (task.disposition) throw new Error(`Task ${id} has a terminal disposition and cannot be imported.`);
   const proofs = values(args, "--proof");
   if (!proofs.length) throw new Error("An imported completion needs at least one --proof reference.");
 
@@ -422,7 +488,7 @@ async function transition(root: string, projectName: string, id: string, next: T
     if (retire) await retireAssignee(root, projectName, id, task);
   }
   task.status = next;
-  if (next !== "in_progress") delete task.blocker;
+  if (next !== "in_progress") { delete task.blocker; delete task.deferred; }
   await writeTask(root, projectName, id, task);
   console.log(`${id}  ${next}`);
 }
@@ -513,6 +579,7 @@ export async function prove(root: string, projectName: string, id: string, args:
 
 export async function block(root: string, projectName: string, id: string, args: string[]) {
   const task = await readTask(root, projectName, taskId(id));
+  if (task.disposition) throw new Error(`Task ${id} has a terminal disposition and cannot be blocked.`);
   const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
   if (actor !== task.assignee && actor !== task.coordinator) throw new Error(`Only the assignee or coordinator may block task ${id}.`);
   if (task.status === "done") throw new Error(`Completed task ${id} cannot be blocked.`);
@@ -521,6 +588,46 @@ export async function block(root: string, projectName: string, id: string, args:
   console.log(`${id}  blocked`);
 }
 
+/**
+ * Records a terminal coordinator decision (superseded or rejected). Only the task coordinator may
+ * decide, a completed or already-disposed task is never rewritten, and the decision keeps its
+ * author, time, and reason as immutable audit history.
+ */
+export async function disposition(root: string, projectName: string, id: string, kind: TerminalDisposition["kind"], 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 ${kind} task ${id}.`);
+  if (task.disposition || task.status === "done") throw new Error(`Task ${id} already has terminal history and cannot be ${kind}.`);
+  task.status = kind;
+  task.disposition = { kind, by: actor, at: now(), reason: required(words(args, "--reason"), "--reason") };
+  delete task.blocker;
+  await writeTask(root, projectName, taskId(id), task);
+  console.log(`${id}  ${kind}`);
+}
+
+/**
+ * Holds a task behind a bounded deferral. The accountable owner, the trigger, and an ISO-8601 review
+ * point are mandatory, so a deferral can never become an indefinite open blocker; unblocking clears it.
+ */
+export async function defer(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 defer task ${id}.`);
+  if (task.disposition || task.status === "done") throw new Error(`Task ${id} has terminal history and cannot be deferred.`);
+  const ownerValue = words(args, "--owner");
+  const trigger = words(args, "--trigger");
+  const reviewAt = words(args, "--review-at");
+  if (!ownerValue || !trigger || !reviewAt) throw new Error("A defer needs --owner, --trigger, and --review-at.");
+  if (Number.isNaN(Date.parse(reviewAt))) throw new Error("--review-at must be an ISO-8601 timestamp.");
+  const owner = await canonicalAddress(root, ownerValue);
+  if ((await seat(root, owner)).project !== projectName) throw new Error(`Deferred owner ${owner} does not belong to project ${projectName}.`);
+  const reason = required(words(args, "--reason"), "--reason");
+  task.deferred = { by: actor, at: now(), reason, owner, trigger, review_at: reviewAt };
+  task.blocker = `Deferred until ${reviewAt}: ${reason}`;
+  await writeTask(root, projectName, taskId(id), task);
+  console.log(`${id}  deferred`);
+}
+
 export async function unblock(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"));
@@ -532,6 +639,7 @@ export async function unblock(root: string, projectName: string, id: string, arg
   const { assertDependentsMayUnblock } = await import("./ephemeral-resources");
   await assertDependentsMayUnblock(root, { project: projectName, task: id });
   delete task.blocker;
+  delete task.deferred;
   await writeTask(root, projectName, id, task);
   console.log(`${id}  unblocked`);
 }
@@ -573,6 +681,7 @@ async function directiveFor(root: string, projectName: string, id: string, task:
   if (task.assignee === address) {
     const as = { ...base, role: "assignee" as const };
     if (task.status === "done") return { ...as, lifecycle: "DONE", action: "Perform DONE housekeeping only; start no new implementation." };
+    if (terminal(task)) return undefined;
     if (task.blocker) return { ...as, lifecycle: "BLOCKED", action: `Remain blocked and await coordinator resolution (${task.blocker}). Continue only independent required work.` };
     if (task.status === "review") return { ...as, lifecycle: "REVIEW", action: "Await coordinator review; do not continue implementation." };
     if (task.status === "todo") {
@@ -589,7 +698,7 @@ async function directiveFor(root: string, projectName: string, id: string, task:
       command: `atdd-flow task handoff ${projectName} ${id} --by ${address} --phase ${current} --evidence <message-or-reference>`,
     };
   }
-  if (task.coordinator === address && task.status !== "done") {
+  if (task.coordinator === address && !terminal(task)) {
     const as = { ...base, role: "coordinator" as const };
     if (task.blocker) return { ...as, lifecycle: "BLOCKED", action: `Resolve the blocker (${task.blocker}) and then unblock the task.`, command: `atdd-flow task unblock ${projectName} ${id} --by ${address}` };
     if (task.status === "review") return { ...as, lifecycle: "REVIEW", action: "Review the submitted task; complete it or return it to work.", command: `atdd-flow task open ${projectName} ${id}` };

package/src/threads.ts

@@ -1,7 +1,7 @@
 import { mkdir, readdir, rm, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { notify } from "./adapters";
-import { seatTasks } from "./tasks";
+import { seatTasks, terminal } from "./tasks";
 import {
   atomicYaml, canonicalAddress, desk, has, id, now, paths, project, readYaml,
   required, runtimeAddress, seat, words,
@@ -83,9 +83,9 @@ async function assertRoute(root: string, from: string, recipients: string[]) {
     throw new Error(`${from} may not directly address operator@desk; route through the responsible coordinator and main seat.`);
   }
   if (sender.role === "driver" && targets.some((target) => target.role !== "coordinator")) {
-    // A driver may also reach the actual coordinator of its own non-done task in the same project (e.g. main).
+    // A driver may also reach the actual coordinator of its own non-terminal task in the same project (e.g. main).
     const owners = new Set((await seatTasks(root, sender.project, from))
-      .filter(({ task }) => task.assignee === from && task.status !== "done")
+      .filter(({ task }) => task.assignee === from && !terminal(task))
       .map(({ task }) => task.coordinator));
     const permitted = (target: { address: string; role: string; project: string }) =>
       target.role === "coordinator" || (target.project === sender.project && owners.has(target.address));