@afokapu/atdd-flow 0.3.65 → 0.3.67

package/README.md

@@ -130,7 +130,7 @@ atdd-flow task review example-app runtime-rollout --by driver.runtime@example-ap
 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. A driver whose assigned tasks are all already `done` is retired with `atdd-flow seat retire <address> --by <coordinator-or-main>`, using the same checks. When every assigned task is `done` and the recorded worktree is absent from disk and from `git worktree list`, `seat retire` records the retirement without running worktree finish, deleting the branch, or recreating the worktree; a missing worktree that Git still registers fails closed. Both paths fail closed on unfinished tasks or a dirty or unmerged worktree; on success they record `retired` and a checkpoint, then close the driver's Herdr workspace when `close_inactive` is enabled. `main@<project>` may likewise retire a coordinator seat (never main, the operator, or a seat on the primary checkout) once every task it coordinates or is assigned is `done`, through the same worktree-finish, absent-and-unregistered, and fail-closed paths. Retirement runs in the seat worktree with ATDD Bun from the primary checkout's `node_modules/.bin`, else the primary checkout's own source when it is the ATDD Bun package, else `PATH`; never the seat worktree's copy, which may pin an older toolkit.
+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. A driver whose assigned tasks are all already `done` is retired with `atdd-flow seat retire <address> --by <coordinator-or-main>`, using the same checks. When every assigned task is `done` and the recorded worktree is absent from disk and from `git worktree list`, `seat retire` records the retirement without running worktree finish, deleting the branch, or recreating the worktree; a missing worktree that Git still registers fails closed. Both paths fail closed on unfinished tasks or a dirty or unmerged worktree; on success they record `retired` and a checkpoint, then close the driver's Herdr workspace when `close_inactive` is enabled. `main@<project>` may likewise retire a coordinator seat (never main or the operator) once every task it coordinates or is assigned is `done`. A non-main coordinator sharing the primary checkout is retired as a Desk record without worktree finish; other coordinators use the same worktree-finish, absent-and-unregistered, and fail-closed paths. Retirement runs in the seat worktree with ATDD Bun from the primary checkout's `node_modules/.bin`, else the primary checkout's own source when it is the ATDD Bun package, else `PATH`; never the seat worktree's copy, which may pin an older toolkit.
 
 At 80% context usage a seat writes a structured handover (template and process rules in the lifecycle convention), checks it with `atdd-flow handover <address> --check --file <path>`, and records it with `atdd-flow handover <address> --file <path>`. The seat keeps one durable `handover.yaml` beside its unchanged checkpoint. Recording rejects a missing header, Runtime line, or section, sections out of order, more than 150 lines, vague references such as `latest` or `that PR` without an exact ID, and a `supersedes` value that does not match the recorded handover id. A fresh session bound to the same seat reads it with `atdd-flow handover show <address>`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.65",
+  "version": "0.3.67",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {
@@ -41,7 +41,7 @@
     "bun": ">=1.3.0"
   },
   "devDependencies": {
-    "@afokapu/atdd-bun": "0.10.89"
+    "@afokapu/atdd-bun": "0.10.101"
   },
   "dependencies": {
     "@typesafe-ai/sdk": "^0.6.0",

package/src/cli.ts

@@ -33,7 +33,7 @@ Usage:
   atdd-flow desk migrate
   atdd-flow project init <project>
   atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]
-  atdd-flow project migrate-vcs <project> --to jj [--dry-run]
+  atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary] [--dry-run]
   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]
