@dev-loops/core 1.0.0-rc.2 → 1.0.0-rc.3

package/src/loop/copilot-ci-status.mjs

@@ -5,6 +5,42 @@ const STATUS_CONTEXT_FAILURE_STATES = new Set(["FAILURE", "ERROR"]);
 const STATUS_CONTEXT_PENDING_STATES = new Set(["PENDING", "EXPECTED"]);
 const STATUS_CONTEXT_SUCCESS_STATES = new Set(["SUCCESS"]);
 
+/**
+ * Name of the server-side "Gate evidence" check dev-loops posts on its own
+ * pull requests (`.github/workflows/gate-evidence.yml`). Its conclusion is
+ * DERIVED from the loop's own progress (a clean current-head
+ * pre_approval_gate verdict), not an independent build/test signal — so the
+ * loop must exclude it, by this exact name only, when deriving the CI status
+ * that gates its own pre_approval step. Otherwise the loop could never post
+ * the very verdict that would turn this check green (#1358).
+ */
+export const LOOP_DERIVED_CI_CHECK_NAME = "gate-evidence";
+
+function checkEntryName(entry) {
+  if (typeof entry?.name === "string" && entry.name.length > 0) return entry.name;
+  if (typeof entry?.context === "string" && entry.context.length > 0) return entry.context;
+  return "";
+}
+
+/**
+ * Split rollup/check-run entries into those matching `targetName` and the rest.
+ * Shared by both statusCheckRollup-shaped and check-runs-shaped payloads —
+ * both use `.name` (check-runs also use `.context` for legacy StatusContext).
+ *
+ * @param {Array<object>} entries
+ * @param {string} targetName
+ * @returns {{ matched: Array<object>, rest: Array<object> }}
+ */
+export function partitionEntriesByCheckName(entries, targetName) {
+  const list = Array.isArray(entries) ? entries : [];
+  const matched = [];
+  const rest = [];
+  for (const entry of list) {
+    (checkEntryName(entry) === targetName ? matched : rest).push(entry);
+  }
+  return { matched, rest };
+}
+
 function normalizeHeadScopedCiStatus(status) {
   return VALID_HEAD_SCOPED_CI_STATUSES.has(status) ? status : "none";
 }
