@afokapu/atdd-flow 0.3.17 → 0.3.18

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

@@ -69,6 +69,19 @@ content:
     messages to their coordinator; they do not directly message the operator or main seat. A receipt
     or result addresses the seat that made the request, not every historical participant in the thread.
 
+    For new project topology, `main@project` is the sole primary-checkout and `main`-branch
+    coordinator. A named `coordinator.stream@project` works only from its own linked
+    `integration/stream` branch and worktree; it integrates bounded driver delivery rather than acting
+    as a hidden feature driver. A driver coordinated by that seat derives its governed base from that
+    exact integration head, while a main-coordinated driver derives from main. Reject nested
+    coordinator lineage, mismatched base/worktree placement, and ambiguous placement rather than
+    guessing. Legacy seat, task, and thread identities remain readable without rename or mutation.
+
+    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
+    scheduler is introduced by this workflow.
+
     A driver starts only its assigned ready task. Treat the task's done_when criteria as the required
     delivery scope. Prefer existing repository patterns, components, dependencies, contracts, and
     abstractions. When multiple implementations are correct, choose the smallest effective change that

package/extensions/pi/index.ts

@@ -62,6 +62,7 @@ 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[] : [];
@@ -342,7 +343,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}. 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: `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" });
         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.17",
+  "version": "0.3.18",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {

package/src/multiplexer.ts

@@ -89,6 +89,28 @@ async function projectSeats(root: string, projectName: string) {
   return seats.filter((entry): entry is Seat => Boolean(entry && entry.schema === "atdd-workflow/seat/v2" && !entry.retired));
 }
 
+function assertNewTopologyPlacement(config: Project, entry: Seat, primary: string) {
+  const coordinator = config.roles.coordinator;
+  const namedCoordinatorDefaults = coordinator?.address === "coordinator.{name}@{project}" && coordinator.branch === "integration/{name}";
+  const mainDefaults = config.roles.main?.address === "main@{project}" && config.roles.main.branch === "main";
+  if (entry.role === "main" && mainDefaults && (entry.address !== `main@${config.project}` || entry.branch !== "main" || resolve(entry.worktree) !== primary)) {
+    throw new Error(`Main seat ${entry.address} must use the primary main worktree and branch.`);
+  }
+  if (entry.role !== "coordinator" || !namedCoordinatorDefaults) return;
+  // coordinator@project remains the preserved historical primary identity;
+  // every newly named coordinator must be a single linked integration stream.
+  if (entry.address === `coordinator@${config.project}`) {
+    if (entry.branch !== "main" || resolve(entry.worktree) !== primary) throw new Error(`Legacy primary coordinator ${entry.address} has mismatched placement.`);
+    return;
+  }
+  const suffix = `@${config.project}`;
+  const local = entry.address.endsWith(suffix) ? entry.address.slice(0, -suffix.length) : "";
+  const match = local.match(/^coordinator\.([a-z0-9_-]+)$/);
+  if (!match || entry.branch !== `integration/${match[1]}` || resolve(entry.worktree) === primary) {
+    throw new Error(`Named coordinator ${entry.address} must use one linked integration/<stream> worktree and branch.`);
+  }
+}
+
 async function targets(root: string): Promise<Target[]> {
   let projects: string[];
   try { projects = await readdir(paths(root).work); }
@@ -102,6 +124,7 @@ async function targets(root: string): Promise<Target[]> {
     const primary = resolve(config.repository);
     result.push({ project: name, worktree: primary, workspaceLabel: name });
     for (const entry of await projectSeats(root, name)) {
+      assertNewTopologyPlacement(config, entry, primary);
       if ((entry.role === "main" || entry.role === "coordinator") && resolve(entry.worktree) === primary) {
         result.push({ project: name, worktree: primary, workspaceLabel: name, seat: entry });
         continue;
@@ -148,7 +171,7 @@ async function ensureWorkspace(session: string, target: Target, workspaces: Work
   if (!current) {
     const args = target.workspaceLabel === target.project
       ? ["workspace", "create", "--cwd", target.worktree, "--label", target.workspaceLabel, "--no-focus"]
-      : ["worktree", "open", "--workspace", primary?.id ?? "", "--cwd", primary?.worktree ?? "", "--path", target.worktree, "--label", target.workspaceLabel, "--no-focus"];
+      : ["worktree", "open", "--workspace", primary?.id ?? "", "--path", target.worktree, "--label", target.workspaceLabel, "--no-focus"];
     if (args.includes("")) throw new Error(`Project primary workspace is required to open linked worktree ${target.worktree}.`);
     const created = json(await command(["herdr", "--session", session, ...args]));
     current = { workspace_id: workspaceId(created), label: target.workspaceLabel, worktree: { checkout_path: target.worktree } };

package/src/seats.ts

@@ -10,10 +10,17 @@ import {
 import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
 import { seatTasks } from "./tasks";
 import { projectHerdrSeat } from "./multiplexer";
+import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
+
+const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
 const defaultRoles = (dynamicModels = true): Record<string, Role> => ({
+  main: {
+    address: "main@{project}", branch: "main", worktree: "{repository}",
+    ...(dynamicModels ? {} : { agent: "pi" }),
+  },
   coordinator: {
-    address: "coordinator@{project}", branch: "main", worktree: "{repository}",
+    address: "coordinator.{name}@{project}", branch: "integration/{name}", base: "main", worktree: "{worktree_root}/{name}",
     ...(dynamicModels ? {} : { agent: "pi" }),
   },
   driver: {
@@ -75,10 +82,27 @@ export async function spawn(root: string, projectName: string, roleName: string,
   const config = await project(root, projectName);
   const role = required(config.roles[roleName], `role ${roleName}`);
   const entries = { project: config.project, name, worktree_root: config.worktree_root ?? "" };
-  const address = fill(role.address, entries);
-  const configuredPath = role.worktree ? fill(role.worktree, { ...entries, repository: config.repository ?? "" }) : undefined;
+  // Retain the historical primary coordinator command for existing Desks while
+  // new defaults make main@project the only new primary identity.
+  const legacyPrimaryCoordinator = roleName === "coordinator" && name === "main"
+    && role.address === "coordinator.{name}@{project}" && role.branch === "integration/{name}";
+  const address = legacyPrimaryCoordinator ? `coordinator@${config.project}` : fill(role.address, entries);
+  const configuredPath = legacyPrimaryCoordinator ? config.repository : role.worktree ? fill(role.worktree, { ...entries, repository: config.repository ?? "" }) : undefined;
   const worktree = resolve(required(words(args, "--worktree") ?? configuredPath, "--worktree or role worktree template"));
-  const branch = words(args, "--branch") ?? fill(role.branch, { project: config.project, name });
+  const branch = words(args, "--branch") ?? (legacyPrimaryCoordinator ? "main" : fill(role.branch, { project: config.project, name }));
+  const newMainDefaults = roleName === "main" && role.address === "main@{project}" && role.branch === "main";
+  const newNamedCoordinatorDefaults = roleName === "coordinator" && !legacyPrimaryCoordinator
+    && role.address === "coordinator.{name}@{project}" && role.branch === "integration/{name}";
+  if (newMainDefaults && (branch !== "main" || (config.repository && worktree !== resolve(config.repository)))) {
+    throw new Error(`Main seat main@${config.project} must use the declared primary main worktree and branch.`);
+  }
+  if (newNamedCoordinatorDefaults) {
+    if (!/^[a-z0-9_-]+$/.test(name)) throw new Error("Named coordinator must use one single stream name.");
+    const expectedWorktree = resolve(fill(required(role.worktree, "named coordinator worktree template"), { ...entries, repository: config.repository ?? "" }));
+    if (branch !== `integration/${name}` || worktree !== expectedWorktree) {
+      throw new Error(`Named coordinator ${address} must use its declared integration/${name} branch and linked worktree.`);
+    }
+  }
   await ensureWorktree(config, role, worktree, branch);
   const purpose = words(args, "--purpose") ?? (role.purpose ? fill(role.purpose, entries) : undefined);
   const portfolio = await modelPortfolio(root);
@@ -360,6 +384,17 @@ export async function openSeat(root: string, address: string) {
   // legacy scalar form while the durable record now carries its session too.
   const herdr = record.runtime?.addresses.herdr;
   if (herdr && typeof herdr !== "string") console.log(`herdr: ${herdr.pane} (session: ${herdr.session})`);
+  if (typeof herdr === "string") console.log(`herdr: ${herdr} (unscoped; unverified)`);
+  if (record.runtime?.application === "herdr") {
+    const advisory = await readRuntimeState(root, resolved);
+    const missing = [
+      typeof herdr === "string" || !herdr ? "Herdr session" : undefined,
+      !record.runtime.pi_session || !record.runtime.pi_session_path ? "Pi session/path" : undefined,
+      !record.runtime.launch_receipt || !await exists(record.runtime.launch_receipt) ? "launch receipt" : undefined,
+      !advisory || isRuntimeStateStale(advisory, 60_000) ? "advisory heartbeat" : undefined,
+    ].filter((entry): entry is string => Boolean(entry));
+    console.log(`runtime verification: ${missing.length ? `unverified (${missing.join(", ")})` : "bounded metadata and fresh advisory heartbeat"}`);
+  }
   const checkpointFile = paths(root).checkpointFile(resolved);
   if (await exists(checkpointFile)) console.log(yaml.print(await readYaml<Checkpoint>(checkpointFile)));
   const threadIds = await readdir(paths(root).threads);
@@ -369,4 +404,5 @@ export async function openSeat(root: string, address: string) {
     const entry = await readYaml<{ participants: string[]; state: string; subject: string }>(file);
     if (entry.participants.includes(resolved)) console.log(`${threadId}  ${entry.state}  ${entry.subject}`);
   }
+  console.log(`Convention: ${lifecycleConventionPath}`);
 }

package/src/tasks.ts

@@ -1,4 +1,5 @@
 import { readdir } from "node:fs/promises";
+import { resolve } from "node:path";
 import {
   type Checkpoint, atomicYaml, canonicalAddress, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
 } from "./core";
@@ -10,6 +11,7 @@ export type HandoffState = "executing" | "awaiting_coordinator" | "awaiting_assi
 /** A mutable projection of an immutable evidence message/reference, not a second task lifecycle. */
 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 };
 export type Task = {
   schema: "atdd-workflow/task/v1";
   title: string;
@@ -24,6 +26,8 @@ export type Task = {
   phase?: TaskPhase;
   /** Absent on legacy tasks; evidence remains an opaque immutable message/reference. */
   handoff?: TaskHandoff;
+  /** Exact named-coordinator or main head from which an assigned driver is governed. */
+  governed_base?: GovernedBase;
   done_when: DoneWhen[];
 };
 
@@ -69,6 +73,42 @@ async function writeTask(root: string, projectName: string, id: string, task: Ta
   await atomicYaml(paths(root).taskFile(projectName, id), task);
 }
 
+/** Records the exact parent head for new bounded topology without rewriting legacy tasks. */
+async function governedBase(root: string, projectName: string, coordinatorAddress: string, assignee?: string): Promise<GovernedBase | undefined> {
+  if (!assignee) return undefined;
+  const config = await project(root, projectName);
+  if (!config.repository) return undefined;
+  const coordinator = await seat(root, coordinatorAddress);
+  const driver = await seat(root, assignee);
+  if (driver.role !== "driver") throw new Error(`${assignee} is not a driver seat.`);
+  const primary = resolve(config.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 configured = config.roles.coordinator;
+    // Existing coordinator role templates and coordinator@project records
+    // predate bounded integration lineage and remain readable unchanged.
+    if (configured?.address !== "coordinator.{name}@{project}" || configured.branch !== "integration/{name}" || coordinator.address === `coordinator@${config.project}`) return undefined;
+    const suffix = `@${config.project}`;
+    const local = coordinator.address.endsWith(suffix) ? coordinator.address.slice(0, -suffix.length) : "";
+    const match = local.match(/^coordinator\.([a-z0-9_-]+)$/);
+    if (!match || coordinator.branch !== `integration/${match[1]}` || resolve(coordinator.worktree) === primary) {
+      throw new Error(`Coordinator ${coordinator.address} has mismatched or nested integration lineage.`);
+    }
+    branch = coordinator.branch;
+  } else {
+    throw new Error(`Task coordinator ${coordinator.address} must be main or a named coordinator.`);
+  }
+  const commit = await runOutput(["git", "-C", coordinator.worktree, "rev-parse", branch]);
+  const common = await runOutput(["git", "-C", driver.worktree, "merge-base", commit, driver.branch]);
+  if (common !== commit) throw new Error(`Driver ${driver.address} is not based on the exact coordinator head ${commit}.`);
+  return { coordinator: coordinator.address, branch, commit };
+}
+
 async function retireAssignee(root: string, projectName: string, id: string, task: Task) {
   const assignee = required(task.assignee, `an assignee for task ${id}`);
   const unfinished = (await allTasks(root, projectName))
@@ -107,6 +147,7 @@ export async function add(root: string, projectName: string, id: string, args: s
   const assignee = assigneeValue ? await canonicalAddress(root, assigneeValue) : undefined;
   await seat(root, coordinator);
   if (assignee) await seat(root, assignee);
+  const base = await governedBase(root, projectName, coordinator, assignee);
   const doneWhen = values(args, "--done-when").map((text) => ({ text }));
   if (!doneWhen.length) throw new Error("A task needs at least one --done-when criterion.");
   const dependsOn = words(args, "--depends-on")?.split(",").filter(Boolean).map(taskId);
@@ -116,6 +157,7 @@ export async function add(root: string, projectName: string, id: string, args: s
     status: "todo",
     coordinator,
     ...(assignee ? { assignee } : {}),
+    ...(base ? { governed_base: base } : {}),
     ...(words(args, "--body") ? { body: words(args, "--body") } : {}),
     ...(words(args, "--source") ? { source: words(args, "--source") } : {}),
     ...(dependsOn?.length ? { depends_on: dependsOn } : {}),
@@ -133,7 +175,9 @@ export async function assign(root: string, projectName: string, id: string, args
   if (task.assignee) throw new Error(`Task ${id} is already assigned to ${task.assignee}.`);
   const assignee = await canonicalAddress(root, required(words(args, "--assignee"), "--assignee"));
   await seat(root, assignee);
+  const base = await governedBase(root, projectName, task.coordinator, assignee);
   task.assignee = assignee;
+  if (base) task.governed_base = base;
   await writeTask(root, projectName, id, task);
   console.log(`${id}  assigned  ${assignee}`);
 }