@@ -111,7 +111,7 @@ async function main() {
       if (rest[0] === "configure") return configureProject(root, required(rest[1], "project"), rest.slice(2));
       if (rest[0] === "migrate-vcs") return migrateProjectVcs(root, required(rest[1], "project"), rest.slice(2));
       if (rest[0] === "migrate-named-coordinator-topology") return migrateNamedCoordinatorTopology(root, required(rest[1], "project"), rest.slice(2));
-      throw new Error("Use `atdd-flow project init <project>`, `atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]`, `atdd-flow project migrate-vcs <project> --to jj [--dry-run]`, or `atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>`.");
+      throw new Error("Use `atdd-flow project init <project>`, `atdd-flow project configure <project> [--vcs <git|jj>] [--repository <primary-checkout>] [--worktree-root <directory>]`, `atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary] [--dry-run]`, or `atdd-flow project migrate-named-coordinator-topology <project> --baseline <40-lowercase-hex-remote-main-sha>`.");
     },
     spawn: () => spawn(root, required(rest[0], "project"), required(rest[1], "role"), required(rest[2], "name"), rest.slice(3)),
     bind: () => bind(root, required(rest[0], "address"), rest.slice(1)),

package/src/tasks.ts

@@ -242,7 +242,7 @@ async function retirementBun(root: string, projectName: string) {
   return [required(Bun.which("atdd-bun") ?? undefined, "atdd-bun in the primary checkout node_modules/.bin or on PATH")];
 }
 
