@dev-loops/core 0.2.6 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "type": "module",
   "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
   "exports": {

package/src/bash-exit-one.mjs

@@ -1,5 +1,6 @@
 import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
+import { parseArgs } from "node:util";
 
 export const DEFAULT_OUTPUT_LIMIT = 4000;
 
@@ -79,23 +80,40 @@ export async function appendBashExitOneRecord(logPath, record) {
 }
 
 export function parseCliArgs(argv) {
-  const args = [...argv];
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      log: { type: "string" },
+      record: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
   let logPath;
   let recordJson;
 
-  while (args.length > 0) {
-    const token = args.shift();
-    if (token === "--log") {
-      logPath = args.shift();
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`Unknown argument: ${token.value}`);
+    }
+
+    if (token.kind !== "option") {
+      continue;
+    }
+
+    if (token.name === "log") {
+      logPath = token.value;
       continue;
     }
 
-    if (token === "--record") {
-      recordJson = args.shift();
+    if (token.name === "record") {
+      recordJson = token.value;
       continue;
     }
 
-    throw new Error(`Unknown argument: ${token}`);
+    throw new Error(`Unknown argument: ${token.rawName}`);
   }
 
   if (!logPath) {

package/src/claude/asset-generation.mjs

@@ -72,6 +72,22 @@ export function stripPiOnlyBlocks(body) {
     .replace(/\n{3,}/g, "\n\n");
 }
 
+/**
+ * Rewrite the Pi package-local CLI invocation into the Claude version-pinned `npx` form (#801,
+ * #833). The Pi runtime sources invoke the CLI as `node <dev-loops-package-root>/cli/index.mjs`
+ * (resolves unambiguously from the installed package). The Claude plugin does NOT bundle `cli/`,
+ * so for the generated tree those tokens become `npx dev-loops@<version>` — pinning the version
+ * keeps the CLI from drifting against the published plugin version (#833). The Pi-only
+ * package-root resolution note is removed separately by `stripPiOnlyBlocks`.
+ *
+ * @param {string} body
+ * @param {string} version dev-loops package version to pin (e.g. "0.2.6").
+ * @returns {string}
+ */
+export function rewriteCliInvocation(body, version) {
+  return String(body).split("node <dev-loops-package-root>/cli/index.mjs").join(`npx dev-loops@${version}`);
+}
+
 /**
  * Map a single Pi tool name to its Claude tool name(s).
  * @param {string} name
@@ -131,12 +147,12 @@ function normalizeToolList(value) {
 
 /**
  * Transform a canonical `agents/*.agent.md` into a Claude `.claude/agents/*.md` document.
- * @param {{ source: string, raw: string }} input
+ * @param {{ source: string, raw: string, version?: string }} input
  * @returns {string} Full generated file content.
  */
-export function transformAgent({ source, raw }) {
+export function transformAgent({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = stripPiOnlyBlocks(rawBody);
+  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
   const tools = mapTools(normalizeToolList(frontmatter.tools));
 
   const lines = ["---"];
@@ -155,12 +171,12 @@ export function transformAgent({ source, raw }) {
 
 /**
  * Transform a canonical `skills/<name>/SKILL.md` into a Claude `.claude/skills/<name>/SKILL.md`.
- * @param {{ source: string, raw: string }} input
+ * @param {{ source: string, raw: string, version?: string }} input
  * @returns {string} Full generated file content.
  */
-export function transformSkill({ source, raw }) {
+export function transformSkill({ source, raw, version = "latest" }) {
   const { frontmatter, body: rawBody } = splitFrontmatter(raw, source);
-  const body = stripPiOnlyBlocks(rawBody);
+  const body = rewriteCliInvocation(stripPiOnlyBlocks(rawBody), version);
   const tools = mapTools(normalizeToolList(frontmatter["allowed-tools"]));
 
   const lines = ["---"];

package/src/cli/primitives.mjs

@@ -1,10 +1,75 @@
 import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
 
 /**
  * Shared CLI primitives for arg parsing, validation, and child process execution.
  * Extracted from scripts/_cli-primitives.mjs per issue #548 Phase 2.
  */
 
+/**
+ * Parse argv with node:util parseArgs while preserving the legacy hand-rolled
+ * parser semantics that several callers depend on:
+ *
+ * - Unknown options/positionals throw `Unknown argument: <raw>`.
+ * - A string option whose value is missing or looks like another flag throws
+ *   `Missing value for <--flag>` (matching {@link requireOptionValue}).
+ *
+ * Returns a Map of canonical option name -> value (last-wins for repeats, which
+ * matches the legacy while/shift loops that simply reassigned on each match).
+ *
+ * @param {string[]} argv
+ * @param {Record<string, { type: "string" | "boolean", short?: string }>} options
+ * @param {(message: string) => Error} [parseError]
+ * @param {{ allowPositionals?: boolean, flagPattern?: RegExp }} [config]
+ * @returns {{ values: Map<string, string | boolean>, positionals: string[] }}
+ */
+export function parseCliTokens(argv, options, parseError = null, { allowPositionals = false, flagPattern = /^--/u } = {}) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options,
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  const values = new Map();
+  const positionals = [];
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      if (allowPositionals) {
+        positionals.push(token.value);
+        continue;
+      }
+      throw toCliError(`Unknown argument: ${token.value}`, parseError);
+    }
+
+    if (token.kind !== "option") {
+      continue;
+    }
+
+    const spec = options[token.name];
+    if (!spec) {
+      throw toCliError(`Unknown argument: ${token.rawName}`, parseError);
+    }
+
+    if (spec.type === "boolean") {
+      // A bare boolean flag carries no value (parseArgs → undefined) and means true;
+      // an explicit inline value (e.g. --flag=false) is honored rather than forced true.
+      values.set(token.name, token.value === undefined ? true : token.value !== "false");
+      continue;
+    }
+
+    const value = token.value;
+    if (typeof value !== "string" || value.length === 0 || flagPattern.test(value)) {
+      throw toCliError(`Missing value for ${token.rawName}`, parseError);
+    }
+    values.set(token.name, value);
+  }
+
+  return { values, positionals };
+}
+
 function toCliError(message, parseError) {
   if (typeof parseError === "function") {
     return parseError(message);
@@ -20,6 +85,25 @@ export function requireOptionValue(args, flag, parseError = null, { flagPattern
   return value;
 }
 
+/**
+ * Token-based equivalent of {@link requireOptionValue} for callers that have
+ * migrated to node:util parseArgs with `tokens: true`. Validates the value
+ * attached to a parsed option token, rejecting missing or flag-like values with
+ * the same `Missing value for <--flag>` message the legacy parsers emitted.
+ *
+ * @param {{ value?: string, rawName?: string }} token - a parseArgs option token
+ * @param {(message: string) => Error} [parseError]
+ * @param {{ flagPattern?: RegExp }} [config]
+ * @returns {string}
+ */
+export function requireTokenValue(token, parseError = null, { flagPattern = /^--/u } = {}) {
+  const value = token?.value;
+  if (typeof value !== "string" || value.length === 0 || flagPattern.test(value)) {
+    throw toCliError(`Missing value for ${token?.rawName}`, parseError);
+  }
+  return value;
+}
+
 export function parsePositiveInteger(value, flag, parseError = null) {
   if (!/^\d+$/.test(value) || Number(value) === 0) {
     throw toCliError(`${flag} must be a positive integer`, parseError);

package/src/github/review-threads.mjs

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
 
+import { parseCliTokens } from "../cli/primitives.mjs";
+
 function normalizeId(value, fallback) {
   if (typeof value === "string" && value.trim().length > 0) {
     return value.trim();
@@ -266,34 +268,14 @@ export function classifyReviewThreadsSignal(parsedResult, isCopilotLoginFn) {
 }
 
 
-function requireOptionValue(args, flag) {
-  const value = args.shift();
-
-  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-    throw new Error(`Missing value for ${flag}`);
-  }
-
-  return value;
-}
-
 export function parseCliArgs(argv) {
-  const args = [...argv];
-  const options = {
-    inputPath: undefined,
-  };
-
-  while (args.length > 0) {
-    const token = args.shift();
-
-    if (token === "--input") {
-      options.inputPath = requireOptionValue(args, "--input");
-      continue;
-    }
-
-    throw new Error(`Unknown argument: ${token}`);
-  }
+  const { values } = parseCliTokens(argv, {
+    input: { type: "string" },
+  });
 
-  return options;
+  return {
+    inputPath: values.get("input"),
+  };
 }
 
 export async function readInput({ inputPath, stdin = process.stdin } = {}) {

package/src/loop/copilot-loop-state.mjs

@@ -229,12 +229,6 @@ function isAutoRerequestEligible(snapshot, state) {
  */
 const VALID_SIGNAL_LEVELS = new Set(["high", "mid", "low"]);
 
-function hasExplicitCurrentHeadReviewSignal(raw) {
-  return Boolean(raw)
-    && typeof raw === "object"
-    && Object.prototype.hasOwnProperty.call(raw, "copilotReviewOnCurrentHead");
-}
-
 export function normalizeSnapshot(raw) {
   if (!raw || typeof raw !== "object") {
     throw new Error("Snapshot must be a non-null object");
@@ -351,34 +345,54 @@ export function interpretLoopState(snapshot, refinementConfig) {
 
   // Round-cap enforcement: when maxCopilotRounds is configured and the review-round
   // count has been exhausted, stop re-requests before entering fix/reply-resolve routing.
-  // Gating here (before unresolved-thread checks) ensures round cap takes priority over
-  // the normal fix loop, including unresolved threads, pending CI, and CI failures.
-  // Clean PRs are usually eligible for pre_approval_gate fallback; the only automatic
-  // exception is when the head has advanced since the last submitted Copilot review,
-  // all prior feedback is resolved, and CI is green/credibly green again. In that case
-  // the state re-opens to READY_TO_REREQUEST_REVIEW instead of terminating as clean fallback.
-  // Does NOT interrupt an in-flight review request (requested/already-requested).
+  // Gating here (before unresolved-thread checks) lets a CLEAN PR at the cap terminate as
+  // ROUND_CAP_CLEAN_FALLBACK ahead of the normal fix/wait routing. It does NOT blanket-
+  // override that routing: a NOT-clean PR (unresolved threads or non-green CI) with an
+  // in-flight request deliberately falls through to the normal fix/wait routing below
+  // (see the `!reviewInFlight` branch), and only a not-clean PR with no in-flight request
+  // hard-stops at ROUND_CAP_REACHED.
+  //
+  // Precedence at the cap: copilotReviewRoundCount counts COMPLETED rounds, so at
+  // `>= maxRounds` every permitted Copilot round is already done and any lingering
+  // in-flight request (requested/already-requested) is for a forbidden over-cap round.
+  // A stale Copilot reviewer assignment must therefore NOT block the clean fallback:
+  // when threads are clean and CI is green, route to ROUND_CAP_CLEAN_FALLBACK even if
+  // copilotReviewRequestStatus is requested/already-requested. Otherwise a lingering
+  // assignment would dead-end the loop at WAITING_FOR_COPILOT_REVIEW waiting for a
+  // review that can never come (no further round is permitted past the cap). The
+  // pre_approval_gate (current-head clean evidence, enforced elsewhere) reviews any
+  // post-cap head change, so this proceeds without skipping review of new code.
+  //
+  // An in-flight request only still blocks the cap block when the PR is NOT clean
+  // (unresolved threads or non-green CI) — that legitimately stays in the fix/wait
+  // routing below rather than terminating as a clean fallback.
+  //
+  // Head-advanced handling: even when the head has advanced past the last submitted
+  // Copilot review with clean threads and green CI, re-requesting another Copilot pass
+  // is forbidden at the cap, so this routes to ROUND_CAP_CLEAN_FALLBACK (not
+  // READY_TO_REREQUEST_REVIEW, which would trigger an illegal auto re-request). The
+  // pre_approval_gate handles the current head.
   const maxRounds = refinementConfig?.maxCopilotRounds;
   const reviewInFlight = s.copilotReviewRequestStatus === "requested"
     || s.copilotReviewRequestStatus === "already-requested";
   if (typeof maxRounds === "number" && maxRounds > 0
       && s.copilotReviewRoundCount >= maxRounds
-      && !reviewInFlight
       && state !== STATE.NO_PR && state !== STATE.DONE
       && state !== STATE.PR_DRAFT && state !== STATE.REVIEW_REQUEST_UNAVAILABLE
       && state !== STATE.BLOCKED_NEEDS_USER_DECISION) {
     const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen";
     const cleanThreads = s.unresolvedThreadCount === 0;
-    const headAdvancedSinceLastSubmittedCopilotReview = s.copilotReviewPresent
-      && hasExplicitCurrentHeadReviewSignal(snapshot)
-      && !s.copilotReviewOnCurrentHead;
-    if (cleanThreads && ciClean && headAdvancedSinceLastSubmittedCopilotReview) {
-      state = STATE.READY_TO_REREQUEST_REVIEW;
-    } else if (cleanThreads && ciClean) {
+    if (cleanThreads && ciClean) {
+      // Clean PR at the cap: proceed to the pre_approval_gate fallback regardless of a
+      // lingering Copilot reviewer assignment or an advanced head — no further Copilot
+      // round is permitted, so never re-open for re-request or wait on Copilot here.
       state = STATE.ROUND_CAP_CLEAN_FALLBACK;
-    } else {
+    } else if (!reviewInFlight) {
+      // Not clean and no in-flight request: hard stop at the cap.
       state = STATE.ROUND_CAP_REACHED;
     }
+    // Not clean WITH an in-flight request: leave state undecided so the normal
+    // fix/reply-resolve/wait routing below handles it (do not force a clean fallback).
   }
 
   if (state === undefined) {

package/src/loop/phase-files.mjs

@@ -1,6 +1,8 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 
+import { parseCliTokens } from "../cli/primitives.mjs";
+
 export function createDefaultPhaseManifest(phase) {
   return {
     phase,
@@ -134,45 +136,19 @@ export async function ensurePhaseFiles(projectRoot, phase, patch = {}) {
   };
 }
 
-function requireOptionValue(args, flag) {
-  const value = args.shift();
-
-  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
-    throw new Error(`Missing value for ${flag}`);
-  }
-
-  return value;
-}
-
 export function parseCliArgs(argv) {
-  const args = [...argv];
+  const { values } = parseCliTokens(argv, {
+    "project-root": { type: "string" },
+    phase: { type: "string" },
+    patch: { type: "string" },
+  });
+
   const options = {
-    projectRoot: process.cwd(),
-    phase: undefined,
-    patch: {},
+    projectRoot: values.has("project-root") ? values.get("project-root") : process.cwd(),
+    phase: values.get("phase"),
+    patch: values.has("patch") ? JSON.parse(values.get("patch")) : {},
   };
 
-  while (args.length > 0) {
-    const token = args.shift();
-
-    if (token === "--project-root") {
-      options.projectRoot = requireOptionValue(args, "--project-root");
-      continue;
-    }
-
-    if (token === "--phase") {
-      options.phase = requireOptionValue(args, "--phase");
-      continue;
-    }
-
-    if (token === "--patch") {
-      options.patch = JSON.parse(requireOptionValue(args, "--patch"));
-      continue;
-    }
-
-    throw new Error(`Unknown argument: ${token}`);
-  }
-
   if (!options.phase) {
     throw new Error("Missing required --phase <phase-name> argument");
   }

package/src/loop/queue-board-sync.mjs

@@ -6,6 +6,107 @@ import { main as moveQueueItemMain } from "../../../../scripts/projects/move-que
 
 const DEFAULT_NON_SUCCESS_COLUMN = "Backlog";
 
+// ── State → board column mapping (AC1, AC3, AC5) ─────────────────────────
+//
+// The mapping is intentionally stateless: it is a pure function of the loop
+// state. Because of that, a reverted loop state (e.g. a merged PR reopened, or
+// a ready PR demoted back to draft) maps backward to the earlier column for
+// free (AC5) — there is no persisted "furthest reached" column to unwind.
+
+/** Logical board columns. Display names are config-driven (AC3). */
+export const LOGICAL_COLUMN = Object.freeze({
+  NEXT_UP: "next_up",
+  IN_PROGRESS: "in_progress",
+  READY_FOR_REVIEW: "ready_for_review",
+  DONE: "done",
+});
+
+/** Allow-list of recognized logical column tokens (for config validation). */
+const KNOWN_LOGICAL_COLUMNS = new Set(Object.values(LOGICAL_COLUMN));
+
+/** Keys that must never be copied from untrusted config (prototype pollution). */
+const DANGEROUS_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+/** Default display name for each logical column (AC1 values). */
+export const DEFAULT_STATE_COLUMN_NAMES = Object.freeze({
+  [LOGICAL_COLUMN.NEXT_UP]: "Next Up",
+  [LOGICAL_COLUMN.IN_PROGRESS]: "In Progress",
+  // Ready for Review is opt-in: by default it resolves to In Progress so that
+  // final_approval_ready keeps "In Progress" unless a board configures it.
+  [LOGICAL_COLUMN.READY_FOR_REVIEW]: "In Progress",
+  [LOGICAL_COLUMN.DONE]: "Done",
+});
+
+/**
+ * Default loop-state → logical-column map. Covers both the lifecycle states
+ * (lifecycle-state.mjs) and the inner Copilot loop states (copilot-loop-state.mjs),
+ * plus the conceptual names used by issue #793. Unknown states fall back to
+ * IN_PROGRESS (a safe, visible "work is happening" column) rather than throwing.
+ */
+export const DEFAULT_STATE_LOGICAL_MAP = Object.freeze({
+  // Next Up — work not yet actively in flight
+  issue_opened: LOGICAL_COLUMN.NEXT_UP,
+  issue_intake: LOGICAL_COLUMN.NEXT_UP,
+  refinement: LOGICAL_COLUMN.NEXT_UP,
+  no_pr: LOGICAL_COLUMN.NEXT_UP,
+  pr_draft: LOGICAL_COLUMN.NEXT_UP,
+
+  // In Progress — active implementation / review / feedback resolution
+  implementation: LOGICAL_COLUMN.IN_PROGRESS,
+  // Tolerated alias for `implementation` (conceptual name from issue #793);
+  // the queue driver passes the real `implementation` lifecycle state.
+  local_implementation_active: LOGICAL_COLUMN.IN_PROGRESS,
+  draft_gate: LOGICAL_COLUMN.IN_PROGRESS,
+  pr_ready_no_feedback: LOGICAL_COLUMN.IN_PROGRESS,
+  feedback_resolution: LOGICAL_COLUMN.IN_PROGRESS,
+  copilot_review: LOGICAL_COLUMN.IN_PROGRESS,
+  waiting_for_copilot_review: LOGICAL_COLUMN.IN_PROGRESS,
+  ready_to_rerequest_review: LOGICAL_COLUMN.IN_PROGRESS,
+  unresolved_feedback_present: LOGICAL_COLUMN.IN_PROGRESS,
+  already_fixed_needs_reply_resolve: LOGICAL_COLUMN.IN_PROGRESS,
+  waiting_for_ci: LOGICAL_COLUMN.IN_PROGRESS,
+  review_request_unavailable: LOGICAL_COLUMN.IN_PROGRESS,
+  round_cap_reached: LOGICAL_COLUMN.IN_PROGRESS,
+  round_cap_clean_fallback: LOGICAL_COLUMN.IN_PROGRESS,
+  internal_tooling_direct_gate: LOGICAL_COLUMN.IN_PROGRESS,
+  low_signal_converged: LOGICAL_COLUMN.IN_PROGRESS,
+  blocked_needs_user_decision: LOGICAL_COLUMN.IN_PROGRESS,
+
+  // Ready for Review — final approval gate. Resolves to In Progress unless a
+  // board configures a distinct "Ready for Review" column name (AC1).
+  pre_approval_gate: LOGICAL_COLUMN.READY_FOR_REVIEW,
+  final_approval_ready: LOGICAL_COLUMN.READY_FOR_REVIEW,
+
+  // Done — terminal (lifecycle MERGE = "merge", queue terminal = "done")
+  merge: LOGICAL_COLUMN.DONE,
+  done: LOGICAL_COLUMN.DONE,
+  // Tolerated aliases (conceptual names from issue #793).
+  merged: LOGICAL_COLUMN.DONE,
+  issue_closed: LOGICAL_COLUMN.DONE,
+});
+
+/** Safe default logical column for any state we do not explicitly map. */
+const DEFAULT_LOGICAL_COLUMN = LOGICAL_COLUMN.IN_PROGRESS;
+
+/**
+ * Pure mapping: loop state → board column display name.
+ *
+ * @param {string|null|undefined} loopState - a lifecycle or inner loop state
+ *   name. `null`, `undefined`, and any unrecognized value fall through to the
+ *   safe default logical column (IN_PROGRESS).
+ * @param {{stateColumnMap?:Object, columnNames?:Object}} [mapping]
+ *   Optional overrides. `stateColumnMap` overrides state→logical-column;
+ *   `columnNames` overrides logical-column→display-name. Both fall back to
+ *   the AC1 defaults.
+ * @returns {string} the target board column display name.
+ */
+export function boardColumnForLoopState(loopState, mapping = {}) {
+  const stateMap = { ...DEFAULT_STATE_LOGICAL_MAP, ...(mapping.stateColumnMap ?? {}) };
+  const columnNames = { ...DEFAULT_STATE_COLUMN_NAMES, ...(mapping.columnNames ?? {}) };
+  const logical = stateMap[loopState] ?? DEFAULT_LOGICAL_COLUMN;
+  return columnNames[logical] ?? columnNames[DEFAULT_LOGICAL_COLUMN];
+}
+
 // ── Local config loader ─────────────────────────────────────────────────
 
 function readDevloopsSettings(repoRoot) {
@@ -46,6 +147,62 @@ export function loadBoardConfig(repoRoot) {
   return { enabled: false };
 }
 
+/**
+ * Load the config-driven state→column mapping from `.devloops` `queue` (AC3).
+ *
+ * Reads two optional config keys, both gated behind the same opt-in `queue`
+ * section as `loadBoardConfig` (AC2/AC6):
+ *   - `queue.statusColumns`  — logical-column → display-name overrides
+ *     (keys: next_up, in_progress, ready_for_review, done)
+ *   - `queue.stateColumnMap` — loop-state → logical-column overrides
+ *
+ * Returns a `{ stateColumnMap, columnNames }` shape consumable by
+ * `boardColumnForLoopState`. Missing config yields the AC1 defaults.
+ *
+ * Hardened against untrusted `.devloops` input:
+ *   - `statusColumns` keys are allow-listed to the known logical columns;
+ *     unrecognized keys are ignored.
+ *   - `stateColumnMap` entries whose value is not a known logical column are
+ *     ignored.
+ *   - Dangerous keys (`__proto__`, `prototype`, `constructor`) are skipped and
+ *     results are built on null-prototype objects, so a malicious config key
+ *     cannot pollute Object.prototype.
+ */
+export function loadStateColumnMap(repoRoot) {
+  const { settings: queue } = readDevloopsSettings(repoRoot);
+  // Null-prototype objects: untrusted keys can never reach Object.prototype.
+  const columnNames = Object.assign(Object.create(null), DEFAULT_STATE_COLUMN_NAMES);
+  const stateColumnMap = Object.create(null);
+
+  const statusColumns = queue?.statusColumns;
+  if (statusColumns && typeof statusColumns === "object") {
+    for (const logical of Object.keys(statusColumns)) {
+      if (DANGEROUS_KEYS.has(logical)) continue;
+      // Allow-list: only recognized logical columns may be renamed.
+      if (!KNOWN_LOGICAL_COLUMNS.has(logical)) continue;
+      const name = statusColumns[logical];
+      if (typeof name === "string" && name.trim().length > 0) {
+        columnNames[logical] = name.trim();
+      }
+    }
+  }
+
+  const stateMap = queue?.stateColumnMap;
+  if (stateMap && typeof stateMap === "object") {
+    for (const state of Object.keys(stateMap)) {
+      if (DANGEROUS_KEYS.has(state)) continue;
+      const logical = stateMap[state];
+      // Ignore values that are not a recognized logical column.
+      if (typeof logical !== "string") continue;
+      const trimmed = logical.trim();
+      if (!KNOWN_LOGICAL_COLUMNS.has(trimmed)) continue;
+      stateColumnMap[state] = trimmed;
+    }
+  }
+
+  return { columnNames, stateColumnMap };
+}
+
 // ── Minimal project lookup (read-only, no create/repair) ────────────────
 
 const GET_USER_ID = [
@@ -187,6 +344,14 @@ export async function syncBoardStatus(
   env = process.env,
   dependencies = {},
 ) {
+  // AC4: the not-on-board / fail-open path is a logged no-op. Default to
+  // console.error so it logs in real runs; tests inject their own stub. The
+  // log fires at most once per syncBoardStatus call (single catch, no internal
+  // retry), so it cannot spam.
+  const log = typeof dependencies.log === "function"
+    ? dependencies.log
+    : (msg) => console.error(msg);
+
   const config = loadBoardConfig(repoRoot);
   if (!config.enabled) {
     return { ok: true, skipped: true, reason: config.reason ?? "board not configured" };
@@ -210,7 +375,19 @@ export async function syncBoardStatus(
     );
     return { ok: true, skipped: false, result };
   } catch (err) {
-    return { ok: true, skipped: true, reason: err.message ?? "board sync failed" };
+    // Fail-open: a board hiccup (rate limit, missing column, item not on board)
+    // must never break the loop.
+    const reason = err?.message ?? "board sync failed";
+    // AC4: the explicit "item not on board" case is a clean, logged no-op.
+    // Other fail-open failures (rate limit, missing column, etc.) get a
+    // distinct, distinguishable message so they are not conflated with AC4.
+    const notOnBoard = err?.code === "ITEM_NOT_FOUND" || err?.code === "ITEM_NOT_ON_BOARD";
+    if (notOnBoard) {
+      log(`[board-sync] no-op: item ${itemNumber} is not on the board (${reason})`);
+    } else {
+      log(`[board-sync] sync failed (fail-open) for item ${itemNumber} → "${targetColumn}": ${reason}`);
+    }
+    return { ok: true, skipped: true, reason };
   }
 }
 

package/src/loop/queue-driver.mjs

@@ -13,7 +13,12 @@ import {
   RECOVERABLE_FAILURES,
   appendBugIssue,
 } from "./queue-state.mjs";
-import { syncBoardStatus, nonSuccessBoardColumn } from "./queue-board-sync.mjs";
+import {
+  syncBoardStatus,
+  nonSuccessBoardColumn,
+  boardColumnForLoopState,
+  loadStateColumnMap,
+} from "./queue-board-sync.mjs";
 import { resolveNextUpOrder } from "./queue-board-ordering.mjs";
 
 export const DEFAULT_QUEUE_DRIVER_OPTIONS = {
@@ -52,6 +57,19 @@ export async function runQueue(repoRoot, repo, options = {}) {
   const opts = { ...DEFAULT_QUEUE_DRIVER_OPTIONS, ...options };
   const queue = await readQueue(repoRoot);
 
+  // Config-driven loop-state → board-column mapping (#793, AC1/AC3). Loaded
+  // once per run; resolves logical columns to configured display names, with
+  // the AC1 defaults when no `queue.statusColumns`/`queue.stateColumnMap` is set.
+  const stateColumnMap = loadStateColumnMap(repoRoot);
+  const columnFor = (loopState) => boardColumnForLoopState(loopState, stateColumnMap);
+
+  // Per-item dedup: a single run may resolve consecutive loop states to the
+  // same display column (e.g. implementation → final_approval_ready both
+  // default to "In Progress"). Skip the redundant board write/API call when the
+  // target column is unchanged for that item; a genuinely different column
+  // (e.g. a configured "Ready for Review") still syncs. (#793 round-1 #1)
+  const lastSyncedColumn = new Map();
+
   // Optional board-aware ordering: fetch Next Up order before processing.
   // Fail-open: if the board is unreachable, orderHint stays empty and the
   // driver falls back to the existing queue order.
@@ -95,15 +113,26 @@ export async function runQueue(repoRoot, repo, options = {}) {
       boardSync.push(r);
       return r;
     };
+    // Sync a target to a column, short-circuiting (no API call) when the column
+    // is unchanged from the last sync for the same item in this run.
+    const syncColumn = async (target, column) => {
+      if (lastSyncedColumn.get(target) === column) {
+        return recordBoardSync(Promise.resolve({
+          ok: true, skipped: true, reason: "column unchanged",
+        }));
+      }
+      const r = await recordBoardSync(syncBoardStatus(
+        repo, repoRoot, target, column, opts.env ?? process.env, boardSyncDeps,
+      ));
+      // Only remember the column when the move actually landed, so a fail-open
+      // skip does not suppress a later retry to the same column.
+      if (r.ok && r.skipped !== true) lastSyncedColumn.set(target, column);
+      return r;
+    };
 
-    await recordBoardSync(syncBoardStatus(
-      repo,
-      repoRoot,
-      entry.target,
-      "In Progress",
-      opts.env ?? process.env,
-      boardSyncDeps,
-    ));
+    // Entry has been picked up and is actively running: implementation phase
+    // (real lifecycle state, lifecycle-state.mjs LIFECYCLE_STATE.IMPLEMENTATION).
+    await syncColumn(entry.target, columnFor("implementation"));
 
     try {
       const entryResult = opts.runEntry
@@ -117,12 +146,18 @@ export async function runQueue(repoRoot, repo, options = {}) {
           if (opts.mergeAuthorized) {
             await doTransition(entry, "merging", queue, repoRoot, opts);
             await doTransition(entry, "done", queue, repoRoot, opts, { retrospectiveWritten: true });
-            await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, "Done", opts.env ?? process.env, boardSyncDeps));
+            await syncColumn(entry.target, columnFor("done"));
+          } else {
+            // PR is up with gates passing but merge is not authorized: the work
+            // is awaiting final approval/merge. Map to the final-approval column
+            // (configured "Ready for Review" if present, else "In Progress").
+            // Deduped: when this resolves to the same column already synced for
+            // this item, no extra board write/API call is made.
+            await syncColumn(entry.target, columnFor("final_approval_ready"));
           }
-          // else: stays at gates_passing for future merge run
         } else {
           await doTransition(entry, "done", queue, repoRoot, opts);
-          await recordBoardSync(syncBoardStatus(repo, repoRoot, entry.target, "Done", opts.env ?? process.env, boardSyncDeps));
+          await syncColumn(entry.target, columnFor("done"));
         }
         results.push({ target: entry.target, ok: true, entry: snapshotEntry(entry), boardSync });
       } else {