dev-loops 0.5.0 → 0.7.1

package/scripts/projects/list-queue-items.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
+import { resolveProjectSelector, findProject, applyDevloopsBoard } from "./_resolve-project.mjs";
 import { parseArgs } from "node:util";
-import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
-const USAGE = `Usage: dev-loops queue list --repo <owner/name> --project <number|id> [--column <name>] [--limit <n>]
+const USAGE = `Usage: dev-loops queue list --repo <owner/name> [--project <number|id>] [--column <name>] [--limit <n>]
+       dev-loops queue list --repo <owner/name> [--project <number|id>] --summary [--done-limit <n>]
        (dev-loops project list … is a back-compat alias)
 
 List GitHub Projects V2 items filtered by Status column, ordered by position
@@ -12,13 +14,29 @@ ascending. Returns machine-readable JSON.
 
 Options:
   --repo <owner/name>     Required. Repository to scope the project search.
-  --project <number|id>   Required. Project number (integer) or node ID.
+  --project <number|id>   Project number (integer) or node ID. When omitted,
+                          resolved from .devloops queue.projectNumber /
+                          queue.boardTitle.
   --column <name>         Filter items by Status column value (e.g. "Next Up").
-  --limit <n>             Return at most <n> items.
+  --limit <n>             Return at most <n> items (flat mode only).
+  --summary               Whole-board digest grouped by Status column, in board
+                          column order. Emits { ok, groups: { <status>: { count, items } } }.
+  --group-by status       Alias for --summary. Only "status" is supported.
+  --done-limit <n>        With --summary: cap the "Done" group's items array to
+                          <n> (or the last/terminal board column if no column is
+                          named "Done"). Count stays the true total; use 0 for
+                          counts only.
   --help, -h              Show this help.
 