-async function retireDriver(root: string, projectName: string, assignee: string, id: string, allowAbsentWorktree = false) {
+async function retireDriver(root: string, projectName: string, assignee: string, id: string, allowAbsentWorktree = false, allowPrimaryCheckout = false) {
   const unfinished = (await allTasks(root, projectName))
     .filter((entry) => entry.id !== id && (entry.task.assignee === assignee || entry.task.coordinator === assignee) && !terminal(entry.task))
     .map((entry) => entry.id);
@@ -251,7 +251,10 @@ async function retireDriver(root: string, projectName: string, assignee: string,
   const owner = await seat(root, assignee);
   if (owner.retired) throw new Error(`Seat ${assignee} is already retired.`);
   try {
-    const summary = (allowAbsentWorktree ? await absentUnregisteredWorktree(root, projectName, owner) : undefined)
+    const primary = (await project(root, projectName)).repository;
+    const primaryCheckout = allowPrimaryCheckout && primary && await canonicalPath(owner.worktree) === await canonicalPath(primary);
+    const summary = (primaryCheckout ? `Primary checkout ${owner.worktree} retained; retired without worktree finish.` : undefined)
+      ?? (allowAbsentWorktree ? await absentUnregisteredWorktree(root, projectName, owner) : undefined)
       ?? 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);
@@ -276,18 +279,11 @@ async function retireDriver(root: string, projectName: string, assignee: string,
   await closeRetiredDriverWorkspace(root, owner);
 }
 
-/**
- * Only main retires a coordinator, and never one seated on the primary checkout; a driver may also be
- * retired by the coordinator of every task assigned to it.
- */
+/** Only main retires a coordinator; a driver may also be retired by the coordinator of every task assigned to it. */
 async function assertRetireAuthority(root: string, owner: Seat, actor: string, owned: ListedTask[]) {
   const main = `main@${owner.project}`;
   if (owner.role === "coordinator") {
     if (actor !== main) throw new Error(`Only ${main} may retire coordinator ${owner.address}.`);
-    const primary = (await project(root, owner.project)).repository;
-    if (primary && await canonicalPath(owner.worktree) === await canonicalPath(primary)) {
-      throw new Error(`Cannot retire ${owner.address}; its worktree is the primary checkout.`);
-    }
   } else if (actor !== main && owned.some((entry) => entry.task.coordinator !== actor)) {
     throw new Error(`Only ${main} or the coordinator of every task assigned to ${owner.address} may retire it.`);
   }
@@ -295,7 +291,8 @@ async function assertRetireAuthority(root: string, owner: Seat, actor: string, o
 
 /**
  * Retires a driver whose assigned tasks are all terminal (done, superseded, or rejected), or, for main only, a coordinator
- * (never main or the primary checkout) whose coordinated and assigned tasks are all terminal.
+ * (never main) whose coordinated and assigned tasks are all terminal. A non-main coordinator on the
+ * primary checkout retires its record without invoking worktree finish.
  */
 export async function retireSeat(root: string, address: string, args: string[]) {
   const resolved = await canonicalAddress(root, address);
@@ -310,7 +307,7 @@ export async function retireSeat(root: string, address: string, args: string[])
   const unfinished = owned.filter((entry) => !terminal(entry.task)).map((entry) => entry.id);
   if (unfinished.length) throw new Error(`Cannot retire ${resolved}; it still owns unfinished tasks: ${unfinished.join(", ")}.`);
   await assertRetireAuthority(root, owner, actor, owned);
-  await retireDriver(root, owner.project, resolved, owned.at(-1)!.id, true);
+  await retireDriver(root, owner.project, resolved, owned.at(-1)!.id, true, coordinator && resolved !== `main@${owner.project}`);
   console.log(`${resolved}  retired`);
 }
 

package/src/vcs-migration.ts

@@ -1,6 +1,7 @@
 // URN: component:flow:jj-vcs-migration:vcs-migration:backend:application
 // Tested-By:
 // - test:flow:jj-vcs-migration:E013-UNIT-001
+// - test:flow:jj-vcs-migration:E014-UNIT-001
 // Runtime: bun
 // Purpose: Migrate one legacy Flow Git project to colocated JJ without losing lineage.
 //
@@ -19,8 +20,9 @@
 // Rollback uses the captured branch, commit, and path tuple rather than inferring
 // state from a partial JJ conversion. The durable project VCS is written last.
 
-import { readdir, realpath, rm } from "node:fs/promises";
+import { lstat, readFile, readdir, readlink, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
 import {
   type Project, type Seat, atomicYaml, exists, paths, project, readYaml, required, yaml,
 } from "./core";
@@ -32,6 +34,16 @@ type GitWorktree = { path: string; branch?: string };
 type TaskLite = { assignee?: string; status?: string; governed_base?: { commit?: string } };
 type ReviewsLite = { attempts?: Array<{ delivery_head?: string }> };
 
+/** JJ silently skips new files above this size (snapshot.max-new-file-size default). */
+const SNAPSHOT_MAX_NEW_FILE_BYTES = 1048576;
+const DIRTY_PRIMARY_FLAG = "--allow-dirty-primary";
+
+type DiskState =
+  | { kind: "absent" }
+  | { kind: "file"; sha256: string; exec: boolean }
+  | { kind: "symlink"; target: string };
+type DirtyEntry = { path: string; status: string; disk: DiskState };
+
 export type VcsMigrationPlan = {
   schema: "atdd-flow/vcs-migration-plan/v1";
   project: string;
@@ -40,6 +52,7 @@ export type VcsMigrationPlan = {
   primary: SeatState;
   workspaces: SeatState[];
   lineage: { tasks_checked: number; reviews_checked: number };
+  dirty_primary?: { entries: Array<{ path: string; status: string }> };
 };
 
 type PreparedMigration = {
@@ -47,6 +60,8 @@ type PreparedMigration = {
   repository: string;
   states: SeatState[];
   plan: VcsMigrationPlan;
+  dirty: DirtyEntry[];
+  index: Buffer | null;
 };
 
 /** Run one external VCS command without throwing so rollback can inspect failures. */
@@ -97,19 +112,58 @@ async function activeSeats(root: string, name: string) {
   return records.filter(record => !record.retired);
 }
 
+/** Read one working-copy path exactly as JJ will snapshot it, without following symlinks. */
+async function diskState(worktree: string, path: string): Promise<DiskState> {
+  const full = join(worktree, path);
+  const info = await lstat(full).catch(() => null);
+  if (!info) return { kind: "absent" };
+  if (info.isSymbolicLink()) return { kind: "symlink", target: await readlink(full) };
+  if (info.isDirectory()) throw new Error(`Dirty primary path ${path} is a nested repository or gitlink; JJ cannot retain it.`);
+  const sha256 = createHash("sha256").update(await readFile(full)).digest("hex");
+  return { kind: "file", sha256, exec: (info.mode & 0o111) !== 0 };
+}
+
+/** Capture the primary's uncommitted paths read-only, refusing anything JJ would drop. */
+async function captureDirtyPrimary(worktree: string): Promise<DirtyEntry[]> {
+  // Raw, untrimmed: the first record's leading status space is significant.
+  const status = await Bun.spawn(["git", "status", "--porcelain=v1", "-z", "--untracked-files=all", "--no-renames"], { cwd: worktree, stdout: "pipe", stderr: "pipe" });
+  const [raw, failure, code] = await Promise.all([new Response(status.stdout).text(), new Response(status.stderr).text(), status.exited]);
+  if (code !== 0) throw new Error(`git status failed: ${failure.trim()}`);
+  const entries: DirtyEntry[] = [];
+  for (const record of raw.split("\0").filter(Boolean)) {
+    const flags = record.slice(0, 2), path = record.slice(3);
+    const disk = await diskState(worktree, path);
+    const isNew = flags.includes("?") || flags.includes("A");
+    if (isNew && disk.kind === "file") {
+      const size = (await lstat(join(worktree, path))).size;
+      if (size > SNAPSHOT_MAX_NEW_FILE_BYTES) {
+        throw new Error(`Dirty primary file ${path} (${size} bytes) exceeds the JJ snapshot size limit of ${SNAPSHOT_MAX_NEW_FILE_BYTES} bytes and would not be retained; commit it, move it, or ignore it first.`);
+      }
+    }
+    entries.push({ path, status: flags, disk });
+  }
+  return entries;
+}
+
 /** Capture the exact clean Git tuple that migration must preserve or parent. */
-async function inspectSeat(repository: string, record: Seat): Promise<SeatState> {
+async function inspectSeat(repository: string, record: Seat, allowDirtyPrimary: boolean): Promise<{ state: SeatState; dirty: DirtyEntry[] }> {
   const worktree = await realpath(resolve(record.worktree)).catch(() => null);
   if (!worktree) throw new Error(`Seat ${record.address} worktree does not exist: ${record.worktree}`);
   const top = await realpath(await output(worktree, "git", ["rev-parse", "--show-toplevel"]));
   if (top !== worktree) throw new Error(`Seat ${record.address} is not at a Git worktree root: ${worktree}`);
-  if (await output(worktree, "git", ["status", "--porcelain"])) throw new Error(`Seat ${record.address} worktree is dirty: ${worktree}`);
+  const primary = worktree === repository;
+  let dirty: DirtyEntry[] = [];
+  if (await output(worktree, "git", ["status", "--porcelain"])) {
+    if (!primary) throw new Error(`Seat ${record.address} worktree is dirty: ${worktree}`);
+    if (!allowDirtyPrimary) throw new Error(`Seat ${record.address} worktree is dirty: ${worktree}. Pass ${DIRTY_PRIMARY_FLAG} to retain the primary checkout's uncommitted changes as JJ working-copy state.`);
+    dirty = await captureDirtyPrimary(worktree);
+  }
   const branch = await output(worktree, "git", ["branch", "--show-current"]);
   if (branch !== record.branch) throw new Error(`Seat ${record.address} is checked out at ${branch || "detached HEAD"}, not ${record.branch}.`);
   const commit = await output(worktree, "git", ["rev-parse", "HEAD"]);
   const ref = await output(repository, "git", ["rev-parse", "--verify", `refs/heads/${record.branch}^{commit}`]);
   if (commit !== ref) throw new Error(`Seat ${record.address} HEAD does not match branch ${record.branch}.`);
-  return { address: record.address, branch: record.branch, worktree, commit, primary: worktree === repository };
+  return { state: { address: record.address, branch: record.branch, worktree, commit, primary }, dirty };
 }
 
 /** Parse Git's porcelain registry rather than trusting directory existence alone. */
@@ -195,7 +249,7 @@ async function assertLineage(root: string, name: string, repository: string, sta
 }
 
 /** Build the complete deterministic migration plan before creating .jj metadata. */
-async function prepare(root: string, name: string): Promise<PreparedMigration> {
+async function prepare(root: string, name: string, allowDirtyPrimary: boolean): Promise<PreparedMigration> {
   const config = await project(root, name);
   if (vcsMode(config) !== "git") throw new Error(`Project ${name} is not a Git project.`);
   const repository = await realpath(resolve(required(config.repository, `project ${name} repository`))).catch(() => null);
@@ -205,7 +259,9 @@ async function prepare(root: string, name: string): Promise<PreparedMigration> {
   await assertToolVersions(repository);
   const records = await activeSeats(root, name);
   if (!records.length) throw new Error("Project has no active seats; configure vcs: jj directly before creating seats.");
-  const states = await Promise.all(records.map(record => inspectSeat(repository, record)));
+  const inspected = await Promise.all(records.map(record => inspectSeat(repository, record, allowDirtyPrimary)));
+  const states = inspected.map(entry => entry.state);
+  const dirty = inspected.flatMap(entry => entry.dirty);
   const primary = states.filter(state => state.primary);
   if (primary.length !== 1) throw new Error(`Migration requires exactly one active seat in the primary checkout; found ${primary.length}.`);
   if (new Set(states.map(state => state.worktree)).size !== states.length) throw new Error("Active Flow seats must have distinct worktree paths before migration.");
@@ -213,15 +269,61 @@ async function prepare(root: string, name: string): Promise<PreparedMigration> {
   await assertWorktreeRegistry(repository, states);
   const lineage = await assertLineage(root, name, repository, states);
   const workspaces = states.filter(state => !state.primary);
-  return { config, repository, states, plan: { schema: "atdd-flow/vcs-migration-plan/v1", project: name, from: "git", to: "jj", primary: primary[0]!, workspaces, lineage } };
+  const index = await readIndex(repository);
+  const plan: VcsMigrationPlan = { schema: "atdd-flow/vcs-migration-plan/v1", project: name, from: "git", to: "jj", primary: primary[0]!, workspaces, lineage };
+  if (dirty.length) plan.dirty_primary = { entries: dirty.map(({ path, status }) => ({ path, status })) };
+  return { config, repository, states, plan, dirty, index };
 }
 
 /** The primary bookmark is intentionally not advanced during migration. */
-async function verifyPrimary(state: SeatState) {
+async function verifyPrimary(state: SeatState, dirty: DirtyEntry[]) {
+  if (dirty.length) return verifyDirtyPrimary(state, dirty);
   const ready = await assertBranchReady("jj", state.worktree, state.branch);
   if (ready !== state.commit) throw new Error(`Primary bookmark ${state.branch} changed during JJ migration.`);
 }
 
+/** Read the Git tree entry for one path in the JJ working-copy commit. */
+async function treeEntry(state: SeatState, head: string, path: string) {
+  const listed = await output(state.worktree, "git", ["ls-tree", head, "--", path]);
+  if (!listed) return null;
+  const [meta] = listed.split("\t");
+  const [mode, , blob] = (meta ?? "").split(" ");
+  return { mode: mode!, blob: blob! };
+}
+
+/** True when the tree entry is exactly the captured disk state (content and mode). */
+async function entryMatches(state: SeatState, entry: DirtyEntry, found: { mode: string; blob: string }) {
+  const disk = entry.disk;
+  if (disk.kind === "symlink") {
+    return found.mode === "120000" && await output(state.worktree, "git", ["cat-file", "blob", found.blob]) === disk.target;
+  }
+  if (disk.kind !== "file") return false;
+  const hashed = await output(state.worktree, "git", ["hash-object", "--no-filters", "--", entry.path]);
+  return found.mode === (disk.exec ? "100755" : "100644") && found.blob === hashed;
+}
+
+/** Compare one retained path in the JJ working-copy commit against the captured disk state. */
+async function verifyDirtyPath(state: SeatState, head: string, entry: DirtyEntry) {
+  const now = await diskState(state.worktree, entry.path);
+  if (JSON.stringify(now) !== JSON.stringify(entry.disk)) throw new Error(`Primary path ${entry.path} changed on disk during JJ migration.`);
+  const found = await treeEntry(state, head, entry.path);
+  const retained = entry.disk.kind === "absent" ? found === null : found !== null && await entryMatches(state, entry, found);
+  if (!retained) throw new Error(`Primary path ${entry.path} was not retained exactly in the JJ working copy.`);
+}
+
+/** A dirty primary must be exactly `main` plus the captured manifest, nothing more. */
+async function verifyDirtyPrimary(state: SeatState, dirty: DirtyEntry[]) {
+  const bookmarked = await branchCommit("jj", state.worktree, state.branch);
+  const parent = await output(state.worktree, "jj", ["log", "-r", "@-", "--no-graph", "-T", "commit_id"]);
+  if (bookmarked !== state.commit || parent !== state.commit) throw new Error(`Primary bookmark ${state.branch} changed during JJ migration.`);
+  const head = await output(state.worktree, "jj", ["log", "-r", "@", "--no-graph", "-T", "commit_id"]);
+  const changed = (await output(state.worktree, "git", ["diff-tree", "-r", "-z", "--no-renames", "--name-only", state.commit, head])).split("\0").filter(Boolean);
+  const expected = new Set(dirty.map(entry => entry.path));
+  const extra = changed.filter(path => !expected.has(path));
+  if (extra.length) throw new Error(`JJ working copy contains paths outside the captured dirty manifest: ${extra.join(", ")}`);
+  for (const entry of dirty) await verifyDirtyPath(state, head, entry);
+}
+
 /** Secondary seats may gain one clean child; their legacy tip must be its parent. */
 async function migratedHead(state: SeatState) {
   const current = await output(state.worktree, "jj", ["log", "-r", "@", "--no-graph", "-T", "commit_id"]);
@@ -267,45 +369,77 @@ async function restoreGitWorkspace(repository: string, state: SeatState) {
   return errors;
 }
 
+/** Locate the primary's Git index so JJ's colocation rewrite can be undone byte-for-byte. */
+async function indexPath(repository: string) {
+  return resolve(repository, await output(repository, "git", ["rev-parse", "--git-path", "index"]));
+}
+
+async function readIndex(repository: string): Promise<Buffer | null> {
+  return readFile(await indexPath(repository)).catch(() => null);
+}
+
+/** Restore (or remove) the captured index atomically. */
+async function restoreIndex(repository: string, index: Buffer | null) {
+  const path = await indexPath(repository);
+  if (index === null) return rm(path, { force: true });
+  const temp = `${path}.migrate-restore`;
+  await writeFile(temp, index);
+  await rename(temp, path);
+}
+
+/** JJ records kept commits under refs/jj; they exist only because this attempt initialized JJ. */
+async function removeJjRefs(repository: string) {
+  const refs = (await output(repository, "git", ["for-each-ref", "--format=%(refname)", "refs/jj/"])).split("\n").filter(Boolean);
+  for (const ref of refs) await output(repository, "git", ["update-ref", "-d", ref]);
+}
+
 /** Best-effort rollback never changes project.vcs and reports every incomplete restore. */
-async function rollback(repository: string, primary: SeatState, displaced: SeatState[]) {
+async function rollback(repository: string, primary: SeatState, displaced: SeatState[], index: Buffer | null) {
   const errors: string[] = [];
   for (const state of [...displaced].reverse()) await removePartialWorkspace(repository, state);
   await rm(join(repository, ".jj"), { recursive: true, force: true }).catch(error => errors.push(String(error)));
+  await removeJjRefs(repository).catch(error => errors.push(String(error)));
   const switched = await command(repository, "git", ["switch", primary.branch]);
   if (switched.code) errors.push(switched.err || switched.out);
   for (const state of displaced) errors.push(...await restoreGitWorkspace(repository, state));
+  await restoreIndex(repository, index).catch(error => errors.push(String(error)));
   return errors;
 }
 
-/** Execute the only supported legacy conversion: Git project to colocated JJ. */
-export async function migrateProjectVcs(root: string, name: string, args: string[]) {
+/** Accept exactly `--to jj` plus at most one each of the known flags. */
+function parseMigrationArgs(args: string[]) {
   const toIndex = args.indexOf("--to"), to = toIndex < 0 ? undefined : args[toIndex + 1];
-  const dryRun = args.includes("--dry-run");
-  const consumed = new Set([toIndex, toIndex + 1, ...(dryRun ? [args.indexOf("--dry-run")] : [])]);
+  const flags = ["--dry-run", DIRTY_PRIMARY_FLAG];
+  const rest = args.filter((_arg, index) => index !== toIndex && index !== toIndex + 1);
   const valid = toIndex >= 0 && to === "jj"
     && args.filter(arg => arg === "--to").length === 1
-    && args.filter(arg => arg === "--dry-run").length <= 1
-    && args.every((_arg, index) => consumed.has(index));
-  if (!valid) throw new Error("Use `atdd-flow project migrate-vcs <project> --to jj [--dry-run]`.");
-  const prepared = await prepare(root, name);
+    && rest.every(arg => flags.includes(arg))
+    && new Set(rest).size === rest.length;
+  if (!valid) throw new Error("Use `atdd-flow project migrate-vcs <project> --to jj [--allow-dirty-primary] [--dry-run]`.");
+  return { dryRun: rest.includes("--dry-run"), allowDirtyPrimary: rest.includes(DIRTY_PRIMARY_FLAG) };
+}
+
+/** Execute the only supported legacy conversion: Git project to colocated JJ. */
+export async function migrateProjectVcs(root: string, name: string, args: string[]) {
+  const { dryRun, allowDirtyPrimary } = parseMigrationArgs(args);
+  const prepared = await prepare(root, name, allowDirtyPrimary);
   if (dryRun) { process.stdout.write(yaml.print(prepared.plan)); return; }
 
   const displaced: SeatState[] = [];
   try {
     await output(prepared.repository, "jj", ["git", "init", "--colocate"]);
     await assertRepository("jj", prepared.repository);
-    await verifyPrimary(prepared.plan.primary);
+    await verifyPrimary(prepared.plan.primary, prepared.dirty);
     for (const state of prepared.plan.workspaces) {
       displaced.push(state);
       await convertWorkspace(prepared.repository, state);
     }
-    await verifyPrimary(prepared.plan.primary);
+    await verifyPrimary(prepared.plan.primary, prepared.dirty);
     for (const state of prepared.plan.workspaces) await verifyMigratedWorkspace(state);
     await atomicYaml(paths(root).projectFile(name), { ...prepared.config, vcs: "jj" });
     process.stdout.write(`${name}  migrated git -> jj  ${prepared.states.length} seats  lineage preserved\n`);
   } catch (error) {
-    const rollbackErrors = await rollback(prepared.repository, prepared.plan.primary, displaced);
+    const rollbackErrors = await rollback(prepared.repository, prepared.plan.primary, displaced, prepared.index);
     const suffix = rollbackErrors.length ? ` Automatic rollback was incomplete: ${rollbackErrors.join("; ")}` : " Git worktrees were restored.";
     throw new Error(`JJ migration failed before project.vcs changed: ${(error as Error).message}.${suffix}`);
   }