@afokapu/atdd-flow 0.3.24 → 0.3.26

package/README.md

@@ -16,7 +16,7 @@ Desk (private Git repository)             Code repositories / worktrees
 - A **seat** owns responsibility, branch, worktree, checkpoint, and host addresses; a **task** owns its brief, ownership, dependencies, criteria, and proof.
 - A **thread** owns messages, receipts, results, and decisions; a **host** owns panes and notifications—never durable state.
 
-A stable address, such as `driver.runtime@resolver-os`, survives a different pane, host, model, or replacement agent. A replacement reads its durable seat, task, checkpoint, and threads rather than predecessor-private context.
+A stable address, such as `driver.runtime@example-app`, survives a different pane, host, model, or replacement agent. A replacement reads its durable seat, task, checkpoint, and threads rather than predecessor-private context.
 
 Workflow is a YAML protocol and CLI—not a database, daemon, agent runtime, or task-management SaaS. Git supplies history and replication; a multiplexer may wake an agent, but never owns state.
 
@@ -76,15 +76,25 @@ model. Final behavioral review has its own bounded routing step described below.
 
 ## Configure worktrees and seats
 
-Create a project, then set its policy in `work/<project>/project.yaml`:
+Create a project, declare its primary checkout and linked-worktree root, then adjust its policy in `work/<project>/project.yaml`:
 
 ```sh
-atdd-flow project init resolver-os
+atdd-flow project init example-app
+atdd-flow project configure example-app --repository /Users/you/Github/example-app --worktree-root /Users/you/Github/worktrees/example-app
 ```
 
+`project configure` sets only `repository` and `worktree_root`. It fails closed, leaving the project
+unchanged, when `--repository` is not the top level of a Git repository or a flag is unknown, repeated,
+or missing its value. It never changes seats, runtimes, tasks, branches, worktrees, or repository
+content; it lists each seat whose recorded placement violates the topology as `unprojected`.
+
+A misplaced seat is left unprojected: `multiplexer status` reports it under `unprojected`, and
+`multiplexer apply` and launch projection of other seats continue. Projecting that seat explicitly
+still rejects until its placement is corrected.
+
 ```yaml
-repository: /Users/you/Github/resolver-os
-worktree_root: /Users/you/Github/worktrees/resolver-os
+repository: /Users/you/Github/example-app
+worktree_root: /Users/you/Github/worktrees/example-app
 roles:
   coordinator: { address: coordinator@{project}, branch: main, worktree: '{repository}' }
   driver: { address: driver.{name}@{project}, branch: delivery/{name}, base: main, worktree: '{worktree_root}/{name}' }
@@ -93,11 +103,11 @@ roles:
 The operator or coordinator creates seats; drivers do not choose their policy:
 
 ```sh
-atdd-flow spawn resolver-os coordinator main --worktree /Users/you/Github/resolver-os
-atdd-flow spawn resolver-os driver runtime
+atdd-flow spawn example-app coordinator main --worktree /Users/you/Github/example-app
+atdd-flow spawn example-app driver runtime
 ```
 
-`spawn` creates missing driver worktrees through Git: this example creates `/Users/you/Github/worktrees/resolver-os/runtime` on `delivery/runtime`. ATDD Bun owns safe retirement, not creation. A seat can own several tasks.
+`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.
 
 ## Deliver work
 
@@ -108,14 +118,14 @@ todo → in_progress → review → done
 The coordinator assigns; the driver implements, proves each criterion, and submits for review; only the coordinator marks the task done.
 
 ```sh
-atdd-flow task add resolver-os runtime-rollout --title 'Complete runtime rollout' \
-  --coordinator coordinator@resolver-os --assignee driver.runtime@resolver-os \
+atdd-flow task add example-app runtime-rollout --title 'Complete runtime rollout' \
+  --coordinator coordinator@example-app --assignee driver.runtime@example-app \
   --done-when 'Checks pass'
-atdd-flow task start resolver-os runtime-rollout --by driver.runtime@resolver-os
-atdd-flow task prove resolver-os runtime-rollout --by driver.runtime@resolver-os --item 1 --proof 'CI run 42'
-atdd-flow task review resolver-os runtime-rollout --by driver.runtime@resolver-os
+atdd-flow task start example-app runtime-rollout --by driver.runtime@example-app
+atdd-flow task prove example-app runtime-rollout --by driver.runtime@example-app --item 1 --proof 'CI run 42'
+atdd-flow task review example-app runtime-rollout --by driver.runtime@example-app
 # An independently attached reviewer persists APPROVE, RETURN, or ESCALATE through behavioral-review record
-atdd-flow task done resolver-os runtime-rollout --by coordinator@resolver-os
+atdd-flow task done example-app runtime-rollout --by coordinator@example-app
 ```
 
 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.
