@dev-loops/core 1.0.0-rc.6 → 1.0.0-rc.7

package/src/loop/run-post-merge-actions.mjs

@@ -0,0 +1,148 @@
+/**
+ * Post-merge actions runner (config family: `postMerge.actions`, #1457).
+ *
+ * Runs a repo's declared `postMerge.actions` sequentially, in declared order,
+ * after the dev-loop's merge succeeds — sync a checkout, restart a local
+ * service, run a smoke check. Mirrors the `uiReview.run` recipe's shape and
+ * execution precedent (`packages/core/src/loop/ui-review-provision.mjs`).
+ *
+ * SECURITY: `action.run` / `action.verify` are executed VERBATIM as the
+ * operator declared them in the repo's own committed `.devloops` (same trust
+ * level as `uiReview.run.command`) — this module never builds a command string
+ * by concatenating runtime data (changed-file paths, verify output) into it.
+ * `onlyIfChanged` scoping matches changed-file paths as DATA (plain substring
+ * compare), never by shelling them out. Every `run`/`verify` invocation is
+ * bounded by its own timeout; `verify` polling is bounded by `verifyTimeoutMs`.
+ *
+ * Pure orchestration: the shell-out (`exec`) and clock (`now`/`delay`) are
+ * injected so this module is fully deterministic under test. The CLI wires the
+ * real seams (scripts/loop/run-post-merge-actions.mjs).
+ */
+
+/**
+ * True when at least one changed path contains at least one `onlyIfChanged`
+ * pattern (plain substring match — never a shell-out, never a regex).
+ */
+function matchesOnlyIfChanged(patterns, changedPaths) {
+  return patterns.some((pattern) => changedPaths.some((changedPath) => changedPath.includes(pattern)));
+}
+
+/**
+ * Decide whether `action` runs. Returns a skip-reason string, or `null` to run
+ * it. `changedPaths === null` means the changed-file list could not be
+ * resolved (no PR number, `gh pr diff` failure): AC5 requires an
+ * `onlyIfChanged` action to still run in that case (never silently skipped),
+ * so the bypass is a run, not a skip.
+ */
+function decideSkip(action, changedPaths) {
+  if (!Array.isArray(action.onlyIfChanged) || action.onlyIfChanged.length === 0) return null;
+  if (changedPaths === null) return null; // AC5: scoping unresolved — run unscoped
+  if (matchesOnlyIfChanged(action.onlyIfChanged, changedPaths)) return null;
+  return `no changed file matched onlyIfChanged (${action.onlyIfChanged.join(", ")})`;
+}
+
+/** Run `command` bounded by `timeoutMs` via the injected `exec` seam. */
+async function execBounded(exec, command, cwd, timeoutMs) {
+  let result;
+  try {
+    result = await exec(command, { cwd, timeoutMs });
+  } catch (err) {
+    return { ok: false, detail: (err && err.message) || String(err) };
+  }
+  if (result?.killed) return { ok: false, detail: `timed out after ${timeoutMs}ms` };
+  if (result?.code !== 0) {
+    const stderr = typeof result?.stderr === "string" ? result.stderr.trim() : "";
+    return { ok: false, detail: `exit code ${result?.code}${stderr ? `: ${stderr}` : ""}` };
+  }
+  return { ok: true, detail: null };
+}
+
+/**
+ * Poll `verifyCommand` (bounded per-attempt by the remaining budget) until it
+ * exits 0 or `verifyTimeoutMs` elapses. Mirrors the readiness poll in
+ * `ui-review-provision.mjs`'s `provisionAndBoot` (never a fixed sleep).
+ */
+async function pollVerify(exec, verifyCommand, cwd, verifyTimeoutMs, verifyIntervalMs, { delay, now }) {
+  const deadline = now() + verifyTimeoutMs;
+  let lastDetail = "verify never ran";
+  while (now() <= deadline) {
+    const attemptBudget = Math.max(1, deadline - now());
+    let result;
+    try {
+      result = await exec(verifyCommand, { cwd, timeoutMs: attemptBudget });
+    } catch (err) {
+      result = { code: 1, killed: false, stdout: "", stderr: (err && err.message) || String(err) };
+    }
+    if (!result?.killed && result?.code === 0) return { ok: true, detail: null };
+    const verifyStderr = typeof result?.stderr === "string" ? result.stderr.trim() : "";
+    lastDetail = result?.killed
+      ? "verify command timed out"
+      : `exit code ${result?.code}${verifyStderr ? `: ${verifyStderr}` : ""}`;
+    if (now() + verifyIntervalMs > deadline) break; // would overshoot the deadline
+    await delay(verifyIntervalMs);
+  }
+  return { ok: false, detail: `verify exhausted after ${verifyTimeoutMs}ms (${lastDetail})` };
+}
+
+/**
+ * Run every declared action sequentially, in order, with cwd set to `cwd`
+ * (the resolved main checkout).
+ *
+ * @param {object} input
+ * @param {{name:string,run:string,onlyIfChanged:string[]|null,verify:string|null,
+ *   timeoutMs:number,verifyTimeoutMs:number,verifyIntervalMs:number}[]} input.actions
+ * @param {string[]|null} input.changedPaths - Changed file paths of the merged
+ *   PR, or `null` when unresolved (AC5 bypass).
+ * @param {string} [input.changedPathsUnavailableReason] - Why `changedPaths` is
+ *   `null` (e.g. "no PR number", "gh pr diff failed: ..."), surfaced in the
+ *   bypass warning so the AC5 "states why scoping was bypassed" reads clearly.
+ * @param {string} input.cwd - Absolute path to the main checkout.
+ * @param {object} seams
+ * @param {(command:string, opts:{cwd:string,timeoutMs:number})=>Promise<{code:number|null,killed:boolean,stdout:string,stderr:string}>} seams.exec
+ * @param {(ms:number)=>Promise<void>} [seams.delay]
+ * @param {()=>number} [seams.now]
+ * @param {(msg:string)=>void} [seams.log]
+ * @returns {Promise<{ok:boolean, results:{name:string,status:"ok"|"skipped"|"failed",detail:string|null}[]}>}
+ */
+export async function runPostMergeActions(
+  { actions = [], changedPaths = null, changedPathsUnavailableReason = "unknown reason", cwd },
+  { exec, delay = (ms) => new Promise((r) => setTimeout(r, ms)), now = () => Date.now(), log = () => {} } = {},
+) {
+  if (changedPaths === null && actions.some((a) => Array.isArray(a.onlyIfChanged) && a.onlyIfChanged.length > 0)) {
+    log(`WARNING: changed-file list unavailable (${changedPathsUnavailableReason}) — onlyIfChanged scoping bypassed (affected actions run unscoped)`);
+  }
+
+  const results = [];
+  for (const action of actions) {
+    const skipReason = decideSkip(action, changedPaths);
+    if (skipReason) {
+      log(`skip ${action.name}: ${skipReason}`);
+      results.push({ name: action.name, status: "skipped", detail: skipReason });
+      continue;
+    }
+
+    log(`run ${action.name}: ${action.run}`);
+    const runResult = await execBounded(exec, action.run, cwd, action.timeoutMs);
+    if (!runResult.ok) {
+      const detail = `run failed: ${runResult.detail}`;
+      log(`FAILED ${action.name}: ${detail}`);
+      results.push({ name: action.name, status: "failed", detail });
+      continue;
+    }
+
+    if (action.verify) {
+      log(`verify ${action.name}: ${action.verify}`);
+      const verifyResult = await pollVerify(exec, action.verify, cwd, action.verifyTimeoutMs, action.verifyIntervalMs, { delay, now });
+      if (!verifyResult.ok) {
+        log(`FAILED ${action.name}: ${verifyResult.detail}`);
+        results.push({ name: action.name, status: "failed", detail: verifyResult.detail });
+        continue;
+      }
+    }
+
+    log(`ok ${action.name}`);
+    results.push({ name: action.name, status: "ok", detail: null });
+  }
+
+  return { ok: results.every((r) => r.status !== "failed"), results };
+}

