@afokapu/atdd-flow 0.3.39 → 0.3.40

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.40",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/tasks.ts

@@ -172,9 +172,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) && entry.task.status !== "done")
     .map((entry) => entry.id);
   if (unfinished.length) throw new Error(`Cannot retire ${assignee}; it still owns unfinished tasks: ${unfinished.join(", ")}.`);
 
@@ -182,7 +199,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,20 +223,40 @@ 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 already done, or, for main only, a coordinator
+ * (never main or the primary checkout) whose coordinated and assigned tasks are all done.
+ */
 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 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) => entry.task.status !== "done").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`);
 }