@afokapu/atdd-flow 0.3.3 → 0.3.5

package/README.md

@@ -130,7 +130,7 @@ atdd-flow behavioral-review launch resolver-os runtime-rollout --by coordinator@
 atdd-flow task done resolver-os runtime-rollout --by coordinator@resolver-os
 ```
 
-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. 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.
+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.
 
 ## Communicate and hand over
 

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

@@ -62,6 +62,13 @@ content:
     Start from the current seat, checkpoint, assigned tasks, and relevant thread records. A replacement
     agent resumes from those records; it does not depend on a conversation with its predecessor.
 
+    `operator@desk` is the human authority, not an autonomous agent identity. Never post, approve,
+    or make a decision while claiming that address unless the human operator actually supplied it.
+    Main seats are the normal repository-main integration gateway to the operator. Coordinators may
+    escalate a concrete decision or incident directly to the operator. Drivers send normal work
+    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.
+
     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/package.json

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

package/src/address-book.ts

@@ -0,0 +1,36 @@
+import { readdir } from "node:fs/promises";
+import { paths, readYaml, type Seat } from "./core";
+
+function identity(address: string) {
+  return address === "operator@desk" ? "human" : "agent";
+}
+
+function authority(record: Seat) {
+  if (record.address === "operator@desk") return "Human authority; no autonomous agent may post as this address.";
+  if (record.role === "main") return "Repository-main integration gateway; may escalate to operator@desk.";
+  if (record.role === "coordinator") return "Coordinates assigned work; may escalate a decision or incident to operator@desk.";
+  if (record.role === "driver") return "Delivers assigned work; routes normal communication through its coordinator.";
+  return "See the seat purpose and current assignment.";
+}
+
+export async function addressBook(root: string) {
+  const projects = (await readdir(paths(root).work)).sort();
+  const records: Seat[] = [];
+  for (const project of projects) {
+    const folder = paths(root).seats(project);
+    let locals: string[];
+    try { locals = await readdir(folder); }
+    catch { continue; }
+    for (const local of locals.sort()) {
+      try { records.push(await readYaml<Seat>(`${folder}/${local}/seat.yaml`)); }
+      catch { /* A partially removed legacy seat is not an address-book entry. */ }
+    }
+  }
+  console.log("# Desk address book\n");
+  console.log("`operator@desk` is the human authority. Drivers route normal work through coordinators; main seats are the normal technical gateway to the operator.\n");
+  console.log("| Address | Identity | Purpose / authority |\n| --- | --- | --- |");
+  for (const record of records.sort((left, right) => left.address.localeCompare(right.address))) {
+    const purpose = (record.purpose ?? authority(record)).replaceAll("|", "\\|");
+    console.log(`| ${record.address} | ${identity(record.address)} | ${purpose} |`);
+  }
+}

package/src/cli.ts

@@ -5,6 +5,7 @@ import { init, initProject, spawn, bind, useApplication, attach, launch, describ
 import { addParticipant, openThread, post, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
 import { required, values, words } from "./core";
+import { addressBook } from "./address-book";
 import * as judgment from "./judgment";
 import * as reviews from "./reviews";
 import { status } from "./overview";
@@ -34,6 +35,7 @@ Usage:
   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 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>]
   atdd-flow task open <project> <task-id>
   atdd-flow thread start --with <address,...> --subject <text> [--task <project/task-id>]
@@ -49,6 +51,7 @@ Usage:
   atdd-flow behavioral-review record <project> <task-id> --by <reviewer-address> --file <result-yaml>
   atdd-flow behavioral-review open <project> <task-id>
   atdd-flow open <address>
+  atdd-flow address-book
 
 Global:
   atdd-flow --root <desk-directory> <command>
@@ -98,9 +101,10 @@ async function main() {
       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 === "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|list|open`.");
+      throw new Error("Use `atdd-flow task add|assign|amend|import|start|prove|review|return|done|block|unblock|list|open`.");
     },
     thread: async () => {
       const [subcommand, ...tail] = rest;
@@ -132,6 +136,7 @@ async function main() {
       throw new Error("Use `atdd-flow behavioral-review launch|record|open <project> <task-id>`.");
     },
     open: () => openSeat(root, required(rest[0], "address")),
+    "address-book": () => addressBook(root),
   };
   const action = commands[command];
   if (!action) throw new Error(`Unknown command: ${command}`);

package/src/seats.ts

@@ -179,7 +179,7 @@ async function chooseLaunchModel(root: string, config: Desk, record: Seat, portf
 }
 
 export const launchNotice = (address: string) =>
