@afokapu/atdd-flow 0.3.67 → 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.67",
+  "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";
@@ -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>]
@@ -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"));
+}