@afokapu/atdd-flow 0.3.19 → 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.19",
+  "version": "0.3.21",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -11,6 +11,7 @@ import * as reviews from "./reviews";
 import { status } from "./overview";
 import { multiplexer } from "./multiplexer";
 import * as cleanup from "./ephemeral-resources";
+import * as ownerAlerts from "./owner-escalations";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
 
@@ -32,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>
@@ -45,11 +47,13 @@ Usage:
   atdd-flow task open <project> <task-id>
   atdd-flow cleanup status <project>
   atdd-flow cleanup checklist <project> <task-id>
+  atdd-flow owner-alert scan --by <coordinator-or-main> [--re-notify-after-ms <milliseconds>]
+  atdd-flow owner-alert deliver|acknowledge|execute|resolve <alert-id> --by <address> [--note <text>|--option <id>|--reason <text>]
   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> [--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]
@@ -107,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);
@@ -120,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;
@@ -128,6 +133,20 @@ async function main() {
       if (subcommand === "checklist") return console.log(await cleanup.checklist(root, { project: required(projectName, "project"), task: required(taskId, "task id") }));
       throw new Error("Use `atdd-flow cleanup status <project>` or `atdd-flow cleanup checklist <project> <task-id>`.");
     },
+    "owner-alert": async () => {
+      const [subcommand, alertId, ...tail] = rest;
+      if (subcommand === "scan") {
+        const delay = words(rest.slice(1), "--re-notify-after-ms");
+        if (delay !== undefined && (!Number.isSafeInteger(Number(delay)) || Number(delay) < 0)) throw new Error("--re-notify-after-ms must be a non-negative integer.");
+        return console.log(Bun.YAML.stringify(await ownerAlerts.scanOwnerAlerts(root, { by: required(words(rest.slice(1), "--by"), "--by"), ...(delay === undefined ? {} : { re_notify_after_ms: Number(delay) }) })));
+      }
+      const by = required(words(tail, "--by"), "--by");
+      if (subcommand === "deliver") return ownerAlerts.deliverOwnerAlert(root, required(alertId, "alert id"), { by });
+      if (subcommand === "acknowledge") return ownerAlerts.acknowledgeOwnerAlert(root, required(alertId, "alert id"), { by, note: required(words(tail, "--note"), "--note") });
+      if (subcommand === "execute") return ownerAlerts.chooseOwnerAlertOption(root, required(alertId, "alert id"), { by, option: required(words(tail, "--option"), "--option") as "authorize-safe-fallback" | "provide-cross-project-decision" | "hold-or-resolve" });
+      if (subcommand === "resolve") return ownerAlerts.resolveOwnerAlert(root, required(alertId, "alert id"), { by, reason: required(words(tail, "--reason"), "--reason") });
+      throw new Error("Use `atdd-flow owner-alert scan|deliver|acknowledge|execute|resolve ...`.");
+    },
     thread: async () => {
       const [subcommand, ...tail] = rest;
       if (subcommand === "start") return startThread(root, tail);

package/src/owner-escalations.ts

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { atomicYaml, exists, now as workflowNow, paths, readYaml, required, seat } from "./core";
+import { type Task } from "./tasks";
+import { post, startThread } from "./threads";
+
+type Option = "authorize-safe-fallback" | "provide-cross-project-decision" | "hold-or-resolve";
+type Alert = {
+  schema: "atdd-workflow/owner-alert/v1"; id: string; incident: string; fingerprint: string;
+  state: "blocked" | "waiting" | "resolved" | "superseded";
+  material_class: "cross-project" | "toolkit" | "authorization"; affected_tasks: string[]; evidence: string;
+  fallback: { state: "absent"; evidence: string; safe_automatic_action: "none" };
+  owner_options: { id: Option; text: string }[]; prohibited_actions: string[];
+  delivery: { state: "persisted" | "sent" | "delivered" | "acknowledged" | "executing" | "owner_unavailable"; persisted_at: string; sent_at?: string; delivered_at?: string; acknowledged_at?: string; executing_at?: string; unavailable_reason?: string };
+  notifications: { at: string; thread?: string; message?: string; kind: "initial" | "reminder" }[]; thread?: string;
+  owner_decision?: { option: Option; by: "operator@desk"; at: string }; resolution?: { by: string; reason: string; at: string }; superseded_by?: string;
+};
+type Candidate = Omit<Alert, "id" | "incident" | "fingerprint" | "delivery" | "notifications" | "thread">;
+export type OwnerAlertScan = { created: string[]; sent: string[]; renotified: string[]; unavailable: string[]; ignored: string[] };
+
+const directory = (root: string) => join(root, ".atdd-flow", "owner-alerts");
+export const ownerAlertFile = (root: string, id: string) => join(directory(root), `${id}.yaml`);
+const hash = (value: string) => createHash("sha256").update(value).digest("hex");
+const time = (value?: string) => value ?? workflowNow();
+const options: { id: Option; text: string }[] = [
+  { id: "authorize-safe-fallback", text: "Authorize one named safe fallback; Flow will not infer that authorization." },
+  { id: "provide-cross-project-decision", text: "Provide the named cross-project/toolkit/authorization decision or owner." },
+  { id: "hold-or-resolve", text: "Hold the work explicitly or confirm the blocker is resolved." },
+];
+
+/** Redaction occurs before blocker text enters an alert key, record, or durable mail. */
+export function redactOwnerEvidence(value: string) {
+  return value.replace(/\b(token|password|secret|api[-_ ]?key|authorization)\s*([:=])\s*(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi, "$1$2[REDACTED]")
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]");
+}
+function classification(value: string) {
+  if (/\bcross[- ]project\b/i.test(value)) return "cross-project" as const;
+  if (/\btoolkit\b/i.test(value)) return "toolkit" as const;
+  if (/\bauthorization\b|\bauthori[sz](?:e|ation)\b/i.test(value)) return "authorization" as const;
+}
+async function projects(root: string) {
+  let names: string[]; try { names = await readdir(paths(root).work); } catch { return []; }
+  const found = await Promise.all(names.map(async (name) => ({ name, valid: await exists(paths(root).projectFile(name)) })));
+  return found.filter((entry) => entry.valid).map((entry) => entry.name);
+}
+async function tasks(root: string) {
+  const result: { project: string; id: string; task: Task }[] = [];
+  for (const project of await projects(root)) {
+    let files: string[]; try { files = await readdir(paths(root).tasks(project)); } catch { continue; }
+    for (const file of files.sort()) if (file.endsWith(".yaml") && !file.endsWith(".reviews.yaml")) result.push({ project, id: file.slice(0, -5), task: await readYaml<Task>(join(paths(root).tasks(project), file)) });
+  }
+  return result;
+}
+async function alerts(root: string) {
+  let files: string[]; try { files = await readdir(directory(root)); } catch { return [] as Alert[]; }
+  return Promise.all(files.filter((file) => file.endsWith(".yaml")).sort().map((file) => readYaml<Alert>(join(directory(root), file))));
+}
+async function escalator(root: string, address: string) {
+  const actor = await seat(root, address);
+  if (actor.role !== "coordinator" && actor.role !== "main") throw new Error("Only a coordinator or main seat may scan or resolve owner alerts.");
+  return actor.address;
+}
+async function ownerAvailable(root: string) { try { return (await seat(root, "operator@desk")).role === "operator"; } catch { return false; } }
+async function independent(root: string, entry: { project: string; id: string }, all: Awaited<ReturnType<typeof tasks>>) {
+  for (const other of all) {
+    if (other.project !== entry.project || other.id === entry.id || other.task.status !== "in_progress" || other.task.blocker || !other.task.assignee) continue;
+    try { if ((await readYaml<{ status?: string }>(paths(root).checkpointFile(other.task.assignee))).status === "active") return true; } catch { /* absent checkpoint is not visible execution */ }
+  }
+  return false;
+}
+function candidate(entry: { project: string; id: string; task: Task }): Candidate | undefined {
+  if (entry.task.status === "done" || !entry.task.blocker) return;
+  const material = classification(entry.task.blocker); if (!material) return;
+  return { schema: "atdd-workflow/owner-alert/v1", state: "blocked", material_class: material, affected_tasks: [`${entry.project}/${entry.id}`], evidence: redactOwnerEvidence(entry.task.blocker),
+    fallback: { state: "absent", evidence: "No independent checkpoint-active task is visibly executing in the affected project.", safe_automatic_action: "none" }, owner_options: options,
+    prohibited_actions: ["Do not infer authorization.", "Do not execute an external action.", "Do not expose secrets."] };
+}
+function incident(value: Candidate) { return hash(`${value.material_class}\0${value.affected_tasks.join("\0")}`).slice(0, 16); }
+function fingerprint(value: Candidate) { return hash(JSON.stringify({ state: value.state, evidence: value.evidence, fallback: value.fallback })); }
+async function coordinatorFor(root: string, record: Alert) {
+  return required((await tasks(root)).find((entry) => record.affected_tasks.includes(`${entry.project}/${entry.id}`))?.task.coordinator, "alert coordinator");
+}
+async function send(root: string, record: Alert, kind: "initial" | "reminder", timestamp: string) {
+  const coordinator = await coordinatorFor(root, record);
+  const thread = record.thread ?? await startThread(root, ["--with", `operator@desk,${coordinator}`, "--subject", `Owner alert ${record.id}`]);
+  if (!record.thread) { record.thread = thread; await atomicYaml(ownerAlertFile(root, record.id), record); }
+  const message = await post(root, thread, ["--from", coordinator, "--to", "operator@desk", "--label", "material stall owner alert", "--expects-result", "--body",
+    `OWNER ALERT ${record.id}\nstate: ${record.state}\nclass: ${record.material_class}\naffected: ${record.affected_tasks.join(", ")}\nevidence: ${record.evidence}\nfallback: ${record.fallback.evidence}\nsafe automatic action: ${record.fallback.safe_automatic_action}\noptions: ${record.owner_options.map((option) => `${option.id} (${option.text})`).join("; ")}\nprohibited: ${record.prohibited_actions.join(" ")}`]);
+  record.thread = thread; record.delivery.state = "sent"; record.delivery.sent_at = timestamp; record.notifications.push({ at: timestamp, thread, message, kind });
+}
+
+/** An explicit bounded observation, never a daemon, executor, or authorization proxy. */
+export async function scanOwnerAlerts(root: string, input: { by: string; re_notify_after_ms?: number; now?: string }): Promise<OwnerAlertScan> {
+  await escalator(root, input.by); const timestamp = time(input.now); const result: OwnerAlertScan = { created: [], sent: [], renotified: [], unavailable: [], ignored: [] };
+  const all = await tasks(root); const stored = await alerts(root);
+  for (const entry of all) {
+    const next = candidate(entry);
+    if (!next || await independent(root, entry, all)) { result.ignored.push(`${entry.project}/${entry.id}`); continue; }
+    const key = incident(next); const digest = fingerprint(next); const active = stored.find((record) => record.incident === key && record.state !== "resolved" && record.state !== "superseded");
+    if (active && active.fingerprint !== digest) { active.state = "superseded"; active.superseded_by = `O-${key}-${digest.slice(0, 8)}`; await atomicYaml(ownerAlertFile(root, active.id), active); }
+    const exact = stored.find((record) => record.incident === key && record.fingerprint === digest);
+    if (exact && exact.state !== "superseded") {
+      if (exact.state === "resolved") { result.ignored.push(`${entry.project}/${entry.id}`); continue; }
+      const last = exact.notifications.at(-1)?.at; const delay = input.re_notify_after_ms;
+      if (exact.delivery.state === "sent" && delay !== undefined && delay >= 0 && last && Date.parse(timestamp) - Date.parse(last) >= delay) { await send(root, exact, "reminder", timestamp); await atomicYaml(ownerAlertFile(root, exact.id), exact); result.renotified.push(exact.id); }
+      else result.ignored.push(`${entry.project}/${entry.id}`);
+      continue;
+    }
+    const id = `O-${key}-${digest.slice(0, 8)}`; const record: Alert = { ...next, id, incident: key, fingerprint: digest, delivery: { state: "persisted", persisted_at: timestamp }, notifications: [] };
+    await atomicYaml(ownerAlertFile(root, id), record); result.created.push(id);
+    if (!await ownerAvailable(root)) { record.delivery.state = "owner_unavailable"; record.delivery.unavailable_reason = "operator@desk is absent or is not an operator seat."; await atomicYaml(ownerAlertFile(root, id), record); result.unavailable.push(id); continue; }
+    try { await send(root, record, "initial", timestamp); await atomicYaml(ownerAlertFile(root, id), record); result.sent.push(id); }
+    catch (error) { record.delivery.state = "persisted"; record.delivery.unavailable_reason = `Owner delivery path failed closed: ${(error as Error).message}`; await atomicYaml(ownerAlertFile(root, id), record); result.unavailable.push(id); }
+  }
+  return result;
+}
+async function read(root: string, id: string) { return readYaml<Alert>(ownerAlertFile(root, id)); }
+async function owner(root: string, address: string) { if (address !== "operator@desk" || !await ownerAvailable(root)) throw new Error("Only the available operator@desk seat may update owner delivery state."); }
+export async function deliverOwnerAlert(root: string, id: string, input: { by: string; now?: string }) { await owner(root, input.by); const record = await read(root, id); if (record.delivery.state !== "sent") throw new Error(`Owner alert ${id} is not awaiting delivery.`); record.delivery.state = "delivered"; record.delivery.delivered_at = time(input.now); await atomicYaml(ownerAlertFile(root, id), record); }
+export async function acknowledgeOwnerAlert(root: string, id: string, input: { by: string; note: string; now?: string }) { await owner(root, input.by); required(input.note, "owner acknowledgement note"); const record = await read(root, id); if (record.delivery.state !== "delivered") throw new Error(`Owner alert ${id} must be delivered before acknowledgement.`); record.delivery.state = "acknowledged"; record.delivery.acknowledged_at = time(input.now); await atomicYaml(ownerAlertFile(root, id), record); }
+export async function chooseOwnerAlertOption(root: string, id: string, input: { by: string; option: Option; now?: string }) { await owner(root, input.by); if (!options.some((entry) => entry.id === input.option)) throw new Error("Unknown owner alert option."); const record = await read(root, id); if (record.delivery.state !== "acknowledged") throw new Error(`Owner alert ${id} must be acknowledged before selecting an option.`); record.delivery.state = "executing"; record.delivery.executing_at = time(input.now); record.owner_decision = { option: input.option, by: "operator@desk", at: record.delivery.executing_at }; await atomicYaml(ownerAlertFile(root, id), record); }
+export async function resolveOwnerAlert(root: string, id: string, input: { by: string; reason: string; now?: string }) { const by = await escalator(root, input.by); const record = await read(root, id); if (record.state === "resolved" || record.state === "superseded") throw new Error(`Owner alert ${id} is already terminal.`); record.state = "resolved"; record.resolution = { by, reason: required(input.reason, "resolution reason"), at: time(input.now) }; await atomicYaml(ownerAlertFile(root, id), record); }

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"),
@@ -236,6 +264,7 @@ async function post(root: string, threadId: string, args: string[], overrides: P
   await Promise.all(prepared.filter((entry): entry is NonNullable<typeof entry> => Boolean(entry)).map((entry) => publishNativeMail(root, entry.address, entry.segment, message.id)));
   await Promise.all(recipients.filter((address) => address !== from).map((recipient) => inject(root, recipient, message, threadId, prepared.some((entry) => entry?.address === recipient))));
   console.log(message.id);
+  return message.id;
 }
 
 export async function startThread(root: string, args: string[]) {
@@ -249,6 +278,7 @@ export async function startThread(root: string, args: string[]) {
   };
   await atomicYaml(paths(root).threadFile(record.id), record);
   console.log(record.id);
+  return record.id;
 }
 
 export async function addParticipant(root: string, threadId: string, address: string) {