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

package/lib/orientation.js

@@ -3,6 +3,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { fenceUntrusted } = require('./untrusted-content');
+const { runIssueOperation: defaultRunIssueOperation } = require('./forge-issues');
+const { memoryTrustStatus } = require('./memory-recall');
 
 const DEFAULT_BUDGET_TOKENS = 2000;
 const MIN_BUDGET_TOKENS = 40;
@@ -43,25 +45,6 @@ function readJsonFile(projectRoot, relativeFilePath) {
   }
 }
 
-function readJsonl(projectRoot, relativeFilePath) {
-  const text = readText(projectRoot, relativeFilePath);
-  if (!text) return [];
-  return text
-    .split(/\r?\n/)
-    .map(line => line.trim())
-    .filter(Boolean)
-    .map((line, index) => {
-      try {
-        return JSON.parse(line);
-      } catch (error) {
-        return {
-          _parseError: true,
-          line: index + 1,
-          error: error.message,
-        };
-      }
-    });
-}
 
 function firstLine(value) {
   return String(value || '')
@@ -426,17 +409,43 @@ function buildMemorySection(projectRoot, options = {}) {
     const result = memoryRouter.recall(projectRoot, { limit: MEMORY_SECTION_NOTE_LIMIT }, { store });
     const notes = Array.isArray(result && result.notes) ? result.notes : [];
     if (notes.length === 0) return [];
-    return [buildSection({
-      id: 'remembered_notes',
-      title: 'Remembered Notes',
-      content: notes.map(formatMemoryNote).join('\n'),
-      sources: [source('kernel.remembered_notes', 'kernel_memory', 'project_memory', 'remembered_notes')],
-      priority: 45,
-      preserve: false,
-      // Remembered notes are untrusted DATA (a planted note must not read as directives).
-      // Raw here; the assembler fences it AFTER applyBudget truncation.
-      untrustedSource: 'memory',
-    })];
+    const groups = [
+      {
+        id: 'remembered_notes',
+        title: 'Confirmed Memory',
+        trust: 'confirmed',
+        priority: 45,
+      },
+      {
+        id: 'suggested_memory',
+        title: 'Suggested Memory — Verify Before Relying',
+        trust: 'suggested',
+        priority: 46,
+      },
+    ];
+    return groups.map(group => {
+      const content = notes
+        .filter(note => memoryTrustStatus({
+          tags: note.tags,
+          sourceAgent: note.sourceAgent,
+          value: note.machine ? {} : note.note,
+        }) === group.trust)
+        .map(formatMemoryNote)
+        .filter(line => estimateTokens(line) <= DEFAULT_BUDGET_TOKENS)
+        .join('\n');
+      if (!content) return null;
+      return buildSection({
+        id: group.id,
+        title: group.title,
+        content,
+        sources: [source('kernel.remembered_notes', 'kernel_memory', 'project_memory', group.id)],
+        priority: group.priority,
+        preserve: false,
+        // Remembered notes are untrusted DATA (a planted note must not read as directives).
+        // Raw here; the assembler fences it AFTER applyBudget truncation.
+        untrustedSource: 'memory',
+      });
+    }).filter(Boolean);
   } catch {
     return [];
   } finally {
@@ -470,8 +479,13 @@ function openMemoryStore(projectRoot) {
 /** Render one recall note as a compact `- [date] text` line. */
 function formatMemoryNote(note) {
   const date = typeof note.timestamp === 'string' && note.timestamp ? note.timestamp.slice(0, 10) : '';
-  const prefix = date ? `${date} ` : '';
-  return `- ${prefix}${note.note}`;
+  const trust = memoryTrustStatus({
+    tags: note.tags,
+    sourceAgent: note.sourceAgent,
+    value: note.machine ? {} : note.note,
+  });
+  const sourceAgent = note.sourceAgent || 'unknown';
+  return `- [source=${sourceAgent} trust=${trust} updated=${date || 'unknown'}] ${note.note}`;
 }
 
 function buildQueueSections() {
@@ -671,7 +685,8 @@ const PRIME_KEY_COMMANDS_CONTENT = [
   'forge upgrade [--dry-run] — preview/self-heal safe Forge upgrade readiness',
   'forge gate <verb> <gate-id> — toggle a workflow gate, or approve/reject a human gate',
   'forge role <role> --use <skill> — bind a role to a skill/ideology',
-  'forge merge --auto <pr> — opt-in conditional auto-merge (off by default)',
+  'forge merge --auto <pr> --expect-head <full-sha> --issue <issue-id> — opt-in guarded merge (off by default)',
+  'post-ship loop: forge ship → forge shepherd <pr> --pull --json → guarded forge merge with exact head + owned issue',
 ].map(line => `- ${line}`).join('\n');
 
 function buildPrimeKeyCommandsSection() {
@@ -685,14 +700,24 @@ function buildPrimeKeyCommandsSection() {
   });
 }
 
-function findIssue(projectRoot, issueId) {
-  const issues = readJsonl(projectRoot, '.beads/issues.jsonl')
-    .filter(row => row && !row._parseError && row._type === 'issue');
-  return issues.find(issue => issue.id === issueId) || null;
+// Read a single issue from the Kernel (the sole issue-state authority). The `show`
+// contract returns the issue summary DIRECTLY as `result.data` (ISSUE_SUMMARY_SCHEMA),
+// NOT `result.data.issue` — the nested shape belongs to the mutation envelope. Resilient
+// by contract: any read failure degrades to `null` (not-found) so orientation never crashes.
+async function findIssue(projectRoot, issueId, runIssueOperation = defaultRunIssueOperation) {
+  try {
+    const result = await runIssueOperation('show', [issueId], projectRoot, { issueBackend: 'kernel' });
+    if (result && result.ok && result.data && result.data.id) {
+      return result.data;
+    }
+  } catch {
+    // best-effort: a kernel read failure surfaces as "not found", never a thrown error
+  }
+  return null;
 }
 
-function buildIssueSection(projectRoot, issueId) {
-  const issue = findIssue(projectRoot, issueId);
+async function buildIssueSection(projectRoot, issueId, options = {}) {
+  const issue = await findIssue(projectRoot, issueId, options.runIssueOperation);
   const content = issue
     ? [
       `id: ${issue.id}`,
@@ -700,7 +725,7 @@ function buildIssueSection(projectRoot, issueId) {
       issue.status ? `status: ${issue.status}` : null,
       issue.description ? `description: ${issue.description}` : null,
     ].filter(Boolean).join('\n')
-    : `id: ${issueId}\nstatus: unknown\nIssue not found in compatibility projection.`;
+    : `id: ${issueId}\nstatus: unknown\nIssue not found in the kernel.`;
 
   return {
     issue: issue ? {
@@ -716,19 +741,19 @@ function buildIssueSection(projectRoot, issueId) {
       id: 'issue_summary',
       title: 'Issue Summary',
       content,
-      sources: [source('.beads/issues.jsonl', 'beads_compat', 'compatibility_projection', 'issue_summary')],
+      sources: [source('kernel', 'kernel', 'issue_read', 'issue_summary')],
       priority: 5,
       preserve: true,
     }),
   };
 }
 
-function buildIssueRecap(projectRoot, issueId, options = {}) {
+async function buildIssueRecap(projectRoot, issueId, options = {}) {
   if (!issueId || typeof issueId !== 'string') {
     throw new Error('Issue id is required for issue-scoped recap.');
   }
 
-  const issueResult = buildIssueSection(projectRoot, issueId);
+  const issueResult = await buildIssueSection(projectRoot, issueId, options);
   const sections = [
     issueResult.section,
     ...buildProjectDesignSections(projectRoot),
@@ -761,11 +786,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 +804,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 +813,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 +1149,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 +1164,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/plugin-catalog.js

@@ -91,15 +91,25 @@ const CATALOG = Object.freeze({
   },
 
   // ── Plan ──
-  beads: {
-    name: 'Beads',
+  'forge-kernel-issues': {
+    name: 'Forge Kernel issues',
     type: 'cli',
     tier: 'free',
     stage: 'plan',
-    description: 'Git-backed issue tracking',
+    description: 'Built-in issue tracker backing /plan — forge issue create, forge ready, forge claim',
     detectWhen: [],
-    install: { method: 'npm', cmd: 'bun add -g @beads/bd' },
+    install: { method: 'config', cmd: 'built-in (forge issue create)' },
   },
+  'mermaid-cli': {
+    name: 'Mermaid CLI',
+    type: 'cli',
+    tier: 'free',
+    stage: 'plan',
+    description: 'Render Mermaid architecture diagrams from design docs to SVG/PNG',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'bun add -D @mermaid-js/mermaid-cli', dev: true },
+  },
+
   // ── Dev ──
   'typescript-lsp': {
     name: 'TypeScript LSP',

package/lib/pr-bundle.js

@@ -86,12 +86,12 @@ async function gatherUnresolvedComments(adapter, { owner, repo, pr }) {
  * Predict merge conflicts. `detectConflicts` is optional on the adapter; when
  * absent or failing, report it as unsupported rather than throwing.
  */
-async function gatherConflicts(adapter, { baseRef, cwd }) {
+async function gatherConflicts(adapter, { baseRef, cwd, headRef }) {
   if (typeof adapter.detectConflicts !== 'function') {
     return { supported: false, reason: 'adapter has no detectConflicts capability' };
   }
   try {
-    return await adapter.detectConflicts({ baseRef, cwd });
+    return await adapter.detectConflicts({ baseRef, cwd, headRef });
   } catch (error) {
     return { supported: false, reason: error.message || 'conflict detection failed' };
   }
@@ -145,11 +145,12 @@ 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 });
-  const divergence = await adapter.readDivergence({ baseRef, cwd });
+  // 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, headRef: state.headSha });
   const comments = await gatherUnresolvedComments(adapter, { owner, repo, pr });
-  const conflicts = await gatherConflicts(adapter, { baseRef, cwd });
+  const conflicts = await gatherConflicts(adapter, { baseRef, cwd, headRef: state.headSha });
 
   const requiredSet = requiredRaw === undefined ? null : requiredRaw;
 
@@ -171,6 +172,8 @@ async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter })
       state: String(state.state || 'OPEN').toUpperCase(),
     },
     ci: buildCi(state.checks, requiredSet),
+    // The authoritative required-check source (`protection` or null).
+    requiredSource: adapter.lastRequiredSource || null,
     branch: {
       ahead: divergence.ahead || 0,
       behind: divergence.behind || 0,

package/lib/pr-monitor/journal.js

@@ -35,14 +35,29 @@ function sanitize(part) {
   return String(part || '').replace(/[^A-Za-z0-9._-]+/g, '-');
 }
 
+/**
+ * Resolve the one journal authority shared by every worktree. Standard repos
+ * use `<main-root>/.forge/pr-monitor`; a nonstandard common dir centralizes
+ * beneath that shared metadata directory. No common dir preserves legacy use.
+ */
+function resolveJournalRoot({ root, gitCommonDir }) {
+  const fallbackRoot = path.resolve(root);
+  if (!gitCommonDir) return path.join(fallbackRoot, '.forge', 'pr-monitor');
+  const commonDir = path.resolve(gitCommonDir);
+  if (path.basename(commonDir).toLowerCase() === '.git') {
+    return path.join(path.dirname(commonDir), '.forge', 'pr-monitor');
+  }
+  return path.join(commonDir, 'forge', 'pr-monitor');
+}
+
 /**
  * Resolve (and create) the per-PR journal directory.
  *
  * @param {{ root: string, repo: string, pr: string|number }} ctx
  * @returns {string} absolute directory path
  */
-function journalDir({ root, repo, pr }) {
-  const dir = path.join(root, '.forge', 'pr-monitor', `${sanitize(repo)}-${sanitize(pr)}`);
+function journalDir({ root, gitCommonDir, repo, pr }) {
+  const dir = path.join(resolveJournalRoot({ root, gitCommonDir }), `${sanitize(repo)}-${sanitize(pr)}`);
   fs.mkdirSync(dir, { recursive: true });
   return dir;
 }
@@ -278,6 +293,7 @@ function watcherRunning(dir) {
 
 module.exports = {
   sanitize,
+  resolveJournalRoot,
   journalDir,
   journalPath,
   snapshotPath,