@dev-loops/core 1.0.4-pre.0 → 1.0.4-pre.2

package/src/loop/refinement-grill-state.mjs

@@ -7,7 +7,7 @@
  * synthesis enter ONLY as a bounded input consumed at the `await_answers`
  * state (and reflected in the `synthesized` snapshot flag), never as hidden
  * orchestration inside a deterministic coordinator script (keeps
- * OPS-NO-INLINE-INTERPRETER, #1224, clean).
+ * OPS-NO-INLINE-INTERPRETER clean).
  *
  * Mirrors the shape of `reviewer-loop-state.mjs` / `copilot-loop-state.mjs`:
  * a frozen STATE vocabulary, a frozen TRANSITIONS adjacency table, a
@@ -17,6 +17,15 @@
  * Honest handoff: when a gap is genuinely unanswerable (only-`inferred`, no
  * citation), the machine reaches `needs_human_handoff` naming the question
  * rather than fabricating an answer to force convergence.
+ *
+ * Zero-gap provenance (see ADR 0084, which amends ADR 0029): a zero-open-gap
+ * `detect_gaps` pass resolves to `grill_clean` only for a `plan` surface
+ * (shape-only, no comment surface) or when a `🔬 Grill / refinement results`
+ * comment is already recorded on the target; otherwise it stays at
+ * `detect_gaps` so the semantic pass still runs and records its own
+ * provenance, including a zero-gap outcome. `detectIssueRefinementArtifact`
+ * stays the sole shape/completeness predicate; provenance is a separate
+ * recorded fact, not a second refinedness detector.
  */
 
 import { trimmedOrNull } from "./normalize.mjs";
