@afokapu/atdd-flow 0.3.62 → 0.3.64

package/extensions/pi/index.ts

@@ -6,7 +6,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearStaleRuntimeState, clearRuntimeState, heartbeatRuntimeState, ownsRuntimeState, recordMailActivation, registerRuntimeState, runtimeOwnerToken, withOwnedRuntimeState } from "../../src/runtime-state";
 import { paths, readYaml, type Seat } from "../../src/core";
 import { activationNotice, diagnoseMailActivation, expectsNativeMail } from "../../src/mail-activation-notice";
-import { type NoticeState, createNoticeState, refreshDelivered, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
+import { type NoticeState, createNoticeState, refreshDelivered, sendSettledDirective, sendTaskDirective, shouldNotifyMail } from "../../src/next-action-notices";
 import { handoverThresholdInstruction, runtimeStartupInstruction, successorInstruction } from "../../src/collaboration-policy";
 import { type RecoveryMode, recoveryFor } from "../../src/recovery-bundle";
 import { contextHandoverThreshold, readHandoverReplacement } from "../../src/handover";
@@ -382,7 +382,11 @@ export default function (pi: ExtensionAPI) {
     return message ? { message: message as typeof event.message } : undefined;
   });
   // Nothing queued survives a settled run, so a pending flag left by a cleared queue cannot suppress future notices.