@@ -253,3 +289,26 @@ export function normalizeHeadScopedCiContract({
 
   return buildCiContract(overallStatus);
 }
+
+/**
+ * Derive a loop-safe CI status from a PR `statusCheckRollup` snapshot: the
+ * `LOOP_DERIVED_CI_CHECK_NAME` entry (`gate-evidence`) is excluded from the
+ * status computation before it can block, and surfaced separately so a
+ * genuinely failing check right beside it can never be masked. Every reason
+ * gate-evidence can be red (missing draft_gate/pre_approval evidence,
+ * unresolved threads, a stale runner) is independently tracked elsewhere in
+ * the loop snapshot, so excluding it here loses no real signal: `status`
+ * stays a plain "success" (not an "unconfirmed" crediblyGreen) when it is the
+ * only excluded failure and everything else is green.
+ *
+ * @param {Array<object>} rollup
+ * @returns {{ status: "success"|"failure"|"pending"|"none", excludedFailureDetails: Array<string> }}
+ */
+export function deriveLoopCiStatusFromRollup(rollup) {
+  const { matched, rest } = partitionEntriesByCheckName(rollup, LOOP_DERIVED_CI_CHECK_NAME);
+  const status = normalizeStatusCheckRollupStatus(rest);
+  const excludedFailureDetails = matched.length > 0 && normalizeStatusCheckRollupStatus(matched) === "failure"
+    ? [LOOP_DERIVED_CI_CHECK_NAME]
+    : [];
+  return { status, excludedFailureDetails };
+}

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

@@ -12,7 +12,7 @@
  * becomes an explicit bounded input (agentFixStatus) rather than hidden orchestration behavior.
  */
 
-import { normalizeStatusCheckRollupContract } from "./copilot-ci-status.mjs";
+import { deriveLoopCiStatusFromRollup } from "./copilot-ci-status.mjs";
 
 /** Stable state name constants for the async Copilot review/fix loop. */
 export const STATE = Object.freeze({
@@ -191,7 +191,7 @@ export function isCopilotRoundCapReached({ copilotReviewRoundCount, maxCopilotRo
 }
 
 export function normalizeCiStatus(rollup) {
-  return normalizeStatusCheckRollupContract(rollup).overallStatus;
+  return deriveLoopCiStatusFromRollup(rollup).status;
 }
 
 export function buildSnapshotFromPrFacts({
@@ -206,11 +206,15 @@ export function buildSnapshotFromPrFacts({
   ciStatus,
   lastCopilotRoundMaxSignal = null,
   failureDetails = [],
-  excludedFailureDetails = [],
+  excludedFailureDetails,
 }) {
   const prState = typeof prData?.state === "string" ? prData.state.toUpperCase() : "OPEN";
   const prMerged = prState === "MERGED";
   const prClosed = prState === "CLOSED";
+  // Default derivation excludes the loop's own gate-evidence check (#1358) so a
+  // caller that never threads an explicit ciStatus (e.g. gate-coordination
+  // detection) still never treats it as a blocking CI failure.
+  const rollupDerivation = deriveLoopCiStatusFromRollup(prData?.statusCheckRollup);
 
   return normalizeSnapshot({
     prExists: true,
@@ -225,9 +229,9 @@ export function buildSnapshotFromPrFacts({
     actionableThreadCount,
     copilotReviewRoundCount,
     lastCopilotRoundMaxSignal,
-    ciStatus: ciStatus ?? normalizeCiStatus(prData?.statusCheckRollup),
+    ciStatus: ciStatus ?? rollupDerivation.status,
     failureDetails,
-    excludedFailureDetails,
+    excludedFailureDetails: excludedFailureDetails ?? rollupDerivation.excludedFailureDetails,
   });
 }
 

package/src/loop/gate-carry-forward.mjs

@@ -17,7 +17,7 @@
  * caller records the carried verdict with provenance pointing at the PRIOR head's
  * reviewer (that reviewer genuinely reviewed this angle's surface, which the delta
  * did not touch), clearly marked as carried — see
- * docs/gate-review-sub-loop-contract.md and write-gate-findings-log.mjs's
+ * skills/docs/gate-review-sub-loop-contract.md and write-gate-findings-log.mjs's
  * `carriedFromHead` provenance field.
  *
  * The angle -> review-surface mapping is DERIVED from the single source of truth

package/src/loop/gate-fanin.mjs

@@ -30,7 +30,7 @@ const VALID_VERDICTS = new Set(["clean", "findings_present"]);
  * depth). The flow MUST fail closed with this message and route the gate review
  * to the conductor rather than silently degrading to a single-agent inline
  * review (which requireFanoutProvenance is designed to reject). Documented as a
- * contract in docs/gate-review-sub-loop-contract.md.
+ * contract in skills/docs/gate-review-sub-loop-contract.md.
  */
 export const FANOUT_UNAVAILABLE_MESSAGE = "fan-out unavailable — route to conductor";
 
@@ -79,7 +79,7 @@ export function countDistinctReviewers(perAngle) {
  * is well-formed and consistent. Shared by the write path (write-gate-findings-log)
  * and the enforcement read path (buildPreMergeGateCheck) so both agree.
  *
- * Consistency rule (documented in docs/gate-review-sub-loop-contract.md):
+ * Consistency rule (documented in skills/docs/gate-review-sub-loop-contract.md):
  *   - `distinctReviewers` must be a non-negative integer.
  *   - `perAngle` must be an array, and non-empty when `distinctReviewers > 0`.
  *   - `distinctReviewers` must be <= the count of DISTINCT reviewer identities

package/src/loop/handoff-envelope.mjs

@@ -21,7 +21,7 @@ import {
 import { normalizeRepoSlug } from "../github/repo-slug.mjs";
 import { COPILOT_REVIEW_WAIT_TIMEOUT_MS } from "./policy-constants.mjs";
 import { resolveEffectiveAsyncStartMode } from "./async-start-contract.mjs";
-import { resolveHumanMergeOnly } from "../config/config.mjs";
+import { resolveGateConfig, resolveHumanMergeOnly } from "../config/config.mjs";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -354,20 +354,19 @@ function applySpecSourceVariant(criteria, specSource) {
 
 function deriveGateConfig(settings, subGate) {
   const gateKey = subGate === "pre-approval" ? "preApproval" : subGate;
-  const gateSettings = settings?.gates?.[gateKey];
-  if (!gateSettings) return undefined;
-
-  const angles = Array.isArray(gateSettings.angles) ? [...gateSettings.angles] : [];
-  const excludeAngles = Array.isArray(gateSettings.excludeAngles) ? [...gateSettings.excludeAngles] : [];
-  const filteredAngles = angles.filter((a) => !excludeAngles.includes(a));
-
+  if (!settings?.gates?.[gateKey]) return undefined;
+
+  // Route through the canonical resolver rather than re-parsing
+  // gates.<gate>.angles by hand: resolveGateConfig already folds the unified
+  // angle-entry shape (mandatory/enabled per-entry, D3) into this same
+  // exclude-filtered angles + separate excludeAngles list the envelope
+  // contract has always shipped.
+  const resolved = resolveGateConfig(settings, gateKey);
   return {
-    angles: filteredAngles,
-    excludeAngles: excludeAngles.length > 0 ? excludeAngles : undefined,
-    blockCleanOnFindingSeverities: Array.isArray(gateSettings.blockCleanOnFindingSeverities)
-      ? [...gateSettings.blockCleanOnFindingSeverities]
-      : ["must-fix"],
-    requireCi: gateSettings.requireCi ?? true,
+    angles: resolved.angles ?? [],
+    excludeAngles: resolved.excludeAngles.length > 0 ? resolved.excludeAngles : undefined,
+    blockCleanOnFindingSeverities: resolved.blockCleanOnFindingSeverities,
+    requireCi: resolved.requireCi,
   };
 }
 

package/src/loop/pr-gate-coordination.mjs

@@ -1380,41 +1380,17 @@ function evaluatePrGateCoordinationCore(input = {}) {
   // exhausted and the current head is clean (zero unresolved threads + green CI)
   // — including a POST-CAP head Copilot has not (and will not) re-review, since
   // no further Copilot round is permitted. Re-requesting review is illegal here,
-  // so this MUST NOT dead-end at READY_TO_REREQUEST_REVIEW. It routes to the
-  // pre_approval_gate, which reviews the post-cap head itself (per #848). The CI
-  // guards below still hold (failing / credibly-green CI blocks), and conflicts /
-  // blocked states are handled earlier, so genuinely-blocked states still forbid
-  // pre_approval. Mirrors LOW_SIGNAL_CONVERGED routing with round-cap reasoning.
+  // so this MUST NOT dead-end at READY_TO_REREQUEST_REVIEW — nor at a forced
+  // rerequest for a post-convergence significant change (#1387): the cap makes
+  // that rerequest impossible (request-copilot-review suppresses it), so a
+  // significant change discovered here is reviewed by the pre_approval_gate
+  // fan-out itself, on the post-cap head, same as any other clean fallback. It
+  // routes to the pre_approval_gate, which reviews the post-cap head itself
+  // (per #848). The CI guards below still hold (failing / credibly-green CI
+  // blocks), and conflicts / blocked states are handled earlier, so
+  // genuinely-blocked states still forbid pre_approval. Mirrors
+  // LOW_SIGNAL_CONVERGED routing with round-cap reasoning.
   if (effectiveLifecycleState === STATE.ROUND_CAP_CLEAN_FALLBACK) {
-    if (roundCapNewCycleRequired) {
-      pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW]);
-      pushUnique(forbiddenActions, [
-        PR_CHECKPOINT_ACTION.RUN_DRAFT_GATE,
-        PR_CHECKPOINT_ACTION.MARK_READY_FOR_REVIEW,
-        PR_CHECKPOINT_ACTION.REQUEST_COPILOT_REVIEW,
-        PR_CHECKPOINT_ACTION.RUN_PRE_APPROVAL_GATE,
-        PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY,
-      ]);
-      return buildResult({
-        repo: input.repo ?? null,
-        pr: Number.isInteger(input.pr) ? input.pr : null,
-        currentHeadSha,
-        lifecycleState: STATE.READY_TO_REREQUEST_REVIEW,
-        loopDisposition: DISPOSITION.ACTION_REQUIRED,
-        gateBoundary: PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW,
-        draftGateAlreadySatisfied: roundCapReached ? true : draftGateAlreadySatisfied,
-        draftGate,
-        preApprovalGate,
-        allowedNextActions,
-        forbiddenActions,
-        nextAction: PR_CHECKPOINT_ACTION.REREQUEST_COPILOT_REVIEW,
-        reason: `The previous Copilot cycle converged at the round cap (${copilotReviewRoundCount}/${maxCopilotRounds}), but significant post-convergence changes landed on the current head. Open a new cycle and re-request Copilot review before entering \`pre_approval_gate\`.`,
-        mergeStateStatus,
-        conflictFiles,
-        refinementArtifact,
-        copilotReviewRoundCount,
-      });
-    }
     if (preApprovalRequireCi && (ciStatus === "failure" || ciStatus === "crediblyGreen")) {
       pushUnique(allowedNextActions, [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]);
       pushUnique(forbiddenActions, postDraftForbidden);

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

@@ -172,7 +172,10 @@ function readDevloopsSettings(repoRoot) {
     try {
       const raw = readFileSync(base + ext, "utf8");
       const settings = ext === ".json" ? JSON.parse(raw) : parseYaml(raw);
-      return { settings: settings?.queue ?? null };
+      // `tracker` (issue #1408, the tracker-agnostic seam) is surfaced
+      // alongside `queue` so loadBoardConfig can prefer tracker.board over
+      // the deprecated queue.board without a second file read.
+      return { settings: settings?.queue ?? null, tracker: settings?.tracker ?? null };
     } catch (err) {
       if (err?.code === "ENOENT") {
         // try next extension
@@ -184,21 +187,35 @@ function readDevloopsSettings(repoRoot) {
   if (foundError) {
     return { error: foundError.message };
   }
-  return { settings: null };
+  return { settings: null, tracker: null };
+}
+
+/** Read a board selector ({number} or {title}) into the loadBoardConfig
+ * result shape, or null when neither is set. */
+function boardSelector(board) {
+  if (!board || typeof board !== "object") return null;
+  if (typeof board.number === "number" && board.number > 0) {
+    return { enabled: true, projectNumber: board.number };
+  }
+  if (typeof board.title === "string" && board.title.trim().length > 0) {
+    return { enabled: true, boardTitle: board.title.trim() };
+  }
+  return null;
 }
 
 export function loadBoardConfig(repoRoot) {
-  const { settings: queue, error } = readDevloopsSettings(repoRoot);
+  const { settings: queue, tracker, error } = readDevloopsSettings(repoRoot);
   if (error) {
     return { enabled: false, reason: `config read/parse error: ${error}` };
   }
+  // tracker.board (canonical) takes priority over the deprecated queue.board
+  // (issue #1408) — see resolveTrackerBoard in ../config/config.mjs for the
+  // equivalent resolution against the validated, loaded config.
+  const trackerBoard = boardSelector(tracker?.board);
+  if (trackerBoard) return trackerBoard;
   if (!queue) return { enabled: false };
-  if (typeof queue.projectNumber === "number" && queue.projectNumber > 0) {
-    return { enabled: true, projectNumber: queue.projectNumber };
-  }
-  if (typeof queue.boardTitle === "string" && queue.boardTitle.trim().length > 0) {
-    return { enabled: true, boardTitle: queue.boardTitle.trim() };
-  }
+  const queueBoard = boardSelector(queue.board);
+  if (queueBoard) return queueBoard;
   return { enabled: false };
 }
 

package/src/projects/resolve-project.mjs

@@ -5,6 +5,10 @@ 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.
+//
+// `tracker.board` (issue #1408, the tracker-agnostic seam) takes priority over
+// the deprecated `queue.board` — same precedence as loadBoardConfig in
+// ../loop/queue-board-sync.mjs and resolveTrackerBoard in ../config/config.mjs.
 function resolveSettings(cwd) {
   const basePath = path.join(cwd, ".devloops");
   const extensions = ["", ".yaml", ".yml", ".json"];
@@ -13,13 +17,16 @@ function resolveSettings(cwd) {
       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();
+      const board = settings?.tracker?.board ?? queue?.board;
+      if (board && typeof board === "object") {
+        if (typeof board.number === "number" && Number.isInteger(board.number) && board.number > 0) {
+          out.project = board.number;
+        } else if (typeof board.title === "string" && board.title.trim().length > 0) {
+          out.title = board.title.trim();
+        }
       }
+      if (!queue) return Object.keys(out).length > 0 ? out : null;
       if (typeof queue.archiveOlderThanDays === "number" && Number.isInteger(queue.archiveOlderThanDays) && queue.archiveOlderThanDays > 0) {
         out.olderThanDays = queue.archiveOlderThanDays;
       }
@@ -132,7 +139,7 @@ function resolveProjectSelector(args) {
     : null;
   if (!projectRef && !projectTitle) {
     throw Object.assign(
-      new Error("--project is required (or set queue.projectNumber / queue.boardTitle in .devloops)"),
+      new Error("--project is required (or set queue.board.number / queue.board.title in .devloops)"),
       { code: "INVALID_PROJECT" },
     );
   }
@@ -171,7 +178,7 @@ function findProject(projects, { projectRef, projectTitle }, owner) {
 }
 
 // Apply .devloops board settings when --project was not passed. Precedence:
-// explicit --project flag > queue.projectNumber/boardTitle. Mutates args.
+// explicit --project flag > queue.board.number/queue.board.title. Mutates args.
 function applyDevloopsBoard(args, cwd) {
   if (args.project === undefined) {
     const settings = resolveSettings(cwd);

package/src/tracker/adapter.mjs

@@ -0,0 +1,127 @@
+/**
+ * Tracker adapter interface (issue #1408, the tracker-agnostic seam).
+ *
+ * Abstracts the work-item tracker (issues + optional board/queue) so the loop
+ * reads/writes issues and drives the queue/board through one generic seam.
+ * Mirrors the harness-adapter idiom exactly (`../harness/adapter.mjs`):
+ * `createTrackerAdapter(impl)` validates the Issues REQUIRED_METHODS and
+ * freezes the result; `resolveTrackerAdapter(config)` (see `./index.mjs`)
+ * picks a provider by config, with GitHub as the built-in default.
+ *
+ * Two capability groups (per the #1408 RFC):
+ *   - Issues (REQUIRED): every provider must implement these — the spec of
+ *     record a tracker-backed loop reads/writes.
+ *   - Board (OPTIONAL): present only when the provider has a board/queue.
+ *     Kept as a distinct, checkable capability (not folded into
+ *     REQUIRED_METHODS) so a provider with no board — or a future
+ *     composite/split adapter delegating board vs issues to different
+ *     providers (see the #1408 hybrid-tracker design note) — is still a
+ *     valid Tracker.
+ *
+ * @typedef {Object} TrackerIssue
+ * @property {string|number} id
+ * @property {string} title
+ * @property {string} body
+ * @property {string} url
+ * @property {string} state
+ * @property {string[]} assignees
+ *
+ * @typedef {Object} TrackerRef
+ * @property {string} repo
+ * @property {string|number} id
+ *
+ * @typedef {Object} TrackerAdapter
+ * @property {(urlOrRef: string) => TrackerRef} parseRef
+ * @property {(ref: TrackerRef) => Promise<TrackerIssue>} getIssue
+ * @property {(input: {repo: string, title: string, body: string}) => Promise<{id: string|number, url: string}>} createIssue
+ * @property {(ref: TrackerRef, edits: {title?: string, body?: string, assignees?: string[], milestone?: string}) => Promise<{edited: string[]}>} editIssue
+ * @property {(ref: TrackerRef, body: string) => Promise<{commentUrl: string}>} commentIssue
+ * @property {(filter: {repo: string, state?: string, labels?: string[], limit?: number}) => Promise<TrackerIssue[]>} listIssues
+ *   Every returned object is Issue-shaped (same field names as getIssue), but
+ *   a provider's underlying list call may not fetch per-item detail fields —
+ *   the built-in github provider's `gh issue list` returns only
+ *   id/title/state, so `body`/`url`/`assignees` are populated empty ("", [])
+ *   rather than omitted, not truly fetched. Call getIssue for those fields.
+ * @property {(ref: TrackerRef) => Promise<{hasOpenLinkedPr: boolean, prNumber: number|null}|null>} detectLinkedPr
+ * @property {(cfg: object) => Promise<object>} [ensureBoard]
+ * @property {(board: object) => Promise<object[]>} [listQueueItems]
+ * @property {(board: object, issueId: string|number) => Promise<object>} [addQueueItem]
+ * @property {(board: object, item: object, logicalColumn: string) => Promise<void>} [setItemStatus]
+ * @property {(board: object, item: object, position: object) => Promise<void>} [reorderItem]
+ * @property {(board: object, filter: object) => Promise<void>} [archiveItems]
+ */
+
+/** Issues capability — REQUIRED on every tracker provider. */
+export const REQUIRED_METHODS = Object.freeze([
+  "parseRef",
+  "getIssue",
+  "createIssue",
+  "editIssue",
+  "commentIssue",
+  "listIssues",
+  "detectLinkedPr",
+]);
+
+/** Board capability — OPTIONAL; present only when the provider has a board. */
+export const BOARD_METHODS = Object.freeze([
+  "ensureBoard",
+  "listQueueItems",
+  "addQueueItem",
+  "setItemStatus",
+  "reorderItem",
+  "archiveItems",
+]);
+
+/**
+ * Validate and freeze a tracker-adapter implementation. Requires the full
+ * Issues capability; Board methods are copied through (frozen) when present
+ * but are not required — a provider with no board is still a valid adapter.
+ *
+ * @param {Partial<TrackerAdapter>} impl
+ * @returns {TrackerAdapter}
+ */
+export function createTrackerAdapter(impl) {
+  if (!impl || typeof impl !== "object") {
+    throw new TypeError("createTrackerAdapter: impl must be an object");
+  }
+
+  for (const method of REQUIRED_METHODS) {
+    if (typeof impl[method] !== "function") {
+      throw new TypeError(`createTrackerAdapter: missing required method "${method}"`);
+    }
+  }
+
+  const adapter = {};
+  for (const method of REQUIRED_METHODS) {
+    adapter[method] = impl[method];
+  }
+  for (const method of BOARD_METHODS) {
+    if (typeof impl[method] === "function") {
+      adapter[method] = impl[method];
+    }
+  }
+
+  return Object.freeze(adapter);
+}
+
+/**
+ * Type guard for a value implementing at least the required Issues capability.
+ * @param {*} value
+ * @returns {value is TrackerAdapter}
+ */
+export function isTrackerAdapter(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  return REQUIRED_METHODS.every((method) => typeof value[method] === "function");
+}
+
+/**
+ * Whether an adapter also implements the optional Board capability in full.
+ * @param {*} value
+ * @returns {boolean}
+ */
+export function hasBoardCapability(value) {
+  if (!isTrackerAdapter(value)) return false;
+  return BOARD_METHODS.every((method) => typeof value[method] === "function");
+}

package/src/tracker/github-adapter.mjs

@@ -0,0 +1,150 @@
+import { createTrackerAdapter } from "./adapter.mjs";
+import {
+  viewIssue,
+  createIssue as coreCreateIssue,
+  editIssue as coreEditIssue,
+  commentIssue as coreCommentIssue,
+  listIssues as coreListIssues,
+  detectLinkedIssuePr,
+} from "../github/issue-ops.mjs";
+import { main as moveQueueItemMain } from "../projects/move-queue-item.mjs";
+import { main as listQueueItemsMain } from "../projects/list-queue-items.mjs";
+import { DEFAULT_STATE_COLUMN_NAMES } from "../loop/queue-board-sync.mjs";
+
+/**
+ * The v1 built-in GitHub tracker provider (issue #1408). A facade over the
+ * existing `gh issue` calls (now extracted to `../github/issue-ops.mjs`) and
+ * the GitHub Projects board tooling already in the repo — wiring, not a
+ * rewrite. Registered as the default provider by `./index.mjs`.
+ *
+ * Board capability is intentionally PARTIAL in this pass: only
+ * `listQueueItems`/`setItemStatus` are wired (the two board primitives
+ * already extracted to `../projects/*.mjs`). `ensureBoard`/`addQueueItem`/
+ * `reorderItem`/`archiveItems` still live only as `scripts/projects/*.mjs`
+ * CLI tools and are intentionally NOT duplicated into this adapter — no hot
+ * caller in this pass needs them through the seam, and `packages/core` must
+ * not import from repo-root `scripts/` (that would break `@dev-loops/core`
+ * when installed standalone). Extract them here too when a real caller needs
+ * board-writer access through the adapter (YAGNI).
+ */
+export function createGithubTrackerAdapter({ env = process.env, ghCommand = "gh", run } = {}) {
+  const deps = { env, ghCommand, ...(run ? { run } : {}) };
+  // detectLinkedIssuePr and the projects/*.mjs board primitives all name
+  // their DI param `runChild` (not `run`, unlike the other issue-ops
+  // functions) — pass the same injected runner under both names so a
+  // caller-supplied `run` reaches every dependency, not just issue-ops.
+  const runChildDeps = { env, ...(run ? { runChild: run } : {}) };
+  const linkedPrDeps = { ...runChildDeps, ghCommand };
+
+  function parseRef(urlOrRef) {
+    const trimmed = String(urlOrRef ?? "").trim();
+    // owner/repo#123
+    const hashMatch = /^([^/#\s]+\/[^/#\s]+)#(\d+)$/u.exec(trimmed);
+    if (hashMatch) {
+      return { repo: hashMatch[1], id: Number(hashMatch[2]) };
+    }
+    // Full GitHub issue URL: https://github.com/owner/repo/issues/123
+    const urlMatch = /^https?:\/\/github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)(?:[/?#].*)?$/u.exec(trimmed);
+    if (urlMatch) {
+      return { repo: urlMatch[1], id: Number(urlMatch[2]) };
+    }
+    throw new Error(`parseRef: unrecognized issue reference "${urlOrRef}" (expected "owner/repo#123" or a github.com issue URL)`);
+  }
+
+  async function getIssue({ repo, id }) {
+    const { issue } = await viewIssue({ repo, issue: id, fields: "number,title,body,url,state,assignees" }, deps);
+    return {
+      id: issue.number,
+      title: issue.title ?? "",
+      body: issue.body ?? "",
+      url: issue.url ?? "",
+      state: typeof issue.state === "string" ? issue.state.toLowerCase() : "",
+      assignees: Array.isArray(issue.assignees)
+        ? issue.assignees.map((a) => (typeof a?.login === "string" ? a.login : null)).filter((l) => l !== null)
+        : [],
+    };
+  }
+
+  async function createIssue({ repo, title, body, milestone, labels, assignees }) {
+    const result = await coreCreateIssue({ repo, title, body, milestone, labels, assignees }, deps);
+    return { id: result.issueNumber, url: result.url };
+  }
+
+  async function editIssue({ repo, id }, { title, body, assignees, milestone } = {}) {
+    // The tracker interface's flat `assignees` has no gh-native "replace"
+    // equivalent (`gh issue edit` only supports add/remove); this adapter
+    // treats it as an ADD list, matching the only current usage pattern in
+    // this repo (claiming an issue — see resolve-dev-loop-startup.mjs).
+    const result = await coreEditIssue({
+      repo,
+      issue: id,
+      title,
+      body,
+      addAssignees: assignees,
+      milestone,
+    }, deps);
+    return { edited: result.edited };
+  }
+
+  async function commentIssue({ repo, id }, body) {
+    const result = await coreCommentIssue({ repo, issue: id, body }, deps);
+    return { commentUrl: result.commentUrl };
+  }
+
+  async function listIssues({ repo, state, labels, limit }) {
+    const result = await coreListIssues({ repo, state, labels, limit }, deps);
+    // Normalize to the Tracker interface's Issue shape (same field names as
+    // getIssue), not the raw {number,title,state,labels} coreListIssues
+    // shape. `gh issue list` only returns number/title/state/labels — body/
+    // url/assignees are per-item fields `gh issue view` fetches, and this
+    // repo's list path never had them; fetching them here would be an N+1 gh
+    // call per listed issue. They are populated empty ("", []) rather than
+    // omitted, so every listIssues() result is still Issue-shaped (see
+    // TrackerAdapter.listIssues JSDoc in ./adapter.mjs).
+    return result.issues.map((issue) => ({
+      id: issue.number,
+      title: issue.title,
+      body: "",
+      url: "",
+      state: issue.state,
+      assignees: [],
+    }));
+  }
+
+  async function detectLinkedPr({ repo, id }) {
+    const result = await detectLinkedIssuePr({ repo, issue: id }, linkedPrDeps);
+    return { hasOpenLinkedPr: result.hasOpenLinkedPr, prNumber: result.prNumber };
+  }
+
+  async function listQueueItems(board) {
+    const result = await listQueueItemsMain({ repo: board.repo, project: board.project }, runChildDeps);
+    return result.items ?? [];
+  }
+
+  // `board.columnNames` is the github provider's logical-column -> Status
+  // mapping — callers source it from the existing, already-load-bearing
+  // `queue.statusColumns` config (via `loadStateColumnMap` in
+  // `../loop/queue-board-sync.mjs`), not a tracker-owned config key; unset
+  // falls back to the provider's own defaults (DEFAULT_STATE_COLUMN_NAMES).
+  async function setItemStatus(board, item, logicalColumn) {
+    const columnNames = { ...DEFAULT_STATE_COLUMN_NAMES, ...(board.columnNames ?? {}) };
+    const toColumn = columnNames[logicalColumn];
+    if (!toColumn) {
+      throw new Error(`setItemStatus: no display column configured for logical column "${logicalColumn}"`);
+    }
+    const itemRef = String(item?.itemId ?? item?.number ?? item);
+    await moveQueueItemMain({ repo: board.repo, project: board.project, item: itemRef, toColumn }, runChildDeps);
+  }
+
+  return createTrackerAdapter({
+    parseRef,
+    getIssue,
+    createIssue,
+    editIssue,
+    commentIssue,
+    listIssues,
+    detectLinkedPr,
+    listQueueItems,
+    setItemStatus,
+  });
+}