@afokapu/atdd-flow 0.3.3 → 0.3.4

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.4",
   "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";
@@ -49,6 +50,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>
@@ -132,6 +134,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/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) {