@@ -36,7 +45,10 @@ export const GRILL_STATE = Object.freeze({
 // re_grill, with re_grill either re-entering detect_gaps (a new answerable gap
 // surfaced) or terminating at grill_clean (fixed point). Any I/O/parse failure
 // fails closed to blocked_needs_user_decision; any unresolved (uncitable) gap
-// terminates honestly at needs_human_handoff.
+// terminates honestly at needs_human_handoff. A zero-open-gap detect_gaps pass
+// terminates at grill_clean only with recorded provenance (plan surface, or a
+// posted results comment); otherwise it stays at detect_gaps for the owed
+// semantic pass (ADR 0084).
 export const GRILL_TRANSITIONS = Object.freeze({
   [GRILL_STATE.LOAD_TARGET]: [
     GRILL_STATE.DETECT_GAPS,
@@ -81,12 +93,76 @@ const GRILL_NEXT_ACTIONS = Object.freeze({
 
 const VALID_SURFACES = new Set(["issue", "pr", "plan"]);
 
+// The exact comment title provenance is keyed on (GRILL-SUBLOOP-RATIONALE-COMMENT).
+const RESULTS_COMMENT_TITLE = "🔬 Grill / refinement results";
+// The exact first-line heading a results comment must carry -- SKILL.md Step 4
+// and the output artifact contract require exactly "## " (one hash pair, one
+// space), never a bare title or a different heading level.
+const RESULTS_COMMENT_HEADING = `## ${RESULTS_COMMENT_TITLE}`;
+// A results comment's recorded bypass line: "bypass: operator-authorized by <handle>",
+// with an optional leading @ before the handle and a case-insensitive "bypass:" key.
+const BYPASS_LINE_RE = /^bypass: operator-authorized by @?([A-Za-z0-9][A-Za-z0-9-]{0,38})\s*$/i;
+
 function normalizeCount(value) {
   return typeof value === "number" && Number.isFinite(value) && value > 0
     ? Math.floor(value)
     : 0;
 }
 
+/**
+ * Detect recorded grill provenance from a target's comments: a durable
+ * `🔬 Grill / refinement results` comment, optionally carrying an
+ * `bypass: operator-authorized by <handle>` line. The ephemeral
+ * `tmp/issues/issue-<n>/grill/` transcript is never a comment, so it never
+ * counts here.
+ *
+ * @param {Array<string|{body?: string}>} comments
+ * @returns {{provenanceRecorded: boolean, bypass: boolean, bypassBy: string|null}}
+ */
+export function detectGrillProvenance(comments) {
+  if (!Array.isArray(comments)) {
+    return { provenanceRecorded: false, bypass: false, bypassBy: null };
+  }
+
+  let provenanceRecorded = false;
+  let bypass = false;
+  let bypassBy = null;
+
+  for (const comment of comments) {
+    const body = typeof comment === "string"
+      ? comment
+      : (comment && typeof comment.body === "string" ? comment.body : null);
+    if (body === null) continue;
+
+    const lines = body.split(/\r?\n/);
+    // A comment counts as a results comment only when its FIRST non-empty
+    // line, trimmed, is EXACTLY the "## " heading -- this rejects a bare
+    // title, a different heading level (`###`), a missing space (`##🔬`),
+    // the title merely quoted in a code fence, or the title appearing later
+    // in an unrelated reply.
+    const firstNonEmpty = lines.find((line) => line.trim().length > 0);
+    const isResultsComment = firstNonEmpty !== undefined
+      && firstNonEmpty.trim() === RESULTS_COMMENT_HEADING;
+    if (!isResultsComment) continue;
+
+    provenanceRecorded = true;
+    if (!bypass) {
+      // Take the first bypass-line match across all results comments; a
+      // later comment's bypass line never overwrites an earlier one.
+      for (const line of lines) {
+        const match = line.trim().match(BYPASS_LINE_RE);
+        if (match) {
+          bypass = true;
+          bypassBy = match[1];
+          break;
+        }
+      }
+    }
+  }
+
+  return { provenanceRecorded, bypass, bypassBy };
+}
+
 /**
  * Canonicalize a raw grill snapshot into a deterministic shape.
  *
@@ -119,19 +195,32 @@ export function normalizeGrillSnapshot(raw) {
     // post-synthesis re-grill fixed-point signals
     reGrillRan: Boolean(raw.reGrillRan),
     reGrillFixedPoint: Boolean(raw.reGrillFixedPoint),
+
+    // recorded provenance: a posted `🔬 Grill / refinement results` comment
+    // (see detectGrillProvenance), and whether it carries a recorded bypass line.
+    // A bypass line only ever means anything alongside a recorded comment, so
+    // provenanceBypass is forced false when provenanceRecorded is false --
+    // never a standalone shortcut to grill_clean.
+    provenanceRecorded: Boolean(raw.provenanceRecorded),
+    provenanceBypass: Boolean(raw.provenanceRecorded) && Boolean(raw.provenanceBypass),
   };
 }
 
+const PROVENANCE_MISSING_NEXT_ACTION =
+  "Run the semantic gap pass on the loaded spec, then post the \"🔬 Grill / refinement results\" comment recording the outcome — including a zero-gap pass, which states that no gaps were found";
+
 /**
  * Deterministically interpret the current refinement-grill state.
  *
  * @param {object} snapshot
- * @returns {{state: string, allowedTransitions: string[], nextAction: string}}
+ * @returns {{state: string, allowedTransitions: string[], nextAction: string, reason: string|null, bypass: boolean}}
  */
 export function interpretRefinementGrillState(snapshot) {
   const s = normalizeGrillSnapshot(snapshot);
 
   let state;
+  let reason = null;
+  let bypass = false;
 
   if (s.loadFailed) {
     // Fail closed on any load/parse failure, from any point in the loop.
@@ -155,17 +244,40 @@ export function interpretRefinementGrillState(snapshot) {
     // Bounded answer input present -> apply synthesis.
     state = GRILL_STATE.SYNTHESIZE;
   } else if (s.detectRan) {
-    // Detection ran with no unresolved and no pending answers:
-    // open gaps -> await answers; zero gaps -> clean fixed point
-    // (also the already-refined, zero-iteration path).
-    state = s.openGapCount > 0 ? GRILL_STATE.AWAIT_ANSWERS : GRILL_STATE.GRILL_CLEAN;
+    if (s.openGapCount > 0) {
+      // Detection ran; answerable gaps still open -> await answers.
+      state = GRILL_STATE.AWAIT_ANSWERS;
+    } else if (s.surface === "plan") {
+      // Local plan files have no comment surface: shape-only, zero-iteration clean.
+      state = GRILL_STATE.GRILL_CLEAN;
+      reason = "plan_shape_only";
+    } else if (s.provenanceBypass) {
+      // A recorded bypass line still counts as recorded provenance.
+      state = GRILL_STATE.GRILL_CLEAN;
+      reason = "provenance_bypass_recorded";
+      bypass = true;
+    } else if (s.provenanceRecorded) {
+      state = GRILL_STATE.GRILL_CLEAN;
+      reason = "provenance_recorded";
+    } else {
+      // Zero open gaps but no recorded provenance: the semantic pass is still
+      // owed (ADR 0084) — stay at detect_gaps rather than short-circuiting.
+      state = GRILL_STATE.DETECT_GAPS;
+      reason = "provenance_missing";
+    }
   } else {
     state = GRILL_STATE.DETECT_GAPS;
   }
 
+  const nextAction = reason === "provenance_missing"
+    ? PROVENANCE_MISSING_NEXT_ACTION
+    : GRILL_NEXT_ACTIONS[state];
+
   return {
     state,
     allowedTransitions: [...GRILL_TRANSITIONS[state]],
-    nextAction: GRILL_NEXT_ACTIONS[state],
+    nextAction,
+    reason,
+    bypass,
   };
 }

package/src/loop/review-operation.mjs

@@ -0,0 +1,161 @@
+/**
+ * review-operation
+ *
+ * The ONE operation-scoped authority for the legal dispatchable-angle pool and
+ * the reviewer role it authorizes. write-gate-context.mjs's standalone-review
+ * angle union and the `dev-loops gate resolve-role` CLI both consume this
+ * module instead of reconstructing membership/eligibility rules of their own.
+ * The draft/pre-approval/spike dispatch paths keep calling
+ * `resolveGateAngleContract` directly for their pool, which this module wraps
+ * (see `resolveOperationAnglePool` below) rather than duplicating.
+ *
+ * `resolveOperationAnglePool` owns only the legal CANDIDATE catalog for an
+ * operation. Diff-/tier-/PR-fact-driven SELECTION from that catalog (which
+ * angles actually run this round) and any later spec-of-record pruning stay
+ * downstream dispatch/planning concerns (see write-gate-context.mjs's
+ * `resolveReviewGateAngles`, which imports this module for its union instead
+ * of recomputing it).
+ *
+ * `resolveOperationReviewerRole` is the authoritative exit-code boundary the
+ * `dev-loops gate resolve-role` CLI consumes for standalone/defensive role
+ * resolution: `ok` is fail-closed true only when the merged config loaded
+ * with no errors AND the requested angle is a legal member of the named
+ * operation's pool. `status` is a DIAGNOSTIC field only (never a second
+ * reviewer decision surface); see skills/docs/gate-review-comment-contract.md
+ * and skills/docs/gate-review-sub-loop-contract.md.
+ */
+import { resolveGateAngleContract, resolveGateAngles, resolveReviewerRole, resolveRoleModel } from "../config/config.mjs";
+import { GATE_CONFIG_KEY } from "./gate-fanin.mjs";
+
+/** The closed review-operation vocabulary. Standalone `review` is only ever selected by name, never inferred. */
+export const REVIEW_OPERATIONS = Object.freeze(["draft_gate", "pre_approval_gate", "review", "spike"]);
+
+// GATE_CONFIG_KEY (gate-fanin.mjs) has no `spike` entry — other code relies on
+// its absence of review/spike — so this operation-scoped table adds it locally
+// instead of widening the shared one.
+const OPERATION_GATE_KEY = Object.freeze({ ...GATE_CONFIG_KEY, spike: "spike" });
+
+/**
+ * Resolve the legal candidate angle pool for a review operation from the
+ * fully merged config:
+ *   - draft_gate / pre_approval_gate / spike: the effective `gates.<key>`
+ *     pool (`resolveGateAngleContract(config, key).pool` — mandatory/static/
+ *     additive rules applied, disabled/excluded angles removed).
+ *   - review: the de-duplicated, order-stable union of the static draft and
+ *     pre-approval angle sets (`resolveGateAngles`, NOT the additive/tier
+ *     pool) — standalone review's existing dedicated semantics; it gains no
+ *     diff-tier or additive selection here.
+ * An unrecognized operation throws (arg-identity error, not a config-layer
+ * concern; callers validate `--gate` before ever reaching config load).
+ * @param {import("../config/config.mjs").DevLoopConfig} config
+ * @param {"draft_gate"|"pre_approval_gate"|"review"|"spike"} operation
+ * @returns {string[]}
+ */
+export function resolveOperationAnglePool(config, operation) {
+  if (!REVIEW_OPERATIONS.includes(operation)) {
+    throw new Error(`Unknown review operation: ${JSON.stringify(operation)} (expected one of ${REVIEW_OPERATIONS.join(", ")})`);
+  }
+  if (operation === "review") {
+    return [...new Set([
+      ...(resolveGateAngles(config, "draft") ?? []),
+      ...(resolveGateAngles(config, "preApproval") ?? []),
+    ])];
+  }
+  return resolveGateAngleContract(config, OPERATION_GATE_KEY[operation]).pool ?? [];
+}
+
+/**
+ * @typedef {object} OperationReviewerRoleResult
+ * @property {boolean} ok - Fail-closed reviewer safety boundary: `configErrors.length === 0 && pool.includes(angle)`.
+ * @property {"draft_gate"|"pre_approval_gate"|"review"|"spike"} operation
+ * @property {string} angle
+ * @property {"claude"|"pi"} harness
+ * @property {string} persona
+ * @property {string|null} prompt
+ * @property {string|null} model - Authoritative merged model tier (`resolveRoleModel(..., { kind: "angle" })`).
+ * @property {boolean} fallback
+ * @property {"config-error"|"non-member"|"fallback"|"prompt-missing"|"resolved"} status - Diagnostic only; never a reviewer decision branch.
+ * @property {string[]} warnings
+ * @property {Array<unknown>} configErrors
+ */
+
+/**
+ * Resolve one angle's reviewer role for a review operation, authorized
+ * against `resolveOperationAnglePool`. This is the shared authority a CLI
+ * (`gate resolve-role`), dispatch/planning, or defensive validation all call —
+ * none of them may reimplement membership/union/additive/disabled/spike
+ * classification locally.
+ * @param {{ config: import("../config/config.mjs").DevLoopConfig, errors?: Array<unknown> }} loadResult - the `{ config, errors }` shape `loadDevLoopConfig` returns.
+ * @param {{ operation: "draft_gate"|"pre_approval_gate"|"review"|"spike", angle: string, harness: "claude"|"pi" }} params
+ * @returns {OperationReviewerRoleResult}
+ */
+export function resolveOperationReviewerRole(loadResult, { operation, angle, harness }) {
+  const config = loadResult?.config;
+  const configErrors = Array.isArray(loadResult?.errors) ? loadResult.errors : [];
+  const configErrorPresent = configErrors.length > 0;
+  // An unrecognized operation is a closed-vocabulary argument failure, not a
+  // config-layer concern; it must throw unconditionally, even when a config
+  // error is also on record — never degraded to a misleading config-error
+  // result below. Validate before the try so this throw is never swallowed.
+  if (!REVIEW_OPERATIONS.includes(operation)) {
+    throw new Error(`Unknown review operation: ${JSON.stringify(operation)} (expected one of ${REVIEW_OPERATIONS.join(", ")})`);
+  }
+  let pool;
+  try {
+    pool = resolveOperationAnglePool(config, operation);
+  } catch (error) {
+    // A config that already failed merged schema validation (non-empty
+    // `errors` from loadDevLoopConfig) can still reach here with a gate shape
+    // resolveGateConfig itself rejects (e.g. an invalid
+    // `gates.<gate>.blockCleanOnFindingSeverities`). That is a config-layer
+    // failure the caller's own config-error fail-closed status already
+    // covers, so degrade to an empty pool instead of an unhandled exception
+    // reaching the reviewer boundary. With no config error on record, this is
+    // a real schema-invalid gate shape a caller must see: rethrow.
+    if (!configErrorPresent) throw error;
+    pool = [];
+  }
+  const member = pool.includes(angle);
+  const ok = !configErrorPresent && member;
+
+  const role = resolveReviewerRole(config, angle);
+  const model = resolveRoleModel(config, { role: angle, harness, kind: "angle" });
+
+  const warnings = [];
+  let status;
+  if (configErrorPresent) {
+    status = "config-error";
+    warnings.push(
+      `${configErrors.length} config-layer error(s); the resolved role may be a shipped default and must not be trusted.`,
+    );
+  } else if (!member) {
+    status = "non-member";
+    warnings.push(`angle '${angle}' is not a member of the '${operation}' operation's legal candidate pool.`);
+  } else if (role.fallback) {
+    status = "fallback";
+    warnings.push(
+      `angle '${angle}' is authorized for '${operation}' but has no dedicated persona/prompt entry; the default-reviewer persona is returned.`,
+    );
+  } else if (typeof role.prompt !== "string" || role.prompt.trim() === "") {
+    status = "prompt-missing";
+    warnings.push(
+      `angle '${angle}' resolved persona '${role.persona}' but its focus prompt is null/empty; review with no angle-specific focus instruction.`,
+    );
+  } else {
+    status = "resolved";
+  }
+
+  return {
+    ok,
+    operation,
+    angle,
+    harness,
+    persona: role.persona,
+    prompt: role.prompt,
+    model,
+    fallback: role.fallback,
+    status,
+    warnings,
+    configErrors,
+  };
+}

package/src/loop/spec-authority.mjs

@@ -498,6 +498,27 @@ export function validateSpecAuthorityVerdict(verdict, { findingsCount, criterion
   };
 }
 
+/**
+ * Dispose every spec-authority `finding_conflicts` finding `reject`, whatever
+ * its relevance disposition. Mutates the judge-enriched findings in place; the
+ * judge pass and the durable findings-log writer share it so the ledger's
+ * `judgeDisposition` matches what the judge pass enforces.
+ *
+ * @param {object[]} findings — judge-enriched findings, indexed as the verdict
+ * @param {Iterable<number>} conflictIndices — the `finding_conflicts` indexes
+ * @returns {object[]} the same `findings` array
+ */
+export function rejectFindingConflicts(findings, conflictIndices) {
+  const rejected = new Set(conflictIndices);
+  for (const [i, f] of findings.entries()) {
+    if (rejected.has(i) && f.judgeDisposition !== "reject") {
+      f.judgeRationale = `spec-authority finding_conflicts: rejected against the spec (was relevance-${f.judgeDisposition}) — ${f.judgeRationale ?? ""}`.trim();
+      f.judgeDisposition = "reject";
+    }
+  }
+  return findings;
+}
+
 /**
  * Resolve which prior criterion approvals survive a revision change. This is the
  * one authority for both invalidation rules:

package/src/projects/move-queue-item.mjs

@@ -3,7 +3,7 @@ import { runPickupRefinementGate } from "../loop/issue-refinement-artifact.mjs";
 import { loadStateColumnMap, LOGICAL_COLUMN } from "../loop/queue-board-sync.mjs";
 import { resolveProjectSelector, findProject, parseItemRef } from "./resolve-project.mjs";
 import { ghGraphql, resolveOwner } from "../github/gh.mjs";
-import { validateProjectsRepo, discoverProjects, listProjectFields, paginateNodes, extractStatus } from "./projects-access.mjs";
+import { validateProjectsRepo, discoverProjects, listProjectFields, extractStatus, resolveProjectItem } from "./projects-access.mjs";
 
 // ── Validation ───────────────────────────────────────────────────────────
 
@@ -11,33 +11,6 @@ const validateRepo = validateProjectsRepo;
 
 // ── GraphQL fragments ────────────────────────────────────────────────────
 
-const GET_PROJECT_ITEMS_BY_CONTENT = [
-  "query($projectId:ID!, $after:String) {",
-  "  node(id:$projectId) {",
-  "    ... on ProjectV2 {",
-  "      items(first:100, after:$after, orderBy:{field:POSITION, direction:ASC}) {",
-  "        pageInfo { hasNextPage endCursor }",
-  "        nodes {",
-  "          id",
-  "          fieldValues(first:20) {",
-  "            nodes {",
-  "              ... on ProjectV2ItemFieldSingleSelectValue {",
-  "                field { ... on ProjectV2SingleSelectField { id name } }",
-  "                name",
-  "              }",
-  "            }",
-  "          }",
-  "          content {",
-  "            ... on Issue { __typename number repository { nameWithOwner } }",
-  "            ... on PullRequest { __typename number repository { nameWithOwner } }",
-  "          }",
-  "        }",
-  "      }",
-  "    }",
-  "  }",
-  "}"
-].join("\n");
-
 const UPDATE_ITEM_FIELD = [
   "mutation($projectId:ID!, $itemId:ID!, $fieldId:ID!, $optionId:String!) {",
   "  updateProjectV2ItemFieldValue(input:{projectId:$projectId, itemId:$itemId, fieldId:$fieldId, value:{singleSelectOptionId:$optionId}}) {",
@@ -53,19 +26,6 @@ const UPDATE_ITEM_FIELD = [
 const listAllProjects = discoverProjects;
 const listAllFields = listProjectFields;
 
-// ── Paginated item listing (position order) ──────────────────────────────
-
-function fetchAllItems(projectId, env, runChild) {
-  return paginateNodes({
-    query: GET_PROJECT_ITEMS_BY_CONTENT,
-    variables: { projectId },
-    selectConnection: (payload) => payload?.data?.node?.items,
-    env,
-    runChild,
-    entity: "items",
-  });
-}
-
 const statusOf = extractStatus;
 
 // ── Exit code classification ────────────────────────────────────────────
@@ -84,7 +44,7 @@ function classifyExitCode(err) {
 async function main(args, { env = process.env, runChild, cwd = null } = {}) {
   const child = runChild ?? _runChild;
   const repo = validateRepo(args.repo);
-  const [owner, repoName] = repo.split("/");
+  const [owner] = repo.split("/");
   const selector = resolveProjectSelector(args);
   const itemRef = parseItemRef(args.item);
   const toColumn = (args.toColumn ?? "").trim();
@@ -122,43 +82,9 @@ async function main(args, { env = process.env, runChild, cwd = null } = {}) {
     );
   }
 
-  // 4. Find the item.
-  //
-  // Fetch the full board item list ONCE (paginated, position order) and resolve
-  // BOTH ref kinds against it. This reuses the proven pattern from
-  // reorder-queue-item / list-queue-items: a node-id ref matches by item.id, a
-  // number ref matches by content.number. Both are scoped to the requested repo
-  // so a cross-project ref fails closed with ITEM_NOT_FOUND. (The previous code
-  // used `ProjectV2.item` — a field that does not exist — for the node-id path,
-  // and a single non-paginated `items(first:10)` page for the number path, so it
-  // could not find items beyond the first page.)
-  const allItems = await fetchAllItems(project.id, env, child);
-
-  let match;
-  if (itemRef.kind === "id") {
-    match = allItems.find(
-      (it) => it.id === itemRef.value && it.content?.repository?.nameWithOwner === repo,
-    );
-    if (!match) {
-      throw Object.assign(
-        new Error(`Item "${itemRef.value}" not found in project "${project.title}" for repo "${repo}"`),
-        { code: "ITEM_NOT_FOUND" },
-      );
-    }
-  } else {
-    match = allItems.find(
-      (it) =>
-        it.content &&
-        it.content.repository?.nameWithOwner === repo &&
-        it.content.number === itemRef.value,
-    );
-    if (!match) {
-      throw Object.assign(
-        new Error(`Item #${itemRef.value} not found in project "${project.title}" for repo "${repo}"`),
-        { code: "ITEM_NOT_FOUND" },
-      );
-    }
-  }
+  // 4. Find the item from the issue side or by node, never from the board
+  // listing: `ProjectV2.items` can lag behind GitHub and omit new items.
+  const match = await resolveProjectItem({ projectId: project.id, projectTitle: project.title, repo, itemRef, env, runChild: child });
 
   const itemId = match.id;
   const previousColumn = statusOf(match);

package/src/projects/projects-access.mjs

@@ -200,3 +200,127 @@ export function extractStatus(node) {
   }
   return null;
 }
+
+// ── Single item resolution ─────────────────────────────────────────────────
+
+// Item projection shared by both lookups. It matches the board listing node
+// shape (id, fieldValues, content) so `extractStatus` works on the result.
+const ITEM_FIELDS = [
+  "id isArchived project { id }",
+  "fieldValues(first:20) {",
+  "  nodes {",
+  "    ... on ProjectV2ItemFieldSingleSelectValue {",
+  "      field { ... on ProjectV2SingleSelectField { id name } }",
+  "      name",
+  "    }",
+  "  }",
+  "}",
+  "content {",
+  "  ... on Issue { __typename number repository { nameWithOwner } }",
+  "  ... on PullRequest { __typename number repository { nameWithOwner } }",
+  "}",
+].join("\n");
+
+const GET_ITEMS_BY_CONTENT_NUMBER = [
+  "query($owner:String!, $name:String!, $number:Int!, $after:String) {",
+  "  repository(owner:$owner, name:$name) {",
+  "    issueOrPullRequest(number:$number) {",
+  `      ... on Issue { projectItems(first:100, after:$after, includeArchived:false) { pageInfo { hasNextPage endCursor } nodes { ${ITEM_FIELDS} } } }`,
+  `      ... on PullRequest { projectItems(first:100, after:$after, includeArchived:false) { pageInfo { hasNextPage endCursor } nodes { ${ITEM_FIELDS} } } }`,
+  "    }",
+  "  }",
+  "}",
+].join("\n");
+
+const GET_ITEM_BY_ID = [
+  "query($id:ID!) {",
+  `  node(id:$id) { ... on ProjectV2Item { ${ITEM_FIELDS} } }`,
+  "}",
+].join("\n");
+
+function itemNotFound(message) {
+  return Object.assign(new Error(message), { code: "ITEM_NOT_FOUND" });
+}
+
+/**
+ * Throw GRAPHQL_ERROR for any GraphQL error in `payload` other than NOT_FOUND.
+ * Use it on a `ghGraphql(..., { allowErrors: true })` payload where NOT_FOUND
+ * means "no such entity" and every other error must keep its message.
+ */
+export function assertOnlyNotFoundErrors(payload) {
+  const other = (payload?.errors ?? []).filter((e) => e?.type !== "NOT_FOUND");
+  if (other.length > 0) {
+    throw Object.assign(
+      new Error(`GraphQL errors: ${other.map((e) => e.message).join("; ")}`),
+      { code: "GRAPHQL_ERROR" },
+    );
+  }
+}
+
+/**
+ * Resolve one project item without the whole-board `ProjectV2.items` listing,
+ * which can lag behind GitHub by hours and omit newly added items.
+ *
+ *   - number ref: read the issue or PR's own `projectItems` and pick the
+ *     unarchived item on `projectId`.
+ *   - id ref: look the item node up directly, then verify that it belongs to
+ *     `projectId` and that its content is in `repo`.
+ *
+ * Every miss or mismatch fails closed with code ITEM_NOT_FOUND. Returns a node
+ * in the listing shape: `{ id, isArchived, project, fieldValues, content }`.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectId
+ * @param {string} [opts.projectTitle]  shown in ITEM_NOT_FOUND messages when present
+ * @param {string} opts.repo  validated `owner/name`
+ * @param {{kind:"number"|"id", value:number|string}} opts.itemRef  from parseItemRef
+ * @param {object} opts.env
+ * @param {Function} opts.runChild
+ */
+export async function resolveProjectItem({ projectId, projectTitle, repo, itemRef, env, runChild }) {
+  const projectLabel = projectTitle ?? projectId;
+  if (itemRef.kind === "number") {
+    const [owner, name] = repo.split("/");
+    let after = null;
+    while (true) {
+      const vars = { owner, name, number: itemRef.value };
+      if (after) vars.after = after;
+      const payload = await ghGraphql(GET_ITEMS_BY_CONTENT_NUMBER, vars, env, runChild, { allowErrors: true });
+      const connection = payload?.data?.repository?.issueOrPullRequest?.projectItems;
+      const match = (connection?.nodes ?? []).find((n) => n && n.project?.id === projectId && !n.isArchived);
+      // A partial response can carry errors for other boards the token cannot
+      // read (e.g. FORBIDDEN). A match on the configured board wins; the error
+      // is raised only when no page holds a match.
+      if (match) return match;
+      const pageInfo = connection?.pageInfo ?? {};
+      if (!pageInfo.hasNextPage) {
+        assertOnlyNotFoundErrors(payload);
+        throw itemNotFound(`Item #${itemRef.value} not found in project "${projectLabel}" for repo "${repo}"`);
+      }
+      if (!pageInfo.endCursor) {
+        throw Object.assign(
+          new Error("Invalid projectItems payload: hasNextPage is true but endCursor is missing"),
+          { code: "GH_API_ERROR" },
+        );
+      }
+      after = pageInfo.endCursor;
+    }
+  }
+
+  const payload = await ghGraphql(GET_ITEM_BY_ID, { id: itemRef.value }, env, runChild, { allowErrors: true });
+  assertOnlyNotFoundErrors(payload);
+  const node = payload?.data?.node;
+  if (!node?.id || node.isArchived) {
+    throw itemNotFound(`Item "${itemRef.value}" not found in project "${projectLabel}" for repo "${repo}"`);
+  }
+  if (node.project?.id !== projectId) {
+    throw itemNotFound(
+      `Item "${itemRef.value}" belongs to project "${node.project?.id ?? "(unknown)"}", not "${projectId}"`,
+    );
+  }
+  const itemRepo = node.content?.repository?.nameWithOwner ?? null;
+  if (itemRepo !== repo) {
+    throw itemNotFound(`Item "${itemRef.value}" is for repo "${itemRepo ?? "(none)"}", not "${repo}"`);
+  }
+  return node;
+}