@afokapu/atdd-flow 0.3.66 → 0.3.68

package/README.md

@@ -288,6 +288,18 @@ coordinator to move `review → in_progress`. `ESCALATE` leaves the task in revi
 may explicitly block it) while authoritative intent is resolved. Only the coordinator can transition
 `review → done`.
 
+## Optional Linear one-way mirror
+
+Flow can project an explicitly allowlisted task or message to Linear while keeping Flow authoritative. The default is a deterministic dry run; a live projection additionally requires an owner-accepted pilot reference in the config, the exact same `--authorization` argument, and `LINEAR_API_KEY` in the process environment. It has no inbound command or webhook path.
+
+```sh
+atdd-flow linear mirror task demo delivery --config /secure/local/linear-mirror.yaml
+atdd-flow linear mirror task demo delivery --config /secure/local/linear-mirror.yaml \
+  --apply --authorization owner-approved-pilot
+```
+
+Mappings and body-free immutable receipts are written below the Desk's `.atdd-flow/linear-mirror/`; retrying reuses a canonical Flow ID instead of creating another Linear object. See [the discovery report and owner-reviewable pilot plan](docs/linear-one-way-mirror-pilot.adoc) for the allowlist, redaction, routing, status-map, and rollback contract. Never commit a Linear token or config containing one.
+
 ## Optional Jev helper
 
 Jev is read-only; it cannot mutate state, approve proof, or override ATDD Bun.

package/docs/index.adoc

@@ -0,0 +1,7 @@
+= Flow documentation
+:doc-id: purpose.index
+:status: current
+
+Authored documentation for ATDD Flow.
+
+* xref:linear-one-way-mirror-pilot.adoc[Linear one-way mirror: discovery and pilot plan]

package/docs/linear-one-way-mirror-pilot.adoc

@@ -0,0 +1,70 @@
+= Linear one-way mirror: discovery and pilot plan
+:doc-id: purpose.linear-one-way-mirror-pilot
+:status: current
+
+== Read-only discovery — 2026-10-10
+
+No Linear write was made. The workspace was inspected through read-only team, project, and issue listing calls; no token, credential, issue body, or comment body is retained here.
+
+The only active non-deprecated candidate discovered for an owner-approved pilot is:
+
+* *Team:* `Forge` / key `FOS` / ID `ae91eacd-4cc0-4924-bb1e-4e4fa718d8ca`
+* *Project:* `Play and Run v0.1.0` / MCP-surface identifier `P-FOS-25` / status `In Progress`
+
+IMPORTANT: `P-FOS-25` is the identifier the read-only listing tool displayed; it is *not* a verified Linear project UUID. Linear's issue filter and `issueCreate` need the real UUID. The mirror therefore refuses `authorize` and `--apply` unless the team, project, and every status mapping are UUIDs. Owner/main decision needed before any pilot: confirm the project (and the Forge workflow-state UUIDs) through a read-only lookup and record the UUIDs in the local config. Until then the pilot stays dry-run only; no live write is possible.
+
+This is a proposed routing target, not authorization to write. The former `FRG` team is explicitly marked `(Deprecated)` and is excluded.
+
+== Projection contract
+
+Flow is authoritative. A task has the canonical key `flow:task:<project>/<task-id>`; a message has `flow:message:<thread-id>/<message-id>`. The mirror adds that canonical key as an HTML marker on its Linear object and stores an append-only local mapping to the Linear ID. It does not read a Linear mutation into Flow, parse inbound webhooks, expose an inbound command, or write any Flow task/thread/message from Linear data.
+
+Only explicitly allowlisted Flow projects, task IDs (when supplied), and fields can leave Flow. `title` and `status` are required for a task. `body` and `comment` are opt-in. Redaction is fail-closed and applies to titles and bodies: credential assignments (`secret`, `token`, `password`, `api key`, `authorization`), Bearer values, GitHub tokens (`ghp_`, `gho_`, `ghs_`, `github_pat_`), secret keys (`sk_`, `sk-`), Linear, Slack and AWS credentials, JSON web tokens, private-key blocks, any URL, any email address, and text that looks like a mirror marker are refused before a Linear call. Nothing is partially redacted or rewritten. Unsupported fields are refused rather than silently broadened.
+
+Every attempt writes a body-free immutable receipt below the Desk's `.atdd-flow/linear-mirror/evidence/`. The receipt records canonical ID, idempotency key, route, operation, state mapping, and outcome, but never a Linear token or projected content. Canonical mappings are write-once. Our marker is always the final line of the remote description or comment; marker text elsewhere in a body is ignored. Issue lookup is scoped to the authorized team and project (server-side filter plus a client-side check), and a result outside that route is refused. Comment lookup walks every page of the issue's comments, so a long issue cannot hide an existing projection. Replays first look up the marker and then update the existing object; a retry cannot bind the Flow object to another Linear object. A missing marker on a mapped issue is recorded as drift and fails closed.
+
+== Exact planned status mapping
+
+The pilot config must use the Forge team's actual Linear workflow-state IDs (not guessed display labels) and preserve this deterministic mapping:
+
+[cols="1,2",options="header"]
+|===
+|Flow task state |Linear Forge workflow state
+|`todo` |`Backlog`
+|`in_progress` |`In Progress`
+|`review` |`In Progress` (Flow remains the review authority)
+|`done` |`Completed`
+|===
+
+The current read-only discovery did not retrieve workflow-state UUIDs. An approved pilot operator must insert the exact existing IDs into the config before an `--apply`; an empty mapping is rejected before any write.
+
+== Owner-reviewable pilot
+
+. The owner explicitly accepts this pilot's exact `FOS` / verified-project-UUID route by creating a write-once `operator@desk` authorization record (only after the UUIDs above are verified) from the local config (`atdd-flow linear mirror authorize --config ... --id LMA-... --by operator@desk`). The immutable record binds the complete route, task subset, fields, and status map; a config string cannot authorize a write.
+. Scope is exactly the Flow project `atdd-flow`, initially *only* task `linear-one-way-mirror-contract`; no historical bulk sync and no inbound handling.
+. Run `atdd-flow linear mirror task ... --config <local-config>` without `--apply`. Inspect the durable dry-run receipt and destination payload plan.
+. With a separate Linear credential in `LINEAR_API_KEY`, run the same command with `--apply --authorization <the-exact-accepted-reference>`. The CLI rejects a missing or mismatched reference. The secret stays only in process environment.
+. Verify the Linear issue has its canonical marker, repeat the command to verify idempotency, and project at most one safe Flow message as a comment. Verify all receipts and mapping IDs.
+. If a marker is missing, a route changes, a sensitive value is encountered, or any operation fails, disable by omitting `--apply`/removing the credential. There is no compensating Flow mutation and no remote-delete action. Rollback is therefore *disable the mirror*, preserve receipts, and investigate drift.
+
+Example local config (do not commit a credential):
+
+[source,yaml]
+----
+schema: atdd-flow/linear-mirror-config/v1
+routing:
+  team_id: ae91eacd-4cc0-4924-bb1e-4e4fa718d8ca
+  project_id: <verified Play and Run project UUID>
+  # team_id, project_id and every state must be Linear UUIDs for --apply
+  states:
+    todo: <Forge Backlog workflow-state UUID>
+    in_progress: <Forge In Progress workflow-state UUID>
+    review: <Forge In Progress workflow-state UUID>
+    done: <Forge Completed workflow-state UUID>
+allow:
+  projects: [atdd-flow]
+  task_ids: [linear-one-way-mirror-contract]
+  fields: [title, status, body, comment]
+----
+
+No live write happens merely by adding this file. `--apply`, a matching immutable `LMA-...` authorization from the Desk, and `LINEAR_API_KEY` are all required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@afokapu/atdd-flow",
-  "version": "0.3.66",
+  "version": "0.3.68",
   "description": "Filesystem-first Desk registry for projects, seats, tasks, threads, and handoffs.",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
   "files": [
     "bin",
     "conventions",
+    "docs",
     "extensions",
     "src",
     "README.md",

package/src/cli.ts

@@ -17,6 +17,7 @@ import * as reviews from "./reviews";
 import { status } from "./overview";
 import { multiplexer } from "./multiplexer";
 import * as cleanup from "./ephemeral-resources";
+import { linearCommand } from "./linear-cli";
 import * as ownerAlerts from "./owner-escalations";
 import { recoveryFor } from "./recovery-bundle";
 import { reconcileOnce } from "./reconcile";
@@ -33,7 +34,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]
@@ -69,6 +70,9 @@ Usage:
   atdd-flow cleanup status <project>
   atdd-flow cleanup checklist <project> <task-id>
   atdd-flow reconcile --once [--dry-run]
