forge-workflow 0.1.0-beta.2 → 0.1.0-beta.4

package/lib/orientation.js

@@ -761,11 +761,16 @@ function buildIssueRecap(projectRoot, issueId, options = {}) {
 
 function buildPrime(projectRoot, options = {}) {
   const { project, sections } = buildOrientationSections(projectRoot, options);
-  const orientation = assembleOrientationResult(
-    project,
-    [...sections, buildPrimeKeyCommandsSection()],
-    options
-  );
+  // Prime is the session-entry command, so it LEADS the COMPLETE orientation with LIVE state
+  // (stage / claims / ready / gates / one adoption nudge) when the caller supplied it — the
+  // live-state section is prepended to the full section list (not just the extra sections), so
+  // prime leads with it in every output path. Collected async by the command handler and injected
+  // here so buildPrime itself stays pure and synchronous.
+  const keyCommands = buildPrimeKeyCommandsSection();
+  const allSections = options.liveState
+    ? [...buildPrimeLiveStateSections(options.liveState), ...sections, keyCommands]
+    : [...sections, keyCommands];
+  const orientation = assembleOrientationResult(project, allSections, options);
   return {
     schema_version: 1,
     kind: 'prime',
@@ -774,6 +779,7 @@ function buildPrime(projectRoot, options = {}) {
     token_budget: orientation.token_budget,
     orientation,
     sources: orientation.sources,
+    ...(options.liveState ? { live_state: sanitizeLiveStateForJson(options.liveState) } : {}),
     next_commands: [
       'forge orient --json',
       'forge status --json',
@@ -782,6 +788,290 @@ function buildPrime(projectRoot, options = {}) {
   };
 }
 
+// Cap on claimed issues rendered in the prime live-state block — a bounded nudge, not a dump.
+const LIVE_STATE_CLAIM_LIMIT = 3;
+const LIVE_STATE_GATE_LIMIT = 6;
+
+/**
+ * Render the prime LIVE-state block: current stage, claimed issue(s), ready count, enabled
+ * gates/rails, and ONE progressive-adoption nudge. PURE and bounded — the output is always
+ * ≤ ~10 lines (well under the 20-line cap), with honest fallbacks for every missing field so
+ * a repo with no kernel data still renders a coherent block.
+ *
+ * @param {object} [liveState]
+ * @returns {string}
+ */
+// Hard cap on any single EXTERNAL value (stage name, issue title, gate id) rendered into the
+// live-state block. Counts alone don't bound the block: one long or multiline title/name/id could
+// otherwise bloat live_state or break its one-value-per-line structure. clipValue enforces both.
+const LIVE_STATE_VALUE_MAX = 60;
+
+/** Collapse all whitespace (incl. newlines) to single spaces and hard-cap length with an ellipsis. */
+/**
+ * Sanitized copy of the raw liveState for the `--json` envelope. The rendered text sections are
+ * clipped + provenance-fenced, but `forge prime --json` also emits a `live_state` object — without
+ * this, an attacker-influenceable title/id from Kernel/GitHub would land RAW (unbounded, with
+ * newlines) in the trusted session-entry envelope, bypassing the budget + fence. Clip every string
+ * field so the JSON copy carries the same bounded/newline-collapsed representation as the text path.
+ */
+function sanitizeLiveStateForJson(liveState) {
+  if (!liveState || typeof liveState !== 'object') return liveState;
+  const clip = v => (typeof v === 'string' ? clipValue(v) : v);
+  const clipIssue = i => (i && typeof i === 'object' ? { ...i, id: clip(i.id), title: clip(i.title) } : i);
+  return {
+    ...liveState,
+    stage: liveState.stage && typeof liveState.stage === 'object'
+      ? { ...liveState.stage, id: clip(liveState.stage.id), name: clip(liveState.stage.name) }
+      : liveState.stage,
+    claimed: Array.isArray(liveState.claimed) ? liveState.claimed.map(clipIssue) : liveState.claimed,
+    topReady: clipIssue(liveState.topReady),
+    gates: Array.isArray(liveState.gates) ? liveState.gates.map(clip) : liveState.gates,
+    nudge: clip(liveState.nudge),
+  };
+}
+
+function clipValue(value, max = LIVE_STATE_VALUE_MAX) {
+  const flat = String(value).replace(/\s+/g, ' ').trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/** One-line "Stage: <id> — <name>" (or "not recorded"). */
+function formatStageLine(stage) {
+  if (!stage?.id) return 'Stage: not recorded';
+  const suffix = stage.name ? ` — ${clipValue(stage.name)}` : '';
+  return `Stage: ${clipValue(stage.id)}${suffix}`;
+}
+
+/**
+ * Bounded "Claimed:" lines (capped, with an "…and N more" tail) for the UNTRUSTED claimed block.
+ * id + title are clipped (bounded + newlines collapsed); the title is NOT fenced inline. The whole
+ * block is emitted as a section carrying `untrustedSource`, so the shared post-budget
+ * fenceUntrustedSections wraps it — the ⟦END UNTRUSTED⟧ terminator then always survives a budget
+ * truncation, which an inline per-title fence could not guarantee. Caller guards the empty case.
+ */
+function formatClaimedLines(claimed) {
+  const lines = claimed
+    .slice(0, LIVE_STATE_CLAIM_LIMIT)
+    .map(issue => {
+      const title = issue.title ? ` ${clipValue(issue.title)}` : '';
+      return `Claimed: ${clipValue(issue.id)}${title}`;
+    });
+  if (claimed.length > LIVE_STATE_CLAIM_LIMIT) {
+    lines.push(`Claimed: …and ${claimed.length - LIVE_STATE_CLAIM_LIMIT} more`);
+  }
+  return lines;
+}
+
+/** One-line "Ready: N issue(s) waiting" (or "none"). */
+function formatReadyLine(readyCount) {
+  if (readyCount <= 0) return 'Ready: none';
+  return `Ready: ${readyCount} issue${readyCount === 1 ? '' : 's'} waiting (forge ready)`;
+}
+
+/** One-line "Gates on: <capped list>" (or "defaults"). */
+function formatGatesLine(gates) {
+  if (gates.length === 0) return 'Gates on: defaults';
+  const shown = gates.slice(0, LIVE_STATE_GATE_LIMIT).map(gate => clipValue(gate)).join(', ');
+  return `Gates on: ${shown}${gates.length > LIVE_STATE_GATE_LIMIT ? ', …' : ''}`;
+}
+
+/**
+ * The TRUSTED prime live-state block: stage, ready count, enabled gates, and one adoption nudge —
+ * all internally sourced and safe to act on. Attacker-influenceable claimed issue TITLES are NOT
+ * here; they render separately via formatClaimedBlock into an untrusted, provenance-fenced section.
+ * When nothing is claimed there is no untrusted data, so a plain "Claimed: none" is noted here.
+ */
+function formatPrimeLiveState(liveState = {}) {
+  const claimed = Array.isArray(liveState.claimed) ? liveState.claimed : [];
+  const readyCount = Number.isFinite(liveState.readyCount) ? liveState.readyCount : 0;
+  const gates = Array.isArray(liveState.gates) ? liveState.gates : [];
+
+  const lines = [formatStageLine(liveState.stage)];
+  if (claimed.length === 0) lines.push('Claimed: none');
+  lines.push(formatReadyLine(readyCount), formatGatesLine(gates));
+  if (liveState.nudge) lines.push(`Next: ${liveState.nudge}`);
+  return lines.join('\n');
+}
+
+/**
+ * The UNTRUSTED claimed-work block (attacker-influenceable issue titles), or '' when nothing is
+ * claimed. Emitted as its own section marked `untrustedSource` so fenceUntrustedSections fences it
+ * AFTER applyBudget — the fence terminator survives truncation.
+ */
+function formatClaimedBlock(liveState = {}) {
+  const claimed = Array.isArray(liveState.claimed) ? liveState.claimed : [];
+  if (claimed.length === 0) return '';
+  return formatClaimedLines(claimed).join('\n');
+}
+
+/**
+ * Build the prime live-state sections: a TRUSTED `live_state` block always, plus an UNTRUSTED
+ * `live_state_claimed` block when work is claimed. Splitting is deliberate — only the claimed
+ * titles are attacker-influenceable, so only that block carries `untrustedSource` (the trusted
+ * stage/ready/gates/nudge must stay actionable, not fenced as "data only").
+ * @returns {object[]}
+ */
+function buildPrimeLiveStateSections(liveState) {
+  const sections = [buildSection({
+    id: 'live_state',
+    title: 'Live State',
+    content: formatPrimeLiveState(liveState),
+    sources: [source('kernel.live_state', 'kernel_read_model', 'live_session_state', 'live_state')],
+    // Priority 0 so prime LEADS with live state in every output path: applyBudget orders sections
+    // by priority (project_identity is also 0), and the id tiebreak ('live_state' < 'project_
+    // identity') puts live state first — the session-entry "where am I right now" belongs on top.
+    priority: 0,
+    preserve: true,
+  })];
+  const claimedContent = formatClaimedBlock(liveState);
+  if (claimedContent) {
+    sections.push(buildSection({
+      id: 'live_state_claimed',
+      title: 'Claimed Work',
+      content: claimedContent,
+      sources: [source('kernel.live_state', 'kernel_read_model', 'live_session_state', 'live_state_claimed')],
+      // Issue titles are attacker-influenceable. Marking the WHOLE block untrusted lets the shared
+      // post-budget fenceUntrustedSections wrap it, so the ⟦END UNTRUSTED⟧ terminator always
+      // survives a budget cut (an inline per-title fence could be severed mid-truncation). Id
+      // 'live_state_claimed' sorts right after 'live_state' and before other priority-0 sections.
+      untrustedSource: 'issue-titles',
+      priority: 0,
+      preserve: true,
+    }));
+  }
+  return sections;
+}
+
+/** Deterministic, single-line progressive-adoption nudge (at-most-one) for prime live-state. */
+function buildAdoptionNudge({ claimed = [], readyCount = 0, topReady = null } = {}) {
+  // Issue ids are attacker-influenceable (the broker accepts `--id` as a raw string), and this
+  // string lands in the trusted Live State `Next:` line — clip it (bound + collapse newlines) so a
+  // crafted id cannot break the one-value-per-line structure or inject a fake directive line.
+  if (claimed.length > 0) return `Resume with forge recap ${clipValue(claimed[0].id)} for full context.`;
+  if (readyCount > 0 && topReady && topReady.id) return `Claim work: forge claim ${clipValue(topReady.id)}, then plan or dev.`;
+  return 'No active or ready work — forge plan "<feature>" to start, or forge ready to check.';
+}
+
+/**
+ * True only when a Kernel DB ALREADY EXISTS on disk. `forge prime` is a read-only, session-entry
+ * command, so the live-state read must NEVER lazily create/migrate the Kernel DB (which the
+ * default snapshot path would otherwise do in a fresh repo). resolveKernelDatabasePath only
+ * COMPUTES the path (no side effects); we check the file separately. Never throws.
+ * @param {string} projectRoot
+ * @returns {boolean}
+ */
+function hasExistingKernelDb(projectRoot) {
+  try {
+    const { resolveKernelDatabasePath } = require('./kernel/cli-broker-factory');
+    const databasePath = resolveKernelDatabasePath({ projectRoot });
+    return !!databasePath && fs.existsSync(databasePath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when the live-state read must be SKIPPED to keep `forge prime` strictly READ-ONLY. The
+ * Kernel is the SOLE runtime issue backend (Beads is retired from the runtime — the only remaining
+ * Beads surface is the opt-in `forge migrate` path, so there is NO runtime Beads live-data source
+ * by design). The Kernel read lazily creates/migrates `.git/forge/kernel.sqlite`, so we read live
+ * ONLY when that DB already exists; otherwise prime shows honest-degraded/empty state and never
+ * creates a store. Never throws.
+ * @param {string} projectRoot
+ * @returns {boolean} true iff the read must be skipped.
+ */
+function shouldSkipLiveSnapshot(projectRoot) {
+  return !hasExistingKernelDb(projectRoot);
+}
+
+/**
+ * Acquire the status snapshot for live-state WITHOUT ever creating state. An injected
+ * `_readSnapshot` (tests) bypasses the guards; otherwise the read is gated on a real git repo and
+ * an existing Kernel DB (the sole runtime issue backend — see shouldSkipLiveSnapshot), so a
+ * fresh/un-initialized repo returns null (honest fallback) and nothing is written. Never throws.
+ * @returns {Promise<object|null>}
+ */
+async function acquireLiveSnapshot(projectRoot, env, options) {
+  if (options._readSnapshot) {
+    try { return await options._readSnapshot(); } catch { return null; }
+  }
+  if (!fs.existsSync(path.join(projectRoot, '.git'))) return null;
+  if (shouldSkipLiveSnapshot(projectRoot)) return null; // read-only: never create the store
+  try {
+    const { readStatusSnapshot } = require('./status/snapshot');
+    return await readStatusSnapshot(projectRoot, { env });
+  } catch {
+    return null;
+  }
+}
+
+/** Resolve the current stage for live-state (best-effort, non-throwing). Injectable via options. */
+function resolveLiveStage(projectRoot, claimed, options) {
+  if (Object.hasOwn(options, '_workflowState')) {
+    const ws = options._workflowState;
+    return ws && ws.currentStage ? { id: ws.currentStage, name: ws.currentStage } : null;
+  }
+  try {
+    const status = require('./commands/status');
+    const issueId = claimed[0] ? claimed[0].id : null;
+    const { workflowState } = status.resolveWorkflowState({ projectRoot, issueId });
+    if (workflowState && workflowState.currentStage) {
+      return { id: workflowState.currentStage, name: status.buildAuthoritativeStatus(workflowState).stageName };
+    }
+  } catch { /* stage stays null */ }
+  return null;
+}
+
+/**
+ * Best-effort LIVE-state collector for prime. Async + NON-THROWING and strictly READ-ONLY: it
+ * never creates or migrates the Kernel DB (a fresh repo yields honest fallbacks, not a new DB).
+ * `options.liveState` bypasses all reads; `options._readSnapshot` injects a snapshot (tests).
+ *
+ * @param {string} projectRoot
+ * @param {object} [options] - `{ liveState, env, _readSnapshot, _workflowState }` (all injectable).
+ * @returns {Promise<{stage: object|null, claimed: object[], readyCount: number, gates: string[], nudge: string}>}
+ */
+async function collectPrimeLiveState(projectRoot, options = {}) {
+  if (options.liveState) return options.liveState;
+  const env = options.env || process.env;
+  const gates = readEnabledGates(projectRoot); // config-file backed — safe even with no repo/DB
+
+  const snapshot = await acquireLiveSnapshot(projectRoot, env, options);
+  if (!snapshot) {
+    return { stage: null, claimed: [], readyCount: 0, gates, nudge: buildAdoptionNudge({}) };
+  }
+
+  const claimed = (Array.isArray(snapshot.activeAssigned) ? snapshot.activeAssigned : [])
+    .map(issue => ({ id: issue.id, title: issue.title || null }));
+  const readyList = Array.isArray(snapshot.ready) ? snapshot.ready : [];
+  const readyCount = readyList.length;
+
+  return {
+    stage: resolveLiveStage(projectRoot, claimed, options),
+    claimed,
+    readyCount,
+    gates,
+    nudge: buildAdoptionNudge({ claimed, readyCount, topReady: readyList[0] || null }),
+  };
+}
+
+/**
+ * Read the enabled gate/rail ids from the resolved runtime graph (config-file backed, no kernel
+ * DB — safe on a non-repo path). Never throws; returns [] on any failure.
+ * @param {string} projectRoot
+ * @returns {string[]}
+ */
+function readEnabledGates(projectRoot) {
+  try {
+    const { getResolvedRuntimeGraph } = require('./core/runtime-graph');
+    const graph = getResolvedRuntimeGraph({ projectRoot }) || {};
+    const primitives = [...(graph.rails || []), ...(graph.gates || [])];
+    return primitives.filter(p => p && p.enabled !== false).map(p => p.id).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
 function formatOrientationText(result) {
   const lines = [
     orientationTitle(result.kind),
@@ -834,9 +1124,10 @@ function readOption(args, name, fallback) {
   return fallback;
 }
 
-function runOrientationCommand(build, args, projectRoot) {
+function runOrientationCommand(build, args, projectRoot, extraOptions = {}) {
   const result = build(projectRoot, {
     budgetTokens: readOption(args, '--budget', undefined),
+    ...extraOptions,
   });
   return {
     success: true,
@@ -848,12 +1139,18 @@ module.exports = {
   DEFAULT_BUDGET_TOKENS,
   applyBudget,
   buildSection,
+  buildAdoptionNudge,
   buildIssueRecap,
   buildMemorySection,
   buildOrientation,
   buildOrientationSections,
   buildPrime,
+  buildPrimeLiveStateSections,
+  collectPrimeLiveState,
+  shouldSkipLiveSnapshot,
   discoverWorkFolder,
+  formatPrimeLiveState,
+  formatClaimedBlock,
   estimateTokens,
   formatOrientationText,
   normalizeBudgetTokens,

package/lib/pr-bundle.js

@@ -145,8 +145,9 @@ async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter })
   const state = await adapter.readState(pr);
   // NOTE: required-check lookup needs the base BRANCH name (`base`), not the
   // remote ref (`baseRef`); passing the ref builds a bad protection path and
-  // silently yields a null required set.
-  const requiredRaw = await adapter.readRequiredChecks({ owner, repo, base });
+  // silently yields a null required set. `pr` lets the adapter fall back to the
+  // rollup `isRequired` set when branch protection is unreadable in CI.
+  const requiredRaw = await adapter.readRequiredChecks({ owner, repo, base, pr });
   const divergence = await adapter.readDivergence({ baseRef, cwd });
   const comments = await gatherUnresolvedComments(adapter, { owner, repo, pr });
   const conflicts = await gatherConflicts(adapter, { baseRef, cwd });
@@ -171,6 +172,9 @@ async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter })
       state: String(state.state || 'OPEN').toUpperCase(),
     },
     ci: buildCi(state.checks, requiredSet),
+    // Which source answered the required-checks read (`protection` | `rollup` |
+    // null) — `rollup` is the CI path where branch protection is unreadable.
+    requiredSource: adapter.lastRequiredSource || null,
     branch: {
       ahead: divergence.ahead || 0,
       behind: divergence.behind || 0,

package/lib/pr-monitor/auto-actions.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * PR-monitor Tier-2 auto-actions — the SAFE, fail-closed *action* half of the
+ * shepherd (issue addf5297, epic c2d398e5). Tier-1 (lib/pr-pull.js computeVerdict
+ * + the pr-monitor workflow) LABELS a PR's state but takes no action, so PRs that
+ * only need "master merged in" sit untended until a human/agent nudges them.
+ *
+ * This module decides — PURELY, from the SAME `forge shepherd <pr> --pull --json`
+ * payload the monitor already computes — whether the monitor may take one of two
+ * surface-safe actions:
+ *   1. `updateBranch` — merge base into an OTHERWISE-CLEAN-but-BEHIND PR (the
+ *      "last mile" case). This is the highest-value, safest action: it clears the
+ *      BEHIND churn without ever touching a PR that has a real blocker.
+ *   2. `rerunFlaky`   — re-run a required check whose failure is INFRASTRUCTURAL
+ *      (cancelled / timed-out / stale / startup-failure), never a real test
+ *      FAILURE/ERROR.
+ *
+ * It NEVER merges, NEVER resolves review threads, NEVER force-pushes, NEVER edits
+ * code. It only decides; the workflow executes the `gh` calls (and owns
+ * per-head-SHA idempotency markers). Every gate below is fail-CLOSED: any missing
+ * field, degraded read, real failure, fork, draft, or unclassifiable signal
+ * yields `should:false`.
+ *
+ * @module pr-monitor/auto-actions
+ */
+
+/**
+ * Check conclusions that are INFRASTRUCTURAL flakes — a re-run may legitimately
+ * turn them green. Mirrors lib/pr-shepherd.js `isFailed`'s not-green terminal
+ * conclusions MINUS the genuinely-broken ones (FAILURE/ERROR/ACTION_REQUIRED).
+ */
+const INFRA_CONCLUSIONS = new Set(['CANCELLED', 'TIMED_OUT', 'STALE', 'STARTUP_FAILURE']);
+
+/** Conclusions that mean the code is genuinely broken — NEVER auto-rerun these. */
+const REAL_FAILURE_CONCLUSIONS = new Set(['FAILURE', 'ERROR', 'ACTION_REQUIRED']);
+
+/**
+ * Pull the numeric Actions run id from a job/run "details" URL
+ * (`.../actions/runs/<run>/job/<job>` or `.../actions/runs/<run>`). Returns null
+ * when absent — a null run id fails the rerun decision closed.
+ *
+ * @param {string} url
+ * @returns {string | null}
+ */
+function runIdFromUrl(url) {
+  const m = String(url || '').match(/\/runs\/(\d+)/);
+  return m ? m[1] : null;
+}
+
+/**
+ * A payload is DEGRADED (some verdict-relevant read failed or the head moved
+ * mid-gather) when its evidence lists unreadable sources or a torn read. Acting
+ * on a degraded gather could act on stale/false state, so both actions fail
+ * closed on it — even though `verdict==='BEHIND'` already implies a clean read,
+ * this stays an explicit, independent guard.
+ *
+ * @param {object} payload
+ * @returns {boolean}
+ */
+function isDegraded(payload) {
+  const ev = (payload && payload.evidence) || {};
+  const unreadable = Array.isArray(ev.unreadable) ? ev.unreadable : [];
+  return unreadable.length > 0 || ev.tornRead === true;
+}
+
+/**
+ * Decide whether to auto-update (merge base into) an otherwise-clean-but-BEHIND
+ * PR. Fires ONLY for the "last mile" case:
+ *   - verdict is exactly `BEHIND` (which itself guarantees rank-1 UNKNOWN and
+ *     rank-2 BLOCKED-CONFLICT did NOT fire — i.e. the read was clean and there is
+ *     no conflict);
+ *   - the PR is NOT a draft and NOT a fork (a base-repo token cannot push a fork
+ *     branch, and forks are out of scope);
+ *   - the read is not degraded;
+ *   - and the ONLY blocker is the behind-base one — every other blocker type
+ *     (failing/missing/skipped/pending required checks, bot-status gates,
+ *     unresolved threads, changes-requested / review-required, conflict) is
+ *     absent. `blockers[]` is computed independently of the verdict precedence,
+ *     so it still lists lower-precedence blockers that `BEHIND` masks — which is
+ *     exactly why we key on it rather than on the single verdict string.
+ *
+ * @param {object} payload - the `--pull --json` payload.
+ * @param {{ isFork?: boolean }} [opts]
+ * @returns {{ should: boolean, reason: string }}
+ */
+function decideUpdateBranch(payload, opts = {}) {
+  const skip = (reason) => ({ should: false, reason });
+  if (!payload || typeof payload !== 'object') return skip('no payload — fail closed');
+  if (opts.isFork) return skip('fork PR — a base-repo token cannot update a fork branch');
+  if (isDegraded(payload)) return skip('degraded/torn read — fail closed');
+  if (payload.verdict !== 'BEHIND') return skip(`verdict ${payload.verdict || 'UNKNOWN'} is not BEHIND`);
+  if (payload.draft === true) return skip('draft PR — not ready to advance');
+  if (!Array.isArray(payload.blockers)) return skip('blockers[] unavailable — fail closed');
+  const others = payload.blockers.filter((b) => b && b.type !== 'behind');
+  if (others.length > 0) {
+    return skip(`other blocker(s) present: ${others.map((b) => b.type).join(', ')}`);
+  }
+  return { should: true, reason: 'otherwise-clean-behind — only blocker is behind-base; merge base in' };
+}
+
+/**
+ * Decide whether to re-run flaky REQUIRED checks. Fires ONLY when EVERY failing
+ * required check is infrastructural (cancelled/timed-out/stale/startup-failure)
+ * with a derivable run id, and NONE is a real FAILURE/ERROR/ACTION_REQUIRED. A
+ * single real failure, an unclassifiable conclusion, a required-failing check
+ * with no matching `failures[]` entry, or a missing run id fails the WHOLE
+ * decision closed (never rerun a genuinely-broken PR, never loop on a real bug).
+ *
+ * @param {object} payload - the `--pull --json` payload.
+ * @returns {{ should: boolean, checks: Array<{name:string,conclusion:string,runId:string|null}>, runIds: string[], reason: string }}
+ */
+function decideRerun(payload) {
+  const empty = (reason) => ({ should: false, checks: [], runIds: [], reason });
+  if (!payload || typeof payload !== 'object') return empty('no payload — fail closed');
+  if (isDegraded(payload)) return empty('degraded/torn read — fail closed');
+
+  const rc = payload.requiredChecks || {};
+  const failingNames = Array.isArray(rc.failing) ? rc.failing : [];
+  if (failingNames.length === 0) return empty('no failing required checks');
+
+  const failures = Array.isArray(payload.failures) ? payload.failures : [];
+  const conclByName = new Map();
+  const urlByName = new Map();
+  for (const f of failures) {
+    if (!f || !f.name) continue;
+    if (!conclByName.has(f.name)) {
+      conclByName.set(f.name, String(f.conclusion || '').toUpperCase());
+      urlByName.set(f.name, f.jobUrl || f.detailsUrl || null);
+    }
+  }
+
+  const picked = [];
+  for (const name of failingNames) {
+    const concl = conclByName.get(name);
+    if (!concl) return empty(`required check "${name}" has no known conclusion — cannot confirm flaky, fail closed`);
+    if (REAL_FAILURE_CONCLUSIONS.has(concl)) return empty(`required check "${name}" is a real failure (${concl}) — never rerun`);
+    if (!INFRA_CONCLUSIONS.has(concl)) return empty(`required check "${name}" conclusion ${concl} is not classified infrastructural — fail closed`);
+    picked.push({ name, conclusion: concl, runId: runIdFromUrl(urlByName.get(name)) });
+  }
+
+  const runIds = [...new Set(picked.map((p) => p.runId).filter(Boolean))];
+  if (runIds.length === 0) return empty('no run id derivable from failure jobUrl — fail closed');
+  return {
+    should: true,
+    checks: picked,
+    runIds,
+    reason: `all ${picked.length} failing required check(s) are infrastructural (${picked.map((p) => p.conclusion).join(', ')})`,
+  };
+}
+
+/**
+ * Compute the full auto-action decision from a `--pull --json` payload. Pure and
+ * independently testable — no I/O, no `gh`, no side effects.
+ *
+ * @param {object} payload
+ * @param {{ isFork?: boolean }} [opts]
+ * @returns {{ updateBranch: object, rerunFlaky: object }}
+ */
+function decideAutoActions(payload, opts = {}) {
+  return {
+    updateBranch: decideUpdateBranch(payload, opts),
+    rerunFlaky: decideRerun(payload),
+  };
+}
+
+module.exports = {
+  decideAutoActions,
+  decideUpdateBranch,
+  decideRerun,
+  runIdFromUrl,
+  isDegraded,
+  INFRA_CONCLUSIONS,
+  REAL_FAILURE_CONCLUSIONS,
+};