package/src/loop/size-budget-merge-gate.mjs

@@ -0,0 +1,121 @@
+/**
+ * Size-budget-driven human-approval-required merge gate (phase 3 of the
+ * fail-closed PR size budget). Pure, no I/O: consumes an
+ * already-resolved size-budget outcome (see check-size-budget.mjs's
+ * computeSizeBudget/evaluatePrSizeBudget — this module never recomputes it)
+ * plus a human-scoped review decision, and decides whether merge must wait
+ * for a human APPROVED review with zero unresolved CHANGES_REQUESTED.
+ *
+ * This gate is consulted IN ADDITION TO resolveEffectiveMergeAuthorized /
+ * humanMergeOnly (@dev-loops/core/config) — never instead of, and never as a
+ * relaxation. A `pass` outcome that never touches the T1 tier carries no
+ * size-imposed requirement at all; normal merge authorization applies
+ * unchanged.
+ */
+
+import { SUBMITTED_REVIEW_STATES, isCopilotLogin } from "../github/copilot-helpers.mjs";
+
+const VALID_SIZE_OUTCOMES = new Set(["pass", "escalate", "block"]);
+
+/**
+ * Resolve whether an escalated/T1 PR's merge must wait for a human APPROVED
+ * review with zero unresolved CHANGES_REQUESTED.
+ *
+ * FAILS CLOSED: an unreadable `sizeOutcome`, a non-boolean `touchesT1`, a
+ * `reviewDecision` that is not exactly `"APPROVED"`, or a non-zero/unreadable
+ * `unresolvedChangesRequestedCount` all require human approval (return
+ * `true`). A `pass` outcome that never touches the T1 tier returns `false`
+ * (no size-imposed requirement).
+ *
+ * `sizeOutcome === "block"` is treated at least as strictly as `"escalate"`:
+ * the issue's own wording names only "escalated or T1", but a block outcome
+ * reaching this gate (e.g. new commits landed T1-heavy code after an earlier
+ * `pass`/`escalate` draft-gate check) must never require LESS than escalate
+ * does.
+ *
+ * `reviewDecision` MUST already be scoped to human reviewers only — see
+ * {@link resolveHumanReviewDecision}, which derives it from raw PR reviews
+ * and treats a Copilot review as never satisfying it.
+ *
+ * `touchesT1` is unprefixed here, but the persisted verdict field a caller
+ * would source it from is size-namespaced (`sizeTouchesT1` in
+ * copilot-helpers.mjs's detect-checkpoint-evidence output) — a caller wiring
+ * that evidence in MUST remap the field name, not spread it as-is.
+ *
+ * @param {{
+ *   sizeOutcome?: "pass"|"escalate"|"block"|null,
+ *   touchesT1?: boolean,
+ *   reviewDecision?: "APPROVED"|"CHANGES_REQUESTED"|null,
+ *   unresolvedChangesRequestedCount?: number,
+ * }} [input]
+ * @returns {boolean}
+ */
+export function resolveSizeBudgetHumanApprovalRequired({
+  sizeOutcome,
+  touchesT1,
+  reviewDecision,
+  unresolvedChangesRequestedCount,
+} = {}) {
+  if (!VALID_SIZE_OUTCOMES.has(sizeOutcome)) return true; // size evidence absent/unreadable
+  if (typeof touchesT1 !== "boolean") return true; // T1-touch signal missing/unreadable
+
+  const requiresEscalatedReview = sizeOutcome === "escalate" || sizeOutcome === "block" || touchesT1 === true;
+  if (!requiresEscalatedReview) return false; // pass, T1 untouched — no size-imposed requirement
+
+  if (reviewDecision !== "APPROVED") return true; // absent / CHANGES_REQUESTED / Copilot-only / unknown
+  if (typeof unresolvedChangesRequestedCount !== "number" || unresolvedChangesRequestedCount !== 0) return true;
+  return false;
+}
+
+/**
+ * Reduce raw PR reviews to each human login's LATEST submitted state,
+ * excluding the Copilot bot login entirely (a Copilot review can never
+ * satisfy or block this gate) and any state outside
+ * {@link SUBMITTED_REVIEW_STATES} (e.g. a review payload that already
+ * dropped to a bare object). Reviews are assumed ordered oldest-first (the
+ * order GitHub's REST/GraphQL review lists are returned in), so the last
+ * occurrence of a login wins.
+ *
+ * @param {Array<{ login?: string, state?: string }>} reviews
+ * @returns {Map<string, string>}
+ */
+function latestHumanReviewStatesByLogin(reviews) {
+  const latestByLogin = new Map();
+  for (const review of Array.isArray(reviews) ? reviews : []) {
+    const login = typeof review?.login === "string" ? review.login : null;
+    const state = typeof review?.state === "string" ? review.state : null;
+    if (!login || !state || isCopilotLogin(login) || !SUBMITTED_REVIEW_STATES.has(state)) continue;
+    latestByLogin.set(login, state);
+  }
+  return latestByLogin;
+}
+
+/**
+ * Derive a human-scoped review decision from raw PR reviews, so a Copilot
+ * review can never satisfy {@link resolveSizeBudgetHumanApprovalRequired}'s
+ * `reviewDecision === "APPROVED"` check. A CHANGES_REQUESTED from any human
+ * login wins over an APPROVED from another (matching GitHub's own
+ * reviewDecision semantics: any outstanding requested change blocks).
+ *
+ * @param {Array<{ login?: string, state?: string }>} reviews
+ * @returns {"APPROVED"|"CHANGES_REQUESTED"|null}
+ */
+export function resolveHumanReviewDecision(reviews) {
+  const states = [...latestHumanReviewStatesByLogin(reviews).values()];
+  if (states.includes("CHANGES_REQUESTED")) return "CHANGES_REQUESTED";
+  if (states.includes("APPROVED")) return "APPROVED";
+  return null;
+}
+
+/**
+ * Count human logins whose LATEST submitted review is CHANGES_REQUESTED (a
+ * login who later re-reviewed with APPROVED/COMMENTED, superseding their own
+ * earlier CHANGES_REQUESTED, does not count). Copilot is excluded.
+ *
+ * @param {Array<{ login?: string, state?: string }>} reviews
+ * @returns {number}
+ */
+export function countUnresolvedHumanChangesRequested(reviews) {
+  const states = [...latestHumanReviewStatesByLogin(reviews).values()];
+  return states.filter((state) => state === "CHANGES_REQUESTED").length;
+}

