@afokapu/atdd-flow 0.3.33 → 0.3.35

package/README.md

@@ -109,6 +109,8 @@ atdd-flow spawn example-app driver runtime
 
 `spawn` creates missing driver worktrees through Git: this example creates `/Users/you/Github/worktrees/example-app/runtime` on `delivery/runtime`. ATDD Bun owns safe retirement, not creation. A seat can own several tasks.
 
+For the canonical named-coordinator topology, create an unassigned `todo` task first, then use `atdd-flow spawn <project> driver <name> --task <task-id>`. Flow derives the fresh `delivery/<name>` worktree from the task coordinator's exact `integration/<stream>` head (or `main` for `main@project`), records that commit as `governed_base`, assigns the task, and reports the integration return branch. It refuses existing seats, worktrees, or branches and invalid, dirty, stale, generic, nested, or cross-project coordinator lineage rather than reusing history.
+
 ## Deliver work
 
 ```text

package/conventions/atdd-flow.collaboration/atdd-flow.collaboration.convention.yaml

@@ -0,0 +1,44 @@
+schema_version: 1.0.0
+rule_id: atdd-flow.collaboration
+kind: policy
+status: active
+name: Collaborate through durable accountable delegation
+statement: >-
+  Agents use accountable delegation, evidence-based escalation, economical delivery,
+  and bounded two-way resolution while keeping work within its assigned project and task.
+content:
+  canonical_policy: >-
+    Delegation flows operator → main → named coordinator → driver. Each level proactively
+    dispatches safe independent work, verifies durable delivery and visible execution, and
+    escalates material blockers upward with exact evidence, an economical recommendation,
+    viable alternatives and tradeoffs, and safe work that can continue. Choose the smallest
+    non-duplicative compliant implementation; do not skip lifecycle or gates. Use bounded
+    two-way evidence dialogue with the responsible actor to resolve assumptions or
+    disagreement; time-box it and escalate only unresolved decisions. Distinguish persisted,
+    delivered, acknowledged, awaiting actor, and executing. Never infer authorization or
+    restart productive sessions merely to relay policy. Proactive next-task discovery stays
+    within the same project. Keep one bounded active task and worktree per driver; assign
+    adjacent work separately. Cross-project dialogue is only for a real dependency or
+    interface through counterpart authority. Prefer atomic assignment; unassigned work needs
+    a project-main decision proposal with purpose, priority, recommended assignee,
+    alternatives, consequences, dependencies, and safe work meanwhile. Promptly complete,
+    supersede, reject, or time-bound defer work. Coordinating actors reconcile their durable
+    inbox as the first action at every session, turn, and task resumption, and after every
+    bounded action, phase completion, or wait before the next action. An actionable
+    expects_result remains visible until answered, executed, delegated with verified delivery
+    and follow-up, or explicitly deferred, superseded, or closed. Messages only communicate,
+    evidence, consensus, authorization, or status; they never request executable work unless it
+    references an existing assigned task. Tasks define, assign, execute, evidence, and complete
+    work; every code or repository mutation requires that task first. The operator accepts and
+    receipts inbound communication from any seat, but sends substantive direction, results, and
+    wakes only to main@project. Only main@project executes that project repository merge; the
+    operator may authorize, relay, or inspect but never merges.
+  projection: >-
+    Keep this full policy only in this convention. Managed AGENTS.md and CLAUDE.md blocks
+    contain only its canonical pointer and preserve all user-authored content outside the
+    marked block.
+metadata:
+  aliases:
+    - ATDD-FLOW-COLLABORATION
+implementation:
+  type: source-resolved

package/extensions/pi/index.ts

@@ -6,6 +6,7 @@ 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 { runtimeStartupInstruction } from "../../src/collaboration-policy";
 
 type Thread = { id?: unknown; participants?: unknown; subject?: unknown };
 export type Mail = { id?: unknown; from?: unknown; to?: unknown; subject?: unknown; created_at?: unknown };
@@ -63,7 +64,6 @@ const defaultHeartbeatMs = 15_000;
 const defaultStaleAfterMs = 60_000;
 const defaultActivationIntervalMs = 25;
 const defaultActivationTimeoutMs = 60_000;
-const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
 function participants(thread: Thread) {
   return Array.isArray(thread.participants) && thread.participants.every((entry) => typeof entry === "string") ? thread.participants as string[] : [];
@@ -358,7 +358,7 @@ export default function (pi: ExtensionAPI) {
       root, seat, piSession, herdrSession, pane,
       activate: async () => {
         if (!await current.activate()) return;
-        pi.sendMessage({ customType: "atdd-flow-start", content: `SYSTEM: you are ${seat}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Convention: ${lifecycleConventionPath}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`, display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
+        pi.sendMessage({ customType: "atdd-flow-start", content: runtimeStartupInstruction(seat), display: true, details: { seat, root } }, { triggerTurn: true, deliverAs: "followUp" });
         await sendTaskDirective(pi, root, seat);
         if (ctx.hasUI) ctx.ui.notify(`ATDD Flow native mail active for ${seat}`, "info");
       },

package/package.json

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

package/src/collaboration-policy.ts

@@ -0,0 +1,76 @@
+import { readFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+export const collaborationConventionPath = "conventions/atdd-flow.collaboration/atdd-flow.collaboration.convention.yaml";
+const startMarker = "<!-- atdd-flow:collaboration-policy:start -->";
+const endMarker = "<!-- atdd-flow:collaboration-policy:end -->";
+export const collaborationPolicyPointer = `ATDD Flow collaboration policy: node_modules/@afokapu/atdd-flow/${collaborationConventionPath} (source checkout: ${collaborationConventionPath})`;
+
+type Convention = { content?: { canonical_policy?: unknown } };
+
+function conventionFile() {
+  return join(import.meta.dir, "..", collaborationConventionPath);
+}
+
+/** The convention is the sole policy text; projections and runtimes resolve it from here. */
+export function canonicalCollaborationPolicy() {
+  const convention = parse(readFileSync(conventionFile(), "utf8")) as Convention;
+  const policy = convention.content?.canonical_policy;
+  if (typeof policy !== "string" || !policy.trim()) throw new Error("Collaboration convention requires content.canonical_policy.");
+  return policy.trim();
+}
+
+function block() {
+  return `${startMarker}\n${collaborationPolicyPointer}\n${endMarker}\n`;
+}
+
+function escaped(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const existingBlock = new RegExp(`${escaped(startMarker)}\\r?\\n[\\s\\S]*?${escaped(endMarker)}(?:\\r?\\n)?`, "g");
+
+/** Replaces every prior managed block with one canonical pointer while retaining all other bytes. */
+export function projectCollaborationPolicyText(source: string) {
+  const matches = [...source.matchAll(existingBlock)];
+  if (matches.length) {
+    const first = matches[0]!;
+    const before = source.slice(0, first.index);
+    const after = source.slice((first.index ?? 0) + first[0].length).replace(existingBlock, "");
+    return `${before}${block()}${after}`;
+  }
+  if (!source) return block();
+  return `${source}${source.endsWith("\n") ? "\n" : "\n\n"}${block()}`;
+}
+
+function lineCount(text: string) {
+  return text ? text.replace(/\r?\n$/, "").split(/\r?\n/).length : 0;
+}
+
+/** Idempotently projects the canonical pointer while preserving user content and refusing oversized instruction files. */
+export async function projectCollaborationPolicy(root: string) {
+  const projections = await Promise.all(["AGENTS.md", "CLAUDE.md"].map(async (name) => {
+    const file = join(root, name);
+    let source = "";
+    try { source = await readFile(file, "utf8"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    return { name, file, source, next: projectCollaborationPolicyText(source) };
+  }));
+  for (const { name, source, next } of projections) {
+    if (lineCount(source) > 20 || lineCount(next) > 20) {
+      throw new Error(`${name} exceeds the 20-line cap; refusing projection without changing user content.`);
+    }
+  }
+  await Promise.all(projections.map(async ({ file, source, next }) => {
+    if (next !== source) await writeFile(file, next, "utf8");
+  }));
+}
+
+/** The one startup handoff for supported Flow-managed runtimes, resolved from the canonical convention. */
+export function runtimeStartupInstruction(seat: string) {
+  return `SYSTEM: you are ${seat}. Collaboration policy: ${canonicalCollaborationPolicy()} Canonical convention: ${collaborationConventionPath}. Read your durable seat and assigned work with: atdd-flow open ${seat}. Continue assigned in_progress work until it is review-ready or explicitly blocked.`;
+}

package/src/seats.ts

@@ -1,18 +1,19 @@
 import { existsSync, realpathSync } from "node:fs";
-import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { basename, dirname, join, resolve } from "node:path";
 import { discoverAddress, discoverHerdrLocator, notify } from "./adapters";
 import {
   type Checkpoint, type Desk, type ModelCandidate, type ModelPortfolio, type Project, type Role, type Runtime, type Seat,
-  atomicYaml, canonicalAddress, desk, exists, fill, migrateDesk, modelPortfolio, now, paths, project, readYaml,
-  required, run, runOutput, runtimeAddress, seat, words, yaml,
+  atomicYaml, canonicalAddress, desk, exists, fill, has, migrateDesk, modelPortfolio, now, paths, project, readYaml,
+  required, run, runOutput, runtimeAddress, seat, taskId, words, yaml,
 } from "./core";
 import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
-import { seatTasks } from "./tasks";
+import { type Task, seatTasks } from "./tasks";
 import { misplacedSeats, projectHerdrSeat } from "./multiplexer";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
+import { projectCollaborationPolicy } from "./collaboration-policy";
 
 const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
@@ -51,6 +52,7 @@ export async function init(root: string, name: string, args: string[]) {
   const config = { schema: "atdd-workflow/desk/v1" as const, desk: name, application: "herdr", executables: defaultExecutables() };
   await Promise.all([mkdir(paths(root).work, { recursive: true }), mkdir(paths(root).threads, { recursive: true })]);
   await Promise.all([atomicYaml(paths(root).desk, config), atomicYaml(paths(root).models, defaultModels())]);
+  await projectCollaborationPolicy(root);
   if (args.includes("--git") && !await exists(join(root, ".git"))) await run(["git", "init", "--initial-branch=main", root]);
   console.log(`Initialized Desk ${root}`);
 }
@@ -58,6 +60,7 @@ export async function init(root: string, name: string, args: string[]) {
 export async function migrate(root: string) {
   if (await migrateDesk(root)) console.log("Migrated legacy coordination registry to desk.yaml");
   else console.log("Desk registry already exists");
+  await projectCollaborationPolicy(root);
 }
 
 export async function initProject(root: string, name: string) {
@@ -109,9 +112,98 @@ async function ensureWorktree(config: Project, role: Role, worktree: string, bra
   await run(command, true);
 }
 
+async function noBranch(config: Project, branch: string) {
+  const probe = Bun.spawn(["git", "-C", required(config.repository, "project repository"), "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+  if (await probe.exited === 0) throw new Error(`Driver branch ${branch} already exists; refusing to reuse it.`);
+}
+
+async function taskCoordinatorBase(root: string, config: Project, task: Task) {
+  const coordinatorAddress = await canonicalAddress(root, task.coordinator);
+  const suffix = `@${config.project}`;
+  if (!coordinatorAddress.endsWith(suffix)) throw new Error(`Task coordinator ${coordinatorAddress} is outside project ${config.project}.`);
+  const coordinator = await seat(root, coordinatorAddress);
+  const primary = resolve(required(config.repository, "project repository"));
+  let branch: string;
+  if (coordinator.role === "main") {
+    if (coordinator.address !== `main@${config.project}` || coordinator.branch !== "main" || resolve(coordinator.worktree) !== primary) {
+      throw new Error(`Main coordinator ${coordinator.address} has mismatched primary lineage.`);
+    }
+    branch = "main";
+  } else if (coordinator.role === "coordinator") {
+    const match = coordinator.address.match(new RegExp(`^coordinator\\.([a-z0-9_-]+)@${config.project}$`));
+    if (!match || coordinator.branch !== `integration/${match[1]}` || resolve(coordinator.worktree) === primary) {
+      throw new Error(`Coordinator ${coordinator.address} has mismatched, generic, or nested integration lineage.`);
+    }
+    branch = coordinator.branch;
+  } else {
+    throw new Error(`Task coordinator ${coordinator.address} must be main or a named coordinator.`);
+  }
+  if (coordinator.project !== config.project) throw new Error(`Task coordinator ${coordinator.address} is outside project ${config.project}.`);
+  if (await runOutput(["git", "-C", coordinator.worktree, "status", "--porcelain"])) {
+    throw new Error(`Coordinator ${coordinator.address} worktree is dirty.`);
+  }
+  const checkedOut = await runOutput(["git", "-C", coordinator.worktree, "branch", "--show-current"]);
+  if (checkedOut !== branch) throw new Error(`Coordinator ${coordinator.address} is not checked out at ${branch}.`);
+  const head = await runOutput(["git", "-C", coordinator.worktree, "rev-parse", "HEAD"]);
+  const branchHead = await runOutput(["git", "-C", required(config.repository, "project repository"), "rev-parse", branch]);
+  if (head !== branchHead) throw new Error(`Coordinator ${coordinator.address} head is stale relative to ${branch}.`);
+  return { coordinator, branch, commit: head };
+}
+
+/** Creates a fresh driver and assigns its existing todo task from the task coordinator's exact head. */
+async function spawnTaskDriver(root: string, config: Project, role: Role, name: string, args: string[]) {
+  if (role.address !== "driver.{name}@{project}" || role.branch !== "delivery/{name}" || !role.worktree) {
+    throw new Error("Task-aware driver spawn requires the canonical driver role topology.");
+  }
+  if (has(args, "--worktree") || has(args, "--branch")) throw new Error("Task-aware driver spawn derives its worktree and branch; do not provide --worktree or --branch.");
+  const id = taskId(required(words(args, "--task"), "--task"));
+  const task = await readYaml<Task>(paths(root).taskFile(config.project, id));
+  if (task.schema !== "atdd-workflow/task/v1") throw new Error(`Unsupported task schema: ${id}`);
+  if (task.status !== "todo" || task.assignee) throw new Error(`Task ${id} must be an unassigned todo task.`);
+  const entries = { project: config.project, name, worktree_root: config.worktree_root ?? "" };
+  const address = fill(role.address, entries);
+  const branch = fill(role.branch, entries);
+  const worktree = resolve(fill(role.worktree, { ...entries, repository: config.repository ?? "" }));
+  if (await exists(paths(root).seatFile(address))) throw new Error(`Driver seat ${address} already exists; refusing to reuse it.`);
+  if (await exists(worktree)) throw new Error(`Driver worktree ${worktree} already exists; refusing to reuse it.`);
+  await noBranch(config, branch);
+  const base = await taskCoordinatorBase(root, config, task);
+  const portfolio = await modelPortfolio(root);
+  const requestedAgent = words(args, "--agent");
+  if (portfolio && requestedAgent) throw new Error("--agent is a legacy pin and cannot be used when models.yaml owns model allocation.");
+  const legacyAgent = portfolio ? undefined : requestedAgent ?? role.agent;
+  const purpose = words(args, "--purpose") ?? (role.purpose ? fill(role.purpose, entries) : undefined);
+  const record: Seat = {
+    schema: "atdd-workflow/seat/v2", address, role: "driver", project: config.project, worktree, branch,
+    ...(legacyAgent ? { agent: legacyAgent } : {}), ...(purpose ? { purpose } : {}),
+  };
+  task.assignee = address;
+  task.governed_base = { coordinator: base.coordinator.address, branch: base.branch, commit: base.commit };
+  let created = false;
+  try {
+    await mkdir(dirname(worktree), { recursive: true });
+    await run(["git", "-C", required(config.repository, "project repository"), "worktree", "add", "-b", branch, worktree, base.commit], true);
+    created = true;
+    const current = await runOutput(["git", "-C", base.coordinator.worktree, "rev-parse", "HEAD"]);
+    const currentBranch = await runOutput(["git", "-C", required(config.repository, "project repository"), "rev-parse", base.branch]);
+    if (current !== base.commit || currentBranch !== base.commit) throw new Error(`Coordinator ${base.coordinator.address} advanced during driver provisioning.`);
+    await atomicYaml(paths(root).seatFile(address), record);
+    await atomicYaml(paths(root).taskFile(config.project, id), task);
+  } catch (error) {
+    if (created) await run(["git", "-C", required(config.repository, "project repository"), "worktree", "remove", "--force", worktree], true).catch(() => undefined);
+    await rm(paths(root).seat(address), { recursive: true, force: true });
+    throw error;
+  }
+  console.log(`${address}  assigned ${id}  return ${base.branch}`);
+}
+
 export async function spawn(root: string, projectName: string, roleName: string, name: string, args: string[]) {
   const config = await project(root, projectName);
   const role = required(config.roles[roleName], `role ${roleName}`);
+  if (words(args, "--task")) {
+    if (roleName !== "driver") throw new Error("--task is supported only for driver spawn.");
+    return spawnTaskDriver(root, config, role, name, args);
+  }
   const entries = { project: config.project, name, worktree_root: config.worktree_root ?? "" };
   // Retain the historical primary coordinator command for existing Desks while
   // new defaults make main@project the only new primary identity.