@afokapu/atdd-flow 0.3.20 → 0.3.21

package/README.md

@@ -120,6 +120,8 @@ 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. 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.
 
+For topology normalization, transfer an active task through the narrow durable command, never by editing its YAML: `atdd-flow task transfer <project> <task-id> --to <main-or-named-coordinator> --reason <text> --by <current-coordinator>`; `main@project` must additionally pass `--authorization <operator-message-id>`. That message must be an immutable `task-transfer-authorization/v1` exact tuple for the project, task, current/target coordinator, reason, and target branch/head; only `operator@desk` creates it through `atdd-flow post --task-transfer-authorization <json>`. The command appends immutable source/target/reason/exact-head/effective-time provenance, keeps earlier phase/review/message evidence intact, derives the new governed base from the accepted target head, and never moves a seat, branch, runtime, or worktree. Same-target, duplicate, nested, mismatched, unauthorized, and manually rewritten transitions fail closed.
+
 ## Communicate and hand over
 
 Threads are the durable inbox/outbox. Workflow persists a message before a best-effort host notification, so a closed pane, rate limit, or missed prompt cannot lose it.

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

@@ -77,6 +77,17 @@ content:
     coordinator lineage, mismatched base/worktree placement, and ambiguous placement rather than
     guessing. Legacy seat, task, and thread identities remain readable without rename or mutation.
 
+    Transfer active task accountability only through `atdd-flow task transfer`, never by rewriting
+    task YAML. The transition retains append-only from/to/reason/exact-head/effective-time provenance
+    and leaves prior task, phase, review, and message evidence attributable. The current coordinator
+    may transfer, while main requires one applicable immutable `operator@desk`
+    `task-transfer-authorization/v1` message. Its project, task, from, to, reason, and exact target
+    branch/head must match the requested transfer before mutation; only `operator@desk` may create
+    that typed authorization. Accept only main or a valid named integration coordinator; atomically
+    derive the new governed base from that accepted target head. Reject same-target, duplicate, nested, mismatched,
+    unauthorized, or manually rewritten transfers. A transfer never moves or changes any seat, branch,
+    runtime binding, worktree, dirty state, or evidence artifact.
+
     Drivers hand work back to their named coordinator for integration and validation. The named
     coordinator hands a reviewed integration candidate to main; only main completes normal
     integration-to-main gates and publication. No automatic merge executor, branch graph, daemon, or

package/package.json

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

package/src/cli.ts

@@ -33,6 +33,7 @@ Usage:
   atdd-flow checkpoint <address> --summary <text> --next <text> [--status active|standby|blocked|complete|unverified]
   atdd-flow task add <project> <task-id> --title <text> --coordinator <address> [--assignee <address>] [--body <text>] [--source <reference>] [--depends-on <task-id,...>] --done-when <text> [--done-when <text> ...]
   atdd-flow task assign <project> <task-id> --assignee <address> --by <coordinator-address>
+  atdd-flow task transfer <project> <task-id> --to <main-or-named-coordinator> --reason <text> --by <actor> [--authorization <operator-message-id>]
   atdd-flow task amend <project> <task-id> [--title <text>] [--body <text>] [--source <reference>] [--depends-on <task-id,...>]
   atdd-flow task import <project> <task-id> --proof <reference> [--proof <reference> ...] [--done-when <text> ...] [--source <reference>]
   atdd-flow task start|review|return <project> <task-id> --by <address>
@@ -52,7 +53,7 @@ Usage:
   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> [--label <non-sensitive-text>] [--expects-result]
+  atdd-flow post <thread-id> --from <address> --to <all|address,...> --body <text> [--label <non-sensitive-text>] [--expects-result] [--task-transfer-authorization <json>]
   atdd-flow receipt <thread-id> <message-id> --from <address> [--body <text>] [--label <non-sensitive-text>]
   atdd-flow result <thread-id> <message-id> --from <address> --body <text> [--label <non-sensitive-text>]
   atdd-flow status [project <project>|task <project> <task-id>|seat <address>|thread <thread-id>] [--all]