package/src/loop/tracker-pr-state.mjs

@@ -29,6 +29,9 @@
  *                   business fields
  */
 
+import { trimmedOrNull } from "./normalize.mjs";
+import { normalizeGateReviewVerdict } from "./policy-constants.mjs";
+
 /** Stable state name constants for the tracker-first story-to-PR lifecycle. */
 export const TRACKER_PR_STATE = Object.freeze({
   /**
@@ -120,19 +123,6 @@ export const REVERSE_SYNC_ACTION = Object.freeze({
   [TRACKER_PR_STATE.BLOCKED_NEEDS_USER_DECISION]: "none",
 });
 
-const GATE_REVIEW_VERDICT_SET = new Set(["clean", "findings_present", "blocked"]);
-
-function normalizeSha(value) {
-  return typeof value === "string" && value.trim().length > 0
-    ? value.trim()
-    : null;
-}
-
-function normalizeGateReviewVerdict(value) {
-  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
-  return GATE_REVIEW_VERDICT_SET.has(normalized) ? normalized : null;
-}
-
 function hasCleanVisibleCurrentHeadDraftGate(snapshot) {
   return snapshot.prHeadSha !== null
     && snapshot.draftGateCommentVisible
@@ -236,9 +226,9 @@ export function normalizeTrackerPrSnapshot(raw) {
     prDraft: normalizeBooleanLike(raw.prDraft),
     prMerged: normalizeBooleanLike(raw.prMerged),
     prClosed: normalizeBooleanLike(raw.prClosed),
-    prHeadSha: prExists ? normalizeSha(raw.prHeadSha) : null,
+    prHeadSha: prExists ? trimmedOrNull(raw.prHeadSha) : null,
     draftGateCommentVisible: normalizeBooleanLike(raw.draftGateCommentVisible),
-    draftGateCommentHeadSha: prExists ? normalizeSha(raw.draftGateCommentHeadSha) : null,
+    draftGateCommentHeadSha: prExists ? trimmedOrNull(raw.draftGateCommentHeadSha) : null,
     draftGateCommentVerdict: normalizeGateReviewVerdict(raw.draftGateCommentVerdict),
   };
 }

package/src/loop/ui-designer-review-scoping.mjs

@@ -0,0 +1,171 @@
+// UI designer/vision recorded-evidence auto-scoping — UI half of ADR 0041
+// (RFC issue #1438, decision #0041), tracked by issue #1443.
+//
+// Deterministic, path-triggered, fail-closed criterion modeled on the UI e2e
+// scoping check (./ui-e2e-scoping.mjs, issue #976): a PR that adds or modifies
+// a *rendered* HTML artifact (docs/articles/*.html or docs/presentations/*.html)
+// MUST carry recorded designer/vision review evidence for every touched
+// rendered artifact, and each recorded outcome MUST be the loop's satisfied
+// state (`ui_review_satisfied`). The check is grounded in the designer/vision
+// review loop's EXISTING outcome + artifact bundle contract — no new evidence
+// schema (ADR 0041: "reuse the designer/vision loop's existing outcome +
+// artifact contract rather than a new shape"). Accessibility facts come from
+// the captured axe.json, never judged from pixels, and no human is required by
+// default — the same autonomy the gate-evidence path already has.
+//
+// Inclusion is triggered by the changed-file set, never by annotating the PR.
+// Light-mode and spike-mode relaxed-gate carve-outs are honored: when the PR
+// is light-dispatched / under the light threshold or a spike run, the required
+// designer/vision check is exempt (the requirement is relaxed exactly like the
+// other gates), letting small and exploratory work stay cheap (ADR 0041).
+
+import { classifyRenderedArtifactPath } from "./ui-e2e-scoping.mjs";
+
+// The recorded outcome the required check treats as the satisfied state. The
+// designer/vision loop emits exactly one of these (ui-designer-review-loop.md);
+// any other recorded outcome (continue_ui_fix_loop, blocked_needs_human_decision)
+// or an absent outcome blocks.
+export const DESIGNER_REVIEW_SATISFIED_OUTCOME = "ui_review_satisfied";
+
+// The loop's existing outcome enum, re-used verbatim (no new schema).
+export const DESIGNER_REVIEW_OUTCOMES = Object.freeze([
+  DESIGNER_REVIEW_SATISFIED_OUTCOME,
+  "continue_ui_fix_loop",
+  "blocked_needs_human_decision",
+]);
+
+/**
+ * Normalize a designer/vision recorded-evidence value into an artifact-id →
+ * outcome map, tolerating both the array and keyed-object shapes.
+ *
+ * The evidence reuses the loop's existing outcome + artifact-bundle record: an
+ * entry identifies the rendered artifact by its full repo-relative path and
+ * carries the loop's `outcome`. A  record may also carry its `artifactBundle`
+ * (the loop's existing bundle) - carried through untouched, never validated to
+ * a new shape here.
+ *
+ * @param {Array<{artifact:string,outcome:string,artifactBundle?:object}>|Record<string,{outcome:string,artifactBundle?:object}>|null} evidence
+ * @returns {Map<string,{outcome:string,artifactBundle?:object}>}
+ */
+export function normalizeDesignerReviewEvidence(evidence) {
+  const byArtifact = new Map();
+  if (evidence == null) return byArtifact;
+  if (Array.isArray(evidence)) {
+    for (const entry of evidence) {
+      if (entry && typeof entry === "object" && typeof entry.artifact === "string" && entry.artifact.length > 0) {
+        byArtifact.set(entry.artifact, entry);
+      }
+    }
+    return byArtifact;
+  }
+  if (typeof evidence === "object") {
+    for (const [artifact, record] of Object.entries(evidence)) {
+      if (record && typeof record === "object") {
+        byArtifact.set(artifact, record);
+      }
+    }
+  }
+  return byArtifact;
+}
+
+/**
+ * Deterministic designer/vision recorded-evidence scoping check.
+ *
+ * @param {string[]} changedPaths - PR changed-file paths.
+ * @param {{
+ *   designerReviewEvidence?: Array|Record|null,
+ *   designerReviewExempt?: boolean,
+ * }} [opts]
+ *   designerReviewEvidence: the loop's recorded outcome + artifact bundle for
+ *     the artifacts in scope (null/undefined = "not recorded" → fails closed).
+ *   designerReviewExempt: true when a light-mode/spike relaxed-gate carve-out
+ *     applies (relaxes the requirement entirely).
+ * @returns {{
+ *   required: boolean,
+ *   artifacts: Array<{path,kind,id,registered}>,
+ *   missing: string[],
+ *   unsatisfied: string[],
+ *   satisfied: boolean,
+ *   reason: string|null,
+ * }}
+ */
+export function evaluateUiDesignerReviewScoping(changedPaths = [], {
+  designerReviewEvidence = null,
+  designerReviewExempt = false,
+} = {}) {
+  const artifacts = [];
+  const seen = new Set();
+  for (const p of Array.isArray(changedPaths) ? changedPaths : []) {
+    const descriptor = classifyRenderedArtifactPath(p);
+    // The designer/vision recorded-evidence requirement applies ONLY to
+    // rendered HTML deliverables (docs/articles|presentations/*.html). The
+    // shared classifier also recognizes the headless viewer source path
+    // (kind "viewer"), which is a runtime script, not a rendered artifact -
+    // exclude it so a viewer-source change does not demand designer evidence.
+    if (descriptor && descriptor.kind !== "viewer" && !seen.has(descriptor.path)) {
+      seen.add(descriptor.path);
+      artifacts.push(descriptor);
+    }
+  }
+
+  const required = artifacts.length > 0;
+  if (!required) {
+    return { required: false, artifacts, missing: [], unsatisfied: [], satisfied: true, reason: null };
+  }
+
+  // Honor the light/spike relaxed-gate carve-outs (ADR 0041): the requirement
+  // is exempt, so a rendered artifact change in those runs does not block.
+  if (designerReviewExempt === true) {
+    return {
+      required: true,
+      artifacts,
+      missing: [],
+      unsatisfied: [],
+      satisfied: true,
+      reason: "exempted_by_relaxed_gate_profile",
+    };
+  }
+
+  const byArtifact = normalizeDesignerReviewEvidence(designerReviewEvidence);
+
+  // Fail closed: any touched rendered artifact with NO recorded designer/vision
+  // evidence blocks and names itself so the fix is unambiguous (record the loop's
+  // outcome+bundle for it).
+  const missing = artifacts.filter((a) => !byArtifact.has(a.id)).map((a) => a.id);
+  if (missing.length > 0) {
+    return {
+      required: true,
+      artifacts,
+      missing,
+      unsatisfied: [],
+      satisfied: false,
+      reason:
+        `Designer/vision review evidence is required: this PR changes rendered artifact(s) ` +
+        `${missing.join(", ")} that have no recorded designer/vision review outcome + artifact bundle. ` +
+        `Run the designer/vision review loop for the artifact(s) and record its outcome so the required ` +
+        `recorded-evidence check can pass before this gate can proceed.`,
+    };
+  }
+
+  // Fail closed: recorded evidence exists but the recorded outcome is not the
+  // loop's satisfied state (continue_ui_fix_loop, blocked_needs_human_decision).
+  const unsatisfied = artifacts
+    .filter((a) => (byArtifact.get(a.id)?.outcome ?? null) !== DESIGNER_REVIEW_SATISFIED_OUTCOME)
+    .map((a) => a.id);
+  if (unsatisfied.length > 0) {
+    return {
+      required: true,
+      artifacts,
+      missing: [],
+      unsatisfied,
+      satisfied: false,
+      reason:
+        `Designer/vision review is not satisfied: this PR changes rendered artifact(s) ` +
+        `${unsatisfied.join(", ")}, but the recorded designer/vision review outcome is not ` +
+        `\`${DESIGNER_REVIEW_SATISFIED_OUTCOME}\`. Complete the designer/vision review loop until the ` +
+        `recorded outcome is the satisfied state before this gate can proceed.`,
+    };
+  }
+
+  return { required: true, artifacts, missing: [], unsatisfied: [], satisfied: true, reason: null };
+}

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

@@ -24,6 +24,8 @@
  * posting, visual-regression/pixel-diffing, cross-browser matrix.
  */
 
+import { trimmedOrNull } from "./normalize.mjs";
+
 const MUST_FIX = "must-fix";
 
 /** Request header the drive advertises its drive-session id on, so a cooperating
@@ -282,7 +284,7 @@ export async function driveUiReview(
   // No-retry is a fixed policy — log it every run so the bound is never implicit.
   record(`caps: maxScreenshots=${resolvedCaps.maxScreenshots}, maxFlows=${resolvedCaps.maxFlows}, maxStepsPerFlow=${resolvedCaps.maxStepsPerFlow}, retries=${resolvedCaps.retries} (no-retry)`);
 
-  const session = typeof driveSession === "string" && driveSession.trim().length > 0 ? driveSession.trim() : null;
+  const session = trimmedOrNull(driveSession);
   const base = () => ({ appUrl: appUrl ?? null, logs, driveSession: session });
 
   // 1. Authenticate as the target role. Fail closed: no session -> STOP, drive

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

@@ -22,6 +22,7 @@
 
 import { isClaudeHarness } from "./run-context.mjs";
 import { sanitizeCopilotSummonTokens } from "../github/copilot-helpers.mjs";
+import { trimmedOrNull } from "./normalize.mjs";
 
 /** Findings past this cap are dropped from the artifact and the drop is logged. */
 export const ARTIFACT_MAX_FINDINGS = 100;
@@ -34,10 +35,6 @@ export const ARTIFACT_MAX_SCREENSHOT_BYTES = 4 * 1024 * 1024;
  * a server-log exception the request raised. */
 const SERVER_ERROR_KINDS = new Set(["error-response", "server-log-exception"]);
 
-function normalizeSha(value) {
-  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
-}
-
 /** A confirmed user-facing server error: a must-fix error-response / server-log
  * exception. This is the single-source predicate the severity policy keys off. */
 function isBlockingFinding(finding) {
@@ -195,7 +192,7 @@ export function buildReviewInput({ findings = [], headSha = null, hosting = null
   const verdict = list.length === 0 ? "APPROVE" : (blocking ? "REQUEST_CHANGES" : "COMMENT");
 
   return {
-    headSha: normalizeSha(headSha),
+    headSha: trimmedOrNull(headSha),
     verdict,
     inlineComments,
     summaryFindings,

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

@@ -36,6 +36,8 @@
  * rather than dropping anything.
  */
 
+import { trimmedOrNull } from "./normalize.mjs";
+
 const ROW_STATUS = Object.freeze({
   DROPPED: "dropped",
   DROP_FAILED: "drop-failed",
@@ -247,7 +249,7 @@ export async function teardown(
   //    accretes one secret entry per run; deleting it keeps the hosting target
   //    from piling up. Only ever acts on an explicit gist id from the report
   //    result; a missing id is NONE (nothing published, or Claude-hosted).
-  const gistId = typeof gist?.id === "string" && gist.id.trim().length > 0 ? gist.id.trim() : null;
+  const gistId = trimmedOrNull(gist?.id);
   let gistLedger;
   if (!gistId) {
     gistLedger = { id: null, url: gist?.url ?? null, deleted: false, status: GIST_STATUS.NONE, detail: "no hosting gist to prune" };

package/src/projects/list-queue-items.mjs

@@ -1,6 +1,6 @@
 import { runChild as _runChild } from "../cli/primitives.mjs";
-import { parseJsonText } from "../github/review-threads.mjs";
 import { resolveProjectSelector, findProject } from "./resolve-project.mjs";
+import { ghGraphql } from "../github/gh.mjs";
 
 // ── Validation ───────────────────────────────────────────────────────────
 
@@ -30,32 +30,6 @@ function validateRepo(repo) {
   return repo;
 }
 
-// ── API helpers ──────────────────────────────────────────────────────────
-
-async function ghGraphql(query, vars, env, runChild = _runChild) {
-  const fieldArgs = [];
-  for (const [key, value] of Object.entries(vars)) {
-    fieldArgs.push("--field", `${key}=${value}`);
-  }
-  const result = await runChild(
-    "gh",
-    ["api", "graphql", "--field", `query=${query}`, ...fieldArgs],
-    env,
-  );
-  if (result.code !== 0) {
-    const detail = result.stderr.trim() || `exit code ${result.code}`;
-    throw Object.assign(new Error(`gh api graphql failed: ${detail}`), { code: "GH_API_ERROR" });
-  }
-  const payload = parseJsonText(result.stdout);
-  if (payload.errors && payload.errors.length > 0) {
-    throw Object.assign(
-      new Error(`GraphQL errors: ${payload.errors.map((e) => e.message).join("; ")}`),
-      { code: "GRAPHQL_ERROR" },
-    );
-  }
-  return payload;
-}
-
 // ── GraphQL fragments ────────────────────────────────────────────────────
 
 const GET_USER_ID = [

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

@@ -1,8 +1,8 @@
 import { runChild as _runChild } from "../cli/primitives.mjs";
-import { parseJsonText } from "../github/review-threads.mjs";
 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 } from "../github/gh.mjs";
 
 // ── Validation ───────────────────────────────────────────────────────────
 
@@ -29,32 +29,6 @@ function validateRepo(repo) {
   return repo;
 }
 
-// ── API helpers ──────────────────────────────────────────────────────────
-
-async function ghGraphql(query, vars, env, runChild = _runChild) {
-  const fieldArgs = [];
-  for (const [key, value] of Object.entries(vars)) {
-    fieldArgs.push("--field", `${key}=${value}`);
-  }
-  const result = await runChild(
-    "gh",
-    ["api", "graphql", "--field", `query=${query}`, ...fieldArgs],
-    env,
-  );
-  if (result.code !== 0) {
-    const detail = result.stderr.trim() || `exit code ${result.code}`;
-    throw Object.assign(new Error(`gh api graphql failed: ${detail}`), { code: "GH_API_ERROR" });
-  }
-  const payload = parseJsonText(result.stdout);
-  if (payload.errors && payload.errors.length > 0) {
-    throw Object.assign(
-      new Error(`GraphQL errors: ${payload.errors.map((e) => e.message).join("; ")}`),
-      { code: "GRAPHQL_ERROR" },
-    );
-  }
-  return payload;
-}
-
 // ── GraphQL fragments ────────────────────────────────────────────────────
 
 const GET_USER_ID = [