+  atdd-flow linear mirror authorize --config <file> --id <LMA-id> --by operator@desk
+  atdd-flow linear mirror task <project> <task-id> --config <file> [--apply --authorization <LMA-id>]
+  atdd-flow linear mirror message <project> <task-id> <thread-id> <message-id> --config <file> [--apply --authorization <LMA-id>]
   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>]
@@ -111,7 +115,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)),
@@ -177,6 +181,7 @@ async function main() {
       process.stdout.write(Bun.YAML.stringify(await reconcileOnce(root, { dryRun: rest.includes("--dry-run") })));
       return;
     },
+    linear: () => linearCommand(root, rest),
     "owner-alert": async () => {
       const [subcommand, alertId, ...tail] = rest;
       if (subcommand === "scan") {

package/src/linear-cli.ts

@@ -0,0 +1,53 @@
+// URN: component:linear-mirror:outbound:LinearCli:backend:application
+// Tested-By:
+//   - test:linear-mirror:outbound:E001-LINEAR-001-one-way-mirror-fails-closed
+// Runtime: bun
+// Purpose: Command handler for `atdd-flow linear mirror` dry-run and gated apply
+//
+// Reads Flow records only to project them outward; nothing here writes Flow.
+import { has, paths, readYaml, required, words, yaml } from "./core";
+import { linearGraphql } from "./linear-graphql";
+import { authorizeLiveProjection, mirrorMessage, mirrorTask, readMirrorConfig, type MirrorConfig } from "./linear-mirror";
+import type { Task } from "./tasks";
+import type { Message } from "./threads";
+
+const usage = "Use `atdd-flow linear mirror authorize|task|message ...`.";
+const emit = (value: unknown) => process.stdout.write(`${yaml.print(value)}\n`);
+
+type Run = { root: string; config: MirrorConfig; project: string; task: string; apply: boolean; authorization?: string };
+
+/** Projects one Flow task outward; the dry run is the default and needs no credential. */
+async function prepare(run: Run) {
+  const linear = linearGraphql(run.apply ? required(process.env.LINEAR_API_KEY, "LINEAR_API_KEY") : "dry-run");
+  const task = await readYaml<Task>(paths(run.root).taskFile(run.project, run.task));
+  const source = { canonical_id: `flow:task:${run.project}/${run.task}`, project: run.project, task_id: run.task, title: task.title, status: task.status, ...(task.body ? { body: task.body } : {}) };
+  const options = { apply: run.apply, ...(run.authorization ? { authorization: run.authorization } : {}) };
+  return { linear, source, options };
+}
+
+/** Handles `linear mirror authorize|task|message`. */
+export async function linearCommand(root: string, rest: string[]) {
+  if (rest[0] !== "mirror") throw new Error(usage);
+  if (rest[1] === "authorize") {
+    const tail = rest.slice(2);
+    const config = await readMirrorConfig(required(words(tail, "--config"), "--config"));
+    return emit(await authorizeLiveProjection(root, config, { id: required(words(tail, "--id"), "--id"), by: required(words(tail, "--by"), "--by") }));
+  }
+  if (!["task", "message"].includes(rest[1] ?? "")) throw new Error(usage);
+  const kind = rest[1];
+  const tail = rest.slice(kind === "task" ? 4 : 6);
+  const apply = has(tail, "--apply");
+  const authorization = words(tail, "--authorization");
+  if (apply && !authorization) throw new Error("Live Linear writes require an immutable operator@desk authorization id.");
+  const run: Run = {
+    root, config: await readMirrorConfig(required(words(tail, "--config"), "--config")), apply,
+    project: required(rest[2], "project"), task: required(rest[3], "task id"), ...(authorization ? { authorization } : {}),
+  };
+  const { linear, source, options } = await prepare(run);
+  if (kind === "task") return emit(await mirrorTask(root, run.config, source, linear, options));
+  const threadId = required(rest[4], "thread id");
+  const messageId = required(rest[5], "message id");
+  const message = await readYaml<Message>(paths(root).message(threadId, messageId));
+  const projection = { canonical_id: `flow:message:${threadId}/${messageId}`, task_canonical_id: source.canonical_id, project: run.project, task_id: run.task, thread_id: threadId, message_id: messageId, body: message.body };
+  return emit(await mirrorMessage(root, run.config, projection, linear, options));
+}

package/src/linear-graphql.ts

@@ -0,0 +1,103 @@
+// URN: component:linear-mirror:outbound:LinearGraphql:backend:integration
+// Tested-By:
+//   - test:linear-mirror:outbound:E001-LINEAR-001-one-way-mirror-fails-closed
+// Runtime: bun
+// Purpose: Typed outbound-only Linear GraphQL edge for the one-way mirror
+//
+// The edge only ever issues the five mirror operations. The token is read once
+// by the caller and is never stored in config, mappings, receipts, or output.
+import { endsWithMarker, markerFor, type OutboundLinear } from "./linear-mirror";
+
+type GraphqlResponse<T> = { data?: T; errors?: Array<{ message?: string }> };
+type RemoteNode = { id: string; description?: string; state?: { id?: string }; team?: { id?: string }; project?: { id?: string } };
+type Page<N> = { nodes: N[]; pageInfo: { hasNextPage: boolean; endCursor?: string | null } };
+type Execute = <T>(query: string, variables: Record<string, unknown>) => Promise<T>;
+
+/** Safety bound: a mirror that cannot find its marker in this many pages fails closed instead of guessing. */
+const maxPages = 100;
+
+/** Issues one GraphQL request and fails closed on any transport or API error. */
+function executor(apiKey: string, endpoint: string) {
+  return async <T>(query: string, variables: Record<string, unknown>) => {
+    const response = await fetch(endpoint, {
+      method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` }, body: JSON.stringify({ query, variables }),
+    });
+    const value = await response.json() as GraphqlResponse<T>;
+    const reason = value.errors?.map((entry) => entry.message).join("; ") || response.statusText;
+    if (!response.ok || value.errors?.length || !value.data) throw new Error(`Linear GraphQL refused outbound projection: ${reason}`);
+    return value.data;
+  };
+}
+
+/** Normalizes a Linear node into the mirror's remote-issue shape. */
+const remote = (value: RemoteNode) => ({
+  id: value.id, marker: value.description ?? "", state_id: value.state?.id ?? "",
+  ...(value.team?.id ? { team_id: value.team.id } : {}), ...(value.project?.id ? { project_id: value.project.id } : {}),
+});
+
+/** Walks every page; the first matching node wins, and exhausting the bound fails closed. */
+async function firstMatch<N>(fetchPage: (cursor: string | null) => Promise<Page<N> | undefined>, matches: (node: N) => boolean) {
+  let cursor: string | null = null;
+  for (let pages = 0; pages < maxPages; pages += 1) {
+    const page: Page<N> | undefined = await fetchPage(cursor);
+    const found = page?.nodes.find(matches);
+    if (found || !page?.pageInfo.hasNextPage || !page.pageInfo.endCursor) return found;
+    cursor = page.pageInfo.endCursor;
+  }
+  throw new Error("Linear lookup exceeded its page bound; refusing to guess.");
+}
+
+/** Scoped to the authorized team/project; the marker must be the final line of the description. */
+async function findScopedIssue(execute: Execute, key: string, route: { team_id: string; project_id: string }) {
+  const marker = markerFor(key);
+  const found = await firstMatch(async (cursor) => (await execute<{ issues: Page<RemoteNode> }>(queryIssues,
+    { marker, teamId: route.team_id, projectId: route.project_id, cursor })).issues,
+  (node) => endsWithMarker(node.description, marker) && node.team?.id === route.team_id && node.project?.id === route.project_id);
+  return found ? remote(found) : undefined;
+}
+
+/** Paginates the whole comment history so a long issue cannot hide an existing projection. */
+function findKeyedComment(execute: Execute, issueId: string, key: string) {
+  const marker = markerFor(key);
+  return firstMatch(async (cursor) => (await execute<{ issue: { comments: Page<{ id: string; body?: string }> } | null }>(queryComments, { id: issueId, cursor })).issue?.comments,
+    (node) => endsWithMarker(node.body, marker));
+}
+
+const queryIssues = `query MirrorIssue($marker: String!, $teamId: ID!, $projectId: ID!, $cursor: String) { issues(first: 50, after: $cursor, filter: { team: { id: { eq: $teamId } }, project: { id: { eq: $projectId } }, description: { contains: $marker } }) { nodes { id description state { id } team { id } project { id } } pageInfo { hasNextPage endCursor } } }`;
+const createIssueMutation = `mutation CreateMirrorIssue($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id description state { id } team { id } project { id } } } }`;
+const updateIssueMutation = `mutation UpdateMirrorIssue($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { id } } }`;
+const queryComments = `query MirrorComment($id: String!, $cursor: String) { issue(id: $id) { comments(first: 100, after: $cursor) { nodes { id body } pageInfo { hasNextPage endCursor } } } }`;
+const createCommentMutation = `mutation CreateMirrorComment($input: CommentCreateInput!) { commentCreate(input: $input) { success comment { id } } }`;
+const inspectIssueQuery = `query InspectMirrorIssue($id: String!) { issue(id: $id) { id description state { id } team { id } project { id } } }`;
+
+/** Builds the outbound adapter; there is deliberately no Linear-to-Flow read path here. */
+export function linearGraphql(apiKey: string, endpoint = "https://api.linear.app/graphql"): OutboundLinear {
+  if (!apiKey.trim()) throw new Error("LINEAR_API_KEY is required for a live Linear projection.");
+  const execute = executor(apiKey, endpoint);
+  return {
+    findIssueByKey: (key, route) => findScopedIssue(execute, key, route),
+    async createIssue(input) {
+      const data = await execute<{ issueCreate: { success: boolean; issue?: RemoteNode } }>(createIssueMutation,
+        { input: { teamId: input.team_id, projectId: input.project_id, title: input.title, description: input.description, stateId: input.state_id } });
+      if (!data.issueCreate.success || !data.issueCreate.issue) throw new Error("Linear did not confirm issue creation.");
+      return { ...remote(data.issueCreate.issue), marker: input.marker };
+    },
+    async updateIssue(input) {
+      const data = await execute<{ issueUpdate: { success: boolean; issue?: { id: string } } }>(updateIssueMutation,
+        { id: input.id, input: { title: input.title, description: input.description, stateId: input.state_id } });
+      if (!data.issueUpdate.success || !data.issueUpdate.issue) throw new Error("Linear did not confirm issue update.");
+      return data.issueUpdate.issue;
+    },
+    findCommentByKey: (issue_id, key) => findKeyedComment(execute, issue_id, key),
+    async createComment(input) {
+      const data = await execute<{ commentCreate: { success: boolean; comment?: { id: string } } }>(createCommentMutation,
+        { input: { issueId: input.issue_id, body: input.body } });
+      if (!data.commentCreate.success || !data.commentCreate.comment) throw new Error("Linear did not confirm comment creation.");
+      return data.commentCreate.comment;
+    },
+    async inspectIssue(id) {
+      const data = await execute<{ issue: RemoteNode | null }>(inspectIssueQuery, { id });
+      return data.issue ? remote(data.issue) : undefined;
+    },
+  };
+}

package/src/linear-mirror.ts

@@ -0,0 +1,332 @@
+// URN: component:linear-mirror:outbound:LinearMirror:backend:domain
+// Tested-By:
+//   - test:linear-mirror:outbound:E001-LINEAR-001-one-way-mirror-fails-closed
+// Runtime: bun
+// Purpose: Fail-closed outbound-only Flow-to-Linear mirror with immutable evidence
+//
+// Flow stays authoritative. Every projection is allowlisted, redacted, keyed by
+// a canonical Flow id, and recorded as write-once evidence. Live writes also need
+// a write-once operator@desk authorization bound to the exact projection tuple.
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { now, yaml } from "./core";
+import type { TaskStatus } from "./tasks";
+
+/** Deliberately outbound-only Linear projection. Flow records never accept Linear mutations. */
+export type MirrorConfig = {
+  schema: "atdd-flow/linear-mirror-config/v1";
+  routing: { team_id: string; project_id: string; states: Record<TaskStatus, string> };
+  allow: { projects: string[]; task_ids?: string[]; fields: Array<"title" | "status" | "body" | "comment"> };
+};
+
+type ProjectionTuple = { team_id: string; project_id: string; states: Record<TaskStatus, string>; projects: string[]; task_ids: string[]; fields: string[] };
+type LiveAuthorization = { schema: "atdd-flow/linear-mirror-authorization/v1"; id: string; immutable: true; by: "operator@desk"; accepted_at: string; projection: ProjectionTuple };
+
+export type TaskProjection = {
+  canonical_id: string;
+  project: string;
+  task_id: string;
+  title: string;
+  status: TaskStatus;
+  body?: string;
+  /** Fields Flow does not project must be named explicitly and are refused. */
+  unsupported?: string[];
+};
+
+/** The Flow project and task a projected record belongs to. */
+type Scope = { project: string; task_id: string };
+
+export type MessageProjection = Scope & {
+  canonical_id: string;
+  task_canonical_id: string;
+  thread_id: string;
+  message_id: string;
+  body: string;
+  unsupported?: string[];
+};
+
+/** `team_id`/`project_id` are reported when the remote knows them so a lookup can be checked against the route. */
+type RemoteIssue = { id: string; marker: string; state_id: string; team_id?: string; project_id?: string };
+type Route = { team_id: string; project_id: string };
+export type OutboundLinear = {
+  /** Lookup by the canonical Flow key, scoped to the authorized team/project, makes retry-after-partial-write safe. */
+  findIssueByKey(key: string, route: Route): Promise<RemoteIssue | undefined>;
+  createIssue(input: { idempotency_key: string; team_id: string; project_id: string; title: string; description: string; state_id: string; marker: string }): Promise<RemoteIssue>;
+  updateIssue(input: { id: string; title: string; description: string; state_id: string; marker: string }): Promise<{ id: string }>;
+  /** Lookup prevents a retry after a completed remote comment from creating a duplicate. */
+  findCommentByKey(issue_id: string, key: string): Promise<{ id: string } | undefined>;
+  createComment(input: { issue_id: string; body: string; idempotency_key: string; marker: string }): Promise<{ id: string }>;
+  /** Optional read-only inspection records remote drift but never changes Flow. */
+  inspectIssue?(id: string): Promise<RemoteIssue | undefined>;
+};
+
+export type MirrorResult = { mode: "dry-run" | "live"; operation: "create" | "update" | "comment"; idempotency_key: string; receipt: string };
+type Mapping = { schema: "atdd-flow/linear-mirror-mapping/v1"; canonical_id: string; idempotency_key: string; linear_id: string; created_at: string; immutable: true };
+type Evidence = {
+  schema: "atdd-flow/linear-mirror-evidence/v1"; immutable: true; at: string; mode: "dry-run" | "live";
+  operation: MirrorResult["operation"]; outcome: "planned" | "authorized" | "projected" | "drift" | "refused";
+  canonical_id: string; idempotency_key: string; route: { team_id: string; project_id: string }; state_id?: string; linear_id?: string; authorization?: { id: string; content_hash: string }; reason?: string;
+};
+
+const rootFor = (root: string) => join(root, ".atdd-flow", "linear-mirror");
+const authorizationFile = (root: string, id: string) => join(rootFor(root), "authorizations", `${id}.yaml`);
+const authorizationId = (id: string) => {
+  if (!/^LMA-[A-Za-z0-9_-]+$/.test(id)) throw new Error("Linear authorization id must start with LMA- and contain only letters, numbers, underscores, or hyphens.");
+  return id;
+};
+const projectionTuple = (config: MirrorConfig): ProjectionTuple => ({
+  team_id: config.routing.team_id, project_id: config.routing.project_id, states: config.routing.states,
+  projects: [...config.allow.projects].sort(), task_ids: [...(config.allow.task_ids ?? [])].sort(), fields: [...config.allow.fields].sort(),
+});
+const sameProjection = (left: ProjectionTuple, right: ProjectionTuple) => JSON.stringify(left) === JSON.stringify(right);
+const safeName = (value: string) => createHash("sha256").update(value).digest("hex");
+const mappingFile = (root: string, canonicalId: string) => join(rootFor(root), "mappings", `${safeName(canonicalId)}.yaml`);
+export const markerFor = (canonicalId: string) => `<!-- atdd-flow:canonical=${canonicalId} -->`;
+/** Our marker is always the final line; marker text pasted elsewhere in a remote body never identifies an object. */
+export const endsWithMarker = (text: string | undefined, marker: string) => {
+  const lines = (text ?? "").trimEnd().split("\n");
+  return lines[lines.length - 1]?.trim() === marker;
+};
+const markerPrefix = "atdd-flow:canonical=";
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Fail-closed redaction: credential-looking text, URLs, and email addresses never leave Flow. */
+const sensitivePatterns: Array<[string, RegExp]> = [
+  ["credential assignment", /(?:api[_ -]?key|password|passwd|secret|token|authorization)\s*[:=]/i],
+  ["bearer token", /bearer\s+[a-z0-9._~+/=-]+/i],
+  ["GitHub token", /\b(?:gh[pousr]_[A-Za-z0-9]{16,}|github_pat_[A-Za-z0-9_]{16,})/],
+  ["secret key", /\b(?:sk|rk|pk)[-_](?:live|test|proj|ant)?[-_]?[A-Za-z0-9]{16,}/],
+  ["Linear/Slack/AWS credential", /\b(?:lin_(?:api|oauth)_[A-Za-z0-9]{16,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16})/],
+  ["JSON web token", /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\./],
+  ["private key", /-----BEGIN [A-Z ]*PRIVATE KEY-----/],
+  ["URL", /\b[a-z][a-z0-9+.-]*:\/\/\S+/i],
+  ["email address", /[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+/],
+  ["marker text", new RegExp(markerPrefix)],
+];
+const sensitiveKind = (value: string) => sensitivePatterns.find(([, pattern]) => pattern.test(value))?.[0];
+
+async function mapping(root: string, canonicalId: string) {
+  try { return yaml.parse<Mapping>(await readFile(mappingFile(root, canonicalId), "utf8")); }
+  catch { return undefined; }
+}
+
+/** Mapping records are append-only: a canonical Flow record can never be rebound to another Linear object. */
+async function writeMapping(root: string, value: Mapping) {
+  const file = mappingFile(root, value.canonical_id);
+  await mkdir(join(rootFor(root), "mappings"), { recursive: true });
+  try { await writeFile(file, yaml.print(value), { encoding: "utf8", flag: "wx" }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const prior = await mapping(root, value.canonical_id);
+    if (!prior || prior.linear_id !== value.linear_id || prior.idempotency_key !== value.idempotency_key) {
+      throw new Error(`Canonical Flow id ${value.canonical_id} is already mapped inconsistently.`);
+    }
+  }
+}
+
+let receiptSequence = 0;
+
+/** Evidence has no source body, token, or mutable filename; it is safe to retain in the Desk. */
+async function receipt(root: string, value: Evidence) {
+  const folder = join(rootFor(root), "evidence");
+  await mkdir(folder, { recursive: true });
+  // The sequence keeps same-millisecond receipts in write order; the UUID keeps other processes distinct.
+  receiptSequence += 1;
+  const file = join(folder, `${now().replace(/[^0-9]/g, "")}-${String(receiptSequence).padStart(6, "0")}-${randomUUID()}.yaml`);
+  await writeFile(file, yaml.print(value), { encoding: "utf8", flag: "wx" });
+  return file;
+}
+
+const blank = (value?: string) => !value?.trim();
+type Candidate = { project?: string; task_id?: string; canonical_id: string; unsupported?: string[]; title?: string; body?: string };
+
+/** The route and the complete status mapping must be explicit before anything leaves Flow. */
+function assertRouting(config: MirrorConfig) {
+  if (config.schema !== "atdd-flow/linear-mirror-config/v1") throw new Error("Unsupported Linear mirror configuration.");
+  const route = config.routing;
+  if (blank(route?.team_id) || blank(route?.project_id) || !route?.states) throw new Error("Linear mirror routing requires exact team_id, project_id, and status mapping.");
+  for (const state of ["todo", "in_progress", "review", "done"] as const) {
+    if (blank(route.states[state])) throw new Error(`Linear mirror routing has no mapping for ${state}.`);
+  }
+}
+
+/** Only an explicitly allowlisted Flow project (and task, when listed) may be projected. */
+function assertScope(config: MirrorConfig, item: Candidate) {
+  const allow = config.allow;
+  if (!Array.isArray(allow?.projects) || !allow.projects.includes(item.project ?? "")) throw new Error(`Flow project ${item.project ?? ""} is not allowlisted for Linear projection.`);
+  if (item.task_id && allow.task_ids && !allow.task_ids.includes(item.task_id)) throw new Error(`Flow task ${item.task_id} is not allowlisted for Linear projection.`);
+}
+
+/** Unsupported or non-allowlisted fields are refused instead of silently broadened. */
+function assertFields(config: MirrorConfig, item: Candidate, comments: boolean) {
+  const fields = config.allow.fields;
+  if (item.unsupported?.length) throw new Error(`Unsupported Flow fields are not projectable: ${item.unsupported.join(", ")}.`);
+  if (comments) {
+    if (!fields.includes("comment")) throw new Error("Linear comment projection is not allowlisted.");
+  } else if (!fields.includes("title") || !fields.includes("status")) {
+    throw new Error("Linear task projection requires title and status allowlist entries.");
+  }
+}
+
+/** Every refusal happens before any Linear call; sensitive-looking text never leaves Flow. */
+function refuse(config: MirrorConfig, item: Candidate, comments = false) {
+  assertRouting(config);
+  assertScope(config, item);
+  assertFields(config, item, comments);
+  for (const value of [item.title, item.body]) {
+    const kind = value ? sensitiveKind(value) : undefined;
+    if (kind) throw new Error(`Sensitive content (${kind}) was refused by the Linear redaction policy.`);
+  }
+}
+
+function taskPayload(config: MirrorConfig, item: TaskProjection) {
+  const marker = markerFor(item.canonical_id);
+  const description = config.allow.fields.includes("body") && item.body ? `${item.body}\n\n${marker}` : marker;
+  return { marker, description, state_id: config.routing.states[item.status] };
+}
+
+/** Only the human authority can create a write-once approval bound to this exact projection tuple. */
+export async function authorizeLiveProjection(root: string, config: MirrorConfig, input: { id: string; by: string }) {
+  if (input.by !== "operator@desk") throw new Error("Only operator@desk may authorize a live Linear projection.");
+  refuse(config, { canonical_id: "authorization", project: config.allow.projects[0] ?? "" });
+  assertLiveRoute(config);
+  const id = authorizationId(input.id);
+  const record: LiveAuthorization = { schema: "atdd-flow/linear-mirror-authorization/v1", id, immutable: true, by: "operator@desk", accepted_at: now(), projection: projectionTuple(config) };
+  await mkdir(join(rootFor(root), "authorizations"), { recursive: true });
+  try { await writeFile(authorizationFile(root, id), yaml.print(record), { encoding: "utf8", flag: "wx" }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const prior = yaml.parse<LiveAuthorization>(await readFile(authorizationFile(root, id), "utf8"));
+    if (prior.schema !== record.schema || prior.id !== id || prior.immutable !== true || prior.by !== "operator@desk" || !sameProjection(prior.projection, record.projection)) throw new Error(`Live Linear authorization ${id} already exists with a different or mutable approval.`);
+  }
+  return authorizationFile(root, id);
+}
+
+/** A live write needs Linear's real identifiers; display keys or labels cannot scope a lookup. */
+function assertLiveRoute(config: MirrorConfig) {
+  const route = config.routing;
+  const bad = [["team_id", route.team_id], ["project_id", route.project_id], ...Object.entries(route.states).map(([state, value]) => [`states.${state}`, value])]
+    .filter(([, value]) => !uuid.test(value ?? "")).map(([name]) => name);
+  if (bad.length) throw new Error(`Live Linear routing requires verified Linear UUIDs; not a UUID: ${bad.join(", ")}.`);
+}
+
+type ResolvedMode = { mode: "dry-run" } | { mode: "live"; authorization: { id: string; content_hash: string } };
+
+async function mode(root: string, config: MirrorConfig, options?: { apply?: boolean; authorization?: string }): Promise<ResolvedMode> {
+  if (!options?.apply) return { mode: "dry-run" };
+  const id = authorizationId(options.authorization ?? "");
+  let source: string;
+  let record: LiveAuthorization;
+  try { source = await readFile(authorizationFile(root, id), "utf8"); record = yaml.parse<LiveAuthorization>(source); }
+  catch { throw new Error(`Live Linear authorization ${id} is absent from the immutable Desk authorization store.`); }
+  if (record.schema !== "atdd-flow/linear-mirror-authorization/v1" || record.id !== id || record.immutable !== true || record.by !== "operator@desk" || !sameProjection(record.projection, projectionTuple(config))) {
+    throw new Error(`Live Linear authorization ${id} does not bind operator@desk to this exact route and projection allowlist.`);
+  }
+  assertLiveRoute(config);
+  return { mode: "live", authorization: { id, content_hash: createHash("sha256").update(source).digest("hex") } };
+}
+
+async function recordRefusal(root: string, config: MirrorConfig, canonical_id: string, key: string, reason: string) {
+  return receipt(root, {
+    schema: "atdd-flow/linear-mirror-evidence/v1", immutable: true, at: now(), mode: "live", operation: "create", outcome: "refused",
+    canonical_id, idempotency_key: key, route: { team_id: config.routing?.team_id ?? "", project_id: config.routing?.project_id ?? "" }, reason,
+  });
+}
+
+/** A remote that reports a team or project different from the authorized route is out of scope. */
+const outsideRoute = (remote: RemoteIssue, route: Route) =>
+  (remote.team_id ?? route.team_id) !== route.team_id || (remote.project_id ?? route.project_id) !== route.project_id;
+
+/** A retry after a partial remote write adopts the existing issue instead of creating a duplicate. */
+async function priorIssue(root: string, key: string, linear: OutboundLinear, selectedMode: "dry-run" | "live", route: Route) {
+  const prior = await mapping(root, key);
+  if (prior || selectedMode !== "live") return prior;
+  const remote = await linear.findIssueByKey(key, route);
+  if (!remote) return undefined;
+  // A lookup result outside the authorized route or without our trailing marker must never be bound.
+  if (outsideRoute(remote, route) || !endsWithMarker(remote.marker, markerFor(key))) throw new Error(`Linear lookup for ${key} returned an object outside the authorized route or without its canonical marker.`);
+  await writeMapping(root, { schema: "atdd-flow/linear-mirror-mapping/v1", canonical_id: key, idempotency_key: key, linear_id: remote.id, created_at: now(), immutable: true });
+  return mapping(root, key);
+}
+
+/** Projects one allowlisted Flow task: dry-run by default, authorized create/update when applied. */
+export async function mirrorTask(root: string, config: MirrorConfig, item: TaskProjection, linear: OutboundLinear, options?: { apply?: boolean; authorization?: string }): Promise<MirrorResult> {
+  const key = item.canonical_id;
+  try { refuse(config, item); }
+  catch (error) { await recordRefusal(root, config, key, key, (error as Error).message); throw error; }
+  let selected: ResolvedMode;
+  try { selected = await mode(root, config, options); }
+  catch (error) { await recordRefusal(root, config, key, key, (error as Error).message); throw error; }
+  const selectedMode = selected.mode;
+  const payload = taskPayload(config, item);
+  const prior = await priorIssue(root, key, linear, selectedMode, config.routing);
+  const operation: MirrorResult["operation"] = prior ? "update" : "create";
+  const evidence = (outcome: Evidence["outcome"], extra: Partial<Evidence> = {}) => receipt(root, {
+    schema: "atdd-flow/linear-mirror-evidence/v1", immutable: true, at: now(), mode: selectedMode, operation, outcome,
+    canonical_id: key, idempotency_key: key, route: { team_id: config.routing.team_id, project_id: config.routing.project_id }, state_id: payload.state_id,
+    ...(selected.mode === "live" ? { authorization: selected.authorization } : {}), ...extra,
+  });
+  if (selectedMode === "dry-run") return { mode: selectedMode, operation, idempotency_key: key, receipt: await evidence("planned") };
+
+  if (!prior) {
+    await evidence("authorized");
+    const remote = await linear.createIssue({ idempotency_key: key, team_id: config.routing.team_id, project_id: config.routing.project_id, title: item.title, description: payload.description, state_id: payload.state_id, marker: payload.marker });
+    await writeMapping(root, { schema: "atdd-flow/linear-mirror-mapping/v1", canonical_id: key, idempotency_key: key, linear_id: remote.id, created_at: now(), immutable: true });
+    return { mode: selectedMode, operation, idempotency_key: key, receipt: await evidence("projected", { linear_id: remote.id }) };
+  }
+
+  if (linear.inspectIssue) {
+    const remote = await linear.inspectIssue(prior.linear_id);
+    if (!remote || outsideRoute(remote, config.routing) || !endsWithMarker(remote.marker, payload.marker)) {
+      const file = await evidence("drift", { linear_id: prior.linear_id, reason: "Mapped Linear issue lacks its canonical Flow marker or left the authorized route." });
+      throw new Error(`Linear drift detected for ${key}; receipt: ${file}`);
+    }
+  }
+  await evidence("authorized");
+  await linear.updateIssue({ id: prior.linear_id, title: item.title, description: payload.description, state_id: payload.state_id, marker: payload.marker });
+  return { mode: selectedMode, operation, idempotency_key: key, receipt: await evidence("projected", { linear_id: prior.linear_id }) };
+}
+
+/** Messages can only become outbound comments on an already mapped Flow task. */
+export async function mirrorMessage(root: string, config: MirrorConfig, item: MessageProjection, linear: OutboundLinear, options?: { apply?: boolean; authorization?: string }): Promise<MirrorResult> {
+  const key = item.canonical_id;
+  try { refuse(config, { project: item.project, task_id: item.task_id, canonical_id: key, body: item.body, unsupported: item.unsupported }, true); }
+  catch (error) { await recordRefusal(root, config, key, key, (error as Error).message); throw error; }
+  let selected: ResolvedMode;
+  try { selected = await mode(root, config, options); }
+  catch (error) { await recordRefusal(root, config, key, key, (error as Error).message); throw error; }
+  const selectedMode = selected.mode;
+  const parent = await mapping(root, item.task_canonical_id);
+  if (!parent) throw new Error(`Cannot project ${key}: its authoritative Flow task has no Linear mapping.`);
+  const marker = markerFor(key);
+  const folderReceipt = async (outcome: Evidence["outcome"], linear_id?: string) => receipt(root, {
+    schema: "atdd-flow/linear-mirror-evidence/v1", immutable: true, at: now(), mode: selectedMode, operation: "comment", outcome,
+    canonical_id: key, idempotency_key: key, route: { team_id: config.routing.team_id, project_id: config.routing.project_id }, linear_id,
+    ...(selected.mode === "live" ? { authorization: selected.authorization } : {}),
+  });
+  if (selectedMode === "dry-run") return { mode: selectedMode, operation: "comment", idempotency_key: key, receipt: await folderReceipt("planned", parent.linear_id) };
+  // This receipt precedes both remote lookup and creation, so a failed lookup
+  // leaves immutable operator authorization evidence without an external write.
+  await folderReceipt("authorized", parent.linear_id);
+  let existing = await mapping(root, key);
+  if (!existing) {
+    const remote = await linear.findCommentByKey(parent.linear_id, key);
+    if (remote) {
+      await writeMapping(root, { schema: "atdd-flow/linear-mirror-mapping/v1", canonical_id: key, idempotency_key: key, linear_id: remote.id, created_at: now(), immutable: true });
+      existing = await mapping(root, key);
+    }
+  }
+  if (existing) return { mode: selectedMode, operation: "comment", idempotency_key: key, receipt: await folderReceipt("projected", existing.linear_id) };
+  const remote = await linear.createComment({ issue_id: parent.linear_id, body: `${item.body}\n\n${marker}`, idempotency_key: key, marker });
+  await writeMapping(root, { schema: "atdd-flow/linear-mirror-mapping/v1", canonical_id: key, idempotency_key: key, linear_id: remote.id, created_at: now(), immutable: true });
+  return { mode: selectedMode, operation: "comment", idempotency_key: key, receipt: await folderReceipt("projected", remote.id) };
+}
+
+/** There is intentionally no parser or writer from Linear to Flow. */
+export async function applyInboundChange(_root: string, _change: unknown): Promise<never> {
+  throw new Error("Linear mirror is one-way: inbound Linear changes are refused and cannot mutate Flow.");
+}
+
+export async function readMirrorConfig(file: string) {
+  return yaml.parse<MirrorConfig>(await readFile(file, "utf8"));
+}

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}`);
   }