+Grouping / aggregation is done via --summary (this mode). Do NOT pipe flat
+output through inline parsers (e.g. \`| python3\`) or reduce/group_by jq filters
+to build a per-status digest — the summary mode is the sanctioned one-call path.
+
+--summary is mutually exclusive with --column and --limit (both exit 1).
+
 Output (stdout):
-  JSON: { ok: true, items: [{ issueNumber, prNumber, title, url, itemId, contentId, status }, ...] }
+  flat:    { ok: true, items: [{ issueNumber, prNumber, title, url, itemId, contentId, status }, ...] }
+  summary: { ok: true, groups: { "<Status>": { count, items: [ <item>, ... ] }, ... } }
 
 ${JQ_OUTPUT_USAGE}
 
@@ -47,6 +65,9 @@ function parseCliArgs(argv) {
       project: { type: "string" },
       column: { type: "string" },
       limit: { type: "string" },
+      summary: { type: "boolean" },
+      "group-by": { type: "string" },
+      "done-limit": { type: "string" },
       help: { type: "boolean", short: "h" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
@@ -87,14 +108,33 @@ function parseCliArgs(argv) {
         args.limit = val;
         break;
       }
-      case "jq":
-        args.jq = requireValue(token, "--jq requires a filter");
+      case "summary":
+        if (token.value !== undefined) {
+          throw parseError(`Unknown flag: ${token.rawName}=${token.value}`);
+        }
+        args.summary = true;
+        break;
+      case "group-by": {
+        const val = requireValue(token, "--group-by requires a value (only \"status\" is supported)");
+        if (val !== "status") {
+          throw parseError(`--group-by only supports "status", got "${val}"`);
+        }
+        args.summary = true;
         break;
-      case "silent":
-        args.silent = true;
+      }
+      case "done-limit": {
+        const raw = requireValue(token, "--done-limit requires a non-negative integer");
+        const val = Number(raw);
+        if (!Number.isInteger(val) || val < 0) {
+          throw parseError(`--done-limit must be a non-negative integer, got "${raw}"`);
+        }
+        args.doneLimit = val;
         break;
-      default:
+      }
+      default: {
+        if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
         throw parseError(`Unknown flag: ${token.rawName}`);
+      }
     }
   }
   return args;
@@ -103,7 +143,6 @@ function parseCliArgs(argv) {
 
 const OWNER_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$/;
 const REPO_NAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9_.-]*[a-zA-Z0-9])?$/;
-const GLOBAL_NODE_ID_RE = /^[A-Za-z0-9_]+$/;
 
 function validateRepo(repo) {
   if (!repo || typeof repo !== "string") {
@@ -128,31 +167,6 @@ function validateRepo(repo) {
   return repo;
 }
 
-function parseProjectRef(raw) {
-  if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
-    throw Object.assign(new Error("--project is required"), { code: "INVALID_PROJECT" });
-  }
-  const trimmed = raw.trim();
-  const asNum = Number(trimmed);
-  if (Number.isInteger(asNum) && asNum > 0 && String(asNum) === trimmed) {
-    return { kind: "number", value: asNum };
-  }
-  // Reject bare "0" — valid node ID character but not a meaningful project reference
-  if (trimmed === "0") {
-    throw Object.assign(
-      new Error(`--project must be a positive integer or a node ID, got "${raw}"`),
-      { code: "INVALID_PROJECT" },
-    );
-  }
-  if (GLOBAL_NODE_ID_RE.test(trimmed)) {
-    return { kind: "id", value: trimmed };
-  }
-  throw Object.assign(
-    new Error(`--project must be a positive integer or a node ID, got "${raw}"`),
-    { code: "INVALID_PROJECT" },
-  );
-}
-
 // ── API helpers ──────────────────────────────────────────────────────────
 
 async function ghGraphql(query, vars, env, runChild = _runChild) {
@@ -369,34 +383,39 @@ async function main(args, { env = process.env, runChild } = {}) {
   const child = runChild ?? _runChild;
   const repo = validateRepo(args.repo);
   const [owner] = repo.split("/");
-  const projectRef = parseProjectRef(args.project);
+  const selector = resolveProjectSelector(args);
 
-  // 1. Resolve owner (user or org)
-  const { id: ownerId, kind: ownerKind } = await resolveOwner(owner, env, child);
+  // Mutual exclusion: --summary is the whole-board grouped view; --column/--limit
+  // are flat-mode knobs. Combining them is ambiguous.
+  if (args.summary && args.column) {
+    throw Object.assign(
+      new Error("--summary and --column are mutually exclusive (--column filters to one status; --summary groups the whole board)"),
+      { code: "INVALID_ARGS" },
+    );
+  }
+  if (args.summary && args.limit) {
+    throw Object.assign(
+      new Error("--summary and --limit are mutually exclusive; use --done-limit to cap the Done group (or terminal column if no Done column exists)"),
+      { code: "INVALID_ARGS" },
+    );
+  }
+  if (args.doneLimit !== undefined && !args.summary) {
+    throw Object.assign(
+      new Error("--done-limit only applies with --summary"),
+      { code: "INVALID_ARGS" },
+    );
+  }
+
+  // 1. Resolve owner (user or org).
+  // URI refs encode owner+kind directly; skip the API round-trip for owner resolution.
+  const projectOwner = selector.projectRef?.kind === "uri" ? selector.projectRef.owner : owner;
+  const ownerKind = selector.projectRef?.kind === "uri"
+    ? selector.projectRef.ownerKind
+    : (await resolveOwner(owner, env, child)).kind;
 
   // 2. Resolve project
-  let project;
-  if (projectRef.kind === "id") {
-    // Direct ID: use it directly (verify it belongs to owner via projects list)
-    const projects = await listAllProjects(owner, ownerKind, env, child);
-    project = projects.find((p) => p.id === projectRef.value);
-    if (!project) {
-      throw Object.assign(
-        new Error(`Project with ID "${projectRef.value}" not found under owner "${owner}"`),
-        { code: "PROJECT_NOT_FOUND" },
-      );
-    }
-  } else {
-    // By number
-    const projects = await listAllProjects(owner, ownerKind, env, child);
-    project = projects.find((p) => p.number === projectRef.value);
-    if (!project) {
-      throw Object.assign(
-        new Error(`Project number ${projectRef.value} not found under owner "${owner}"`),
-        { code: "PROJECT_NOT_FOUND" },
-      );
-    }
-  }
+  const projects = await listAllProjects(projectOwner, ownerKind, env, child);
+  const project = findProject(projects, selector, projectOwner);
 
   // 3. Resolve Status field and target column
   const fieldNodes = await listAllFields(project.id, env, child);
@@ -458,7 +477,35 @@ async function main(args, { env = process.env, runChild } = {}) {
     });
   }
 
-  // 5. Items are returned in position order from GraphQL. Apply limit.
+  // 5a. Summary mode: group by Status column in board option order.
+  if (args.summary) {
+    // Object.create(null): board option names are free text, so a column named
+    // "__proto__"/"constructor" must be an own key, not touch Object.prototype.
+    const groups = Object.create(null);
+    for (const option of statusField.options) {
+      groups[option.name] = { count: 0, items: [] };
+    }
+    for (const r of results) {
+      // Items with null status belong to no Status option, so they are excluded here — matches --column filtering behavior.
+      if (r.status === null) continue;
+      const group = groups[r.status];
+      if (!group) continue; // status value not among current board options
+      group.count += 1;
+      group.items.push(r);
+    }
+    if (args.doneLimit !== undefined) {
+      // Cap "Done" per the issue AC; if no column is literally named "Done",
+      // fall back to the last board option (conventionally the terminal column)
+      // so --done-limit is honest instead of a silent no-op.
+      const doneGroup = groups.Done ?? groups[statusField.options.at(-1)?.name];
+      if (doneGroup) {
+        doneGroup.items = doneGroup.items.slice(0, args.doneLimit);
+      }
+    }
+    return { ok: true, groups };
+  }
+
+  // 5b. Flat mode: items are returned in position order from GraphQL. Apply limit.
   const limited = args.limit ? results.slice(0, args.limit) : results;
 
   return {
@@ -469,7 +516,7 @@ async function main(args, { env = process.env, runChild } = {}) {
 
 // ── CLI entrypoint ──────────────────────────────────────────────────────
 
-async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd(), runChild } = {}) {
   let args;
   try {
     args = parseCliArgs(argv);
@@ -482,8 +529,12 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
     stdout.write(USAGE);
     return;
   }
+
+  // Resolve the board from .devloops when --project is absent.
+  applyDevloopsBoard(args, cwd);
+
   try {
-    const result = await main(args, { env });
+    const result = await main(args, { env, runChild });
     process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
   } catch (err) {
     stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
@@ -498,4 +549,4 @@ if (isDirectCliRun(import.meta.url)) {
   });
 }
 
-export { main };
+export { main, parseCliArgs, runCli };

package/scripts/projects/move-queue-item.mjs

@@ -1,20 +1,24 @@
 #!/usr/bin/env node
 import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
 import { runChild as _runChild } from "../_cli-primitives.mjs";
+import { resolveProjectSelector, findProject, applyDevloopsBoard } from "./_resolve-project.mjs";
 import { parseArgs } from "node:util";
-import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
-const USAGE = `Usage: dev-loops queue move --repo <owner/name> --project <number|id> --item <number|node-id> --to-column <name>
+const USAGE = `Usage: dev-loops queue move --repo <owner/name> --project <number|id|board-uri> --item <number|node-id> --to-column <name>
        (dev-loops project move … is a back-compat alias)
 
 Move a GitHub Projects V2 item between Status columns.
 
 Options:
-  --repo <owner/name>         Required. Repository to scope the project search.
-  --project <number|id>       Required. Project number (integer) or node ID.
-  --item <number|node-id>     Required. Item to move: issue/PR number, or project item node ID.
-  --to-column <name>          Required. Target Status column (e.g. "Next Up", "In Progress").
-  --help, -h                  Show this help.
+  --repo <owner/name>                 Required. Repository to scope the project search.
+  --project <number|id|board-uri>     Project number, node ID, or board URI
+                                      (e.g. https://github.com/users/me/projects/3).
+                                      When omitted, resolved from .devloops
+                                      queue.projectNumber / queue.boardTitle.
+  --item <number|node-id>             Required. Item to move: issue/PR number, or project item node ID.
+  --to-column <name>                  Required. Target Status column (e.g. "Next Up", "In Progress").
+  --help, -h                          Show this help.
 
 Output (stdout):
   JSON: { ok: true, item: { itemId, issueNumber, prNumber, previousColumn, newColumn } }
@@ -80,14 +84,10 @@ function parseCliArgs(argv) {
       case "to-column":
         args.toColumn = requireValue(token, "--to-column requires a value");
         break;
-      case "jq":
-        args.jq = requireValue(token, "--jq requires a filter");
-        break;
-      case "silent":
-        args.silent = true;
-        break;
-      default:
+      default: {
+        if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
         throw parseError(`Unknown flag: ${token.rawName}`);
+      }
     }
   }
   return args;
@@ -118,24 +118,6 @@ function validateRepo(repo) {
   return repo;
 }
 
-function parseProjectRef(raw) {
-  if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
-    throw Object.assign(new Error("--project is required"), { code: "INVALID_PROJECT" });
-  }
-  const trimmed = raw.trim();
-  const asNum = Number(trimmed);
-  if (Number.isInteger(asNum) && asNum > 0 && String(asNum) === trimmed) {
-    return { kind: "number", value: asNum };
-  }
-  if (trimmed === "0") {
-    throw Object.assign(new Error(`--project must be a positive integer or a node ID, got "${raw}"`), { code: "INVALID_PROJECT" });
-  }
-  if (GLOBAL_NODE_ID_RE.test(trimmed)) {
-    return { kind: "id", value: trimmed };
-  }
-  throw Object.assign(new Error(`--project must be a positive integer or a node ID, got "${raw}"`), { code: "INVALID_PROJECT" });
-}
-
 function parseItemRef(raw) {
   if (!raw || typeof raw !== "string" || raw.trim().length === 0) {
     throw Object.assign(new Error("--item is required"), { code: "INVALID_ITEM" });
@@ -390,30 +372,23 @@ async function main(args, { env = process.env, runChild } = {}) {
   const child = runChild ?? _runChild;
   const repo = validateRepo(args.repo);
   const [owner, repoName] = repo.split("/");
-  const projectRef = parseProjectRef(args.project);
+  const selector = resolveProjectSelector(args);
   const itemRef = parseItemRef(args.item);
   const toColumn = (args.toColumn ?? "").trim();
   if (!toColumn) {
     throw Object.assign(new Error("--to-column is required"), { code: "INVALID_COLUMN" });
   }
 
-  // 1. Resolve owner
-  const { id: ownerId, kind: ownerKind } = await resolveOwner(owner, env, child);
+  // 1. Resolve owner.
+  // URI refs encode owner+kind directly; skip the API round-trip for owner resolution.
+  const projectOwner = selector.projectRef?.kind === "uri" ? selector.projectRef.owner : owner;
+  const ownerKind = selector.projectRef?.kind === "uri"
+    ? selector.projectRef.ownerKind
+    : (await resolveOwner(owner, env, child)).kind;
 
   // 2. Resolve project
-  const projects = await listAllProjects(owner, ownerKind, env, child);
-  let project;
-  if (projectRef.kind === "id") {
-    project = projects.find((p) => p.id === projectRef.value);
-  } else {
-    project = projects.find((p) => p.number === projectRef.value);
-  }
-  if (!project) {
-    throw Object.assign(
-      new Error(`Project ${projectRef.kind === "id" ? `"${projectRef.value}"` : `number ${projectRef.value}`} not found under owner "${owner}"`),
-      { code: "PROJECT_NOT_FOUND" },
-    );
-  }
+  const projects = await listAllProjects(projectOwner, ownerKind, env, child);
+  const project = findProject(projects, selector, projectOwner);
 
   // 3. Resolve Status field and target column
   const fieldNodes = await listAllFields(project.id, env, child);
@@ -527,7 +502,7 @@ async function main(args, { env = process.env, runChild } = {}) {
 
 // ── CLI entrypoint ──────────────────────────────────────────────────────
 
-async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env } = {}) {
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd() } = {}) {
   let args;
   try {
     args = parseCliArgs(argv);
@@ -540,6 +515,10 @@ async function runCli(argv, { stdout = process.stdout, stderr = process.stderr,
     stdout.write(USAGE);
     return;
   }
+
+  // Resolve the board from .devloops when --project is absent.
+  applyDevloopsBoard(args, cwd);
+
   try {
     const result = await main(args, { env });
     process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });

package/scripts/projects/reconcile-queue.mjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+// Reconcile board Status columns from live GitHub state (#1069). For each queue
+// item it derives the target column from live facts (merged PR / closed issue →
+// Done; open ready non-draft PR → In Progress) and moves ONLY the items whose
+// derived column differs from their current Status. Backlog/Next Up ordering is
+// left untouched (items that derive null are skipped). Idempotent: a second run
+// over a converged board performs no moves.
+import { formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
+import { applyDevloopsBoard } from "./_resolve-project.mjs";
+import { main as listQueueItems } from "./list-queue-items.mjs";
+import { main as moveQueueItem } from "./move-queue-item.mjs";
+import { detectLinkedIssuePr } from "../github/detect-linked-issue-pr.mjs";
+import { planReconcile, loadStateColumnMap, LOGICAL_COLUMN } from "@dev-loops/core/loop/queue-board-sync";
+import { runChild as _runChild } from "../_cli-primitives.mjs";
+
+const USAGE = `Usage: dev-loops queue reconcile --repo <owner/name> [--project <number|id|board-uri>]
+       (dev-loops project reconcile … is a back-compat alias)
+
+Reconcile board Status columns from live GitHub state. Derives each item's
+target column from live GitHub facts (merged PR or closed issue → Done; an open,
+ready non-draft PR → In Progress) and moves ONLY the items whose derived column
+differs from their current Status. Backlog/Next Up ordering is left untouched.
+Idempotent: a second run over a converged board performs no moves. Best-effort:
+individual per-item failures are recorded but do not fail the run.
+
+Options:
+  --repo <owner/name>     Required. Repository to scope the project search.
+  --project <number|id|board-uri>
+                          Project number (integer), node ID, or board URI. When
+                          omitted, resolved from .devloops queue.projectNumber /
+                          queue.boardTitle.
+  --help, -h              Show this help.
+
+Output (stdout):
+  JSON: { ok: true, moved, unchanged, reconciled: [{ number, from, to, ok }, ...] }
+
+${JQ_OUTPUT_USAGE}
+
+Exit codes:
+  0 — success (reconcile is best-effort; per-item failures do not fail the run)
+  1 — usage or argument error
+  2 — GitHub API error / invalid --jq filter
+  3 — project, field, or column not found
+`.trim();
+
+function parseCliArgs(argv) {
+  const parseError = (message) => Object.assign(new Error(message), { usage: USAGE, code: "INVALID_ARGS" });
+  const requireValue = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw parseError(message);
+    }
+    return v;
+  };
+
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unexpected argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        if (token.value !== undefined) {
+          throw parseError(`Unknown flag: ${token.rawName}=${token.value}`);
+        }
+        args.help = true;
+        break;
+      case "repo":
+        args.repo = requireValue(token, "--repo requires a value (owner/name)");
+        break;
+      case "project":
+        args.project = requireValue(token, "--project requires a value (number or node ID)");
+        break;
+      default: {
+        if (matchJqOutputToken(token, args, (t) => requireValue(t, "--jq requires a filter"))) break;
+        throw parseError(`Unknown flag: ${token.rawName}`);
+      }
+    }
+  }
+  return args;
+}
+
+async function ghJson(argv, { env, runChild }) {
+  const child = runChild ?? _runChild;
+  const result = await child("gh", argv, env);
+  if (result.code !== 0) {
+    const detail = result.stderr?.trim() || `exit code ${result.code}`;
+    throw Object.assign(new Error(`gh command failed: ${detail}`), { code: "GH_API_ERROR" });
+  }
+  return parseJsonText(result.stdout);
+}
+
+// Real live-facts gatherer. For each item, resolve GitHub state into the fact
+// shape consumed by deriveReconcileColumn. Keyed by the stable item node id
+// (item.itemId), not the bare number, so a multi-repo board where two items
+// share a number (repo-A PR #5 vs repo-B issue #5) cannot collide. Per-item gh
+// failures are swallowed (best-effort): the item records all-null PR fields →
+// derives null → untouched.
+export async function gatherLiveFacts(items, repo, { env, runChild, doneColumn } = {}) {
+  const byItemId = new Map();
+  for (const item of items) {
+    const number = item.prNumber != null ? item.prNumber : item.issueNumber;
+    if (number == null || item.itemId == null) continue;
+    // Done is terminal for reconcile; planReconcile treats a missing fact as
+    // unchanged. At loop startup (doneColumn set) we skip the gh calls for
+    // Done items entirely — terminal + perf. An explicit `dev-loops queue
+    // reconcile` run passes no doneColumn, so Done items ARE gathered and a
+    // reopened/re-linked artifact can be moved back out of Done (recovery).
+    if (doneColumn != null && item.status === doneColumn) continue;
+    try {
+      if (item.prNumber != null) {
+        const pr = await ghJson(["pr", "view", String(item.prNumber), "--repo", repo, "--json", "state,isDraft,mergedAt"], { env, runChild });
+        byItemId.set(item.itemId, {
+          itemKind: "pr",
+          issueState: null,
+          prState: pr?.mergedAt ? "MERGED" : String(pr?.state ?? "").toUpperCase(),
+          prIsDraft: pr?.isDraft === true,
+        });
+      } else {
+        const issue = await ghJson(["issue", "view", String(item.issueNumber), "--repo", repo, "--json", "state"], { env, runChild });
+        const issueState = String(issue?.state ?? "").toUpperCase();
+        if (issueState === "CLOSED") {
+          byItemId.set(item.itemId, { itemKind: "issue", issueState: "CLOSED", prState: null, prIsDraft: null });
+          continue;
+        }
+        let prState = null;
+        let prIsDraft = null;
+        const linkage = await detectLinkedIssuePr({ repo, issue: item.issueNumber }, { env, runChild });
+        if (linkage?.hasOpenLinkedPr) {
+          const pr = await ghJson(["pr", "view", String(linkage.prNumber), "--repo", repo, "--json", "state,isDraft,mergedAt"], { env, runChild });
+          prState = pr?.mergedAt ? "MERGED" : String(pr?.state ?? "").toUpperCase();
+          prIsDraft = pr?.isDraft === true;
+        }
+        byItemId.set(item.itemId, { itemKind: "issue", issueState: "OPEN", prState, prIsDraft });
+      }
+    } catch {
+      // Best-effort: record inert facts so the item derives null (untouched).
+      byItemId.set(item.itemId, {
+        itemKind: item.prNumber != null ? "pr" : "issue",
+        issueState: item.prNumber != null ? null : "OPEN",
+        prState: null,
+        prIsDraft: null,
+      });
+    }
+  }
+  return byItemId;
+}
+
+async function main(args, { env = process.env, runChild, cwd = process.cwd(), listItems, gatherFacts, moveItem, skipTerminalColumn = false } = {}) {
+  // Resolve the board from .devloops when --project is absent. Idempotent (only
+  // mutates when args.project === undefined), so callers that reach main()
+  // directly (e.g. the loop-startup self-heal) still resolve the board.
+  applyDevloopsBoard(args, cwd);
+
+  const list = await (listItems ?? ((a, o) => listQueueItems(a, o)))(
+    { repo: args.repo, project: args.project, projectTitle: args.projectTitle },
+    { env, runChild },
+  );
+  const items = list.items ?? [];
+
+  const { columnNames } = loadStateColumnMap(cwd);
+
+  // Loop startup (skipTerminalColumn: true) skips Done items for speed. An
+  // explicit CLI run (default false) leaves doneColumn null so Done items are
+  // gathered and a reopened/re-linked artifact can be recovered out of Done.
+  const doneColumn = skipTerminalColumn ? columnNames[LOGICAL_COLUMN.DONE] : null;
+
+  const factsByItemId = await (gatherFacts ?? ((its, repo, o) => gatherLiveFacts(its, repo, o)))(
+    items,
+    args.repo,
+    { env, runChild, doneColumn },
+  );
+
+  const { moves, unchanged } = planReconcile(items, factsByItemId, columnNames);
+
+  const move = moveItem ?? ((a, o) => moveQueueItem(a, o));
+  const reconciled = [];
+  let moved = 0;
+  for (const m of moves) {
+    try {
+      // Move by the stable item node id (move-queue-item accepts a node id per
+      // its `--item <number|node-id>` contract) so a multi-repo number collision
+      // can never target the wrong item.
+      await move(
+        { repo: args.repo, project: args.project, projectTitle: args.projectTitle, item: m.itemId, toColumn: m.to },
+        { env, runChild },
+      );
+      reconciled.push({ number: m.number, from: m.from, to: m.to, ok: true });
+      moved += 1;
+    } catch (err) {
+      // Best-effort: a single failed move does not abort the reconcile loop.
+      reconciled.push({ number: m.number, from: m.from, to: m.to, ok: false, error: err?.message ?? "move failed" });
+    }
+  }
+
+  return { ok: true, moved, unchanged, reconciled };
+}
+
+function classifyExitCode(err) {
+  if (err.code === "INVALID_ARGS" || err.code === "INVALID_REPO" || err.code === "INVALID_PROJECT") return 1;
+  if (err.code === "PROJECT_NOT_FOUND" || err.code === "FIELD_NOT_FOUND" || err.code === "COLUMN_NOT_FOUND") return 3;
+  return 2;
+}
+
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, cwd = process.cwd(), runChild } = {}) {
+  let args;
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.help) {
+    stdout.write(USAGE);
+    return;
+  }
+
+  try {
+    const result = await main(args, { env, runChild, cwd });
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
+  } catch (err) {
+    stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
+    process.exitCode = classifyExitCode(err);
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(JSON.stringify({ ok: false, error: error.message, code: error.code ?? "UNKNOWN" }) + "\n");
+    process.exitCode = 2;
+  });
+}
+
+export { main, parseCliArgs, runCli };