@afokapu/atdd-flow 0.3.56 → 0.3.57

package/extensions/pi/index.ts

@@ -5,7 +5,7 @@ import { parse, stringify } from "yaml";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
 import { paths, readYaml, type Seat } from "../../src/core";
-import { directiveNotice, nextDirective } from "../../src/tasks";
+import { type NoticeState, createNoticeState, refreshDelivered, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
 import { handoverThresholdInstruction, runtimeStartupInstruction, successorInstruction } from "../../src/collaboration-policy";
 import { type RecoveryMode, recoveryFor } from "../../src/recovery-bundle";
 import { contextHandoverThreshold, readHandoverReplacement } from "../../src/handover";
@@ -341,18 +341,6 @@ const unsetOrEqual = (recorded: string | undefined, live: string | undefined) =>
 const sessionUnsetOrEqual = (runtime: Seat["runtime"], piSession?: string, piSessionPath?: string) =>
   unsetOrEqual(runtime?.pi_session, piSession) && unsetOrEqual(runtime?.pi_session_path, piSessionPath);
 
-/** Injects the current task-derived action; failure to derive never blocks mail or startup. */
-async function sendTaskDirective(pi: ExtensionAPI, root: string, seat: string) {
-  try {
-    const directive = await nextDirective(root, seat);
-    if (!directive) return;
-    pi.sendMessage({
-      customType: "atdd-flow-next-action", content: directiveNotice(seat, directive), display: true,
-      details: { project: directive.project, task: directive.task, lifecycle: directive.lifecycle, role: directive.role, authority: "task" },
-    }, { triggerTurn: true, deliverAs: "followUp" });
-  } catch { /* The durable task remains authoritative and is re-derived at the next startup or wake. */ }
-}
-
 /** The recovery bundle is advisory; any failure falls back to the plain prompt. */
 const recovery = (root: string, seat: string, mode: RecoveryMode, session?: string) => recoveryFor(root, seat, mode, session).catch(() => undefined);
 
@@ -365,6 +353,15 @@ export default function (pi: ExtensionAPI) {
   let handoverPrompted = false;
   // Host-attach only: mail older than this activation is consumed without a prompt, so a long backlog cannot trigger one turn per message.
   let hostActivatedAt: number | undefined;
+  const notices: NoticeState = createNoticeState();
+  const host = pi as unknown as Parameters<typeof sendTaskDirective>[0];
+  // Held follow-ups are re-derived when Pi delivers them, so a notice queued before a state change cannot reach the model stale.
+  pi.on("message_end", async (event) => {
+    const message = await refreshDelivered(root, seat, notices, event.message as Parameters<typeof refreshDelivered>[3]);
+    return message ? { message: message as typeof event.message } : undefined;
+  });
+  // Nothing queued survives a settled run, so a pending flag left by a cleared queue cannot suppress future notices.
+  pi.on("agent_settled", () => { notices.pending = false; });
   pi.on("turn_end", async (_event, ctx) => {
     if (handoverPrompted) return;
     const percent = ctx.getContextUsage()?.percent;
@@ -399,9 +396,10 @@ export default function (pi: ExtensionAPI) {
     runtime = createPiRuntime({ root, seat, deferActivation: true, deliver: async (mail, thread, path, sendIfOwned) => {
       if (!sendIfOwned) return false;
       if (hostActivatedAt !== undefined && Date.parse(typeof mail.created_at === "string" ? mail.created_at : "") < hostActivatedAt) return sendIfOwned(async () => undefined);
+      const notify = typeof mail.id === "string" && typeof thread.id === "string" && await shouldNotifyMail(root, seat, notices, thread.id, mail.id);
       return sendIfOwned(async () => {
-        // Task state is re-read at every wake, so queued mail cannot carry a stale action.
-        await sendTaskDirective(pi, root, seat);
+        if (!notify) return;
+        await sendTaskDirective(host, root, seat, notices);
         pi.sendMessage({
           customType: "atdd-flow-mail",
           content: mailNotice(typeof thread.id === "string" ? thread.id : "unknown", { ...mail, subject: typeof thread.subject === "string" ? thread.subject : undefined }),
@@ -442,7 +440,7 @@ export default function (pi: ExtensionAPI) {
             display: true, details: { seat, handover: successor.handover.id, authority: "handover-replacement" },
           }, { triggerTurn: true, deliverAs: "followUp" });
         }
-        await sendTaskDirective(pi, root, seat);
+        await sendTaskDirective(host, root, seat, notices);
         if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
       },
     }).catch(() => undefined);

package/package.json

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

package/src/next-action-notices.ts

@@ -0,0 +1,102 @@
+// URN: component:flow:e007:next-action-notices:backend:application
+// Tested-By:
+// - test:flow:next-action-notice-correctness
+// Runtime: bun
+// Purpose: Keep Pi next-action and mail notices current and non-repeating.
+
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { type TaskDirective, directiveNotice, nextDirective } from "./tasks";
+
+/** Per-session notice memory. Nothing here is durable; task and thread records stay authoritative. */
+export type NoticeState = {
+  /** A next-action follow-up has been queued and not yet delivered. */
+  pending: boolean;
+  lastDelivered?: string;
+  /** Blocker notices already delivered this session, keyed by task and blocker text. */
+  blockers: Set<string>;
+  /** Mail ids already notified this session. */
+  mail: Set<string>;
+};
+
+export type NoticeHost = {
+  sendMessage: (message: { customType: string; content: string; display: boolean; details: Record<string, unknown> }, options: { triggerTurn: boolean; deliverAs: "followUp" }) => void;
+};
+
+/** A delivered message as Pi hands it to `message_end`; only the fields used here. */
+export type NoticeMessage = { role?: string; customType?: string; content?: unknown; details?: Record<string, unknown> };
+
+export const createNoticeState = (): NoticeState => ({ pending: false, blockers: new Set(), mail: new Set() });
+
+const directiveKey = (directive: TaskDirective) =>
+  [directive.project, directive.task, directive.lifecycle, directive.role, directive.action, directive.command ?? ""].join("|");
+
+const directiveDetails = (directive: TaskDirective) =>
+  ({ project: directive.project, task: directive.task, lifecycle: directive.lifecycle, role: directive.role, authority: "task" });
+
+/** Queues the current task-derived action unless one is pending or the last delivered one is unchanged. */
+export async function sendTaskDirective(host: NoticeHost, root: string, seat: string, state: NoticeState) {
+  if (state.pending) return;
+  try {
+    const directive = await nextDirective(root, seat);
+    if (!directive || state.pending) return;
+    const key = directiveKey(directive);
+    if (key === state.lastDelivered || state.blockers.has(key)) return;
+    state.pending = true;
+    host.sendMessage({ customType: "atdd-flow-next-action", content: directiveNotice(seat, directive), display: true, details: directiveDetails(directive) }, { triggerTurn: true, deliverAs: "followUp" });
+  } catch {
+    state.pending = false; // The durable task remains authoritative and is re-derived at the next startup or wake.
+  }
+}
+
+/** Re-derives a held next-action follow-up when Pi delivers it; a queued message cannot be dropped, so it is replaced by the shortest truthful text. */
+async function currentDirective(root: string, seat: string, state: NoticeState, message: NoticeMessage): Promise<NoticeMessage> {
+  state.pending = false;
+  const directive = await nextDirective(root, seat).catch(() => undefined);
+  if (!directive) {
+    state.lastDelivered = undefined;
+    return { ...message, content: `SYSTEM: next-action notice for ${seat} withdrawn: task state has no actionable step. Task state outranks mail.`, details: { authority: "task", lifecycle: "NONE" } };
+  }
+  const key = directiveKey(directive);
+  if (key === state.lastDelivered) {
+    return { ...message, content: `SYSTEM: next action for ${seat} unchanged on ${directive.project}/${directive.task} [${directive.lifecycle}]; see the previous notice.`, details: directiveDetails(directive) };
+  }
+  state.lastDelivered = key;
+  if (directive.lifecycle === "BLOCKED") state.blockers.add(key);
+  return { ...message, content: directiveNotice(seat, directive), details: directiveDetails(directive) };
+}
+
+const isMailFile = (file: string, mailId: string) => file.startsWith("M-") && file.endsWith(".yaml") && file !== `${mailId}.yaml`;
+
+const cites = (record: Record<string, unknown> | undefined, seat: string, mailId: string) =>
+  record?.from === seat && (record.in_reply_to === mailId || String(record.body ?? "").includes(mailId));
+
+const readRecord = (path: string) => readFile(path, "utf8").then((raw) => parse(raw) as Record<string, unknown>).catch(() => undefined);
+
+/** True when this seat already replied to, or cited, the mail in the same thread. */
+export async function answeredBy(root: string, seat: string, threadId: string, mailId: string) {
+  const folder = join(root, "threads", threadId);
+  for (const file of (await readdir(folder).catch(() => [] as string[])).filter((entry) => isMailFile(entry, mailId))) {
+    if (cites(await readRecord(join(folder, file)), seat, mailId)) return true;
+  }
+  return false;
+}
+
+/** At most one notice per mail id per session, and none for mail this seat already answered. */
+export async function shouldNotifyMail(root: string, seat: string, state: NoticeState, threadId: string, mailId: string) {
+  if (state.mail.has(mailId)) return false;
+  state.mail.add(mailId);
+  return !await answeredBy(root, seat, threadId, mailId).catch(() => false);
+}
+
+/** `message_end` hook: keeps held notices truthful at the moment they reach the model. */
+export async function refreshDelivered(root: string, seat: string, state: NoticeState, message: NoticeMessage): Promise<NoticeMessage | undefined> {
+  if (message.role !== "custom") return undefined;
+  if (message.customType === "atdd-flow-next-action") return currentDirective(root, seat, state, message);
+  if (message.customType !== "atdd-flow-mail") return undefined;
+  const { thread, message: mailId } = message.details ?? {};
+  if (typeof thread !== "string" || typeof mailId !== "string") return undefined;
+  if (!await answeredBy(root, seat, thread, mailId).catch(() => false)) return undefined;
+  return { ...message, content: `SYSTEM: Flow mail ${mailId} on thread ${thread} was already answered by ${seat}; no action.` };
+}

package/src/tasks.ts

@@ -9,7 +9,8 @@ export type TaskStatus = "todo" | "in_progress" | "review" | "done" | "supersede
 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 };
+/** `submitted_phase` is absent on legacy records; it lets a same-phase accept be told apart from a never-submitted phase. */
+export type TaskHandoff = { state: HandoffState; evidence: string; updated_at: string; submitted_phase?: TaskPhase };
 export type DoneWhen = { text: string; proof?: string };
 export type GovernedBase = { coordinator: string; branch: string; commit: string };
 /** An append-only accountability decision; prior coordinator evidence remains untouched. */
@@ -539,7 +540,7 @@ export async function submitHandoff(root: string, projectName: string, id: strin
   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() };
+  task.handoff = { state: "awaiting_coordinator", evidence, updated_at: now(), submitted_phase: task.phase };
   await writeTask(root, projectName, taskId(id), task);
   console.log(`${id}  handoff awaiting_coordinator`);
 }
@@ -662,7 +663,7 @@ export async function open(root: string, projectName: string, id: string) {
 export type TaskDirective = {
   project: string;
   task: string;
-  lifecycle: "TODO" | "PLAN" | "RED" | "GREEN" | "REFACTOR" | "REVIEW" | "DONE" | "BLOCKED";
+  lifecycle: "TODO" | "PLAN" | "RED" | "GREEN" | "REFACTOR" | "REVIEW" | "BLOCKED";
   role: "assignee" | "coordinator";
   action: string;
   command?: string;
@@ -675,43 +676,65 @@ const phaseActions: Record<TaskPhase, string> = {
   refactor: "Refactor only after GREEN acceptance, then submit the REFACTOR handoff",
 };
 
-/** Pure projection of an existing task record; it creates no durable state. */
-async function directiveFor(root: string, projectName: string, id: string, task: Task, address: string): Promise<TaskDirective | undefined> {
-  const base = { project: projectName, task: id };
-  if (task.assignee === address) {
-    const as = { ...base, role: "assignee" as const };
-    if (task.status === "done") return { ...as, lifecycle: "DONE", action: "Perform DONE housekeeping only; start no new implementation." };
-    if (terminal(task)) return undefined;
-    if (task.blocker) return { ...as, lifecycle: "BLOCKED", action: `Remain blocked and await coordinator resolution (${task.blocker}). Continue only independent required work.` };
-    if (task.status === "review") return { ...as, lifecycle: "REVIEW", action: "Await coordinator review; do not continue implementation." };
-    if (task.status === "todo") {
-      const waiting = await ready(root, projectName, task);
-      return waiting.length
-        ? { ...as, lifecycle: "TODO", action: `Wait; dependencies are unfinished: ${waiting.join(", ")}.` }
-        : { ...as, lifecycle: "TODO", action: "Start assigned ready task.", command: `atdd-flow task start ${projectName} ${id} --by ${address}` };
-    }
-    const current = task.phase ?? "plan";
-    const lifecycle = current.toUpperCase() as TaskDirective["lifecycle"];
-    if (task.handoff?.state === "awaiting_coordinator") return { ...as, lifecycle, action: `Await coordinator response to the ${lifecycle} handoff; do not continue to the next phase.` };
+const phaseOrder: TaskPhase[] = ["plan", "red", "green", "refactor"];
+
+const phaseCommand = (projectName: string, id: string, address: string, current: TaskPhase) =>
+  `atdd-flow task handoff ${projectName} ${id} --by ${address} --phase ${current} --evidence <message-or-reference>`;
+
+/** An assignee whose submitted phase was accepted without naming a later phase is directed forward, never to resubmit. */
+function acceptedDirective(base: Pick<TaskDirective, "project" | "task" | "role">, id: string, address: string, current: TaskPhase): TaskDirective {
+  const next = phaseOrder[phaseOrder.indexOf(current) + 1];
+  if (!next) {
     return {
-      ...as, lifecycle, action: `${phaseActions[current]}.`,
-      command: `atdd-flow task handoff ${projectName} ${id} --by ${address} --phase ${current} --evidence <message-or-reference>`,
+      ...base, lifecycle: "REVIEW", action: "REFACTOR accepted; record a proof for every done_when item, then submit the task for review.",
+      command: `atdd-flow task review ${base.project} ${id} --by ${address}`,
     };
   }
-  if (task.coordinator === address && !terminal(task)) {
-    const as = { ...base, role: "coordinator" as const };
-    if (task.blocker) return { ...as, lifecycle: "BLOCKED", action: `Resolve the blocker (${task.blocker}) and then unblock the task.`, command: `atdd-flow task unblock ${projectName} ${id} --by ${address}` };
-    if (task.status === "review") return { ...as, lifecycle: "REVIEW", action: "Review the submitted task; complete it or return it to work.", command: `atdd-flow task open ${projectName} ${id}` };
-    if (task.status === "in_progress" && task.handoff?.state === "awaiting_coordinator") {
-      const current = task.phase ?? "plan";
-      return { ...as, lifecycle: current.toUpperCase() as TaskDirective["lifecycle"], action: `Accept or return the ${current.toUpperCase()} handoff.`, command: `atdd-flow task respond ${projectName} ${id} --by ${address} --outcome <accept|return> --phase <plan|red|green|refactor>` };
-    }
+  return {
+    ...base, lifecycle: next.toUpperCase() as TaskDirective["lifecycle"], action: `${current.toUpperCase()} accepted; ${phaseActions[next]}.`,
+    command: phaseCommand(base.project, id, address, next),
+  };
+}
+
+async function assigneeDirective(root: string, projectName: string, id: string, task: Task, address: string): Promise<TaskDirective> {
+  const as = { project: projectName, task: id, role: "assignee" as const };
+  if (task.status === "review") return { ...as, lifecycle: "REVIEW", action: "Await coordinator review; do not continue implementation." };
+  if (task.status === "todo") {
+    const waiting = await ready(root, projectName, task);
+    return waiting.length
+      ? { ...as, lifecycle: "TODO", action: `Wait; dependencies are unfinished: ${waiting.join(", ")}.` }
+      : { ...as, lifecycle: "TODO", action: "Start assigned ready task.", command: `atdd-flow task start ${projectName} ${id} --by ${address}` };
+  }
+  const current = task.phase ?? "plan";
+  const lifecycle = current.toUpperCase() as TaskDirective["lifecycle"];
+  if (task.handoff?.state === "awaiting_coordinator") return { ...as, lifecycle, action: `Await coordinator response to the ${lifecycle} handoff; do not continue to the next phase.` };
+  if (task.handoff?.state === "awaiting_assignee" && task.handoff.submitted_phase === current) return acceptedDirective(as, id, address, current);
+  return { ...as, lifecycle, action: `${phaseActions[current]}.`, command: phaseCommand(projectName, id, address, current) };
+}
+
+function coordinatorDirective(projectName: string, id: string, task: Task, address: string): TaskDirective | undefined {
+  const as = { project: projectName, task: id, role: "coordinator" as const };
+  if (task.blocker) return { ...as, lifecycle: "BLOCKED", action: `Resolve the blocker (${task.blocker}) and then unblock the task.`, command: `atdd-flow task unblock ${projectName} ${id} --by ${address}` };
+  if (task.status === "review") return { ...as, lifecycle: "REVIEW", action: "Review the submitted task; complete it or return it to work.", command: `atdd-flow task open ${projectName} ${id}` };
+  if (task.status === "in_progress" && task.handoff?.state === "awaiting_coordinator") {
+    const current = task.phase ?? "plan";
+    return { ...as, lifecycle: current.toUpperCase() as TaskDirective["lifecycle"], action: `Accept or return the ${current.toUpperCase()} handoff.`, command: `atdd-flow task respond ${projectName} ${id} --by ${address} --outcome <accept|return> --phase <plan|red|green|refactor>` };
   }
   return undefined;
 }
 
+/**
+ * Pure projection of an existing task record; it creates no durable state. Terminal and deferred tasks
+ * yield nothing for any role, a blocked assignee is told nothing, and only the coordinator hears of a blocker.
+ */
+async function directiveFor(root: string, projectName: string, id: string, task: Task, address: string): Promise<TaskDirective | undefined> {
+  if (terminal(task) || task.deferred) return undefined;
+  if (task.assignee === address && !task.blocker) return assigneeDirective(root, projectName, id, task, address);
+  return task.coordinator === address ? coordinatorDirective(projectName, id, task, address) : undefined;
+}
+
 const directiveRank = (directive: TaskDirective, task: Task) =>
-  directive.lifecycle === "DONE" ? 4 : directive.lifecycle === "BLOCKED" ? 3 : task.status === "todo" ? 2 : task.status === "review" ? 1 : 0;
+  directive.lifecycle === "BLOCKED" ? 3 : task.status === "todo" ? 2 : task.status === "review" ? 1 : 0;
 
 /**
  * Derives the one next required action for an address from authoritative task
@@ -727,10 +750,8 @@ export async function nextDirective(root: string, address: string): Promise<Task
     if (directive) candidates.push({ directive, task: entry.task });
   }
   const best = (role: "assignee" | "coordinator") => {
-    const pool = candidates.filter((entry) => entry.directive.role === role)
-      .sort((left, right) => directiveRank(left.directive, left.task) - directiveRank(right.directive, right.task));
-    // Completed housekeeping names the most recent completed task, not the oldest.
-    return pool[0] && directiveRank(pool[0].directive, pool[0].task) === 4 ? pool.at(-1) : pool[0];
+    return candidates.filter((entry) => entry.directive.role === role)
+      .sort((left, right) => directiveRank(left.directive, left.task) - directiveRank(right.directive, right.task))[0];
   };
   return (best("assignee") ?? best("coordinator"))?.directive;
 }