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

package/lib/memory-recall.js

@@ -0,0 +1,151 @@
+'use strict';
+
+/**
+ * @module memory-recall
+ *
+ * Pure selection core for the per-turn memory-recall hook (the query-relevant tier-2
+ * that complements the recency digest pushed at SessionStart). Kept free of stdin/fs so
+ * it is fully testable; lib/commands/hooks.js does the I/O wiring around it.
+ *
+ * Design constraints (verified against the Claude Code hooks contract + external memory
+ * research, kernel issue 781f6f65):
+ *   - UserPromptSubmit additionalContext APPENDS to history every prompt, so a per-turn
+ *     injector must stay tiny: a hard token budget, a relevance floor, and cross-turn
+ *     dedupe. Below the bar -> inject NOTHING (silence is safe; a wrong memory at
+ *     authority every turn is not).
+ *   - Anaphora guard: a trivial query ("continue", "fix it") carries no retrieval signal,
+ *     so ranking on it is worse than silence. Require a minimum of distinct content tokens.
+ *   - Scope is a FILTER; relevance is the RANKER (bm25). Never sort by recency here — that
+ *     is the recency digest's job, not tier-2's.
+ */
+
+// A query needs at least this many distinct content tokens to be worth ranking on.
+// Below it we treat the prompt as anaphora and inject nothing.
+const MIN_QUERY_TOKENS = 2;
+
+// Default token budget for the whole tier-2 injection. Deliberately small: it rides on
+// EVERY prompt, and it must never starve the always-on SessionStart digest.
+const DEFAULT_TOKEN_BUDGET = 400;
+
+// Default relevance floor for the live hook path so it never runs floor-less. bm25 is
+// more-negative-is-better, so 0 keeps every token-AND FTS match: the ACTIVE relevance gate
+// today is the token-AND match plus the anaphora guard, and the numeric floor is a knob to
+// be tightened (made negative) once shadow-logging measurement (781f6f65 step 0) shows where
+// the corpus's relevant/irrelevant boundary sits. Named + wired so the default is explicit,
+// not an accidental `undefined`.
+const DEFAULT_SCORE_FLOOR = 0;
+
+// Short/function words that carry no retrieval signal. Not exhaustive — just enough to
+// stop pure anaphora ("do that now", "same for it") from clearing the guard.
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'but', 'for', 'to', 'of', 'in', 'on', 'at', 'by', 'is',
+  'it', 'this', 'that', 'these', 'those', 'do', 'did', 'now', 'then', 'same', 'again',
+  'continue', 'go', 'ok', 'okay', 'yes', 'no', 'fix', 'please', 'thanks', 'with', 'as',
+  'we', 'i', 'you', 'he', 'she', 'they', 'them', 'his', 'her', 'my', 'our', 'your',
+]);
+
+// Rough token estimate: ~4 chars/token, matching lib/memory-digest.js's convention so
+// the two tiers budget on the same scale.
+function estimateTokens(text) {
+  return Math.ceil(String(text || '').length / 4);
+}
+
+/**
+ * Parse the JSON payload Claude Code delivers on a UserPromptSubmit hook's stdin. Never
+ * throws — any malformed input yields an empty prompt so the hook fails open.
+ *
+ * @param {string} raw
+ * @returns {{ prompt: string, sessionId: (string|null) }}
+ */
+function parseHookInput(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { prompt: '', sessionId: null };
+    }
+    const prompt = typeof parsed.prompt === 'string' ? parsed.prompt : '';
+    const sessionId = typeof parsed.session_id === 'string' ? parsed.session_id : null;
+    return { prompt, sessionId };
+  } catch {
+    return { prompt: '', sessionId: null };
+  }
+}
+
+/**
+ * Distinct content tokens in a query — lowercased, length >= 3, minus stopwords. The
+ * anaphora guard counts these; the FTS layer does its own tokenization for the actual match.
+ *
+ * @param {string} query
+ * @returns {string[]}
+ */
+function meaningfulTokens(query) {
+  const seen = new Set();
+  // Unicode-aware split, matching the FTS tokenizer (/[\p{L}\p{N}]+/gu in the kernel driver)
+  // so non-Latin prompts (Cyrillic/CJK/accented) aren't silently stripped — otherwise the
+  // anaphora guard would disable recall for every non-Latin-script user.
+  for (const rawToken of String(query || '').toLowerCase().split(/[^\p{L}\p{N}]+/u)) {
+    if (!rawToken) continue;
+    if (STOPWORDS.has(rawToken)) continue;
+    // The length>=3 filter suppresses ASCII noise ("it", "do"), but CJK words are 1-2 chars
+    // and any non-ASCII token is inherently content — keep those regardless of length.
+    if (rawToken.length < 3 && /^[a-z0-9]+$/.test(rawToken)) continue;
+    seen.add(rawToken);
+  }
+  return [...seen];
+}
+
+/**
+ * Choose which memories to inject this turn. PURE.
+ *
+ * @param {object} args
+ * @param {string} args.query — the submitted prompt
+ * @param {Array<{key:string, value:string, score:number}>} args.hits — bm25-ordered
+ *   (best/lowest score first), already relevance-only (token-AND matched)
+ * @param {number} [args.scoreFloor] — keep only hits with score <= floor (more negative =
+ *   stronger). Omit/null to rely on the FTS match alone. The VALUE is corpus-dependent and
+ *   should be tuned from shadow-logging measurement, not guessed — this is the knob.
+ * @param {number} [args.tokenBudget]
+ * @param {string[]} [args.excludeKeys] — keys injected on recent turns (cross-turn dedupe)
+ * @returns {{ lines: string[], injectedKeys: string[] }}
+ */
+function selectInjection({ query, hits, scoreFloor = null, tokenBudget = DEFAULT_TOKEN_BUDGET, excludeKeys = [] }) {
+  // Anaphora guard: a query with too little signal ranks garbage — stay silent.
+  if (meaningfulTokens(query).length < MIN_QUERY_TOKENS) {
+    return { lines: [], injectedKeys: [] };
+  }
+
+  const exclude = new Set(excludeKeys || []);
+  const lines = [];
+  const injectedKeys = [];
+  let spent = 0;
+
+  for (const hit of hits || []) {
+    if (!hit || typeof hit.key !== 'string') continue;
+    if (exclude.has(hit.key)) continue;
+    // Relevance floor: below the bar contributes nothing. bm25 is more-negative-is-better.
+    if (typeof scoreFloor === 'number' && !(typeof hit.score === 'number' && hit.score <= scoreFloor)) {
+      continue;
+    }
+    const body = String(hit.value == null ? '' : hit.value);
+    const cost = estimateTokens(body);
+    if (spent + cost > tokenBudget) {
+      // Budget exhausted; stop rather than skip-and-continue so the strongest fit.
+      break;
+    }
+    lines.push(body);
+    injectedKeys.push(hit.key);
+    spent += cost;
+  }
+
+  return { lines, injectedKeys };
+}
+
+module.exports = {
+  MIN_QUERY_TOKENS,
+  DEFAULT_TOKEN_BUDGET,
+  DEFAULT_SCORE_FLOOR,
+  estimateTokens,
+  parseHookInput,
+  meaningfulTokens,
+  selectInjection,
+};

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,