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

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/loop/reviewer-loop-state.mjs

@@ -1,6 +1,7 @@
 /**
  * Deterministic state machine and bounded planning/merge contracts for reviewer-side PR loops.
  */
+import { SUBMITTED_REVIEW_STATES } from "../github/copilot-helpers.mjs";
 
 export const REVIEWER_STATE = Object.freeze({
   WAITING_FOR_REVIEW_REQUEST: "waiting_for_review_request",
@@ -105,7 +106,6 @@ const VALID_LOCAL_RUN_STATUSES = new Set(["none", "running", "completed", "faile
 const VALID_LOCAL_MERGE_STATUSES = new Set(["none", "ready", "failed"]);
 const VALID_DRAFT_NOTIFICATION_STATUSES = new Set(["none", "notified"]);
 const VALID_SUBMISSION_STATUSES = new Set(["none", "submitted", "failed"]);
-const VALID_SUBMITTED_REVIEW_STATES = new Set(["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED"]);
 
 const SUPPORTED_REVIEW_ANGLES = Object.freeze([
   "correctness",
@@ -143,7 +143,7 @@ function normalizeSubmittedReviewState(value) {
   }
 
   const normalized = value.trim().toUpperCase();
-  return VALID_SUBMITTED_REVIEW_STATES.has(normalized) ? normalized : null;
+  return SUBMITTED_REVIEW_STATES.has(normalized) ? normalized : null;
 }
 
 /**

package/src/loop/ui-e2e-scoping.mjs

@@ -38,8 +38,10 @@ export const VIEWER_SOURCE_PATHS = Object.freeze([
 export const REGISTERED_ARTIFACT_PATHS = Object.freeze([
   "docs/presentations/introducing-dev-loops.html",
   "docs/presentations/dev-loops-deep-dive.html",
+  "docs/presentations/how-dev-loops-decided-itself.html",
   "docs/articles/introducing-dev-loops.html",
   "docs/articles/dev-loops-deep-dive.html",
+  "docs/articles/how-dev-loops-decided-itself.html",
 ]);
 
 export const VIEWER_ARTIFACT_ID = "inspect-run-viewer";

package/src/loop/ui-review-drive.mjs

@@ -44,6 +44,19 @@ export function isErrorResponseStatus(status) {
   return typeof status === "number" && (status < 200 || status >= 400);
 }
 
+/** The one owner of the request-abort carve-out: a request the browser itself
+ * aborted carries no defect signal. Navigating away cancels in-flight asset
+ * requests, so these appear on every multi-step flow. Matched per engine:
+ * WebKit reports "cancelled", Chromium "net::ERR_ABORTED", Firefox
+ * "NS_BINDING_ABORTED". Matching is case-insensitive and substring-based because
+ * engines wrap the token in longer text. A genuine DNS/connection/TLS failure
+ * carries a different token and is still classified must-fix. */
+export function isAbortedRequestFailure(failure) {
+  if (typeof failure !== "string") return false;
+  const f = failure.toLowerCase();
+  return f.includes("cancelled") || f.includes("canceled") || f.includes("err_aborted") || f.includes("ns_binding_aborted");
+}
+
 /** Bound the stack text carried onto a page-error failure so a runaway stack
  * (or a synthetic error with a huge stack) can't bloat the feed envelope. Keeps
  * the head — the top frames, where the throwing file:line sits. Exported so the
@@ -157,6 +170,16 @@ export function classifyFailures({
   }
 
   for (const f of requestFailures) {
+    // A request the BROWSER aborted is not evidence of a defect: navigating away
+    // cancels every asset request still in flight, so a flow with more than one
+    // `goto` manufactures one of these per unfinished image/font on the page it
+    // left. Measured on sofatutor 2026-08-05: a clean two-goto admin2 walk
+    // produced 13, all "cancelled", all classified must-fix — and since
+    // `ok: failures.length === 0`, they failed an otherwise passing drive and
+    // would have been posted as findings against the PR. This is the request-abort
+    // counterpart of the 3xx carve-out in isErrorResponseStatus: a real
+    // server/network fault still arrives with its own failure text and is kept.
+    if (isAbortedRequestFailure(f.failure)) continue;
     failures.push({
       kind: "request-failed",
       severity: MUST_FIX,

package/src/loop/ui-review-provision.mjs

@@ -37,6 +37,10 @@ const MUST_FIX = "must-fix";
  * @param {object} seams - Injected IO (all required except clock/log defaults).
  * @param {(a:{repoRoot:string,pr:number,branch?:string})=>Promise<{path:string,created:boolean,reused:boolean}>} seams.ensureWorktree
  * @param {(a:{worktreePath:string,repoRoot:string})=>{ok:boolean,message?:string,mainWorktreePath?:string|null}} seams.assertNotPrimary
+ * @param {(a:{worktreePath:string,repoRoot:string,pr:number})=>Promise<{ok:boolean,sha?:string|null,detail?:string}>} [seams.pinPrHead] -
+ *   Pin the worktree to the PR head and report the resolved SHA. Optional only
+ *   for back-compat: omitting it leaves the ref UNVERIFIED and is logged as such.
+ *   Runs after the primary-checkout guard, never before.
  * @param {(a:{repoRoot:string,worktreePath:string})=>Promise<{changed:boolean,detail:string}>} seams.detectDepDelta
  * @param {(a:{worktreePath:string})=>Promise<{ok:boolean,detail:string}>} seams.installDeps
  * @param {(worktreePath:string)=>Promise<object|null>} seams.resolveRunRecipe
@@ -58,6 +62,7 @@ export async function provisionAndBoot(
   {
     ensureWorktree,
     assertNotPrimary,
+    pinPrHead,
     detectDepDelta,
     installDeps,
     resolveRunRecipe,
@@ -111,6 +116,36 @@ export async function provisionAndBoot(
     );
   }
 
+  // 2b. Pin the worktree to the PR head, AFTER the primary-checkout guard above
+  //     (this checks out a ref, so it must never run in the primary checkout).
+  //     ensureWorktree resolves `branch` against what already exists, so the
+  //     default `pr-<n>` lands wherever that name happens to point — the base
+  //     branch when no remote carries it, and a same-named remote branch that
+  //     is not this PR's head when one does. A fork PR's head branch is on no
+  //     candidate remote at all. Reviewing the wrong commit still reports
+  //     ok:true, so pin the head explicitly and record the resolved SHA.
+  let headSha = null;
+  if (pinPrHead) {
+    const pin = await pinPrHead({ worktreePath, repoRoot, pr });
+    if (!pin?.ok) {
+      return stop(
+        `cannot pin PR head: ${pin?.detail ?? "unknown failure"}`,
+        {
+          kind: "pr-head-unpinned",
+          severity: MUST_FIX,
+          message: `the worktree could not be pinned to PR #${pr}'s head, so it cannot be reviewed as that PR: ${pin?.detail ?? "unknown failure"}`,
+        },
+        { worktreePath },
+      );
+    }
+    headSha = pin.sha ?? null;
+    record(`worktree pinned to PR head ${headSha ?? "(sha unknown)"}${pin.detail ? ` (${pin.detail})` : ""}`);
+  } else {
+    // Never silent: a caller without the seam gets an unverified ref, which is
+    // exactly the failure mode this step exists to close.
+    record("WARNING: PR head not pinned (no pinPrHead seam) — worktree ref is UNVERIFIED");
+  }
+
   // 3. Install only the dependency-lock delta vs. the primary checkout. No delta
   //    => deps are shared; installing anything would be a blind re-install.
   const delta = await detectDepDelta({ repoRoot, worktreePath });
@@ -256,6 +291,7 @@ export async function provisionAndBoot(
     worktreePath,
     created: wt.created,
     reused: wt.reused,
+    headSha,
     depInstall,
     migrations,
     boot: bootResult,

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 tracker.board — or the deprecated queue.board — number / 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,
+  });
+}

package/src/tracker/index.mjs

@@ -0,0 +1,50 @@
+export { createTrackerAdapter, isTrackerAdapter, hasBoardCapability, REQUIRED_METHODS, BOARD_METHODS } from "./adapter.mjs";
+export { createGithubTrackerAdapter } from "./github-adapter.mjs";
+export { createNoopTrackerAdapter } from "./noop-adapter.mjs";
+
+import { createGithubTrackerAdapter } from "./github-adapter.mjs";
+
+/** Built-in provider registry — GitHub is the only baked-in provider in v1
+ * (issue #1408); an external provider registers here post-1.0 (or a consumer
+ * passes its own adapter directly, bypassing this registry entirely). */
+const BUILTIN_PROVIDERS = Object.freeze({
+  github: createGithubTrackerAdapter,
+});
+
+/**
+ * Resolve the tracker adapter for the given effective dev-loop config.
+ *
+ * Config-driven with NO global/singleton state (#1408 design constraint): a
+ * future multi-tracker or per-capability layer just calls this again with a
+ * different scoped config, and it stays additive — this function never reads
+ * outside its `config` argument.
+ *
+ * `config?.tracker?.provider` selects a provider FROM THE REGISTERED
+ * `providers` map (default `"github"`, the only one registered out of the
+ * box) — the registry is extensible, not built-in-only: a consumer passes
+ * `{ providers: { ...builtins, jira: createJiraAdapter } }` to register an
+ * external provider (post-1.0 consumer concern). An unknown provider (not in
+ * whatever `providers` was actually passed) fails closed rather than
+ * silently falling back to GitHub. `config?.tracker?.plugin` is reserved for
+ * a consumer's own module-loading resolver in front of this — not
+ * implemented in this pass (non-goal, #1408).
+ *
+ * @param {import("../config/config.mjs").DevLoopConfig|null|undefined} config
+ * @param {{ env?: NodeJS.ProcessEnv, ghCommand?: string, providers?: Record<string, Function> }} [deps]
+ * @returns {import("./adapter.mjs").TrackerAdapter}
+ */
+export function resolveTrackerAdapter(config, { env, ghCommand, providers = BUILTIN_PROVIDERS } = {}) {
+  const provider = config?.tracker?.provider?.trim() || "github";
+  const factory = providers[provider];
+  if (typeof factory !== "function") {
+    throw new Error(
+      `Unknown tracker.provider "${provider}" — no adapter is registered for it. ` +
+      `Registered: ${Object.keys(providers).join(", ")} ("github" is the built-in default; ` +
+      `any others listed here were registered by the caller). ` +
+      `An external provider is a post-1.0 consumer concern: register it by passing ` +
+      `{ providers: { ...builtins, "${provider}": createYourAdapter } } to resolveTrackerAdapter ` +
+      `(setting tracker.provider in .devloops alone does not register one).`,
+    );
+  }
+  return factory({ ...(env !== undefined ? { env } : {}), ...(ghCommand !== undefined ? { ghCommand } : {}) });
+}

package/src/tracker/noop-adapter.mjs

@@ -0,0 +1,35 @@
+import { createTrackerAdapter } from "./adapter.mjs";
+
+/**
+ * Create a minimal, in-memory tracker adapter for tests. Every Issues method
+ * is a deterministic stub; Board methods are included so tests can also
+ * exercise the optional capability without a real GitHub Projects board.
+ *
+ * @param {Partial<import("./adapter.mjs").TrackerAdapter>} [overrides]
+ * @returns {import("./adapter.mjs").TrackerAdapter}
+ */
+export function createNoopTrackerAdapter(overrides = {}) {
+  return createTrackerAdapter({
+    parseRef: (urlOrRef) => ({ repo: "", id: String(urlOrRef) }),
+    getIssue: async (ref) => ({
+      id: ref?.id ?? "",
+      title: "",
+      body: "",
+      url: "",
+      state: "open",
+      assignees: [],
+    }),
+    createIssue: async () => ({ id: "0", url: "" }),
+    editIssue: async () => ({ edited: [] }),
+    commentIssue: async () => ({ commentUrl: "" }),
+    listIssues: async () => [],
+    detectLinkedPr: async () => null,
+    ensureBoard: async () => ({}),
+    listQueueItems: async () => [],
+    addQueueItem: async () => ({}),
+    setItemStatus: async () => {},
+    reorderItem: async () => {},
+    archiveItems: async () => {},
+    ...overrides,
+  });
+}