-  pi.on("agent_settled", () => { notices.pending = false; });
+  pi.on("agent_settled", async () => {
+    notices.pending = false;
+    // Run completion is not task completion; one bounded continuation per unchanged directive.
+    await sendSettledDirective(host, root, seat, notices);
+  });
   pi.on("turn_end", async (_event, ctx) => {
     if (handoverPrompted) return;
     const percent = ctx.getContextUsage()?.percent;

package/package.json

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

package/src/cli.ts

@@ -19,6 +19,7 @@ import { multiplexer } from "./multiplexer";
 import * as cleanup from "./ephemeral-resources";
 import * as ownerAlerts from "./owner-escalations";
 import { recoveryFor } from "./recovery-bundle";
+import { reconcileOnce } from "./reconcile";
 import { recordHandover, requestHandoverReplacement, resumedHandoverReplacement, showHandover } from "./handover";
 
 const usage = `atdd-flow — filesystem-first agent seats and tasks
@@ -30,7 +31,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 project configure <project> [--vcs <git|jj>] [--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]
@@ -65,6 +66,7 @@ Usage:
   atdd-flow task open <project> <task-id>
   atdd-flow cleanup status <project>
   atdd-flow cleanup checklist <project> <task-id>
+  atdd-flow reconcile --once [--dry-run]
   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>]
@@ -166,6 +168,12 @@ 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>`.");
     },
+    reconcile: async () => {
+      if (!rest.includes("--once") || rest.some((value) => value !== "--once" && value !== "--dry-run"))
+        throw new Error("Use `atdd-flow reconcile --once [--dry-run]`.");
+      process.stdout.write(Bun.YAML.stringify(await reconcileOnce(root, { dryRun: rest.includes("--dry-run") })));
+      return;
+    },
     "owner-alert": async () => {
       const [subcommand, alertId, ...tail] = rest;
       if (subcommand === "scan") {

package/src/core.ts

@@ -44,6 +44,8 @@ type LegacyCoordination = { schema: "atdd-workflow/coordination/v2"; site: strin
 export type Project = {
   schema: string;
   project: string;
+  /** Repository VCS. Omitted preserves the historical Git behavior. */
+  vcs?: "git" | "jj";
   repository?: string;
   worktree_root?: string;
   roles: Record<string, Role>;

package/src/next-action-notices.ts

@@ -14,6 +14,8 @@ export type NoticeState = {
   /** A next-action follow-up has been queued and not yet delivered. */
   pending: boolean;
   lastDelivered?: string;
+  /** One automatic post-settlement continuation per unchanged directive. */
+  settledNudged?: string;
   /** Blocker notices already delivered this session, keyed by task and blocker text. */
   blockers: Set<string>;
   /** Mail ids already notified this session. */
@@ -50,19 +52,46 @@ export async function sendTaskDirective(host: NoticeHost, root: string, seat: st
   }
 }
 
+/** A settled model turn is not task completion. Give one additional nudge for a
+ * still-actionable directive, but never loop on unchanged task state. */
+export async function sendSettledDirective(host: NoticeHost, root: string, seat: string, state: NoticeState) {
+  if (state.pending) return;
+  try {
+    const directive = await nextDirective(root, seat);
+    if (!directive?.command) return; // Waiting for an authority or dependency is not work for this seat.
+    const key = directiveKey(directive);
+    if (key !== state.lastDelivered) return sendTaskDirective(host, root, seat, state);
+    if (state.settledNudged === key) return;
+    state.settledNudged = key;
+    state.pending = true;
+    host.sendMessage({
+      customType: "atdd-flow-next-action",
+      content: directiveNotice(seat, directive),
+      display: true,
+      details: { ...directiveDetails(directive), continuation: true },
+    }, { triggerTurn: true, deliverAs: "followUp" });
+  } catch { state.pending = false; }
+}
+
 /** Re-derives a held next-action follow-up when Pi delivers it; a queued message cannot be dropped, so it is replaced by the shortest truthful text. */
 async function currentDirective(root: string, seat: string, state: NoticeState, message: NoticeMessage): Promise<NoticeMessage> {
   state.pending = false;
   const directive = await nextDirective(root, seat).catch(() => undefined);
   if (!directive) {
     state.lastDelivered = undefined;
+    state.settledNudged = undefined;
     return { ...message, content: `SYSTEM: next-action notice for ${seat} withdrawn: task state has no actionable step. Task state outranks mail.`, details: { authority: "task", lifecycle: "NONE" } };
   }
   const key = directiveKey(directive);
   if (key === state.lastDelivered) {
+    if (message.details?.continuation === true && directive.command) {
+      return { ...message, content: `${directiveNotice(seat, directive)} The task remains open. Continue or escalate a real blocker; do not stop merely because this turn ended.`,
+        details: { ...directiveDetails(directive), continuation: true } };
+    }
     return { ...message, content: `SYSTEM: next action for ${seat} unchanged on ${directive.project}/${directive.task} [${directive.lifecycle}]; see the previous notice.`, details: directiveDetails(directive) };
   }
   state.lastDelivered = key;
+  state.settledNudged = undefined;
   if (directive.lifecycle === "BLOCKED") state.blockers.add(key);
   return { ...message, content: directiveNotice(seat, directive), details: directiveDetails(directive) };
 }

package/src/reconcile.ts

@@ -0,0 +1,151 @@
+// URN: component:flow:e012:reconcile:backend:application
+// Tested-By:
+// - test:flow:continuation:E012-UNIT-001
+// Runtime: bun
+// Purpose: Wake idle owners of existing actionable Flow obligations.
+import { createHash } from "node:crypto";
+import { mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { notify } from "./adapters";
+import { type HerdrLocator, type Seat, atomicYaml, paths, readYaml, runOutput } from "./core";
+import { type TaskDirective, directiveNotice, nextDirective } from "./tasks";
+import { isRuntimeStateStale, readRuntimeState, withOwnedRuntimeState } from "./runtime-state";
+
+type Outcome = "woke" | "dry_run" | "cooldown" | "exhausted" | "inactive" | "unverified" | "busy" | "replaced" | "wake_failed";
+export type Reconciliation = { seat: string; task: string; outcome: Outcome };
+export type ReconcileOptions = {
+  now?: Date;
+  dryRun?: boolean;
+  cooldownMs?: number;
+  maxNudges?: number;
+  inspect?: (locator: HerdrLocator, seat: string) => Promise<string>;
+  wake?: (locator: HerdrLocator, notice: string) => Promise<void>;
+};
+
+type Attempt = { schema: "atdd-flow/continuation-attempt/v1"; key: string; at: string; count: number };
+type Target = { owner: Seat; directive: TaskDirective; locator: HerdrLocator; token: string };
+type Settings = Required<Pick<ReconcileOptions, "now" | "cooldownMs" | "maxNudges" | "inspect" | "wake">> & { dryRun: boolean };
+
+const agentName = (address: string) => `flow-${address.replace(/[^a-z0-9_-]/gi, "-").toLowerCase()}`.slice(0, 32);
+const fingerprint = (target: Target) =>
+  createHash("sha256").update(JSON.stringify({ directive: target.directive, session: target.owner.runtime?.pi_session, owner: target.token })).digest("hex");
+const attemptFile = (root: string, address: string) =>
+  join(root, ".atdd-flow", "continuation", `${encodeURIComponent(address)}.yaml`);
+
+/** Read Herdr status without treating missing or mismatched identities as healthy.
+ * The live host is an observation surface, never a seat registry.
+ */
+async function inspectHerdr(locator: HerdrLocator, address: string) {
+  const raw = JSON.parse(await runOutput(["herdr", "--session", locator.session, "agent", "get", agentName(address)]));
+  const envelope = raw?.result ?? raw;
+  const agent = envelope?.agent ?? envelope;
+  if (agent?.name !== agentName(address) || agent?.pane_id !== locator.pane) return "unverified";
+  return String(agent?.agent_status ?? agent?.status ?? agent?.state ?? "unverified").toLowerCase();
+}
+
+/** Discover durable seat identity from the existing Desk directories.
+ * No second fleet registry is created or synchronized.
+ */
+async function seats(root: string): Promise<Seat[]> {
+  const found: Seat[] = [];
+  for (const project of await readdir(paths(root).work, { withFileTypes: true })) {
+    if (!project.isDirectory()) continue;
+    for (const local of await readdir(paths(root).seats(project.name), { withFileTypes: true }).catch(() => [])) {
+      if (!local.isDirectory()) continue;
+      found.push(await readYaml<Seat>(join(paths(root).seats(project.name), local.name, "seat.yaml")));
+    }
+  }
+  return found;
+}
+
+function validateLimits(cooldownMs: number, maxNudges: number) {
+  if (!Number.isFinite(cooldownMs) || cooldownMs < 0) throw new Error("Invalid continuation cooldown.");
+  if (!Number.isInteger(maxNudges) || maxNudges < 1) throw new Error("Invalid maximum nudge count.");
+}
+
+function settings(options: ReconcileOptions): Settings {
+  const cooldownMs = options.cooldownMs ?? 5 * 60_000;
+  const maxNudges = options.maxNudges ?? 2;
+  validateLimits(cooldownMs, maxNudges);
+  return {
+    now: options.now ?? new Date(),
+    dryRun: options.dryRun ?? false,
+    cooldownMs, maxNudges,
+    inspect: options.inspect ?? inspectHerdr,
+    wake: options.wake ?? ((locator, notice) => notify("herdr", locator.pane, notice, locator.session)),
+  };
+}
+
+const outcome = (owner: Seat, directive: TaskDirective, status: Outcome): Reconciliation =>
+  ({ seat: owner.address, task: `${directive.project}/${directive.task}`, outcome: status });
+
+/** An actionable target also needs a live, matching runtime observation.
+ * This deliberately refuses an unknown or stale session rather than guessing.
+ */
+async function target(root: string, owner: Seat, directive: TaskDirective, at: Date): Promise<Target | undefined> {
+  const runtime = owner.runtime;
+  const locator = runtime?.addresses.herdr;
+  if (runtime?.application !== "herdr" || !locator || typeof locator === "string") return;
+  const active = await readRuntimeState(root, owner.address);
+  if (!active) return;
+  if (isRuntimeStateStale(active, 60_000, at)) return;
+  if (runtime.pi_session && active.pi_session !== runtime.pi_session) return;
+  return { owner, directive, locator, token: active.owner_token };
+}
+
+/** The per-seat retry memo is advisory: changing work or replacing an agent
+ * starts a new key, while unchanged instructions have bounded retries.
+ */
+function attemptDisposition(previous: Attempt | undefined, key: string, config: Settings): Outcome | undefined {
+  if (previous?.schema !== "atdd-flow/continuation-attempt/v1") return;
+  if (previous.key !== key) return;
+  if (previous.count >= config.maxNudges) return "exhausted";
+  if (config.now.getTime() - Date.parse(previous.at) < config.cooldownMs) return "cooldown";
+}
+
+/** Write the attempt before contacting Herdr, so a transient host failure
+ * cannot turn repeated reconciliation into a prompt storm.
+ */
+async function wakeOnce(root: string, candidate: Target, config: Settings): Promise<Outcome> {
+  const file = attemptFile(root, candidate.owner.address);
+  const key = fingerprint(candidate);
+  const previous = await readYaml<Attempt>(file).catch(() => undefined);
+  const suppressed = attemptDisposition(previous, key, config);
+  if (suppressed) return suppressed;
+  const count = previous?.key === key ? previous.count + 1 : 1;
+  await mkdir(join(root, ".atdd-flow", "continuation"), { recursive: true });
+  await atomicYaml(file, { schema: "atdd-flow/continuation-attempt/v1", key, at: config.now.toISOString(), count } satisfies Attempt);
+  try {
+    await config.wake(candidate.locator, `${directiveNotice(candidate.owner.address, candidate.directive)} The task remains open. Continue within your authority; escalate a real blocker rather than ending the obligation.`);
+    return "woke";
+  } catch { return "wake_failed"; }
+}
+
+async function reconcileSeat(root: string, owner: Seat, config: Settings): Promise<Reconciliation | undefined> {
+  if (owner.retired) return;
+  const directive = await nextDirective(root, owner.address);
+  // A directive without a command is a legitimate wait on another actor.
+  if (!directive?.command) return;
+  const candidate = await target(root, owner, directive, config.now);
+  if (!candidate) return outcome(owner, directive, "inactive");
+  let status: string;
+  try { status = await config.inspect(candidate.locator, owner.address); }
+  catch { return outcome(owner, directive, "unverified"); }
+  if (status === "unverified") return outcome(owner, directive, "unverified");
+  if (status !== "idle" && status !== "done") return outcome(owner, directive, "busy");
+  if (config.dryRun) return outcome(owner, directive, "dry_run");
+  // Serialize with a live runtime's token-fenced wake; a replacement cannot be prompted.
+  const result = await withOwnedRuntimeState(root, owner.address, candidate.token, () => wakeOnce(root, candidate, config));
+  return outcome(owner, directive, result.owned ? result.value : "replaced");
+}
+
+/** One-shot, advisory fleet reconciliation. Task state remains the sole work authority. */
+export async function reconcileOnce(root: string, options: ReconcileOptions = {}): Promise<Reconciliation[]> {
+  const config = settings(options);
+  const results: Reconciliation[] = [];
+  for (const owner of await seats(root)) {
+    const result = await reconcileSeat(root, owner, config);
+    if (result) results.push(result);
+  }
+  return results;
+}

package/src/reviews.ts

@@ -10,6 +10,7 @@ import {
 } from "./judgment";
 import { availableModelCandidates, bind, resolveExecutable, resolveModelCommand } from "./seats";
 import { type Task } from "./tasks";
+import { assertBranchReady, changedFiles, currentCommit, diffCommand, planArtifacts, vcsMode, type VcsMode } from "./vcs";
 
 const conventionRule = "atdd-bun.review.behavioral-reconciliation";
 const conventionRelativePath = "conventions/atdd-bun.review/atdd-bun.review.behavioral-reconciliation.convention.yaml";
@@ -105,34 +106,15 @@ export async function behavioralReviewRequired(root: string, task: Task) {
   return explicitWorkflowProfile(policyRoot);
 }
 
-async function currentHead(worktree: string) {
-  return runOutput(["git", "rev-parse", "HEAD"], worktree);
-}
-
-async function assertCleanDelivery(worktree: string) {
-  const dirty = await runOutput(["git", "status", "--porcelain"], worktree);
-  if (dirty) throw new Error("Final behavioral review requires a clean committed delivery worktree.");
-}
-
-async function changedFiles(worktree: string, base: string) {
-  const outputs = await Promise.allSettled([
-    runOutput(["git", "diff", "--name-only", `${base}...HEAD`], worktree),
-    runOutput(["git", "diff", "--name-only"], worktree),
-    runOutput(["git", "diff", "--name-only", "--cached"], worktree),
-    runOutput(["git", "ls-files", "--others", "--exclude-standard"], worktree),
-  ]);
-  return [...new Set(outputs.flatMap((output) => output.status === "fulfilled"
-    ? output.value.split("\n").map((entry) => entry.trim()).filter(Boolean)
-    : []
-  ))].slice(0, 200);
-}
-
-async function planArtifacts(worktree: string) {
-  try {
-    const output = await runOutput(["git", "ls-files", "plan"], worktree);
-    return output.split("\n").map((entry) => entry.trim()).filter((entry) => entry.endsWith(".yaml")).slice(0, 400);
-  } catch {
-    return [];
+async function cleanDeliveryRevision(mode: VcsMode, worktree: string, branch: string) {
+  if (mode === "git") {
+    const dirty = await runOutput(["git", "status", "--porcelain"], worktree);
+    if (dirty) throw new Error("Final behavioral review requires a clean committed delivery worktree.");
+    return currentCommit(mode, worktree);
+  }
+  try { return await assertBranchReady(mode, worktree, branch); }
+  catch (error) {
+    throw new Error(`Final behavioral review requires a clean committed delivery worktree: ${(error as Error).message}`);
   }
 }
 
@@ -172,9 +154,10 @@ async function route(
   options: JudgmentOptions = {},
 ) {
   const config = await project(root, projectName);
+  const mode = vcsMode(config);
   const role = config.roles[owner.role];
   const base = role?.base ?? config.roles.coordinator?.branch ?? "main";
-  const [files, plans] = await Promise.all([changedFiles(owner.worktree, base), planArtifacts(owner.worktree)]);
+  const [files, plans] = await Promise.all([changedFiles(mode, owner.worktree, base), planArtifacts(mode, owner.worktree)]);
   const judgment = await routeBehavioralReview({
     title: task.title,
     ...(task.body ? { body: task.body } : {}),
@@ -188,6 +171,7 @@ async function route(
     files,
     plans,
     base,
+    mode,
   };
 }
 
@@ -250,7 +234,8 @@ export async function launchBehavioralReview(
   if (!task.done_when.every((entry) => Boolean(entry.proof))) throw new Error(`Task ${taskId} is missing delivery proof.`);
 
   const owner = await ownerForTask(root, task);
-  await assertCleanDelivery(owner.worktree);
+  const mode = vcsMode(await project(root, projectName));
+  const head = await cleanDeliveryRevision(mode, owner.worktree, owner.branch);
 
   let gateOutput: string;
   try {
@@ -294,7 +279,6 @@ export async function launchBehavioralReview(
   }
 
   const reviewer = await writeReviewerSeat(root, projectName, taskId, owner);
-  const head = await currentHead(owner.worktree);
   const history = await readBehavioralReviews(root, projectName, taskId) ?? {
     schema: "atdd-workflow/behavioral-reviews/v1" as const,
     task: `${projectName}/${taskId}`,
@@ -327,7 +311,7 @@ export async function launchBehavioralReview(
       runtime: { worktree: owner.worktree, branch: owner.branch, head },
       implementation: {
         changed_files: routed.files,
-        diff_command: `git diff ${routed.base}...HEAD`,
+        diff_command: diffCommand(routed.mode, routed.base),
       },
     },
   };
@@ -420,8 +404,9 @@ export async function recordBehavioralReview(root: string, projectName: string,
   const actor = required(words(args, "--by"), "--by");
   if (actor !== attempt.reviewer.address) throw new Error(`Only ${attempt.reviewer.address} may record review ${attempt.id}.`);
   const owner = await ownerForTask(root, task);
-  await assertCleanDelivery(owner.worktree);
-  if (await currentHead(owner.worktree) !== attempt.delivery_head) throw new Error("Delivery HEAD changed during behavioral review; launch a new review against the current delivery.");
+  const mode = vcsMode(await project(root, projectName));
+  const head = await cleanDeliveryRevision(mode, owner.worktree, owner.branch);
+  if (head !== attempt.delivery_head) throw new Error(mode === "git" ? "Delivery HEAD changed during behavioral review; launch a new review against the current delivery." : "Delivery revision changed during behavioral review; launch a new review against the current delivery.");
   const file = required(words(args, "--file"), "--file");
   const result = validateResult(yaml.parse(await readFile(file, "utf8")));
   attempt.status = "complete";
@@ -443,6 +428,7 @@ export async function assertAcceptedBehavioralReview(root: string, projectName:
   if (latest.status !== "complete" || !latest.result) throw new Error(`Task ${taskId} has no completed final behavioral review.`);
   if (latest.result.decision !== "APPROVE") throw new Error(`Task ${taskId} final behavioral review is ${latest.result.decision}, not APPROVE.`);
   const owner = await ownerForTask(root, task);
-  await assertCleanDelivery(owner.worktree);
-  if (await currentHead(owner.worktree) !== latest.delivery_head) throw new Error(`Task ${taskId} changed after final behavioral review; review the current delivery before completion.`);
+  const mode = vcsMode(await project(root, projectName));
+  const head = await cleanDeliveryRevision(mode, owner.worktree, owner.branch);
+  if (head !== latest.delivery_head) throw new Error(`Task ${taskId} changed after final behavioral review; review the current delivery before completion.`);
 }

package/src/seats.ts

@@ -15,6 +15,7 @@ import { isRuntimeStateStale, readRuntimeState } from "./runtime-state";
 import { resolveExactSessionAdoptionAuthorization } from "./adoption-authorizations";
 import { projectCollaborationPolicy } from "./collaboration-policy";
 import { assertReplacementTarget, replacementForMainLaunch } from "./handover";
+import { addWorkspace, assertBranchReady, assertRepository, branchCommit, branchExists, commitExists, isAncestor, rollbackWorkspace, vcsMode } from "./vcs";
 
 const lifecycleConventionPath = "conventions/atdd-workflow.workflow/atdd-workflow.workflow.lifecycle.convention.yaml";
 
@@ -72,11 +73,11 @@ 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>]`.";
+const configureUsage = "Use `atdd-flow project configure <project> [--vcs <git|jj>] [--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.
+ * The supported way to declare an existing project's VCS, primary checkout, and linked-worktree root.
+ * Everything is validated before one atomic write; no seat, task, runtime, branch/bookmark, or workspace is mutated.
  */
 type MigrationSeat = { folder: string; record: Seat };
 
@@ -179,18 +180,27 @@ export async function configureProject(root: string, name: string, args: string[
   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);
+    if (!["--vcs", "--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 selectedVcs = values.get("--vcs");
+  if (selectedVcs && selectedVcs !== "git" && selectedVcs !== "jj") throw new Error(configureUsage);
+  const currentMode = vcsMode(config);
+  const mode = (selectedVcs ?? currentMode) as "git" | "jj";
+  if (selectedVcs && selectedVcs !== currentMode && (await migrationSeats(root, config)).length) {
+    throw new Error(`Project VCS cannot change from ${currentMode} to ${selectedVcs} after seats exist.`);
+  }
   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;
+  const configuredRepository = repository ?? config.repository;
+  if (selectedVcs && !configuredRepository) throw new Error("Project repository is required before selecting a VCS.");
+  const repositoryPath = configuredRepository ? resolve(configuredRepository) : undefined;
+  if (repositoryPath && (repository || selectedVcs)) {
+    try { await assertRepository(mode, repositoryPath); }
+    catch (error) { throw new Error((error as Error).message); }
+    config.repository = repositoryPath;
   }
+  if (selectedVcs) config.vcs = mode;
   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}`);
@@ -200,18 +210,13 @@ export async function configureProject(root: string, name: string, args: string[
 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 });
-  const ref = `refs/heads/${branch}`;
-  const probe = Bun.spawn(["git", "-C", config.repository, "show-ref", "--verify", "--quiet", ref]);
-  const branchExists = await probe.exited === 0;
-  const command = branchExists
-    ? ["git", "-C", config.repository, "worktree", "add", worktree, branch]
-    : ["git", "-C", config.repository, "worktree", "add", "-b", branch, worktree, role.base ?? "HEAD"];
-  await run(command, true);
+  await addWorkspace(vcsMode(config), config.repository, worktree, branch, role.base ?? "HEAD");
 }
 
 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.`);
+  if (await branchExists(vcsMode(config), required(config.repository, "project repository"), branch)) {
+    throw new Error(`Driver branch ${branch} already exists; refusing to reuse it.`);
+  }
 }
 
 async function taskCoordinatorBase(root: string, config: Project, task: Task, requireCleanCheckout = true) {
@@ -236,16 +241,19 @@ async function taskCoordinatorBase(root: string, config: Project, task: Task, re
     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]);
+  const mode = vcsMode(config);
+  const branchHead = await branchCommit(mode, coordinator.worktree, 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.`);
+  if (mode === "git") {
+    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"]);
+    if (head !== branchHead) throw new Error(`Coordinator ${coordinator.address} head is stale relative to ${branch}.`);
+  } else {
+    try { await assertBranchReady(mode, coordinator.worktree, branch); }
+    catch (error) { throw new Error(`Coordinator ${coordinator.address} is not ready: ${(error as Error).message}`); }
   }
-  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"]);
-  if (head !== branchHead) throw new Error(`Coordinator ${coordinator.address} head is stale relative to ${branch}.`);
   return { coordinator, branch, commit: branchHead };
 }
 
@@ -288,10 +296,9 @@ async function spawnTaskDriver(root: string, config: Project, role: Role, name:
   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}.`); }
+    const repository = required(config.repository, "project repository");
+    if (!await commitExists(repository, baseArgument)) throw new Error(`Explicit base ${baseArgument} does not exist locally in the configured repository.`);
+    if (!await isAncestor(repository, coordinatorBase.commit, baseArgument)) throw new Error(`Explicit base ${baseArgument} does not descend ${coordinatorBase.branch}.`);
     base = { ...coordinatorBase, commit: baseArgument };
   }
   if (dryRun) {
@@ -311,23 +318,22 @@ async function spawnTaskDriver(root: string, config: Project, role: Role, name:
   task.assignee = address;
   task.governed_base = { coordinator: base.coordinator.address, branch: base.branch, commit: base.commit };
   let created = false;
+  const mode = vcsMode(config);
+  const repository = required(config.repository, "project repository");
   try {
     await mkdir(dirname(worktree), { recursive: true });
-    await run(["git", "-C", required(config.repository, "project repository"), "worktree", "add", "-b", branch, worktree, base.commit], true);
+    await addWorkspace(mode, repository, worktree, branch, base.commit);
     created = true;
-    const currentBranch = await runOutput(["git", "-C", required(config.repository, "project repository"), "rev-parse", coordinatorBase.branch]);
+    const currentBranch = await branchCommit(mode, base.coordinator.worktree, 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"]);
+      const current = await assertBranchReady(mode, base.coordinator.worktree, coordinatorBase.branch);
       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);
-      await run(["git", "-C", required(config.repository, "project repository"), "branch", "-D", branch], true).catch(() => undefined);
-    }
+    if (created) await rollbackWorkspace(mode, repository, worktree, branch);
     await rm(paths(root).seat(address), { recursive: true, force: true });
     throw error;
   }

package/src/tasks.ts

@@ -3,6 +3,7 @@ import { basename, dirname, join, resolve } from "node:path";
 import {
   type Checkpoint, type Seat, atomicYaml, canonicalAddress, exists, now, paths, project, readYaml, required, runOutput, seat, taskId, values, words,
 } from "./core";
+import { branchCommit, currentCommit, isAncestor, vcsMode, type VcsMode } from "./vcs";
 
 export type TaskStatus = "todo" | "in_progress" | "review" | "done" | "superseded" | "rejected";
 /** An optional, descriptive implementation phase; task status remains the lifecycle authority. */
@@ -124,15 +125,18 @@ async function governedBase(root: string, projectName: string, coordinatorAddres
 }
 
 /** The recorded branch when it resolves; otherwise the driver worktree HEAD; otherwise fail closed. */
-async function driverLineageRef(driver: Seat): Promise<LineageRef> {
-  const resolveRef = (ref: string) => runOutput(["git", "-C", driver.worktree, "rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
-  try { return { ref: driver.branch, commit: await resolveRef(driver.branch) }; }
+async function driverLineageRef(mode: VcsMode, driver: Seat): Promise<LineageRef> {
+  try { return { ref: driver.branch, commit: await branchCommit(mode, driver.worktree, driver.branch) }; }
   catch {
     if (!await exists(driver.worktree)) {
       throw new Error(`Driver ${driver.address} branch ${driver.branch} no longer resolves and its worktree ${driver.worktree} is missing; cannot verify lineage.`);
     }
-    try { return { ref: "HEAD", commit: await resolveRef("HEAD"), reason: `recorded branch ${driver.branch} no longer resolves; used worktree HEAD` }; }
-    catch { throw new Error(`Driver ${driver.address} branch ${driver.branch} no longer resolves and worktree ${driver.worktree} has no valid HEAD.`); }
+    try {
+      const commit = await currentCommit(mode, driver.worktree);
+      return { ref: mode === "git" ? "HEAD" : "@", commit, reason: `recorded branch ${driver.branch} no longer resolves; used worktree ${mode === "git" ? "HEAD" : "@"}` };
+    } catch {
+      throw new Error(`Driver ${driver.address} branch ${driver.branch} no longer resolves and worktree ${driver.worktree} has no valid current revision.`);
+    }
   }
 }
 
@@ -165,10 +169,10 @@ async function governedLineage(root: string, projectName: string, coordinatorAdd
   } 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 lineage = await driverLineageRef(driver);
-  const common = await runOutput(["git", "-C", driver.worktree, "merge-base", commit, lineage.commit]);
-  if (common !== commit) throw new Error(`Driver ${driver.address} is not based on the exact coordinator head ${commit}.`);
+  const mode = vcsMode(config);
+  const commit = await branchCommit(mode, coordinator.worktree, branch);
+  const lineage = await driverLineageRef(mode, driver);
+  if (!await isAncestor(driver.worktree, commit, lineage.commit)) throw new Error(`Driver ${driver.address} is not based on the exact coordinator head ${commit}.`);
   return { base: { coordinator: coordinator.address, branch, commit }, lineage };
 }
 
@@ -248,7 +252,7 @@ async function retireDriver(root: string, projectName: string, assignee: string,
   if (owner.retired) throw new Error(`Seat ${assignee} is already retired.`);
   try {
     const summary = (allowAbsentWorktree ? await absentUnregisteredWorktree(root, projectName, owner) : undefined)
-      ?? await runOutput([...await retirementBun(root, projectName), "worktree", "finish", "--delete-branch"], owner.worktree);
+      ?? await runOutput([...await retirementBun(root, projectName), "worktree", "finish", "--delete-branch", "--vcs", vcsMode(await project(root, projectName))], owner.worktree);
     owner.retired = { task: `${projectName}/${id}`, completed_at: now(), summary };
     await atomicYaml(paths(root).seatFile(assignee), owner);
     const checkpoint: Checkpoint = {

package/src/vcs.ts

@@ -0,0 +1,186 @@
+// URN: component:flow:jj-vcs:vcs:backend:application
+// Tested-By:
+// - test:flow:jj-vcs:E011-UNIT-001
+// Runtime: bun
+// Purpose: Provide the narrow Git/Jujutsu repository capability used by Flow.
+//
+// VCS selection is deliberately project-scoped: one Desk may coordinate Git and
+// Jujutsu repositories at the same time. The durable Flow model keeps calling
+// the delivery reference a branch; in JJ mode that reference is a bookmark.
+//
+// JJ support is intentionally colocated-only. Git remains the interchange layer
+// for exact commit ancestry and remote-compatible refs, while JJ owns working
+// copies, workspace creation, and bookmark movement. This keeps the capability
+// additive and preserves existing Git review and publication assumptions.
+//
+// A JJ working copy is itself a commit. An untouched workspace may therefore sit
+// on an empty @ child whose parent is the governed bookmark. That is equivalent
+// to a clean Git checkout for readiness checks; a non-empty @ is real work and
+// must move the delivery bookmark before it can be considered ready.
+//
+// These helpers contain the VCS-specific mechanics so seats, tasks, and reviews
+// keep their existing responsibilities instead of growing parallel Git/JJ paths.
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+import type { Project } from "./core";
+import { run, runOutput } from "./core";
+
+export type VcsMode = "git" | "jj";
+
+export function vcsMode(config: Pick<Project, "vcs">): VcsMode {
+  const mode = config.vcs ?? "git";
+  if (mode !== "git" && mode !== "jj") throw new Error(`Unsupported project VCS: ${String(mode)}`);
+  return mode;
+}
+
+export function workspaceName(branch: string) {
+  return branch.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+async function jjVersion(cwd: string) {
+  const output = await runOutput(["jj", "version"], cwd);
+  const match = output.match(/\b(\d+)\.(\d+)\.(\d+)\b/);
+  if (!match) throw new Error(`Unable to parse Jujutsu version from: ${output}`);
+  const [, major, minor] = match.map(Number);
+  if (major === 0 && minor < 46) throw new Error(`Jujutsu 0.46.0 or newer is required; found ${match[0]}.`);
+}
+
+export async function assertRepository(mode: VcsMode, path: string) {
+  const requested = resolve(path);
+  if (mode === "git") {
+    try {
+      const expected = await realpath(requested);
+      const top = await realpath(await runOutput(["git", "-C", expected, "rev-parse", "--show-toplevel"]));
+      if (top === expected) return;
+    } catch { /* Preserve the established configuration diagnostic below. */ }
+    throw new Error(`${requested} is not the top level of a Git repository.`);
+  }
+  let expected: string;
+  try { expected = await realpath(requested); }
+  catch { throw new Error(`${requested} is not the top level of a Jujutsu repository.`); }
+  await jjVersion(expected);
+  const top = await realpath(await runOutput(["jj", "root"], expected));
+  if (top !== expected) throw new Error(`${expected} is not the top level of a Jujutsu repository.`);
+  // Colocation must be concrete, not inferred from a successful JJ command:
+  // the same directory must also be the Git top level used for shared refs.
+  const gitTop = await realpath(await runOutput(["git", "-C", expected, "rev-parse", "--show-toplevel"]));
+  if (gitTop !== expected) throw new Error(`${expected} is not a colocated Git-backed Jujutsu repository.`);
+  await runOutput(["jj", "git", "colocation", "status"], expected);
+}
+
+export async function snapshot(mode: VcsMode, cwd: string) {
+  if (mode === "jj") await runOutput(["jj", "status"], cwd);
+}
+
+export async function branchCommit(mode: VcsMode, cwd: string, branch: string) {
+  if (mode === "git") return runOutput(["git", "-C", cwd, "rev-parse", branch]);
+  await snapshot(mode, cwd);
+  return runOutput(["jj", "log", "-r", branch, "--no-graph", "-T", "commit_id"], cwd);
+}
+
+export async function currentCommit(mode: VcsMode, cwd: string) {
+  if (mode === "git") return runOutput(["git", "-C", cwd, "rev-parse", "HEAD"]);
+  await snapshot(mode, cwd);
+  return runOutput(["jj", "log", "-r", "@", "--no-graph", "-T", "commit_id"], cwd);
+}
+
+export async function branchExists(mode: VcsMode, cwd: string, branch: string) {
+  if (mode === "git") {
+    try { await runOutput(["git", "-C", cwd, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]); return true; }
+    catch { return false; }
+  }
+  try { await branchCommit(mode, cwd, branch); return true; }
+  catch { return false; }
+}
+
+export async function commitExists(cwd: string, commit: string) {
+  try { await runOutput(["git", "-C", cwd, "cat-file", "-e", `${commit}^{commit}`]); return true; }
+  catch { return false; }
+}
+
+export async function isAncestor(cwd: string, ancestor: string, descendant: string) {
+  try { await run(["git", "-C", cwd, "merge-base", "--is-ancestor", ancestor, descendant], true); return true; }
+  catch { return false; }
+}
+
+export async function assertBranchReady(mode: VcsMode, cwd: string, branch: string) {
+  if (mode === "git") {
+    if (await runOutput(["git", "-C", cwd, "status", "--porcelain"])) throw new Error(`Worktree ${cwd} is dirty.`);
+    const checkedOut = await runOutput(["git", "-C", cwd, "branch", "--show-current"]);
+    if (checkedOut !== branch) throw new Error(`Worktree ${cwd} is not checked out at ${branch}.`);
+  } else {
+    await snapshot(mode, cwd);
+    const conflicts = await runOutput(["jj", "log", "-r", "@ & conflicts()", "--no-graph", "-T", "commit_id"], cwd);
+    if (conflicts) throw new Error(`Jujutsu workspace ${cwd} has unresolved conflicts.`);
+  }
+  const [current, expected] = await Promise.all([currentCommit(mode, cwd), branchCommit(mode, cwd, branch)]);
+  if (current === expected) return expected;
+  if (mode === "jj") {
+    const [parent, changed] = await Promise.all([
+      runOutput(["jj", "log", "-r", "@-", "--no-graph", "-T", "commit_id"], cwd),
+      runOutput(["jj", "diff", "-r", "@", "--name-only"], cwd),
+    ]);
+    if (parent === expected && !changed) return expected;
+  }
+  throw new Error(`Worktree ${cwd} is stale relative to ${branch}.`);
+}
+
+export async function addWorkspace(mode: VcsMode, repository: string, worktree: string, branch: string, base: string) {
+  if (mode === "git") {
+    const exists = await branchExists(mode, repository, branch);
+    await run(exists
+      ? ["git", "-C", repository, "worktree", "add", worktree, branch]
+      : ["git", "-C", repository, "worktree", "add", "-b", branch, worktree, base], true);
+    return;
+  }
+  if (await branchExists(mode, repository, branch)) {
+    await run(["jj", "workspace", "add", "--colocate", "--name", workspaceName(branch), "-r", branch, worktree], true, repository);
+  } else {
+    await run(["jj", "workspace", "add", "--colocate", "--name", workspaceName(branch), "-r", base, worktree], true, repository);
+    await run(["jj", "bookmark", "set", branch, "-r", "@"], true, worktree);
+  }
+  await assertBranchReady(mode, worktree, branch);
+}
+
+export async function rollbackWorkspace(mode: VcsMode, repository: string, worktree: string, branch: string) {
+  if (mode === "git") {
+    await run(["git", "-C", repository, "worktree", "remove", "--force", worktree], true).catch(() => undefined);
+    await run(["git", "-C", repository, "branch", "-D", branch], true).catch(() => undefined);
+    return;
+  }
+  await run(["jj", "workspace", "remove", workspaceName(branch)], true, repository).catch(() => undefined);
+  await run(["jj", "bookmark", "delete", branch], true, repository).catch(() => undefined);
+}
+
+export async function changedFiles(mode: VcsMode, worktree: string, base: string) {
+  if (mode === "jj") {
+    await snapshot(mode, worktree);
+    const output = await runOutput(["jj", "diff", "--name-only", "--from", base, "--to", "@"], worktree);
+    return output.split("\n").map(entry => entry.trim()).filter(Boolean).slice(0, 200);
+  }
+  const outputs = await Promise.allSettled([
+    runOutput(["git", "diff", "--name-only", `${base}...HEAD`], worktree),
+    runOutput(["git", "diff", "--name-only"], worktree),
+    runOutput(["git", "diff", "--name-only", "--cached"], worktree),
+    runOutput(["git", "ls-files", "--others", "--exclude-standard"], worktree),
+  ]);
+  return [...new Set(outputs.flatMap(output => output.status === "fulfilled"
+    ? output.value.split("\n").map(entry => entry.trim()).filter(Boolean)
+    : []
+  ))].slice(0, 200);
+}
+
+export async function planArtifacts(mode: VcsMode, worktree: string) {
+  try {
+    const output = mode === "git"
+      ? await runOutput(["git", "ls-files", "plan"], worktree)
+      : await runOutput(["jj", "file", "list", "plan"], worktree);
+    return output.split("\n").map(entry => entry.trim()).filter(entry => entry.endsWith(".yaml")).slice(0, 400);
+  } catch {
+    return [];
+  }
+}
+
+export function diffCommand(mode: VcsMode, base: string) {
+  return mode === "git" ? `git diff ${base}...HEAD` : `jj diff --from ${base} --to @`;
+}