@@ -127,11 +137,11 @@ For topology normalization, transfer an active task through the narrow durable c
 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.
 
 ```sh
-atdd-flow thread start --with coordinator@resolver-os,driver.runtime@resolver-os \
-  --subject 'Runtime rollout' --task resolver-os/runtime-rollout
-atdd-flow post T-... --from coordinator@resolver-os --to driver.runtime@resolver-os \
+atdd-flow thread start --with coordinator@example-app,driver.runtime@example-app \
+  --subject 'Runtime rollout' --task example-app/runtime-rollout
+atdd-flow post T-... --from coordinator@example-app --to driver.runtime@example-app \
   --label 'implementation request' --expects-result --body 'Implement the task and return proof references.'
-atdd-flow result T-... M-... --from driver.runtime@resolver-os --label 'proof returned' --body 'CI run 42; PR #81.'
+atdd-flow result T-... M-... --from driver.runtime@example-app --label 'proof returned' --body 'CI run 42; PR #81.'
 ```
 
 New durable thread and message IDs are human-readable: `T-` or `M-`, a UTC-second
@@ -149,14 +159,14 @@ For a shared boundary: driver → coordinator → affected coordinator(s) → mi
 
 ```sh
 atdd-flow status
-atdd-flow status seat driver.runtime@resolver-os
-atdd-flow open driver.runtime@resolver-os
+atdd-flow status seat driver.runtime@example-app
+atdd-flow open driver.runtime@example-app
 ```
 
 Herdr and tmux can notify an already attached host pane. Flow does not create host panes: the operator starts the agent in its declared worktree with `ATDD_WORKFLOW_ROOT` and `ATDD_WORKFLOW_SEAT`, then attaches that pane deterministically.
 
 ```sh
-atdd-flow attach driver.runtime@resolver-os --application herdr
+atdd-flow attach driver.runtime@example-app --application herdr
 ```
 
 ### Optional Herdr worktree projection
@@ -213,10 +223,10 @@ To host Pi in Herdr, create a pane with the durable Desk and seat identity, then
 PI_EXTENSION="$(atdd-flow pi extension-path)"
 herdr pane split --current --direction right --cwd /path/to/worktree --no-focus \
   --env ATDD_WORKFLOW_ROOT=/path/to/desk \
-  --env ATDD_WORKFLOW_SEAT=driver.runtime@resolver-os
+  --env ATDD_WORKFLOW_SEAT=driver.runtime@example-app
 # Use the pane id returned above.
 herdr agent start pi-runtime --kind pi --pane <pane-id> -- --extension "$PI_EXTENSION"
-atdd-flow --root /path/to/desk attach driver.runtime@resolver-os --application herdr --wake native
+atdd-flow --root /path/to/desk attach driver.runtime@example-app --application herdr --wake native
 ```
 
 Pi receives its identity and startup task from the extension itself. Its normal TUI remains visible and manually usable; incoming Desk mail wakes it through Pi's native message API. The runtime lifecycle has one internal bounded inbox transport; it does not add a second watcher, registry, mailbox, reservation system, or routing path.
@@ -265,7 +275,7 @@ Jev is read-only; it cannot mutate state, approve proof, or override ATDD Bun.
 
 ```sh
 atdd-flow scout --goal 'Fix payment retry behavior' --path src/payment/retry.ts --path src/profile/avatar.ts
-atdd-flow focus-check resolver-os runtime-rollout --action 'Add a generic retry orchestration service'
+atdd-flow focus-check example-app runtime-rollout --action 'Add a generic retry orchestration service'
 ```
 
 `scout` selects likely files. `focus-check` returns `REQUIRED`, `USEFUL_BUT_NOT_REQUIRED`, or `SPECULATIVE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "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, spawn, bind, useApplication, attach, describe, checkpoint, launchPiRuntime, migrate, openSeat, piExtensionPath } from "./seats";
