dev-loops 0.7.1 → 0.8.0

package/scripts/loop/run-watch-cycle.mjs

@@ -10,6 +10,9 @@ import { runHandoff } from "./copilot-pr-handoff.mjs";
 import { STATE } from "@dev-loops/core/loop/copilot-loop-state";
 import { DEFAULT_POLL_INTERVAL_MS } from "@dev-loops/core/loop/policy-constants";
 import { detectCopilotSessionActivity } from "./detect-copilot-session-activity.mjs";
+import { ensureAsyncRunnerOwnership } from "./_pr-runner-coordination.mjs";
+import { resolveRepoRoot } from "./_repo-root-resolver.mjs";
+import { resolveStaleRunnerMaxAgeMs } from "./_stale-runner-detection.mjs";
 import { parseArgs } from "node:util";
 import {
   EXTERNAL_HEALTHY_WAIT_TIMEOUT_POLICY,
@@ -205,6 +208,33 @@ function buildWatchCycleContractTrace({
     },
   };
 }
+// A blocking watch can run for the full external-healthy-wait timeout (30 min for
+// Copilot/CI), which equals the runner-coordination stale window. Without a
+// heartbeat the claim ages to stale across a single watch and the next step is
+// refused. Refresh the lease on entry, on a periodic interval below
+// the stale window, and once more on return so the resuming runner has a fresh claim.
+async function runWatchHoldingLease(watchFactory, { repo, pr, env, cwd, ensureOwnershipImpl }) {
+  const heartbeat = async () => {
+    try {
+      // claimIfMissing:true self-heals a missing record but never stomps a live
+      // competitor (assertRunnerOwnership refuses to write on OWNERSHIP_LOST), so
+      // fail-closed competitor semantics are preserved.
+      await ensureOwnershipImpl({ repo, pr, env, cwd, claimIfMissing: true, requireExisting: false });
+    } catch {
+      // best-effort: a heartbeat failure must never affect the watch
+    }
+  };
+  const intervalMs = Math.max(1, Math.floor(resolveStaleRunnerMaxAgeMs({}, env) / 2));
+  await heartbeat();
+  const timer = setInterval(() => { void heartbeat(); }, intervalMs);
+  if (typeof timer.unref === "function") timer.unref();
+  try {
+    return await watchFactory();
+  } finally {
+    clearInterval(timer);
+    await heartbeat();
+  }
+}
 export function parseWatchCycleCliArgs(argv) {
   const options = {
     help: false,
@@ -278,9 +308,11 @@ export async function runWatchCycle(
     detectCopilotSessionActivityImpl = detectCopilotSessionActivity,
     fetchPrHeadBranchImpl = fetchPrHeadBranch,
     watchWorkflowRunImpl = watchWorkflowRun,
+    ensureOwnershipImpl = ensureAsyncRunnerOwnership,
     detectSessionActivity = false,
   } = {},
 ) {
+  const leaseCwd = resolveRepoRoot(process.cwd());
   const handoff = await runHandoffImpl(options, { env, ghCommand });
   const result = {
     ok: true,
@@ -370,13 +402,16 @@ export async function runWatchCycle(
       session.activity === "active"
       && Number.isInteger(session.runId)
     ) {
-      const workflowWatchResult = await watchWorkflowRunImpl(
-        {
-          repo: options.repo,
-          runId: session.runId,
-          timeoutMs: persistentWatchTimeoutMs,
-        },
-        { env, ghCommand },
+      const workflowWatchResult = await runWatchHoldingLease(
+        () => watchWorkflowRunImpl(
+          {
+            repo: options.repo,
+            runId: session.runId,
+            timeoutMs: persistentWatchTimeoutMs,
+          },
+          { env, ghCommand },
+        ),
+        { repo: options.repo, pr: options.pr, env, cwd: leaseCwd, ensureOwnershipImpl },
       );
       workflowRunWatch = {
         attempted: true,

package/scripts/loop/sanctioned-commands.mjs

@@ -26,15 +26,18 @@ export const SANCTIONED_COMMANDS = Object.freeze({
   reads: Object.freeze({
     "pr-facts": "scripts/github/view-pr.mjs",
     "ci-status": "scripts/github/probe-ci-status.mjs",
+    "ci-wait": "scripts/github/wait-pr-checks.mjs",
     "ci-logs": "scripts/github/fetch-ci-logs.mjs",
     "issue-list": "scripts/github/list-issues.mjs",
     "copilot-review-state": "scripts/github/probe-copilot-review.mjs",
+    "review-threads": "scripts/github/list-review-threads.mjs",
     "gate-coordination": "scripts/loop/detect-pr-gate-coordination-state.mjs",
   }),
 
   // Metadata edits.
   edits: Object.freeze({
     "pr-body-title-assignee-milestone": "scripts/github/edit-pr.mjs",
+    "issue-body-title-assignee-milestone": "scripts/github/edit-issue.mjs",
     "issue-comment": "scripts/github/comment-issue.mjs",
   }),
 

package/scripts/loop/validate-pr-body-spec.mjs

@@ -24,8 +24,8 @@ const USAGE = `Usage:
   validate-pr-body-spec.mjs --input <path> [--expected-issue <n>]
 Validate that a PR body carries the lightweight spec-of-record invariants
 (Objective/why, In scope, Explicit non-goals, testable Acceptance criteria,
-Definition of done, Open questions/risks, and a GitHub closing-keyword issue
-reference such as \`Closes #123\`).
+Definition of done, Open questions/risks, and — unless --no-issue is given —
+a GitHub closing-keyword issue reference such as \`Closes #123\`).
 Required (exactly one):
   --repo <owner/name> --pr <number>   Fetch the PR body via gh and validate it
   --input <path>                      Path to a JSON file with { "body": "..." }
@@ -34,7 +34,14 @@ Required (exactly one):
 Optional:
   --expected-issue <n>                Positive integer; the referenced closing
                                       issue(s) must include this number, else
-                                      "closes_wrong_issue".
+                                      "closes_wrong_issue". Mutually exclusive
+                                      with --no-issue.
+  --no-issue                          Explicit issue-less mode (#1210): the PR
+                                      is the sole artifact, so a closing-issue
+                                      reference is FORBIDDEN rather than
+                                      required — one present fails closed under
+                                      "unexpected_closing_issue_reference".
+                                      Mutually exclusive with --expected-issue.
 Success output (stdout, JSON):
   {
     "ok": true | false,
@@ -61,6 +68,7 @@ export function parseValidatePrBodySpecCliArgs(argv) {
     pr: undefined,
     input: undefined,
     expectedIssue: undefined,
+    noIssue: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -70,6 +78,7 @@ export function parseValidatePrBodySpecCliArgs(argv) {
       pr: { type: "string" },
       input: { type: "string" },
       "expected-issue": { type: "string" },
+      "no-issue": { type: "boolean" },
       ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
@@ -111,12 +120,19 @@ export function parseValidatePrBodySpecCliArgs(argv) {
       options.expectedIssue = Number(value);
       continue;
     }
+    if (token.name === "no-issue") {
+      options.noIssue = true;
+      continue;
+    }
     if (matchJqOutputToken(token, options, (t) => requireTokenValue(t, parseError))) continue;
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.help) {
     return options;
   }
+  if (options.noIssue && Number.isInteger(options.expectedIssue)) {
+    throw parseError("--no-issue is mutually exclusive with --expected-issue; provide exactly one issue-linkage mode");
+  }
   const hasInput = typeof options.input === "string" && options.input.length > 0;
   const hasAnyRemote = (typeof options.repo === "string" && options.repo.length > 0) || Number.isInteger(options.pr);
   const hasRemotePair = typeof options.repo === "string" && options.repo.length > 0 && Number.isInteger(options.pr);
@@ -163,12 +179,12 @@ export async function validatePrBodySpecFromOptions(options, { env = process.env
     const body = typeof payload.body === "string" ? payload.body : "";
     const repo = typeof payload.repo === "string" ? payload.repo : options.repo ?? null;
     const pr = Number.isInteger(payload.pr) ? payload.pr : options.pr ?? null;
-    return { ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null }), repo, pr };
+    return { ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null, issueLess: options.noIssue }), repo, pr };
   }
   parseRepoSlug(options.repo);
   const body = await fetchPrBody({ repo: options.repo, pr: options.pr }, { env, ghCommand });
   return {
-    ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null }),
+    ...validatePrBodySpec({ body, expectedIssue: options.expectedIssue ?? null, issueLess: options.noIssue }),
     repo: options.repo,
     pr: options.pr,
   };

package/scripts/pages/build-state-atlas.mjs

@@ -2,10 +2,10 @@
 // state machine rendered as a mermaid diagram, emitted DETERMINISTICALLY from
 // the code's own exported tables so the page can never drift from the code.
 //
-// Four diagrams come straight from packages/core/src/loop tables (copilot loop,
-// reviewer loop, outer conductor routing, and the public dev-loop gate hub); two
-// more are authored from documented, table-less sources (the PR lifecycle
-// contract and the release pipeline workflow).
+// Five diagrams come straight from packages/core/src/loop tables (copilot loop,
+// reviewer loop, outer conductor routing, the public dev-loop gate hub, and the
+// PR lifecycle contract); one more (the release pipeline workflow) is authored
+// from a documented, table-less source.
 //
 // The page reuses the article design system (docs/articles/introducing-dev-loops.html):
 // the same :root tokens, body gradient, and typography. It intentionally defines
@@ -13,8 +13,10 @@
 // (NAV_CSS references --heading/--kicker/--accent-soft, all declared here).
 import { STATE, TRANSITIONS } from '../../packages/core/src/loop/copilot-loop-state.mjs';
 import { REVIEWER_STATE, REVIEWER_TRANSITIONS } from '../../packages/core/src/loop/reviewer-loop-state.mjs';
+import { GRILL_STATE, GRILL_TRANSITIONS } from '../../packages/core/src/loop/refinement-grill-state.mjs';
 import { OUTER_STATE, OUTER_TRANSITIONS } from '../../packages/core/src/loop/conductor-routing.mjs';
 import { PUBLIC_DEV_LOOP_GATE_CONTRACT } from '../../packages/core/src/loop/public-dev-loop-routing-contract.mjs';
+import { PR_LIFECYCLE_STATES, PR_LIFECYCLE_TRANSITIONS } from '../../packages/core/src/loop/pr-lifecycle.mjs';
 
 // Classify a state/gate id by name into one of four visual classes. Colors are
 // drawn from the site's own dark palette (accent violet, kicker blue,
@@ -80,7 +82,7 @@ function gateClass(row) {
 }
 
 function renderGateFlowchart(contract) {
-  const lines = ['flowchart TD', '    router(["dev-loop router"])'];
+  const lines = ['flowchart LR', '    router(["dev-loop router"])'];
   for (const row of contract) {
     const strategy = row.selectedStrategy ?? 'none';
     lines.push(`    router -->|${row.routeKind}| ${row.gate}["${row.gate} — ${strategy}"]`);
@@ -99,53 +101,26 @@ const reviewerDiagram = renderStateDiagram(
   edgesFromTransitions(Object.values(REVIEWER_STATE), REVIEWER_TRANSITIONS),
   Object.values(REVIEWER_STATE),
 );
+const refinementGrillDiagram = renderStateDiagram(
+  edgesFromTransitions(Object.values(GRILL_STATE), GRILL_TRANSITIONS),
+  Object.values(GRILL_STATE),
+);
 const outerDiagram = renderStateDiagram(
   edgesFromTransitions(Object.values(OUTER_STATE), OUTER_TRANSITIONS),
   Object.values(OUTER_STATE),
 );
 const gateDiagram = renderGateFlowchart(PUBLIC_DEV_LOOP_GATE_CONTRACT);
 
-// --- Statically-authored diagrams (documented, table-less sources) ---
+// PR lifecycle: the 13-state vocabulary + required transitions exported by
+// packages/core/src/loop/pr-lifecycle.mjs (issue #1193), re-exported here so
+// this module's public surface is unchanged. The L2/L3 state-machine
+// conformance harness (scripts/docs/validate-state-machine-conformance.mjs)
+// imports the same core module directly rather than through this one, so it
+// never pulls in this page generator's diagram-rendering work at load time.
+export { PR_LIFECYCLE_STATES, PR_LIFECYCLE_TRANSITIONS };
+const prLifecycleDiagram = renderStateDiagram(PR_LIFECYCLE_TRANSITIONS, PR_LIFECYCLE_STATES);
 
-// PR lifecycle: the 13-state vocabulary + required transitions from
-// skills/docs/pr-lifecycle-contract.md.
-const prLifecycleStates = [
-  'draft_local_review_gate',
-  'draft_local_remediation',
-  'ready_state_needs_copilot_request',
-  'waiting_for_copilot_review',
-  'copilot_feedback_remediation',
-  'copilot_reply_resolve_pending',
-  'merge_conflict_resolution',
-  'final_local_preapproval_gate',
-  'final_gate_remediation',
-  'waiting_for_human_pr_approval',
-  'waiting_for_merge',
-  'terminal_slice_complete',
-  'stopped_needs_user_decision',
-];
-const prLifecycleDiagram = renderStateDiagram([
-  ['draft_local_review_gate', 'draft_local_remediation'],
-  ['draft_local_review_gate', 'ready_state_needs_copilot_request'],
-  ['draft_local_review_gate', 'stopped_needs_user_decision'],
-  ['draft_local_remediation', 'draft_local_review_gate'],
-  ['ready_state_needs_copilot_request', 'waiting_for_copilot_review'],
-  ['ready_state_needs_copilot_request', 'stopped_needs_user_decision'],
-  ['waiting_for_copilot_review', 'copilot_feedback_remediation'],
-  ['copilot_feedback_remediation', 'copilot_reply_resolve_pending'],
-  ['copilot_reply_resolve_pending', 'ready_state_needs_copilot_request'],
-  ['waiting_for_copilot_review', 'merge_conflict_resolution'],
-  ['merge_conflict_resolution', 'waiting_for_copilot_review'],
-  ['waiting_for_copilot_review', 'final_local_preapproval_gate'],
-  ['final_local_preapproval_gate', 'final_gate_remediation'],
-  ['final_local_preapproval_gate', 'waiting_for_human_pr_approval'],
-  ['final_gate_remediation', 'final_local_preapproval_gate'],
-  ['waiting_for_human_pr_approval', 'waiting_for_merge'],
-  ['waiting_for_human_pr_approval', 'draft_local_review_gate'],
-  ['waiting_for_merge', 'terminal_slice_complete'],
-  ['terminal_slice_complete', '[*]'],
-  ['stopped_needs_user_decision', '[*]'],
-], prLifecycleStates);
+// --- Statically-authored diagram (documented, table-less source) ---
 
 // Release pipeline: the fail-closed gate chain from .github/workflows/release.yml.
 const releasePipelineNodes = [
@@ -189,7 +164,7 @@ const releaseDiagram = [
 
 const INTRO_PROSE = [
   'dev-loops drives every pull request through closed, deterministic state machines. Workflow control lives in the graph; agent judgment enters only as bounded, explicit inputs, never as hidden orchestration. Exactly one state applies at a time, and each state exposes the legal transitions out of it.',
-  "Every diagram on this page is generated at site-build time from the code's own exported tables — the copilot loop's <code>STATE</code>/<code>TRANSITIONS</code>, the reviewer loop's <code>REVIEWER_STATE</code>/<code>REVIEWER_TRANSITIONS</code>, the outer loop's <code>OUTER_STATE</code>/<code>OUTER_TRANSITIONS</code>, and the public router's <code>PUBLIC_DEV_LOOP_GATE_CONTRACT</code>. They cannot drift from the code: change a transition table and this page changes with it. Two diagrams (the PR lifecycle and the release pipeline) are authored from documented contracts that have no single code table.",
+  "Every diagram on this page is generated at site-build time from the code's own exported tables — the copilot loop's <code>STATE</code>/<code>TRANSITIONS</code>, the reviewer loop's <code>REVIEWER_STATE</code>/<code>REVIEWER_TRANSITIONS</code>, the outer loop's <code>OUTER_STATE</code>/<code>OUTER_TRANSITIONS</code>, the public router's <code>PUBLIC_DEV_LOOP_GATE_CONTRACT</code>, and the PR lifecycle's <code>PR_LIFECYCLE_STATES</code>/<code>PR_LIFECYCLE_TRANSITIONS</code>. They cannot drift from the code: change a transition table and this page changes with it. One diagram (the release pipeline) is authored from a documented contract that has no single code table.",
   'The state names are not labels for a picture — they are the literal contract identifiers that appear in logs, handoff envelopes, and gate artifacts. Nodes are coloured by role: <strong>active / in-progress</strong> steps the loop advances itself, <strong>waiting-on-external</strong> states that block on something outside the loop (CI, Copilot, a human), <strong>blocked / fail-closed</strong> states that stop or reconcile rather than guess, and <strong>terminal</strong> states where the slice is complete.',
 ];
 
@@ -217,7 +192,7 @@ const SECTIONS = [
   {
     id: 'pr-lifecycle',
     title: 'PR lifecycle contract',
-    source: 'skills/docs/pr-lifecycle-contract.md (documented vocabulary)',
+    source: 'packages/core/src/loop/pr-lifecycle.mjs — PR_LIFECYCLE_STATES + PR_LIFECYCLE_TRANSITIONS',
     prose: [
       'One PR moves through a stable thirteen-state vocabulary from draft to merge. These identifiers are part of the contract surface even as the helper implementations around them change. Two local gates guard the path — <code>draft_gate</code> (draft to ready-for-review) and <code>pre_approval_gate</code> (before final approval) — and both are fail-closed fan-out reviews that run independent angle chains and must produce clean current-head evidence to pass.',
       'All gate evidence is per-head: a new push re-opens the gates, and ready-to-draft resets the lifecycle back into draft-stage gating. A conflicted head detours through <code>merge_conflict_resolution</code> before any further gate progression — a conflicted PR is never treated as approval- or merge-ready, even if older gate comments and CI were green. Human approval and merge are explicit external waits, not hidden remediation states.',
@@ -244,6 +219,16 @@ const SECTIONS = [
     ],
     diagram: reviewerDiagram,
   },
+  {
+    id: 'refinement-grill',
+    title: 'Refinement / grill sub-loop',
+    source: 'packages/core/src/loop/refinement-grill-state.mjs — GRILL_STATE + GRILL_TRANSITIONS',
+    prose: [
+      'Before a slice enters the loop, the refinement grill runs as a closed, deterministic sub-loop over the issue, PR body, or plan file. It loads the target, detects spec gaps, and iterates detect-gaps to answer to synthesize to re-grill until it reaches a fixed point. The iteration lives entirely in the transition graph; the LLM answer and synthesis enter only as a bounded input consumed at the await_answers state, never as hidden orchestration in a coordinator script.',
+      'Write-back synthesizes only sharpened Acceptance criteria, Definition of done, and Non-goals into the body — the raw Q&A transcript never lands in the artifact. An uncitable gap stops honestly at needs_human_handoff naming the question rather than fabricating an answer to force convergence, and any load or parse failure fails closed to blocked_needs_user_decision.',
+    ],
+    diagram: refinementGrillDiagram,
+  },
   {
     id: 'release-pipeline',
     title: 'Release pipeline',
@@ -270,7 +255,7 @@ function sectionMarkup(s) {
         <h2>${s.title}</h2>
         <p class="source">Diagram generated from <code>${s.source}</code></p>
 ${proseParagraphs(s.prose)}
-        <div class="diagram"><div class="mermaid">
+        <div class="diagram"><button class="expand" type="button" aria-label="View diagram fullscreen">⤢ Fullscreen</button><div class="mermaid">
 ${escapeMermaid(s.diagram)}
 </div></div>
       </section>`;
@@ -404,6 +389,16 @@ export function buildStateAtlasHtml() {
   }
   .diagram .mermaid { text-align: center; }
   .diagram .mermaid svg { max-width: 100%; height: auto; }
+  .diagram { position: relative; }
+  .diagram .expand { position: sticky; float: right; top: 0.6rem; right: 0.6rem; margin: 0 0 -2rem; z-index: 2; font: 600 0.72rem var(--font); color: var(--copy); background: rgba(15, 23, 42, 0.85); border: 1px solid var(--card-border); border-radius: 8px; padding: 0.35rem 0.6rem; cursor: pointer; }
+  .diagram .expand:hover { color: var(--heading); border-color: var(--accent); }
+  .diagram .mermaid { cursor: zoom-in; }
+  .diagram .mermaid:fullscreen { cursor: zoom-out; background: #0b1220; display: flex; align-items: center; justify-content: center; padding: 2rem; }
+  .diagram .mermaid:-webkit-full-screen { cursor: zoom-out; background: #0b1220; display: flex; align-items: center; justify-content: center; padding: 2rem; }
+  .diagram .mermaid:-webkit-full-screen svg { max-width: calc(100vw - 4rem); max-height: calc(100vh - 4rem); width: auto; height: auto; }
+  .diagram .mermaid:fullscreen svg { max-width: calc(100vw - 4rem); max-height: calc(100vh - 4rem); width: auto; height: auto; }
+  .diagram .mermaid.fs-fallback { position: fixed; inset: 0; z-index: 50; background: #0b1220; display: flex; align-items: center; justify-content: center; padding: 1rem; cursor: zoom-out; overflow: auto; }
+  .diagram .mermaid.fs-fallback svg { max-width: calc(100vw - 2rem); max-height: calc(100vh - 2rem); width: auto; height: auto; }
 </style>
 </head>
 <body>
@@ -416,6 +411,28 @@ ${sections}
     </main>
     <script src="assets/mermaid.min.js"></script>
     <script>
+      let fsInFlight = false;
+      document.addEventListener('click', async (e) => {
+        if (fsInFlight) return;
+        const target = e.target instanceof Element ? e.target : e.target?.parentElement;
+        if (!target) return;
+        const btn = target.closest('.diagram .expand');
+        const box = btn ? btn.parentElement.querySelector('.mermaid') : target.closest('.diagram .mermaid');
+        if (!box) return;
+        fsInFlight = true;
+        try {
+          const fsElement = document.fullscreenElement || document.webkitFullscreenElement;
+          if (fsElement === box) {
+            await (document.exitFullscreen || document.webkitExitFullscreen)?.call(document);
+            return;
+          }
+          if (box.classList.contains('fs-fallback')) { box.classList.remove('fs-fallback'); return; }
+          const request = box.requestFullscreen || box.webkitRequestFullscreen;
+          if (request) await request.call(box);
+          else box.classList.add('fs-fallback'); // iOS Safari: CSS overlay fallback
+        } catch { /* fullscreen denied: fall back to the CSS overlay */ box.classList.add('fs-fallback'); }
+        finally { fsInFlight = false; }
+      });
       mermaid.initialize({
         startOnLoad: true,
         securityLevel: 'strict',

package/scripts/projects/_resolve-project.mjs

@@ -1,148 +1 @@
-import { readFileSync } from "node:fs";
-import path from "node:path";
-import { parse as parseYaml } from "yaml";
-
-// Read .devloops (and extension variants) queue settings, mirroring the
-// resolution used by ensure-queue-board.mjs. Returns { project }, { title },
-// and/or { olderThanDays } when configured; never throws on a missing/bad file.
-function resolveSettings(cwd) {
-  const basePath = path.join(cwd, ".devloops");
-  const extensions = ["", ".yaml", ".yml", ".json"];
-  for (const ext of extensions) {
-    try {
-      const raw = readFileSync(basePath + ext, "utf-8");
-      const settings = ext === ".json" ? JSON.parse(raw) : parseYaml(raw);
-      const queue = settings?.queue;
-      if (!queue) return null;
-      const out = {};
-      if (typeof queue.projectNumber === "number" && Number.isInteger(queue.projectNumber) && queue.projectNumber > 0) {
-        out.project = queue.projectNumber;
-      } else if (typeof queue.boardTitle === "string" && queue.boardTitle.trim().length > 0) {
-        out.title = queue.boardTitle.trim();
-      }
-      if (typeof queue.archiveOlderThanDays === "number" && Number.isInteger(queue.archiveOlderThanDays) && queue.archiveOlderThanDays > 0) {
-        out.olderThanDays = queue.archiveOlderThanDays;
-      }
-      return out;
-    } catch {
-      // extension not present or unparseable — try next
-    }
-  }
-  return null;
-}
-
-// Parse a --project value into { kind:"id"|"number"|"uri", ... }. Throws
-// INVALID_PROJECT on empty/malformed input (bare "0" is rejected too).
-//
-// Supported forms:
-//   <n>           positive integer  → { kind:"number", value:<n> }
-//   <NODE_ID>     alphanumeric/_ ID → { kind:"id", value:<NODE_ID> }
-//   https://github.com/users/<login>/projects/<n>
-//   https://github.com/orgs/<login>/projects/<n>
-//                 board URI        → { kind:"uri", number:<n>, owner:<login>, ownerKind:"user"|"org" }
-const GLOBAL_NODE_ID_RE = /^[A-Za-z0-9_]+$/;
-
-// GitHub Projects V2 board URI pattern (user- or org-scoped boards).
-const BOARD_URI_RE = /^https:\/\/github\.com\/(users|orgs)\/([A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)\/projects\/(\d+)$/;
-
-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();
-
-  // Board URI: https://github.com/users/<login>/projects/<n>
-  //            https://github.com/orgs/<login>/projects/<n>
-  const uriMatch = BOARD_URI_RE.exec(trimmed);
-  if (uriMatch) {
-    const ownerKind = uriMatch[1] === "users" ? "user" : "org";
-    const owner = uriMatch[2];
-    const number = Number(uriMatch[3]);
-    if (number < 1) {
-      throw Object.assign(
-        new Error(`--project board URI must reference a positive project number, got "${raw}"`),
-        { code: "INVALID_PROJECT" },
-      );
-    }
-    return { kind: "uri", number, owner, ownerKind };
-  }
-
-  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, a node ID, or a board URI, 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, a node ID, or a board URI, got "${raw}"`),
-    { code: "INVALID_PROJECT" },
-  );
-}
-
-// Selector precedence: explicit --project ref wins; else resolve by board title
-// from .devloops (passed as args.projectTitle by runCli). Fail closed if neither.
-function resolveProjectSelector(args) {
-  const hasProjectRef = typeof args.project === "string" && args.project.trim().length > 0;
-  const projectRef = hasProjectRef ? parseProjectRef(args.project) : null;
-  const projectTitle = !hasProjectRef && typeof args.projectTitle === "string" && args.projectTitle.trim().length > 0
-    ? args.projectTitle.trim()
-    : null;
-  if (!projectRef && !projectTitle) {
-    throw Object.assign(
-      new Error("--project is required (or set queue.projectNumber / queue.boardTitle in .devloops)"),
-      { code: "INVALID_PROJECT" },
-    );
-  }
-  return { projectRef, projectTitle };
-}
-
-// Find the project in `projects` matching the resolved selector; throws
-// PROJECT_NOT_FOUND (desc: "<id>" / number N / title "T" / URI number N under "<owner>").
-function findProject(projects, { projectRef, projectTitle }, owner) {
-  let project;
-  if (projectRef) {
-    if (projectRef.kind === "id") {
-      project = projects.find((p) => p.id === projectRef.value);
-    } else if (projectRef.kind === "uri") {
-      project = projects.find((p) => p.number === projectRef.number);
-    } else {
-      project = projects.find((p) => p.number === projectRef.value);
-    }
-  } else {
-    project = projects.find((p) => p.title === projectTitle);
-  }
-  if (!project) {
-    const desc = projectRef
-      ? (projectRef.kind === "id"
-          ? `"${projectRef.value}"`
-          : projectRef.kind === "uri"
-            ? `URI number ${projectRef.number} under "${projectRef.owner}"`
-            : `number ${projectRef.value}`)
-      : `title "${projectTitle}"`;
-    throw Object.assign(
-      new Error(`Project ${desc} not found under owner "${owner}"`),
-      { code: "PROJECT_NOT_FOUND" },
-    );
-  }
-  return project;
-}
-
-// Apply .devloops board settings when --project was not passed. Precedence:
-// explicit --project flag > queue.projectNumber/boardTitle. Mutates args.
-function applyDevloopsBoard(args, cwd) {
-  if (args.project === undefined) {
-    const settings = resolveSettings(cwd);
-    if (settings?.project) args.project = String(settings.project);
-    else if (settings?.title) args.projectTitle = settings.title;
-  }
-}
-
-export { resolveSettings, parseProjectRef, resolveProjectSelector, findProject, applyDevloopsBoard };
+export { resolveSettings, parseProjectRef, parseItemRef, resolveProjectSelector, findProject, applyDevloopsBoard } from "@dev-loops/core/projects/resolve-project";