@@ -110,6 +111,7 @@ async function main() {
       const [subcommand, projectName, taskId, ...tail] = rest;
       if (subcommand === "add") return tasks.add(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "assign") return tasks.assign(root, required(projectName, "project"), required(taskId, "task id"), tail);
+      if (subcommand === "transfer") return tasks.transfer(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "amend") return tasks.amend(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "import") return tasks.importCompleted(root, required(projectName, "project"), required(taskId, "task id"), tail);
       if (subcommand === "start") return tasks.start(root, required(projectName, "project"), required(taskId, "task id"), tail);
@@ -123,7 +125,7 @@ async function main() {
       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|handoff|respond|review|return|done|block|unblock|list|open`.");
+      throw new Error("Use `atdd-flow task add|assign|transfer|amend|import|start|prove|handoff|respond|review|return|done|block|unblock|list|open`.");
     },
     cleanup: async () => {
       const [subcommand, projectName, taskId] = rest;

package/src/tasks.ts

@@ -12,6 +12,16 @@ export type HandoffState = "executing" | "awaiting_coordinator" | "awaiting_assi
 export type TaskHandoff = { state: HandoffState; evidence: string; updated_at: string };
 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. */
+export type CoordinatorTransfer = {
+  from: string;
+  to: string;
+  reason: string;
+  /** Required when main executes the transfer; references an operator@desk message. */
+  authorization?: string;
+  exact_head: { branch: string; commit: string };
+  effective_at: string;
+};
 export type Task = {
   schema: "atdd-workflow/task/v1";
   title: string;
@@ -28,6 +38,8 @@ export type Task = {
   handoff?: TaskHandoff;
   /** Exact named-coordinator or main head from which an assigned driver is governed. */
   governed_base?: GovernedBase;
+  /** Absent on legacy tasks; later entries never rewrite earlier coordinator evidence. */
+  coordinator_transfers?: CoordinatorTransfer[];
   done_when: DoneWhen[];
 };
 
@@ -40,9 +52,29 @@ const transitions: Record<TaskStatus, TaskStatus[]> = {
   done: [],
 };
 
+function assertCoordinatorIntegrity(task: Task, id: string) {
+  const transfers = task.coordinator_transfers;
+  if (transfers && !Array.isArray(transfers)) throw new Error(`Task ${id} has invalid immutable transfer provenance.`);
+  const latest = transfers?.at(-1);
+  if (latest) {
+    if (!latest.from || !latest.to || !latest.reason || !latest.effective_at || !latest.exact_head?.branch || !latest.exact_head.commit) {
+      throw new Error(`Task ${id} has invalid immutable transfer provenance.`);
+    }
+    if (task.coordinator !== latest.to || !task.governed_base
+      || task.governed_base.coordinator !== latest.to
+      || task.governed_base.branch !== latest.exact_head.branch
+      || task.governed_base.commit !== latest.exact_head.commit) {
+      throw new Error(`Task ${id} coordinator is not backed by immutable transfer provenance.`);
+    }
+  } else if (task.governed_base && task.governed_base.coordinator !== task.coordinator) {
+    throw new Error(`Task ${id} coordinator is not backed by immutable transfer provenance.`);
+  }
+}
+
 async function readTask(root: string, projectName: string, id: string) {
   const record = await readYaml<Task>(paths(root).taskFile(projectName, id));
   if (record.schema !== "atdd-workflow/task/v1") throw new Error(`Unsupported task schema: ${id}`);
+  assertCoordinatorIntegrity(record, id);
   return record;
 }
 
@@ -182,6 +214,92 @@ export async function assign(root: string, projectName: string, id: string, args
   console.log(`${id}  assigned  ${assignee}`);
 }
 
+type TransferAuthorization = {
+  schema: "atdd-workflow/task-transfer-authorization/v1";
+  project: string;
+  task: string;
+  from: string;
+  to: string;
+  reason: string;
+  exact_head: { branch: string; commit: string };
+};
+
+async function operatorAuthorization(root: string, reference: string, main: string, expected: TransferAuthorization) {
+  type AuthorizationMessage = { schema?: string; id?: string; from?: string; to?: "all" | string[]; authorization?: TransferAuthorization };
+  type AuthorizationThread = { schema?: string; participants?: string[] };
+  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) => {
+      try {
+        const [thread, message] = await Promise.all([
+          readYaml<AuthorizationThread>(paths(root).threadFile(entry.name)),
+          readYaml<AuthorizationMessage>(paths(root).message(entry.name, reference)),
+        ]);
+        return { thread, message };
+      } catch { return undefined; }
+    }))).filter((entry): entry is NonNullable<typeof entry> =>
+      entry?.thread.schema === "atdd-workflow/thread/v1" && entry.thread.participants?.includes(main) === true
+      && entry.message.schema === "atdd-workflow/message/v1" && entry.message.id === reference);
+  if (matches.length !== 1 || matches[0]?.message.from !== "operator@desk") {
+    throw new Error(`Authorization ${reference} is not an owner-authorized topology plan.`);
+  }
+  if (matches[0].message.to !== "all" && !matches[0].message.to?.includes(main)) {
+    throw new Error(`Authorization ${reference} is not applicable to ${main}.`);
+  }
+  const authorization = matches[0].message.authorization;
+  if (!authorization || authorization.schema !== expected.schema
+    || authorization.project !== expected.project || authorization.task !== expected.task
+    || authorization.from !== expected.from || authorization.to !== expected.to
+    || authorization.reason !== expected.reason
+    || authorization.exact_head?.branch !== expected.exact_head.branch
+    || authorization.exact_head.commit !== expected.exact_head.commit) {
+    throw new Error(`Authorization ${reference} is not an exact transfer authorization.`);
+  }
+}
+
+/**
+ * Changes only the current task accountability projection. The record is
+ * append-only and validates the target's existing topology; it never creates,
+ * moves, cleans, or binds a seat/worktree.
+ */
+export async function transfer(root: string, projectName: string, id: string, args: string[]) {
+  const task = await readTask(root, projectName, taskId(id));
+  const config = await project(root, projectName);
+  const actor = await canonicalAddress(root, required(words(args, "--by"), "--by"));
+  const target = await canonicalAddress(root, required(words(args, "--to"), "--to"));
+  const main = `main@${config.project}`;
+  if (target === task.coordinator) throw new Error(`Task ${id} is already accountable to ${target}.`);
+  if (actor !== main && actor !== task.coordinator) throw new Error(`Only ${main} or the current coordinator may transfer task ${id}.`);
+
+  // governedBase confirms main/named-coordinator identity, exact branch head,
+  // and the driver's descendant relationship before accountability changes.
+  const base = await governedBase(root, projectName, target, task.assignee);
+  if (!base) throw new Error(`Task ${id} needs an assigned driver and governed repository before transfer.`);
+  const authorization = actor === main ? required(words(args, "--authorization"), "an owner-authorized topology plan") : undefined;
+  if (authorization) await operatorAuthorization(root, authorization, main, {
+    schema: "atdd-workflow/task-transfer-authorization/v1",
+    project: config.project,
+    task: id,
+    from: task.coordinator,
+    to: target,
+    reason: required(words(args, "--reason"), "--reason"),
+    exact_head: { branch: base.branch, commit: base.commit },
+  });
+  const transfer: CoordinatorTransfer = {
+    from: task.coordinator,
+    to: target,
+    reason: required(words(args, "--reason"), "--reason"),
+    ...(authorization ? { authorization } : {}),
+    exact_head: { branch: base.branch, commit: base.commit },
+    effective_at: now(),
+  };
+  task.coordinator = target;
+  task.governed_base = base;
+  task.coordinator_transfers = [...(task.coordinator_transfers ?? []), transfer];
+  await writeTask(root, projectName, taskId(id), task);
+  console.log(`${id}  coordinator transferred  ${transfer.from} -> ${transfer.to}`);
+}
+
 export async function amend(root: string, projectName: string, id: string, args: string[]) {
   const task = await readTask(root, projectName, taskId(id));
   const title = words(args, "--title");

package/src/threads.ts

@@ -8,6 +8,15 @@ import {
 
 export type Thread = { schema: string; id: string; subject: string; participants: string[]; state: "open" | "closed"; summary?: string; task?: string };
 export type Kind = "message" | "receipt" | "result";
+export type TransferAuthorization = {
+  schema: "atdd-workflow/task-transfer-authorization/v1";
+  project: string;
+  task: string;
+  from: string;
+  to: string;
+  reason: string;
+  exact_head: { branch: string; commit: string };
+};
 export type Message = {
   schema: string;
   id: string;
@@ -18,6 +27,8 @@ export type Message = {
   expects_result?: boolean;
   created_at: string;
   body: string;
+  /** Immutable owner authorization for one exact coordinator-transfer tuple. */
+  authorization?: TransferAuthorization;
 };
 
 async function thread(root: string, threadId: string) {
@@ -212,6 +223,21 @@ async function inject(root: string, address: string, message: Message, threadId:
   catch (error) { console.warn(`Notification for ${address} was not delivered: ${(error as Error).message}`); }
 }
 
+function transferAuthorization(args: string[], from: string) {
+  const encoded = words(args, "--task-transfer-authorization");
+  if (!encoded) return undefined;
+  if (from !== "operator@desk") throw new Error("Only operator@desk may create a task transfer authorization.");
+  let authorization: unknown;
+  try { authorization = JSON.parse(encoded); }
+  catch { throw new Error("--task-transfer-authorization must be valid JSON."); }
+  const value = authorization as Partial<TransferAuthorization>;
+  if (!value || value.schema !== "atdd-workflow/task-transfer-authorization/v1"
+    || ![value.project, value.task, value.from, value.to, value.reason, value.exact_head?.branch, value.exact_head?.commit].every((entry) => typeof entry === "string" && entry.length)) {
+    throw new Error("--task-transfer-authorization must contain one exact task-transfer-authorization/v1 tuple.");
+  }
+  return value as TransferAuthorization;
+}
+
 async function post(root: string, threadId: string, args: string[], overrides: Partial<Message> = {}) {
   const record = await thread(root, threadId);
   const from = await canonicalAddress(root, required(overrides.from ?? words(args, "--from"), "--from"));
@@ -221,11 +247,13 @@ async function post(root: string, threadId: string, args: string[], overrides: P
   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 kind = overrides.kind ?? "message";
+  const authorization = overrides.authorization ?? transferAuthorization(args, from);
   // Labels are an explicit, non-sensitive operator hint; message bodies never enter durable IDs.
   const label = words(args, "--label") ?? kind;
   const message: Message = {
     schema: "atdd-workflow/message/v1", id: id("M", label), from, to: toValue === "all" ? "all" : recipients,
     kind,
+    ...(authorization ? { authorization } : {}),
     ...(overrides.in_reply_to ? { in_reply_to: overrides.in_reply_to } : {}),
     ...(overrides.expects_result || has(args, "--expects-result") ? { expects_result: true } : {}),
     created_at: now(), body: required(overrides.body ?? words(args, "--body"), "--body"),