@afokapu/atdd-flow 0.3.4 → 0.3.6

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
 
@@ -178,7 +178,15 @@ runtime:
   wake: native
 ```
 
-`application` identifies the visible pane. `wake: native` tells Flow not to also send a host prompt; the Pi extension reads `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, observes final `M-*.yaml` files, filters recipients, and queues a follow-up turn that tells Pi which durable file to read. Other agents keep `wake: host` and use their normal host notification adapter.
+`application` identifies the visible pane. `wake: native` tells Flow not to also send a host prompt; the Pi extension reads `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, observes final `M-*.yaml` files, filters recipients, and queues a compact follow-up containing the thread subject, sender, recipients, thread/message IDs, and `atdd-flow message read <message-id>`. It never embeds the message body. Other agents keep `wake: host` and receive the same compact notification through their normal host adapter.
+
+Read one durable message without loading its complete thread:
+
+```sh
+atdd-flow message read M-...
+```
+
+The output includes only the message and its thread ID/subject; Flow rejects missing or ambiguous message IDs.
 
 Pi’s native wake-up is intentionally lightweight: no daemon, duplicate mailbox, or separate extension installation. The extension is shipped inside the Flow package. Its in-memory message-id guard tolerates duplicate filesystem events; the Desk thread files remain the source of truth.
 

package/extensions/pi/index.ts

@@ -4,8 +4,8 @@ import { join } from "node:path";
 import { parse } from "yaml";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-type Thread = { participants?: unknown };
-type Mail = { id?: unknown; from?: unknown; to?: unknown };
+type Thread = { participants?: unknown; subject?: unknown };
+type Mail = { id?: unknown; from?: unknown; to?: unknown; subject?: unknown };
 
 const finalMail = /^M-[^.]+\.yaml$/;
 
@@ -21,6 +21,15 @@ export function addressedTo(mail: Mail, thread: Thread, seat: string) {
   return mail.to === "all" && participants(thread).includes(seat);
 }
 
+/** A compact wake notice; the durable message body is read only on demand. */
+export function mailNotice(threadId: string, mail: Mail) {
+  const id = typeof mail.id === "string" ? mail.id : "unknown";
+  const subject = typeof mail.subject === "string" ? mail.subject : undefined;
+  const from = typeof mail.from === "string" ? mail.from : "unknown";
+  const recipients = mail.to === "all" ? "all" : Array.isArray(mail.to) ? mail.to.join(", ") : "unknown";
+  return `SYSTEM: Flow mail ${id} | thread ${threadId}${subject ? ` (${subject})` : ""} | ${from} → ${recipients}. Read: atdd-flow message read ${id}`;
+}
+
 /**
  * A Pi-native wake adapter. The Desk remains authoritative: this extension
  * only observes final immutable mail files and tells Pi where to read them.
@@ -55,7 +64,7 @@ export default function (pi: ExtensionAPI) {
         delivered.add(key);
         pi.sendMessage({
           customType: "atdd-flow-mail",
-          content: `SYSTEM: new Flow mail ${id}. Read ${file}`,
+          content: mailNotice(threadId, { ...mail, id, subject: typeof thread.subject === "string" ? thread.subject : undefined }),
           display: true,
           details: { thread: threadId, message: id, path: file },
         }, { triggerTurn: true, deliverAs: "followUp" });

package/package.json

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

package/src/cli.ts

@@ -2,7 +2,7 @@
 
 import { basename, resolve } from "node:path";
 import { init, initProject, spawn, bind, useApplication, attach, launch, describe, checkpoint, migrate, openSeat, piExtensionPath } from "./seats";
-import { addParticipant, openThread, post, receipt, result, startThread } from "./threads";
+import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
 import { required, values, words } from "./core";
 import { addressBook } from "./address-book";
@@ -35,11 +35,13 @@ 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>]
   atdd-flow thread add <thread-id> <address>
   atdd-flow thread open <thread-id>
+  atdd-flow message read <message-id>
   atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--expects-result]
   atdd-flow receipt <thread-id> <message-id> --from <address> [--body <text>]
   atdd-flow result <thread-id> <message-id> --from <address> --body <text>
@@ -100,9 +102,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;
@@ -111,6 +114,10 @@ async function main() {
       if (subcommand === "open") return openThread(root, required(tail[0], "thread id"));
       throw new Error("Use `atdd-flow thread start|add|open`.");
     },
+    message: async () => {
+      if (rest[0] === "read") return readMessage(root, required(rest[1], "message id"));
+      throw new Error("Use `atdd-flow message read <message-id>`.");
+    },
     post: () => post(root, required(rest[0], "thread id"), rest.slice(1)),
     receipt: () => receipt(root, required(rest[0], "thread id"), required(rest[1], "message id"), rest.slice(2)),
     result: () => result(root, required(rest[0], "thread id"), required(rest[1], "message id"), rest.slice(2)),

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

@@ -81,8 +81,10 @@ async function inject(root: string, address: string, message: Message, threadId:
   if (runtime.wake === "native") return;
   const nativeAddress = runtime.addresses[runtime.application];
   if (!nativeAddress) return;
-  const file = paths(root).message(threadId, message.id);
-  const notice = `SYSTEM: new thread mail ${message.id} from ${message.from}. Read ${file}`;
+  const record = await thread(root, threadId);
+  const recipients = message.to === "all" ? "all" : message.to.join(", ");
+  const subject = record.subject.replace(/\s+/g, " ").trim();
+  const notice = `SYSTEM: Flow mail ${message.id} | thread ${threadId} (${subject}) | ${message.from} → ${recipients}. Read: atdd-flow message read ${message.id}`;
   try { await notify(runtime.application, nativeAddress, notice, (await desk(root)).herdr_session); }
   catch (error) { console.warn(`Notification for ${address} was not delivered: ${(error as Error).message}`); }
 }
@@ -132,6 +134,28 @@ export async function openThread(root: string, threadId: string) {
   console.log(Bun.YAML.stringify({ ...record, messages: all }));
 }
 
+/** Reads one durable message without loading or printing its whole thread. */
+export async function readMessage(root: string, messageId: string) {
+  if (!/^M-[A-Za-z0-9_-]+$/.test(messageId)) throw new Error(`Invalid message id: ${messageId}.`);
+  const folders = await readdir(paths(root).threads, { withFileTypes: true });
+  const matches = await Promise.all(folders
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith("T-"))
+    .map(async (entry) => {
+      const file = paths(root).message(entry.name, messageId);
+      try { return { thread: await thread(root, entry.name), message: await readYaml<Message>(file) }; }
+      catch { return undefined; }
+    }));
+  const found = matches.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry));
+  if (!found.length) throw new Error(`Message ${messageId} does not exist in this Desk.`);
+  if (found.length > 1) throw new Error(`Message ${messageId} is ambiguous across threads: ${found.map((entry) => entry.thread.id).join(", ")}.`);
+  const entry = found[0];
+  console.log(Bun.YAML.stringify({
+    schema: "atdd-workflow/message-read/v1",
+    thread: { id: entry.thread.id, subject: entry.thread.subject },
+    message: entry.message,
+  }));
+}
+
 export async function receipt(root: string, threadId: string, messageId: string, args: string[]) {
   const from = await canonicalAddress(root, required(words(args, "--from"), "--from"));
   const target = await replyTarget(root, threadId, messageId, from, false);