@dev-loops/core 1.0.3 → 1.0.4-pre.1

package/src/loop/run-inspection.mjs

@@ -555,6 +555,12 @@ export function composeRunInspectionSnapshot({
   if (lifecyclePhase === null) {
     // Fallback: derive from available PR facts
     const loopIter = loopIterations ?? {};
+    // Deferring the loop-iteration fan-out cannot change the phase: every copilot
+    // state maps to one (COPILOT_INNER_STATE_MAP is total over STATE), so whenever
+    // copilot evidence is present the phase is already resolved above and this
+    // fallback never runs. It runs only when that evidence is ABSENT, where there
+    // is no thread count to consult from any source — so there is nothing here to
+    // reconcile between a deferred and a full inspection.
     const hasUnresolvedThreads = typeof loopIter.unresolvedReviewThreads === "number"
       && loopIter.unresolvedReviewThreads > 0;
     const copilotState = copilotLiveOk && copilotEvidence !== null

package/src/loop/spec-authority.mjs

@@ -98,6 +98,17 @@ export const SPEC_AUTHORITY_OUTCOME_VALUES = Object.freeze(
  * three resolve autonomously. Exported so no consumer re-hardcodes the set. */
 export const HUMAN_SPEC_DECISION_OUTCOME = SPEC_AUTHORITY_OUTCOMES.SPEC_CANNOT_DECIDE;
 
+/** The two outcomes that REQUIRE explicit conflict evidence: a non-empty
+ * `conflictingCriteria` array of criterion ids (SPEC-AUTHORITY-CONFLICT-EVIDENCE).
+ * The enforcer and the divergence guard bind to this set directly; the guard
+ * also pins the producer contract prose (`agents/judge.agent.md`) to it, so
+ * producer and enforcer cannot silently diverge. SPEC-AUTHORITY-CONFLICT-EVIDENCE
+ * in this module is the governing rule. */
+export const SPEC_AUTHORITY_CONFLICT_OUTCOMES = Object.freeze([
+  SPEC_AUTHORITY_OUTCOMES.FINDING_CONFLICTS,
+  SPEC_AUTHORITY_OUTCOMES.REMEDIATION_CONFLICTS,
+]);
+
 /**
  * Does an outcome require the loop to stop at the human-spec-decision state?
  * Only `spec_cannot_decide` does — a finding/remediation conflict alone never
@@ -364,15 +375,17 @@ export function validateSpecAuthorityDecision(decision, { specDigest, headSha, c
   // The two conflict outcomes require explicit conflict evidence: a non-empty
   // conflictingCriteria drawn from the spec. Autonomous rejection is only
   // legitimate when it names what the finding/remedy conflicts with.
-  const isConflict =
-    d.outcome === SPEC_AUTHORITY_OUTCOMES.FINDING_CONFLICTS ||
-    d.outcome === SPEC_AUTHORITY_OUTCOMES.REMEDIATION_CONFLICTS;
+  const isConflict = SPEC_AUTHORITY_CONFLICT_OUTCOMES.includes(d.outcome);
   let conflictingCriteria = [];
   if (isConflict) {
-    const conflicts = normalizeIdSet(d.conflictingCriteria, "decision.conflictingCriteria");
-    if (conflicts.size === 0) {
-      throw new Error(`SPEC-AUTHORITY-CONFLICT-EVIDENCE: ${d.outcome} decision requires non-empty conflictingCriteria (explicit conflict evidence; fail closed)`);
+    // Absent, non-array, and empty all mean "no conflict evidence". Route them
+    // to the named rule (not the generic id-set shape error) so a human hitting
+    // this is pointed at the fix — populate the field — rather than a hand-edit;
+    // naming the criteria in `rationale` prose alone does not satisfy it.
+    if (!Array.isArray(d.conflictingCriteria) || d.conflictingCriteria.length === 0) {
+      throw new Error(`SPEC-AUTHORITY-CONFLICT-EVIDENCE: ${d.outcome} decision requires a non-empty conflictingCriteria array of criterion ids (explicit conflict evidence; naming them in rationale prose alone does not satisfy it; fail closed)`);
     }
+    const conflicts = normalizeIdSet(d.conflictingCriteria, "decision.conflictingCriteria");
     const unknownConflicts = [...conflicts].filter((id) => !fullCriteria.has(id));
     if (unknownConflicts.length > 0) {
       throw new Error(`spec-authority decision.conflictingCriteria names unknown criterion id(s): ${unknownConflicts.join(", ")}`);
@@ -485,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/loop/ui-e2e-scoping.mjs

@@ -40,6 +40,7 @@ export const REGISTERED_ARTIFACT_PATHS = Object.freeze([
   "docs/presentations/dev-loops-deep-dive.html",
   "docs/presentations/how-dev-loops-decided-itself.html",
   "docs/presentations/state-graph-surface.html",
+  "docs/presentations/finding-the-flow.html",
   "docs/articles/introducing-dev-loops.html",
   "docs/articles/dev-loops-deep-dive.html",
   "docs/articles/how-dev-loops-decided-itself.html",

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;
+}