dev-loops 0.6.0 → 0.7.1

package/scripts/refine/promote-plan.mjs

@@ -17,6 +17,7 @@ import {
   writeLinkedPrNumber,
   PLAN_FILE_PROMOTE_ACTION,
 } from "@dev-loops/core/loop/plan-file-promote-contract";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const CREATE_PR_PATH = fileURLToPath(new URL("../github/create-pr.mjs", import.meta.url));
 
@@ -42,9 +43,14 @@ Optional:
   --branch <name>     Branch name to commit the plan on (default: derived from the plan path)
   --json              Machine-readable JSON output
   --help              Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)
+
 Exit codes:
   0  Promotion succeeded (or idempotent no-op for an already-linked plan)
-  1  Argument error, or fail-closed (plan not ready / git / PR-create failure); no issue ever created`.trim();
+  1  Argument error, or fail-closed (plan not ready / git / PR-create failure); no issue ever created
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -57,6 +63,7 @@ export function parsePromotePlanCliArgs(argv) {
       base: { type: "string" },
       branch: { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -88,6 +95,7 @@ export function parsePromotePlanCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.planFile !== "string" || options.planFile.trim().length === 0) {
@@ -123,11 +131,14 @@ function parsePrNumberFromGhOutput(text) {
   return match ? Number.parseInt(match[1], 10) : null;
 }
 
-function emit(stdout, json, summary, humanLines) {
-  if (json) {
-    stdout.write(`${JSON.stringify(summary)}\n`);
+// Sets process.exitCode from `summary.ok` (0/1), or the shared --jq/--silent
+// contract's exit code (0/1/2) when --json + --jq/--silent are in play.
+function emit(stdout, options, summary, humanLines) {
+  if (options.json) {
+    process.exitCode = emitResult(summary, { jq: options.jq, silent: options.silent, stdout });
   } else {
     stdout.write(`${humanLines.join("\n")}\n`);
+    process.exitCode = summary.ok ? 0 : 1;
   }
 }
 
@@ -161,8 +172,7 @@ export async function runCli(argv = process.argv.slice(2), {
   if (!decision.ok) {
     // Fail closed: no git, no gh, no issue — surface the reason and stop.
     const summary = { ok: false, reason: decision.reason, planFileIntakeState: decision.planFileIntakeState ?? null };
-    emit(stdout, options.json, summary, [`promote-plan: FAIL (${decision.reason})`]);
-    process.exitCode = 1;
+    emit(stdout, options, summary, [`promote-plan: FAIL (${decision.reason})`]);
     return summary;
   }
 
@@ -174,7 +184,7 @@ export async function runCli(argv = process.argv.slice(2), {
       planFile: planPath,
       prNumber: decision.existingPrNumber,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       "promote-plan: PASS (already promoted)",
       `  plan: ${planPath}`,
       `  pr: #${decision.existingPrNumber} (existing; opened nothing)`,
@@ -207,8 +217,7 @@ export async function runCli(argv = process.argv.slice(2), {
 
   const fail = (reason, detail) => {
     const summary = { ok: false, reason, detail: detail ?? null, planFile: planPath };
-    emit(stdout, options.json, summary, [`promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`]);
-    process.exitCode = 1;
+    emit(stdout, options, summary, [`promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`]);
     return summary;
   };
 
@@ -294,11 +303,10 @@ export async function runCli(argv = process.argv.slice(2), {
       branch,
       recovery: `gh pr create failed, so no PR was opened, but the plan is committed and branch ${branch} is pushed. Re-run promote-plan to recover: the commit step is idempotent (skips when nothing is staged) and the push is idempotent, so a clean re-run will retry opening the PR.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (pr_create_failed)${detail ? `: ${detail}` : ""}`,
       `  branch: ${branch} (committed and pushed; no PR opened — re-run promote-plan to recover, it is idempotent and will retry opening the PR)`,
     ]);
-    process.exitCode = 1;
     return summary;
   }
   const prNumber = parsePrNumberFromGhOutput(prCreate.stdout);
@@ -315,11 +323,10 @@ export async function runCli(argv = process.argv.slice(2), {
       branch,
       recovery: `A draft PR was opened on branch ${branch} but its number could not be parsed from gh output. Find it with: gh pr list --head "${branch}" --json number,url. Then record the link with: node scripts/refine/promote-plan.mjs is idempotent only once the front-matter prNumber is set, so add it manually (prNumber: <n>) and commit ${planDocRelPath}.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (pr_number_unparseable)`,
       `  branch: ${branch} (a draft PR is open; its number could not be parsed — recover via 'gh pr list --head "${branch}"')`,
     ]);
-    process.exitCode = 1;
     return summary;
   }
 