+import { init, initProject, configureProject, 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";
@@ -23,6 +23,7 @@ Usage:
   atdd-flow init <desk-directory> [--git]
   atdd-flow desk migrate
   atdd-flow project init <project>
+  atdd-flow project configure <project> [--repository <primary-checkout>] [--worktree-root <directory>]
   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]
@@ -87,7 +88,8 @@ async function main() {
     },
     project: async () => {
       if (rest[0] === "init") return initProject(root, required(rest[1], "project"));
-      throw new Error("Use `atdd-flow project init <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>]`.");
     },
     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/multiplexer.ts

@@ -89,6 +89,21 @@ async function projectSeats(root: string, projectName: string) {
   return seats.filter((entry): entry is Seat => Boolean(entry && entry.schema === "atdd-workflow/seat/v2" && !entry.retired));
 }
 
+export type UnprojectedSeat = { address: string; reason: string };
+
+/** Seats whose recorded placement violates the project topology; they are never projected. */
+export async function misplacedSeats(root: string, projectName: string): Promise<UnprojectedSeat[]> {
+  const config = await project(root, projectName);
+  if (!config.repository) return [];
+  const primary = resolve(config.repository);
+  const result: UnprojectedSeat[] = [];
+  for (const entry of await projectSeats(root, projectName)) {
+    try { assertNewTopologyPlacement(config, entry, primary); }
+    catch (error) { result.push({ address: entry.address, reason: (error as Error).message }); }
+  }
+  return result;
+}
+
 function assertNewTopologyPlacement(config: Project, entry: Seat, primary: string) {
   const coordinator = config.roles.coordinator;
   const namedCoordinatorDefaults = coordinator?.address === "coordinator.{name}@{project}" && coordinator.branch === "integration/{name}";
@@ -111,7 +126,11 @@ function assertNewTopologyPlacement(config: Project, entry: Seat, primary: strin
   }
 }
 
