@afokapu/atdd-flow 0.3.45 → 0.3.47

package/package.json

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

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { basename, resolve } from "node:path";
-import { init, initProject, configureProject, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
+import { init, initProject, configureProject, migrateNamedCoordinatorTopology, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
 import { createExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { addParticipant, openThread, post, readMessage, receipt, result, startThread } from "./threads";
 import * as tasks from "./tasks";
@@ -25,6 +25,7 @@ Usage:
   atdd-flow desk migrate
   atdd-flow project init <project>
   atdd-flow project configure <project> [--repository <primary-checkout>] [--worktree-root <directory>]
+  atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>
   atdd-flow spawn <project> <role> <name> [--worktree <path>] [--branch <branch>] [--agent <legacy-executable>]
   atdd-flow bind <address> [--application <application>] --address <native-address> [--session <name>] [--agent <executable>] [--worktree <path>] [--wake host|native]
   atdd-flow attach <address> [--application <application>] [--wake host|native]
@@ -95,7 +96,8 @@ async function main() {
     project: async () => {
       if (rest[0] === "init") return initProject(root, required(rest[1], "project"));
       if (rest[0] === "configure") return configureProject(root, required(rest[1], "project"), rest.slice(2));
-      throw new Error("Use `atdd-flow project init <project>` or `atdd-flow project configure <project> [--repository <primary-checkout>] [--worktree-root <directory>]`.");
+      if (rest[0] === "migrate-named-coordinator-topology") return migrateNamedCoordinatorTopology(root, required(rest[1], "project"), rest.slice(2));
+      throw new Error("Use `atdd-flow project init <project>`, `atdd-flow project configure <project> [--repository <primary-checkout>] [--worktree-root <directory>]`, or `atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>`.");
     },
     spawn: () => spawn(root, required(rest[0], "project"), required(rest[1], "role"), required(rest[2], "name"), rest.slice(3)),
     bind: () => bind(root, required(rest[0], "address"), rest.slice(1)),

package/src/seats.ts

@@ -1,5 +1,5 @@
 import { existsSync, realpathSync } from "node:fs";
-import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { basename, dirname, join, resolve } from "node:path";
 import { discoverAddress, discoverHerdrLocator, notify } from "./adapters";
@@ -77,6 +77,102 @@ const configureUsage = "Use `atdd-flow project configure <project> [--repository
  * The supported way to declare an existing project's primary checkout and linked-worktree root.
  * Everything is validated before one atomic write; only those two project fields change.
  */
+type MigrationSeat = { folder: string; record: Seat };
+
+const namedTopologyMigrationUsage = "Use `atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>`.";
+
+async function migrationSeats(root: string, config: Project): Promise<MigrationSeat[]> {
+  const directory = paths(root).seats(config.project);
+  if (!await exists(directory)) return [];
+  return Promise.all((await readdir(directory, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map(async (entry) => ({
+    folder: entry.name,
+    record: await readYaml<Seat>(join(directory, entry.name, "seat.yaml")),
+  })));
+}
+
+/**
+ * Validates existing coordinator records without provisioning anything. A policy
+ * migration must preserve generic history while refusing ambiguous named resources.
+ */
+function assertMigrationTopology(config: Project, seats: MigrationSeat[]) {
+  const primary = resolve(config.repository!);
+  const root = resolve(config.worktree_root!);
+  const coordinators = seats.filter(({ record }) => record.role === "coordinator");
+  const genericAddress = `coordinator@${config.project}`;
+  const generic = coordinators.filter(({ record }) => record.address === genericAddress);
+  if (generic.length > 1 || generic.some(({ folder }) => folder !== "coordinator")) throw new Error("Legacy generic coordinator collides with another coordinator record.");
+
+  const named = coordinators.filter(({ record }) => record.address !== genericAddress);
+  for (const { record } of generic) for (const namedRecord of named) {
+    if (record.branch === namedRecord.branch || record.worktree === namedRecord.worktree) {
+      throw new Error("Legacy generic coordinator collides with a named coordinator resource.");
+    }
+  }
+  const addresses = new Set<string>(), branches = new Set<string>(), worktrees = new Set<string>();
+  for (const { record } of named) {
+    if (!record.address.match(new RegExp(`^coordinator\\.([a-z0-9_-]+)@${config.project}$`))) throw new Error("Named coordinator seat collision.");
+    if (addresses.has(record.address)) throw new Error("Named coordinator seat collision.");
+    addresses.add(record.address);
+    if (branches.has(record.branch)) throw new Error("Named coordinator branch collision.");
+    branches.add(record.branch);
+    const worktree = resolve(record.worktree);
+    if (worktrees.has(worktree)) throw new Error("Named coordinator worktree collision.");
+    worktrees.add(worktree);
+  }
+  for (const { record } of named) {
+    const stream = record.address.slice("coordinator.".length, -(`@${config.project}`).length);
+    const worktree = resolve(record.worktree);
+    if (record.branch !== `integration/${stream}` || worktree !== resolve(join(root, stream)) || worktree === primary) {
+      throw new Error("Named coordinator seat collision.");
+    }
+  }
+  for (const { record } of seats.filter(({ record }) => record.role !== "coordinator")) for (const namedRecord of named) {
+    if (record.branch === namedRecord.branch) throw new Error("Named coordinator branch collision.");
+    if (resolve(record.worktree) === resolve(namedRecord.worktree)) throw new Error("Named coordinator worktree collision.");
+  }
+}
+
+/**
+ * Migrates only an existing project's coordinator role template. Validation is
+ * read-only and precedes the one atomic policy write, so no resource can leak.
+ */
+export async function migrateNamedCoordinatorTopology(root: string, name: string, args: string[]) {
+  if (args.length !== 2 || args[0] !== "--baseline" || !args[1]) throw new Error(args.includes("--baseline") ? namedTopologyMigrationUsage : "Missing --baseline.");
+  const baseline = args[1]!;
+  if (!/^[0-9a-f]{40}$/.test(baseline)) throw new Error("--baseline must be a full lowercase SHA-1.");
+  if (!await exists(paths(root).projectFile(name))) throw new Error(`Project ${name} does not exist.`);
+  const config = await project(root, name);
+  if (!config.repository) throw new Error(`Project ${name} has no repository.`);
+  if (!config.worktree_root) throw new Error(`Project ${name} has no worktree_root.`);
+  const repository = resolve(config.repository), worktreeRoot = resolve(config.worktree_root);
+  const top = existsSync(repository) ? Bun.spawnSync(["git", "-C", repository, "rev-parse", "--show-toplevel"], { stdout: "pipe", stderr: "pipe" }) : undefined;
+  if (!top || top.exitCode !== 0 || realpathSync(top.stdout.toString().trim()) !== realpathSync(repository)) throw new Error(`Project ${name} repository is not a Git top level.`);
+  try { if (!(await stat(worktreeRoot)).isDirectory()) throw new Error(); }
+  catch { throw new Error(`Project ${name} has no worktree_root.`); }
+
+  const remote = (await runOutput(["git", "-C", repository, "ls-remote", "--exit-code", "origin", "refs/heads/main"])).trim().split(/\s+/)[0];
+  if (remote !== baseline) throw new Error(`Baseline ${baseline} does not equal origin/main.`);
+  try { await runOutput(["git", "-C", repository, "cat-file", "-e", `${baseline}^{commit}`]); }
+  catch { throw new Error(`Baseline ${baseline} is not available locally.`); }
+  assertMigrationTopology(config, await migrationSeats(root, config));
+
+  const coordinator = config.roles.coordinator;
+  if (!coordinator) throw new Error(`Project ${name} has no coordinator role policy.`);
+  const next: Project = {
+    ...config,
+    roles: {
+      ...config.roles,
+      coordinator: {
+        ...coordinator,
+        address: "coordinator.{name}@{project}", branch: "integration/{name}", base: "main", worktree: "{worktree_root}/{name}",
+      },
+    },
+  };
+  try { await atomicYaml(paths(root).projectFile(name), next); }
+  catch { throw new Error("Unable to atomically write migration policy."); }
+  console.log(`${name}  named coordinator topology migrated`);
+}
+
 export async function configureProject(root: string, name: string, args: string[]) {
   const config = await project(root, name);
   const values = new Map<string, string>();
@@ -117,7 +213,7 @@ async function noBranch(config: Project, branch: string) {
   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) {
+async function taskCoordinatorBase(root: string, config: Project, task: Task, requireCleanCheckout = true) {
   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}.`);
@@ -139,15 +235,17 @@ async function taskCoordinatorBase(root: string, config: Project, task: Task) {
     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}.`);
+  const repository = required(config.repository, "project repository");
+  const branchHead = await runOutput(["git", "-C", repository, "rev-parse", branch]);
+  if (!requireCleanCheckout) return { coordinator, branch, commit: branchHead };
   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 };
+  return { coordinator, branch, commit: branchHead };
 }
 
 /** Creates a fresh driver and assigns its existing todo task from the task coordinator's exact head. */
@@ -156,6 +254,22 @@ async function spawnTaskDriver(root: string, config: Project, role: Role, name:
     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 baseArgument = words(args, "--base");
+  const dryRun = has(args, "--dry-run");
+  const explicit = args.includes("--base") || dryRun;
+  if (explicit) {
+    const allowed = new Set(["--task", "--base", "--dry-run"]);
+    const taskArgument = words(args, "--task");
+    const onlyExpectedValues = args.every((arg, index) => allowed.has(arg)
+      || (index > 0 && ["--task", "--base"].includes(args[index - 1]!)));
+    if (!onlyExpectedValues || args.filter((arg) => arg === "--task").length !== 1
+      || args.filter((arg) => arg === "--base").length !== 1
+      || args.filter((arg) => arg === "--dry-run").length > 1
+      || !taskArgument || taskArgument.startsWith("--")
+      || !baseArgument || !/^[0-9a-f]{40}$/.test(baseArgument)) {
+      throw new Error("Task-aware explicit base requires one --task <task-id> and one --base <full-40-lowercase-commit-sha>.");
+    }
+  }
   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}`);
@@ -167,7 +281,23 @@ async function spawnTaskDriver(root: string, config: Project, role: Role, name:
   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);
+  // An explicit baseline is governed by the repository ref, never by a
+  // potentially dirty or stale coordinator checkout. Legacy spawn retains its
+  // existing clean-checkout guard and derives exactly as before.
+  const coordinatorBase = await taskCoordinatorBase(root, config, task, !baseArgument);
+  let base = coordinatorBase;
+  if (baseArgument) {
+    try { await runOutput(["git", "-C", required(config.repository, "project repository"), "cat-file", "-e", `${baseArgument}^{commit}`]); }
+    catch { throw new Error(`Explicit base ${baseArgument} does not exist locally in the configured repository.`); }
+    try { await run(["git", "-C", required(config.repository, "project repository"), "merge-base", "--is-ancestor", coordinatorBase.commit, baseArgument], true); }
+    catch { throw new Error(`Explicit base ${baseArgument} does not descend ${coordinatorBase.branch}.`); }
+    base = { ...coordinatorBase, commit: baseArgument };
+  }
+  if (dryRun) {
+    if (!baseArgument) throw new Error("--dry-run is supported only with explicit --base task-aware spawn.");
+    console.log(`${address}  dry-run ${id}  base ${base.commit}  branch ${branch}  worktree ${worktree}`);
+    return;
+  }
   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.");
@@ -184,17 +314,23 @@ async function spawnTaskDriver(root: string, config: Project, role: Role, name:
     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.`);
+    const currentBranch = await runOutput(["git", "-C", required(config.repository, "project repository"), "rev-parse", coordinatorBase.branch]);
+    if (currentBranch !== coordinatorBase.commit) throw new Error(`Coordinator ${base.coordinator.address} advanced during driver provisioning.`);
+    if (!baseArgument) {
+      const current = await runOutput(["git", "-C", base.coordinator.worktree, "rev-parse", "HEAD"]);
+      if (current !== coordinatorBase.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);
+    if (created) {
+      await run(["git", "-C", required(config.repository, "project repository"), "worktree", "remove", "--force", worktree], true).catch(() => undefined);
+      await run(["git", "-C", required(config.repository, "project repository"), "branch", "-D", branch], true).catch(() => undefined);
+    }
     await rm(paths(root).seat(address), { recursive: true, force: true });
     throw error;
   }
-  console.log(`${address}  assigned ${id}  return ${base.branch}`);
+  console.log(`${address}  assigned ${id}  return ${base.branch}${baseArgument ? `  base ${base.commit}` : ""}`);
 }
 
 export async function spawn(root: string, projectName: string, roleName: string, name: string, args: string[]) {