@afokapu/atdd-flow 0.3.61 → 0.3.63

package/package.json

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

package/src/cli.ts

@@ -30,7 +30,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]

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/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. */
@@ -13,6 +14,7 @@ export type HandoffState = "executing" | "awaiting_coordinator" | "awaiting_assi
 export type TaskHandoff = { state: HandoffState; evidence: string; updated_at: string; submitted_phase?: TaskPhase };
 export type DoneWhen = { text: string; proof?: string };
 export type GovernedBase = { coordinator: string; branch: string; commit: string };
+export type LineageRef = { ref: string; commit: string; reason?: string };
 /** An append-only accountability decision; prior coordinator evidence remains untouched. */
 export type CoordinatorTransfer = {
   from: string;
@@ -21,6 +23,8 @@ export type CoordinatorTransfer = {
   /** Required when main executes the transfer; references an operator@desk message. */
   authorization?: string;
   exact_head: { branch: string; commit: string };
+  /** The driver ref used for the lineage check; HEAD means the recorded branch no longer resolved. */
+  lineage_ref?: LineageRef;
   effective_at: string;
 };
 export type TerminalDisposition = { kind: "superseded" | "rejected"; by: string; at: string; reason: string };
@@ -117,6 +121,26 @@ async function writeTask(root: string, projectName: string, id: string, task: Ta
 
 /** 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> {
+  return (await governedLineage(root, projectName, coordinatorAddress, assignee))?.base;
+}
+
+/** The recorded branch when it resolves; otherwise the driver worktree HEAD; otherwise fail closed. */
+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 {
+      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.`);
+    }
+  }
+}
+
+async function governedLineage(root: string, projectName: string, coordinatorAddress: string, assignee?: string): Promise<{ base: GovernedBase; lineage: LineageRef } | undefined> {
   if (!assignee) return undefined;
   const config = await project(root, projectName);
   if (!config.repository) return undefined;
@@ -145,10 +169,11 @@ async function governedBase(root: string, projectName: string, coordinatorAddres
   } 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 };
+  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 };
 }
 
 /**
@@ -227,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 = {
@@ -390,8 +415,9 @@ export async function transfer(root: string, projectName: string, id: string, ar
 
   // governedBase confirms main/named-coordinator identity, exact branch head,
   // and the driver's descendant relationship before accountability changes.
-  const base = await governedBase(root, projectName, target, task.assignee);
-  if (!base) throw new Error(`Task ${id} needs an assigned driver and governed repository before transfer.`);
+  const governed = await governedLineage(root, projectName, target, task.assignee);
+  const base = governed?.base;
+  if (!governed || !base) throw new Error(`Task ${id} needs an assigned driver and governed repository before transfer.`);
   const authorization = actor === main ? required(words(args, "--authorization"), "an owner-authorized topology plan") : undefined;
   if (authorization) await operatorAuthorization(root, authorization, main, {
     schema: "atdd-workflow/task-transfer-authorization/v1",
@@ -408,6 +434,7 @@ export async function transfer(root: string, projectName: string, id: string, ar
     reason: required(words(args, "--reason"), "--reason"),
     ...(authorization ? { authorization } : {}),
     exact_head: { branch: base.branch, commit: base.commit },
+    lineage_ref: governed.lineage,
     effective_at: now(),
   };
   task.coordinator = target;

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 @`;
+}