-  `SYSTEM: you are ${address}. Read your durable seat and assigned task with: atdd-flow open ${address}. Use the installed atdd-flow command; never use bunx to replace it or run atdd-flow init against an existing Desk. If your native pane binding differs from the Desk record, report it to the operator or coordinator. Continue assigned in_progress work until it is review-ready or explicitly blocked.`;
+  `SYSTEM: you are ${address}. Read your durable seat and assigned task with: atdd-flow open ${address}. Use the installed atdd-flow command; never use bunx to replace it or run atdd-flow init against an existing Desk. Routing: operator@desk is the human authority; drivers report to coordinators, and main seats are the normal technical gateway to the operator. Continue assigned in_progress work until it is review-ready or explicitly blocked.`;
 
 /** Pi loads this extension inside its own process, so it can wake without host text injection. */
 export const piExtensionPath = () => join(import.meta.dir, "..", "extensions", "pi", "index.ts");

package/src/tasks.ts

@@ -240,6 +240,17 @@ export async function block(root: string, projectName: string, id: string, args:
   console.log(`${id}  blocked`);
 }
 
+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"));
+  if (actor !== task.coordinator) throw new Error(`Only ${task.coordinator} may unblock task ${id}.`);
+  if (task.status !== "in_progress") throw new Error(`Task ${id} can only be unblocked while in_progress.`);
+  if (!task.blocker) throw new Error(`Task ${id} has no blocker to clear.`);
+  delete task.blocker;
+  await writeTask(root, projectName, id, task);
+  console.log(`${id}  unblocked`);
+}
+
 export async function list(root: string, projectName: string, args: string[]) {
   const coordinator = words(args, "--coordinator") ? await canonicalAddress(root, required(words(args, "--coordinator"), "--coordinator")) : undefined;
   const assignee = words(args, "--assignee") ? await canonicalAddress(root, required(words(args, "--assignee"), "--assignee")) : undefined;

package/src/threads.ts

@@ -36,6 +36,7 @@ async function replyTarget(root: string, threadId: string, messageId: string, fr
   const recipients = target.to === "all" ? record.participants.filter((address) => address !== target.from) : target.to;
   if (!recipients.includes(from)) throw new Error(`${from} was not a recipient of message ${messageId}.`);
   if (needsResult && !target.expects_result) throw new Error(`Message ${messageId} does not expect a result.`);
+  return target;
 }
 
 async function seatsByRole(root: string, projectName: string, role: string) {
@@ -61,6 +62,18 @@ async function resolveRecipients(root: string, value: string, participants: stri
   return [...new Set(expanded.flat())];
 }
 
+async function assertRoute(root: string, from: string, recipients: string[]) {
+  if (from === "operator@desk") return;
+  const sender = await seat(root, from);
+  const targets = await Promise.all(recipients.map((address) => seat(root, address)));
+  if (targets.some((target) => target.address === "operator@desk") && !["main", "coordinator"].includes(sender.role)) {
+    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")) {
+    throw new Error(`${from} may message only a coordinator; coordinators and main seats handle further escalation.`);
+  }
+}
+
 async function inject(root: string, address: string, message: Message, threadId: string) {
   const target = await seat(root, address);
   const runtime = target.runtime;
@@ -81,6 +94,7 @@ async function post(root: string, threadId: string, args: string[], overrides: P
   const toValue = overrides.to ?? words(args, "--to") ?? "all";
   const recipients = Array.isArray(toValue) ? toValue : await resolveRecipients(root, toValue, record.participants);
   if (recipients.some((address) => !record.participants.includes(address))) throw new Error("Recipients must be thread participants.");
+  await assertRoute(root, from, recipients.filter((address) => address !== from));
   const message: Message = {
     schema: "atdd-workflow/message/v1", id: id("M"), from, to: toValue === "all" ? "all" : recipients,
     kind: overrides.kind ?? "message",
@@ -120,14 +134,14 @@ export async function openThread(root: string, threadId: string) {
 
 export async function receipt(root: string, threadId: string, messageId: string, args: string[]) {
   const from = await canonicalAddress(root, required(words(args, "--from"), "--from"));
-  await replyTarget(root, threadId, messageId, from, false);
-  return post(root, threadId, args, { from, kind: "receipt", in_reply_to: messageId, body: words(args, "--body") ?? `Received ${messageId}.` });
+  const target = await replyTarget(root, threadId, messageId, from, false);
+  return post(root, threadId, args, { from, to: [target.from], kind: "receipt", in_reply_to: messageId, body: words(args, "--body") ?? `Received ${messageId}.` });
 }
 
 export async function result(root: string, threadId: string, messageId: string, args: string[]) {
   const from = await canonicalAddress(root, required(words(args, "--from"), "--from"));
-  await replyTarget(root, threadId, messageId, from, true);
-  return post(root, threadId, args, { from, kind: "result", in_reply_to: messageId, body: required(words(args, "--body"), "--body") });
+  const target = await replyTarget(root, threadId, messageId, from, true);
+  return post(root, threadId, args, { from, to: [target.from], kind: "result", in_reply_to: messageId, body: required(words(args, "--body"), "--body") });
 }
 
 export async function status(root: string) {