@afokapu/atdd-flow 0.3.16 → 0.3.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "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/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/tasks.ts

@@ -4,6 +4,11 @@ import {
 } 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 Task = {
   schema: "atdd-workflow/task/v1";
@@ -15,6 +20,10 @@ 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;
   done_when: DoneWhen[];
 };
 
@@ -220,6 +229,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"));