@@ -340,11 +347,10 @@ export async function runCli(argv = process.argv.slice(2), {
       prNumber,
       recovery: `PR #${prNumber} is open but the plan->PR link commit failed. ${planDocRelPath} now carries prNumber: ${prNumber} in its front-matter; record the link with: git add -- "${planDocRelPath}" && git commit -m "docs(plan): link to PR #${prNumber}" && git push.`,
     };
-    emit(stdout, options.json, summary, [
+    emit(stdout, options, summary, [
       `promote-plan: FAIL (${reason})${detail ? `: ${detail}` : ""}`,
       `  pr: #${prNumber} (open; plan->PR link NOT committed — recover manually)`,
     ]);
-    process.exitCode = 1;
     return summary;
   };
   const linkedMarkdown = writeLinkedPrNumber(markdownText, prNumber);
@@ -370,7 +376,7 @@ export async function runCli(argv = process.argv.slice(2), {
     branch,
     prNumber,
   };
-  emit(stdout, options.json, summary, [
+  emit(stdout, options, summary, [
     "promote-plan: PASS",
     `  plan: ${planPath}`,
     `  branch: ${branch}`,

package/scripts/refine/prose-linkage-detector.mjs

@@ -80,7 +80,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runProseLinkageDetector(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/refine-plan-file.mjs

@@ -13,6 +13,7 @@ import {
 } from "@dev-loops/core/loop/plan-file-refine-contract";
 import { PLAN_FILE_REFINEMENT_SECTIONS } from "@dev-loops/core/loop/plan-file-intake-contract";
 import { classifyDocsGrillFinding } from "../loop/docs-grill-contract.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   refine-plan-file.mjs --plan-file <path> --payload <path> [--json]
@@ -31,9 +32,14 @@ Required:
 Optional:
   --json              Machine-readable JSON output
   --help              Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)
+
 Exit codes:
   0  Refinement succeeded; plan written in place; stop for local human review
-  1  Argument error, or fail-closed refine/grill/ambiguous state (no write)`.trim();
+  1  Argument error, or fail-closed refine/grill/ambiguous state (no write)
+  2  Invalid --jq filter`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -45,6 +51,7 @@ export function parseRefinePlanFileCliArgs(argv) {
       "plan-file": { type: "string" },
       payload: { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -72,6 +79,7 @@ export function parseRefinePlanFileCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (typeof options.planFile !== "string" || options.planFile.trim().length === 0) {
@@ -123,11 +131,12 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   if (!result.ok) {
     // Fail closed: surface the reason, do not write, do not advance, do not promote.
     if (options.json) {
-      stdout.write(`${JSON.stringify({ ok: false, reason: result.reason, planFileIntakeState: result.planFileIntakeState ?? null })}\n`);
+      const failurePayload = { ok: false, reason: result.reason, planFileIntakeState: result.planFileIntakeState ?? null };
+      process.exitCode = emitResult(failurePayload, { jq: options.jq, silent: options.silent, stdout });
     } else {
       stdout.write(`refine-plan-file: FAIL (${result.reason})\n`);
+      process.exitCode = 1;
     }
-    process.exitCode = 1;
     return result;
   }
 
@@ -142,7 +151,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
     grillDispositions: result.grillDispositions,
   };
   if (options.json) {
-    stdout.write(`${JSON.stringify(summary)}\n`);
+    process.exitCode = emitResult(summary, { jq: options.jq, silent: options.silent, stdout });
   } else {
     stdout.write(
       [

package/scripts/refine/refinement-completeness-checker.mjs

@@ -76,7 +76,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runRefinementCompletenessChecker(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/scaffold-spike-file.mjs

@@ -14,7 +14,7 @@ import path from "node:path";
 import { parseArgs } from "node:util";
 
 import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-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";
 import { SPIKE_FILE_EXPLORATION_SECTIONS } from "./validate-spike-file.mjs";
 
 // Placeholder bodies the operator fills in during the spike. Non-empty so the
@@ -113,14 +113,10 @@ function parseCliArgs(argv) {
       case "out":
         args.out = requireValue(token, "--out requires a value (path)");
         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;

package/scripts/refine/scope-boundary-cross-checker.mjs

@@ -151,7 +151,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runScopeBoundaryCrossChecker(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/tree-integrity-validator.mjs

@@ -199,7 +199,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const tree = await loadTreeFromInput(options.input);
   const result = runTreeIntegrityValidator(tree);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/validate-plan-file.mjs

@@ -52,7 +52,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const markdownText = await readFile(options.input, "utf8");
   const result = validatePlanFile(markdownText);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/validate-spike-file.mjs

@@ -75,7 +75,7 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   }
   const markdownText = await readFile(options.input, "utf8");
   const result = validateSpikeFile(markdownText);
-  writeCheckerOutput(result, { stdout, json: options.json });
+  process.exitCode = writeCheckerOutput(result, { stdout, json: options.json, jq: options.jq, silent: options.silent });
   return result;
 }
 

package/scripts/refine/verify.mjs

@@ -9,6 +9,7 @@ import { runProseLinkageDetector } from "./prose-linkage-detector.mjs";
 import { runScopeBoundaryCrossChecker } from "./scope-boundary-cross-checker.mjs";
 import { runRefinementCompletenessChecker } from "./refinement-completeness-checker.mjs";
 import { runTreeIntegrityValidator } from "./tree-integrity-validator.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult, matchJqOutputToken } from "../lib/jq-output.mjs";
 
 const USAGE = `Usage:
   dev-loops refine verify --issue <number> [--repo <owner/name>] [--json]
@@ -26,7 +27,10 @@ Required (exactly one mode):
 Optional:
   --repo <owner/name>       Repository slug for online mode
   --json                    Machine-readable JSON output (default: human-readable summary)
-  --help                    Show this help`.trim();
+  --help                    Show this help
+
+${JQ_OUTPUT_USAGE}
+(--jq/--silent only apply together with --json; the default text output is unaffected.)`.trim();
 
 const parseError = buildParseError(USAGE);
 
@@ -39,6 +43,7 @@ export function parseRefineVerifyCliArgs(argv) {
       repo: { type: "string" },
       input: { type: "string" },
       json: { type: "boolean" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -79,6 +84,7 @@ export function parseRefineVerifyCliArgs(argv) {
       options.json = true;
       continue;
     }
+    if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
 
@@ -177,13 +183,12 @@ export async function runCli(
   };
 
   if (options.json) {
-    stdout.write(`${JSON.stringify(payload)}\n`);
+    process.exitCode = emitResult(payload, { jq: options.jq, silent: options.silent, stdout });
   } else {
     writeHumanOutput(result, tree, { stdout });
-  }
-
-  if (!result.ok) {
-    process.exitCode = 1;
+    if (!result.ok) {
+      process.exitCode = 1;
+    }
   }
   return payload;
 }

package/scripts/release/assert-core-dependency-version.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+/**
+ * Release-time guard: fail closed when the published `dev-loops` package's
+ * `@dev-loops/core` dependency does not resolve to the same major.minor as the
+ * version being released. This is the check that would have caught #1033
+ * (`dev-loops@0.6.2` shipping `@dev-loops/core@^0.2.6`).
+ *
+ * Runs in release.yml BEFORE the GitHub Release is created, so a mismatched
+ * manifest never becomes a release (and never fires npm-publish). release.yml
+ * has no `npm ci`, so this script imports only `node:` builtins — a workspace
+ * import here would ERR_MODULE_NOT_FOUND and skip the guard entirely (same
+ * constraint as extract-changelog-section.mjs).
+ *
+ * Usage:
+ *   node scripts/release/assert-core-dependency-version.mjs [--release-version <v>] [--manifest <path>]
+ *
+ * --release-version defaults to the manifest `version`. Pass the tag-derived
+ * version in release.yml so a manifest that forgot its own bump is also caught.
+ * Exits 0 on lockstep, 1 on mismatch, 2 on usage/parse errors.
+ */
+import { realpathSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const CORE_DEP = "@dev-loops/core";
+
+function isDirectCliRun(importMetaUrl, argv1 = process.argv[1]) {
+  if (typeof argv1 !== "string" || argv1.length === 0) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(importMetaUrl));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract the `major.minor` token from a semver version or npm range.
+ * Handles leading range operators (^, ~, >=, >, <=, <, =, v) and compound
+ * ranges by taking the first `<digits>.<digits>` occurrence.
+ * @param {string} spec
+ * @returns {string} e.g. "0.6"
+ */
+export function extractMajorMinor(spec) {
+  const match = String(spec).match(/(\d+)\.(\d+)/);
+  if (!match) {
+    throw new Error(`cannot parse a major.minor version from "${spec}"`);
+  }
+  return `${match[1]}.${match[2]}`;
+}
+
+/**
+ * Assert the `@dev-loops/core` dependency range is in lockstep (same
+ * major.minor) with the release version. Throws on mismatch (fail closed).
+ * @param {{releaseVersion: string, coreRange: string}} input
+ * @returns {{releaseVersion: string, coreRange: string, majorMinor: string}}
+ */
+export function assertCoreDependencyInLockstep({ releaseVersion, coreRange } = {}) {
+  if (!releaseVersion) throw new Error("releaseVersion is required");
+  if (!coreRange) {
+    throw new Error(`root package must declare a "${CORE_DEP}" dependency`);
+  }
+  const releaseMajorMinor = extractMajorMinor(releaseVersion);
+  const coreMajorMinor = extractMajorMinor(coreRange);
+  if (releaseMajorMinor !== coreMajorMinor) {
+    throw new Error(
+      `${CORE_DEP} dependency "${coreRange}" (major.minor ${coreMajorMinor}) does not match ` +
+        `the release version ${releaseVersion} (major.minor ${releaseMajorMinor}). ` +
+        `Bump the ${CORE_DEP} range to ^${releaseMajorMinor}.0 before releasing (root cause of #1033).`,
+    );
+  }
+  return { releaseVersion, coreRange, majorMinor: releaseMajorMinor };
+}
+
+function usageError(message) {
+  const err = new Error(message);
+  err.usage = true;
+  return err;
+}
+
+function parseArgs(argv) {
+  const out = { manifest: "package.json", releaseVersion: null };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--release-version" || arg === "--manifest") {
+      const value = argv[++i];
+      // Fail closed like extract-changelog-section.mjs: a flag missing its value
+      // is a usage error (exit 2), not a silent fallback that defeats the guard.
+      if (value === undefined) throw usageError(`${arg} requires a value`);
+      if (arg === "--release-version") out.releaseVersion = value;
+      else out.manifest = value;
+    } else {
+      throw usageError(`unknown argument: ${arg}`);
+    }
+  }
+  return out;
+}
+
+async function main(argv) {
+  const { manifest, releaseVersion } = parseArgs(argv);
+  // An unreadable or invalid manifest is a usage/parse error (exit 2), not a
+  // lockstep mismatch (exit 1) — matches the header contract and extract-changelog-section.mjs.
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(manifest, "utf8"));
+  } catch (err) {
+    throw usageError(`cannot read or parse manifest "${manifest}": ${err.message}`);
+  }
+  const coreRange = pkg.dependencies?.[CORE_DEP];
+  const result = assertCoreDependencyInLockstep({
+    releaseVersion: releaseVersion ?? pkg.version,
+    coreRange,
+  });
+  process.stdout.write(
+    `${CORE_DEP} ${result.coreRange} is in lockstep with release ${result.releaseVersion} (major.minor ${result.majorMinor}).\n`,
+  );
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(`::error::${err.message}\n`);
+    process.exit(err.usage ? 2 : 1);
+  });
+}

package/scripts/release/extract-changelog-section.mjs

@@ -1,6 +1,20 @@
+import { realpathSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-
-import { isDirectCliRun } from "../_core-helpers.mjs";
+import { fileURLToPath } from "node:url";
+
+// Inlined (was scripts/_core-helpers.mjs -> @dev-loops/core): this script runs
+// in release.yml with no `npm ci`, so it must import only node: builtins.
+// A workspace import here ERR_MODULE_NOT_FOUNDs and the Release never gets made.
+function isDirectCliRun(importMetaUrl, argv1 = process.argv[1]) {
+  if (typeof argv1 !== "string" || argv1.length === 0) {
+    return false;
+  }
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(importMetaUrl));
+  } catch {
+    return false;
+  }
+}
 
 const USAGE = `Usage: extract-changelog-section.mjs --version <v> [--changelog <path>]
 

package/skills/copilot-pr-followup/SKILL.md

@@ -243,7 +243,8 @@ When unresolved feedback exists, use a narrow follow-up loop:
     - resolve the review-round cap from config via `resolveRefinementConfig(config, "maxCopilotRounds")` from `@dev-loops/core/config`; default config ships `maxCopilotRounds: 5`
     - **Opt out entirely:** `maxCopilotRounds: 0` disables the external Copilot review gate for the repo — the loop runs `draft_gate → pre_approval_gate` with the local harness only, never requesting or waiting on Copilot. Use this when the repo has no Copilot reviewer configured or prefers local-harness-only review.
     - use the completed Copilot review-round count from `detect-copilot-loop-state.mjs` / `copilot-pr-handoff.mjs` as the current PR's review-round count
-    - if completed review rounds have reached the maximum (default: 5), do **not** re-request Copilot review
+    - if completed review rounds have reached the maximum (default: 5), do **not** re-request Copilot review within that concluded cycle
+    - if the loop already converged and then significant post-convergence changes land on a newer head (new/changed product or test logic, not doc/message/comment-only edits), treat that as a NEW cycle and re-request Copilot review when regular rounds are already > 0 (the prior cycle's cap does not suppress this new-cycle request)
     - when the round limit is reached **and** the refreshed thread snapshot proves zero unresolved threads **and** current-head CI is green or credibly green, treat that clean state as eligible for `pre_approval_gate` fallback instead of deadlocking on another Copilot rerequest
     - when using that fallback, add a short round-exhaustion note to the visible `pre_approval_gate` gate evidence so the PR records why no further Copilot rerequest occurred
     - if the round cap is reached before the PR is thread-clean or before CI is green/credibly green, reply-resolve any remaining intentionally deferred threads with a short `deferred to follow-up` note, then stop and report that the Copilot round limit was reached
@@ -305,7 +306,7 @@ Do NOT use `gh pr comment`, `gh api`, or `gh pr review` for gate comments.
 Both gates run this same checkpoint review chain. It is an **agent-orchestrated skill procedure** — a node script cannot spawn the per-angle reviewers, so the conductor agent drives the fan-out and uses the pure `@dev-loops/core/loop/gate-fanin` helpers only for consolidation, batching, and ledger mapping. The cost model is **build once, seed many**: the context-builder script builds ONE deterministic, neutral context bundle (diff + adjacent code) and each independent reviewer is seeded with that identical bundle verbatim instead of re-deriving it (work-dedup; no fork primitive, no Workflow tool). See [Gate Review Sub-Loop Contract](../../docs/gate-review-sub-loop-contract.md).
 
 1. **Context (Phase 1) — build the neutral bundle ONCE:** build/read the gate-context artifact via `scripts/github/write-gate-context.mjs` (`buildGateContext` resolves the angle set through `resolveGateAnglesDynamic`; mandatory angles always survive). The artifact at `tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.json` carries the resolved angles + change scope + acceptance-criteria pointer. When the resolver was handed a diff with `diffOutput`, `buildGateContext` also persists the FULL diff to `tmp/gate-context/<repo-slug>/pr-<N>/<gate>-<headSha>.diff` and records `scope.diffPath` (relative) plus `scope.changedFiles` (full repo-relative paths). It ADDITIONALLY builds a deterministic, neutral `adjacentCode` bundle — each changed file plus its 1-hop import in/out-edges (callers/callees/imports), with size guards (skip lockfiles/generated/binary/minified; cap per-file bytes; truncate the long tail) recorded in a `stripped`/`truncated`/`missing` manifest. This single bundle is the build-once seed; reviewers do not re-derive the diff + adjacent code.
-2. **Fan-out (Phase 2) — seed each reviewer with the bundle verbatim:** plan batches with `planFanoutBatches(angles, resolveMaxFanoutReviewers(config))` (default cap 8). Spawn one scoped `review` agent per resolved angle (plain Agent tool), parallel up to the cap, batching any overflow sequentially. When `degraded` is true, record the sequential degradation in the gate evidence. Reviewers are independent: each is seeded with the IDENTICAL neutral bundle (the gate-context artifact's `scope.diffPath` + `adjacentCode`) verbatim plus its single angle, and never inherits the conductor agent's conversation or opinions. Each reviewer follows the [review agent scoped angle-review mode](../../agents/review.agent.md): fresh context, single angle, read-only, writing its per-angle findings artifact to `tmp/gate-reviews/<repo-slug>/pr-<N>/<gate>-<headSha>/<angle>.json`. Brief each reviewer to use the provided bundle as its base and to review like an external code reviewer hunting real bugs: read the FULL diff (from `scope.diffPath`, or `git diff` when null) and the bundled adjacent code (callers, callees, imports) rather than re-deriving them, then review adversarially for concrete defects (edge cases, input validation, numeric coercion incl. NaN/Infinity/floats/negatives, null/undefined, boundary conditions, mismatched caller/callee contracts, dedup/identity bugs) with `file:line` + the failing scenario — not process nits like "no test exists". Reviewers are read-only and MAY widen scope (open adjacent repo files beyond the bundle) only when their angle genuinely needs more; that widening is recorded in the optional `contextWidened` field on each per-angle findings artifact.
+2. **Fan-out (Phase 2) — seed each reviewer with the bundle verbatim:** plan batches with `planFanoutBatches(angles, cap)` using the `gates.maxFanoutReviewers` cap (default 8). Spawn one scoped `review` agent per resolved angle (plain Agent tool), parallel up to the cap, batching any overflow sequentially. When `degraded` is true, record the sequential degradation in the gate evidence. Reviewers are independent: each is seeded with the IDENTICAL neutral bundle (the gate-context artifact's `scope.diffPath` + `adjacentCode`) verbatim plus its single angle, and never inherits the conductor agent's conversation or opinions. Each reviewer follows the [review agent scoped angle-review mode](../../agents/review.agent.md): fresh context, single angle, read-only, writing its per-angle findings artifact to `tmp/gate-reviews/<repo-slug>/pr-<N>/<gate>-<headSha>/<angle>.json`. Brief each reviewer to use the provided bundle as its base and to review like an external code reviewer hunting real bugs: read the FULL diff (from `scope.diffPath`, or `git diff` when null) and the bundled adjacent code (callers, callees, imports) rather than re-deriving them, then review adversarially for concrete defects (edge cases, input validation, numeric coercion incl. NaN/Infinity/floats/negatives, null/undefined, boundary conditions, mismatched caller/callee contracts, dedup/identity bugs) with `file:line` + the failing scenario — not process nits like "no test exists". Reviewers are read-only and MAY widen scope (open adjacent repo files beyond the bundle) only when their angle genuinely needs more; that widening is recorded in the optional `contextWidened` field on each per-angle findings artifact.
 3. **Fan-in (Phase 3):** consolidate the per-angle artifacts via `consolidateFanin({ angleResults, blockCleanOnFindingSeverities })` (blocking severities from `resolveGateConfig(config, <configKey>).blockCleanOnFindingSeverities`, where `<configKey>` is the config key for the gate — `draft` for `draft_gate`, `preApproval` for `pre_approval_gate` — not the `draft_gate|pre_approval_gate` artifact name). It yields the gate `verdict` (`clean` when no blocking-severity finding remains, `findings_present` when one does, `blocked` when any per-angle artifact is malformed/missing). Map consolidated findings with `toFindingsLogShape(...)` and write the disposition ledger via `write-gate-findings-log.mjs` **before** the visible comment. The ledger is written regardless of any comment opt-out. Then, when `resolveGatePostFindingsComments(config)` is true (default; opt-out via `gates.postFindingsComments: false`), post the consolidated findings as a visible, marker-tagged PR comment via `node <resolved-skill-scripts>/github/post-gate-findings.mjs --repo <owner/name> --pr <number> --gate <gate> --head-sha <current_head_sha> --findings '<toFindingsLogShape JSON>'` so the findings are auditable and Copilot/humans are aware of them. The helper is idempotent per gate (exactly one comment per gate, updated in place on each run; the reviewed head is shown in the body) and posts a brief "no findings" note when the consolidated set is empty. When `postFindingsComments` is false the helper no-ops with a `skipped` result and you skip this post step; the ledger still records the findings.
 4. **Verdict (Phase 4):** post the verdict with the [Gate comment command](#mandatory-gate-comment-command-contract) using `--execution-mode fanout_fanin` and `--findings-json <path>`. Write that JSON from the collected per-angle results (the same per-angle `{angle, verdict, findings}` artifacts at `tmp/gate-reviews/<repo-slug>/pr-<N>/<gate>-<headSha>/<angle>.json` that fed `consolidateFanin` in Phase 3; the flat `toFindingsLogShape` output is also accepted and grouped by `.angle`) so the verdict comment renders the structured per-angle breakdown instead of a wall-of-text summary. Do NOT use `--findings-summary` for a fan-out gate — that is the inline_single_agent fallback.
 5. **Retry (Phase 5):** on blocking findings, drive each internal fan-out finding through the SAME fix → reply-with-resolving-commit → resolve loop used for external Copilot review comments (Step 7 above): fix on the branch, push the resolving commit, then re-run only the `findings_present` angles from the previous pass (the context-builder and fan-in always re-run); repeat until the consolidated verdict is `clean` for the current head SHA. Internal fan-out findings and external review comments are handled identically by that loop.
@@ -322,11 +323,7 @@ The canonical checkpoint verdict comment contract is [Gate Review Comment Contra
 - **CI prerequisite:** resolve the draft gate config first (`resolveGateConfig(config, "draft")`). When `requireCi=true` (default), wait for green current-head CI before entering `draft_gate`. When `requireCi=false`, the draft gate may proceed without green CI. This draft-only override does **not** relax `pre_approval_gate`; final approval and merge readiness still require green current-head CI.
 - **Pass criteria:** all configured draft gate angles pass; all findings at severities in `blockCleanOnFindingSeverities` are addressed; validation passes; no unrelated files are included.
 - **Next step after passing:** mark the PR ready for review.
-- **Board status sync (best-effort, after ready-for-review):** once the PR is created/marked ready for review, sync the linked issue's board item to "In Progress" so the queue board reflects active work without a manual `dev-loops queue sync-status --to-column <col>`:
-  ```sh
-  node <resolved-skill-scripts>/projects/sync-item-status.mjs --repo <owner/name> --item <linked-issue> --to-column "In Progress"
-  ```
-  Best-effort and NON-FATAL: it uses local `gh` auth (no CI/PAT), exits 0 when the board is not configured / the item is not on the board / the API fails, and never blocks marking the PR ready.
+- **Board status sync (built-in, after ready-for-review):** the In-Progress board move is now performed automatically as a deterministic tail of `ready-for-review.mjs` — marking the PR ready couples the board move to the ready transition (#1069), so no separate `sync-item-status` step is needed. It stays best-effort and NON-FATAL: it uses local `gh` auth (no CI/PAT), exits 0 when the board is not configured / the item is not on the board / the API fails, and never blocks marking the PR ready.
 - **Non-substitution rule:** a clean `draft_gate` comment only authorizes the draft → ready-for-review transition for that head SHA. It does **not** satisfy `pre_approval_gate`, final-approval readiness, or merge-ready requirements.
 - **Required PR comment:** post a visible checkpoint verdict comment using the mandatory [Gate comment command](#mandatory-gate-comment-command-contract). Keep validation reporting concise: include command names with pass/fail status. Do **not** paste raw passing test output into the visible gate comment. If you include a failing validation excerpt, keep it focused and truncate it to a deterministic retained-prefix length before posting the comment. See [Gate Review Comment Contract](../../docs/gate-review-comment-contract.md). Do not run `gh pr ready` unless a visible `clean` `draft_gate` checkpoint verdict comment exists for the current head SHA. A checkpoint verdict comment for an older head SHA does not satisfy this requirement for the current head. If findings exist, the PR stays draft and needs fixes before retry. If fixes advance the head SHA while still draft, post a new checkpoint verdict comment for the new head. If the checkpoint verdict comment cannot be posted, fail closed and do not run `gh pr ready`.
 
@@ -340,7 +337,7 @@ This is the default pre-approval gate for this workflow boundary. The canonical
 - **Review angles:** resolved at runtime from config via `resolveGateAngles(config, "preApproval")` from `@dev-loops/core/config`. Default config enables all configured pre-approval gate angle families; consumer repos may opt out individual angles via `excludeAngles`.
 - **Persona mapping:** each angle resolves to a reviewer persona via `resolveReviewerRole(config, angle)` from `@dev-loops/core/config`. Include this prompt in each reviewer's briefing so the reviewer knows exactly what to look for.
 - **Pass criteria:** the sub-loop completes with verdict `clean`; all configured angles pass; if parallel execution is impractical, still run all configured lenses and explicitly record the limitation.
-- **Acceptance criteria verification:** follow the canonical procedure in [Acceptance Criteria Verification](../docs/acceptance-criteria-verification.md) before posting the `pre_approval_gate` comment.
+- **Acceptance criteria verification:** follow the canonical procedure in [Acceptance Criteria Verification](../docs/acceptance-criteria-verification.md) before posting the `pre_approval_gate` comment. After a clean verification this also ticks the verified PR-body checkboxes via `scripts/github/tick-verified-checkboxes.mjs`, so the merged PR shows checked AC.
 - **Next step after passing:** continue the Step 7 flow and then proceed to the human approval checkpoint below.
 - **Non-substitution rule:** a clean `pre_approval_gate` comment is separate from `draft_gate` evidence. It governs final-approval readiness for that head SHA; it does **not** replace the required `draft_gate` evidence for leaving draft.
 - **Required PR comment:** post a visible checkpoint verdict comment using the mandatory [Gate comment command](#mandatory-gate-comment-command-contract). Keep validation reporting concise: include command names with pass/fail status. Do **not** paste raw passing test output into the visible gate comment. If you include a failing validation excerpt, keep it focused and truncate it to a deterministic retained-prefix length before posting the comment. Do not declare final-approval readiness unless a visible `clean` `pre_approval_gate` checkpoint verdict comment exists for the current head SHA. Final-approval readiness must not rely only on local or hidden artifacts; the visible PR comment is the required auditable evidence. If the checkpoint verdict comment cannot be posted, fail closed and do not declare final-approval readiness. A checkpoint verdict comment for an older head SHA does not satisfy this requirement for the current head. If findings exist, follow-up fixes are required before final approval. The `pre_approval_gate` procedure must be entered and completed (visible comment posted) before any merge-ready or approval-ready declaration. Skipping the gate is not recoverable by asserting convergence. If fixes advance the head SHA, post a new checkpoint verdict comment for the new head.
@@ -350,14 +347,14 @@ This is the default pre-approval gate for this workflow boundary. The canonical
 Before any merge-ready or final-approval claim, run `detect-pr-gate-coordination-state.mjs` for the current PR. If it reports `gateBoundary=conflict_resolution` or `mergeStateStatus` is conflicted, stop the normal gate path immediately and use this recovery flow:
 
 1. fetch fresh `origin/main`, confirm the current PR head SHA, and summarize the conflict scope from `mergeStateStatus` plus any reported `conflictFiles`
-2. ask for explicit authorization before any rebase or other branch-state-changing reconciliation command
-3. after authorization, reconcile locally on the PR branch; default to rebase onto latest `origin/main`, unless the operator explicitly chooses another conflict-resolution command
+2. ask for explicit authorization before any merge commit or other branch-state-changing reconciliation command
+3. after authorization, reconcile locally on the PR branch; default to a merge commit (`git merge origin/main`) per the behind-branch integration policy in [Local Implementation Skill](../local-implementation/SKILL.md#branch--review--merge-policy), unless the operator explicitly chooses another conflict-resolution command
 4. auto-resolve simple conflicts when the correct fix is mechanical and clearly in scope; report complex conflicts explicitly and fix them manually only for in-scope files
 5. rerun the smallest honest local validation for the touched conflict slice
 6. rerun `detect-pr-gate-coordination-state.mjs` for the new head
 7. because the head changed, rerun `pre_approval_gate` for the new head before any approval-ready or merge-ready claim
 8. wait for current-head CI again before retrying merge evaluation
-9. if the chosen reconciliation rewrote branch history (for example rebase), ask for explicit authorization before `git push --force-with-lease`, then continue the loop on the updated head
+9. if the chosen reconciliation rewrote branch history (rebase only — merge commits push as a normal fast-forward), ask for explicit authorization before `git push --force-with-lease` (`--force-with-lease` only, never bare `--force`), then continue the loop on the updated head
 
 `mergeStateStatus: CLEAN` alone is not enough to resume approval or merge claims. The existing merge-ready preconditions still apply: zero unresolved review threads, a clean current-head `pre_approval_gate`, and green current-head CI.
 
@@ -384,6 +381,21 @@ node <resolved-skill-scripts>/github/detect-checkpoint-evidence.mjs \
 
 This helper is always-on: it uses `gh api` to fetch visible PR issue comments and fails closed unless both required gate comments exist: a clean `draft_gate` comment for the one-time draft boundary and a clean current-head `pre_approval_gate` comment. Do not run `gh pr merge` if this command exits non-zero. There is no opt-out flag. Resolved threads, green CI, clean Copilot rereview, or local notes do not substitute for this successful helper output. If a final approval or merge boundary sees `gh pr merge` without a same-boundary successful check, treat that as a workflow violation and stop.
 
+### Stale runner-coordination lock held by a completed run
+
+The pre-merge gate evidence check fails closed on the PR's runner-coordination claim (`.pi/runner-coordination/<owner>/<name>/pr-<n>.json`): a fresh merge re-dispatch (new run id) is refused with `ownership_lost`, or `stale_runner` once the claim ages past the max-age window.
+
+The auto-loop now releases its claim best-effort when a run reaches a terminal stop (clean-converged, blocked, or done — including the stop at the human approval checkpoint), so a merge-authorized re-dispatch normally inherits a cleared claim and proceeds. The release is non-fatal: it never blocks the stop, and it never clears a claim owned by a genuinely active competing run.
+
+If a stale claim still blocks the merge because the completing run could not release (crash, killed process, or a pre-#1109 run), the sanctioned recovery for a lock held by a COMPLETED run is an explicit takeover by the merge run:
+
+```sh
+node <resolved-skill-scripts>/loop/pr-runner-coordination.mjs takeover \
+  --repo <owner/name> --pr <number>
+```
+
+`takeover` seizes ownership for the current run id and records the displaced run under `previousRun`. Only take over when the prior owner is genuinely completed/dead. A genuinely active (non-stale) run must still be allowed to block — do not take over to race a live run.
+
 ### Mandatory post-merge retrospective checkpoint write
 
 After a merge succeeds (or an explicit retrospective skip is authorized), write the durable retrospective checkpoint before exiting the subagent session:
@@ -410,7 +422,7 @@ node <resolved-skill-scripts>/projects/archive-done-items.mjs --repo <owner/name
 
 Board and threshold resolve from `.devloops` (`queue.projectNumber`/`queue.boardTitle`, `queue.archiveOlderThanDays`, default 7d), using local `gh` auth — no CI, cron, or PAT. This step is best-effort and NON-FATAL: ignore any failure and never let it block the merge or the retrospective.
 
-Alongside the archive step, sync the linked issue's board item to "Done" so the queue board reflects the merge without a manual `dev-loops queue sync-status --to-column <col>`:
+The deterministic mechanism that converges merged→Done is `dev-loops queue reconcile` — idempotent, run best-effort at loop startup — so the merge lands on the "Done" column without a remembered manual step. The manual sync below is now an optional fallback (e.g. to converge immediately without waiting for the next startup reconcile):
 
 ```sh
 node <resolved-skill-scripts>/projects/sync-item-status.mjs --repo <owner/name> --item <linked-issue> --to-column "Done"