-async function targets(root: string): Promise<Target[]> {
+/**
+ * A misplaced seat is skipped and recorded in `unprojected` so it never aborts projection of other
+ * seats; requesting that seat explicitly (`strict`) still rejects.
+ */
+async function targets(root: string, options: { strict?: string; unprojected?: UnprojectedSeat[] } = {}): Promise<Target[]> {
   let projects: string[];
   try { projects = await readdir(paths(root).work); }
   catch { return []; }
@@ -124,8 +143,13 @@ 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) {
+      try { assertNewTopologyPlacement(config, entry, primary); }
+      catch (error) {
+        if (entry.address === options.strict) throw error;
+        options.unprojected?.push({ address: entry.address, reason: (error as Error).message });
+        continue;
+      }
+      if ((entry.role === "main" || entry.role === "coordinator" || entry.role === "operator") && resolve(entry.worktree) === primary) {
         result.push({ project: name, worktree: primary, workspaceLabel: name, seat: entry });
         continue;
       }
@@ -166,8 +190,16 @@ async function liveWorkspaces(session: string, command: HerdrCommand) {
   return value.workspaces as Workspace[];
 }
 
+/** A live workspace without a checkout path never matches: resolve("") would be the process cwd. */
+function matchWorkspace(workspaces: Workspace[], worktree: string) {
+  return workspaces.find((entry) => {
+    const checkout = entry.worktree?.checkout_path;
+    return typeof checkout === "string" && checkout !== "" && resolve(checkout) === worktree;
+  });
+}
+
 async function ensureWorkspace(session: string, target: Target, workspaces: Workspace[], command: HerdrCommand, primary?: WorkspaceState) {
-  let current = workspaces.find((entry) => resolve(entry.worktree?.checkout_path ?? "") === target.worktree);
+  let current = matchWorkspace(workspaces, target.worktree);
   if (!current) {
     const args = target.workspaceLabel === target.project
       ? ["workspace", "create", "--cwd", target.worktree, "--label", target.workspaceLabel, "--no-focus"]
@@ -229,7 +261,7 @@ async function ensureTarget(session: string, target: Target, workspaces: Workspa
 /** Reconciles exactly one Desk seat into a labeled Herdr workspace/tab/pane. */
 export async function projectHerdrSeat(root: string, address: string, session: string, command: HerdrCommand = herdr): Promise<HerdrSeatProjection> {
   await herdrPolicy();
-  const desired = await targets(root);
+  const desired = await targets(root, { strict: address });
   const target = desired.find((entry) => entry.seat?.address === address);
   if (!target?.seat) throw new Error(`No active Desk projection target exists for ${address}.`);
   const primaryTarget = desired.find((entry) => entry.project === target.project && entry.workspaceLabel === target.project && !entry.seat);
@@ -260,16 +292,17 @@ export async function multiplexer(root: string, args: string[]) {
     console.log("No Herdr session selected; projection was not run.");
     return;
   }
-  const desired = await targets(root);
+  const unprojected: UnprojectedSeat[] = [];
+  const desired = await targets(root, { unprojected });
   const command: HerdrCommand = herdr;
   const workspaces = await liveWorkspaces(session, command);
   if (action === "status") {
-    const present = desired.filter((target) => workspaces.some((entry) => resolve(entry.worktree?.checkout_path ?? "") === target.worktree));
+    const present = desired.filter((target) => matchWorkspace(workspaces, target.worktree));
     const topology = await Promise.all(desired.map(async (target) => {
-      const workspace = workspaces.find((entry) => resolve(entry.worktree?.checkout_path ?? "") === target.worktree);
+      const workspace = matchWorkspace(workspaces, target.worktree);
       return workspace ? topologyCompliant(session, target, workspace, command) : false;
     }));
-    console.log(JSON.stringify({ schema: "atdd-workflow/multiplexer-status/v1", application: "herdr", session, desired: desired.length, present: present.length, topology_compliant: topology.filter(Boolean).length }, null, 2));
+    console.log(JSON.stringify({ schema: "atdd-workflow/multiplexer-status/v1", application: "herdr", session, desired: desired.length, present: present.length, topology_compliant: topology.filter(Boolean).length, unprojected }, null, 2));
     return;
   }
   const primary = new Map<string, WorkspaceState>();
@@ -283,5 +316,6 @@ export async function multiplexer(root: string, args: string[]) {
     }
     await ensureTarget(session, target, workspaces, command, projectPrimary);
   }
+  for (const entry of unprojected) console.log(`unprojected  ${entry.address}: ${entry.reason}`);
   console.log(`Projected ${desired.length} Desk seat worktree(s) into Herdr session ${session}.`);
 }

package/src/seats.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import { basename, dirname, join, resolve } from "node:path";
@@ -10,7 +10,7 @@ import {
 } from "./core";
 import { type ModelSelectionInput, type ModelSelectionResponse, selectModel } from "./judgment";
 import { seatTasks } from "./tasks";
-import { projectHerdrSeat } from "./multiplexer";
+import { misplacedSeats, projectHerdrSeat } from "./multiplexer";
 import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 
@@ -68,6 +68,35 @@ export async function initProject(root: string, name: string) {
   console.log(`Initialized project ${name}`);
 }
 
+const configureUsage = "Use `atdd-flow project configure <project> [--repository <primary-checkout>] [--worktree-root <directory>]`.";
+
+/**
+ * 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.
+ */
+export async function configureProject(root: string, name: string, args: string[]) {
+  const config = await project(root, name);
+  const values = new Map<string, string>();
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index], value = args[index + 1];
+    if (!["--repository", "--worktree-root"].includes(flag) || values.has(flag) || !value || value.startsWith("--")) throw new Error(configureUsage);
+    values.set(flag, value);
+  }
+  if (!values.size) throw new Error(configureUsage);
+  const repository = values.get("--repository"), worktreeRoot = values.get("--worktree-root");
+  if (repository) {
+    const path = resolve(repository);
+    const real = (value: string) => { try { return realpathSync(value); } catch { return value; } };
+    const top = existsSync(path) ? Bun.spawnSync(["git", "-C", path, "rev-parse", "--show-toplevel"], { stdout: "pipe", stderr: "pipe" }) : undefined;
+    if (!top || top.exitCode !== 0 || real(top.stdout.toString().trim()) !== real(path)) throw new Error(`${path} is not the top level of a Git repository.`);
+    config.repository = path;
+  }
+  if (worktreeRoot) config.worktree_root = resolve(worktreeRoot);
+  await atomicYaml(paths(root).projectFile(name), config);
+  for (const entry of await misplacedSeats(root, name)) console.log(`unprojected  ${entry.address}: ${entry.reason}`);
+  console.log(`${name}  configured`);
+}
+
 async function ensureWorktree(config: Project, role: Role, worktree: string, branch: string) {
   if (!config.repository || worktree === resolve(config.repository) || await exists(worktree)) return;
   await mkdir(dirname(worktree), { recursive: true });