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

package/lib/issue-backend.js

@@ -3,10 +3,34 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const VALID_BACKENDS = new Set(['kernel', 'beads']);
+const VALID_BACKENDS = new Set(['kernel']);
 const DEFAULT_BACKEND = 'kernel';
 const ENV_VAR = 'FORGE_ISSUE_BACKEND';
 
+// Backends that Forge used to accept and has since retired. Kept as an explicit set
+// (rather than folding them into the generic "unknown backend" path) so a user who
+// still carries `issueBackend: beads` in config — or `FORGE_ISSUE_BACKEND=beads` in a
+// shell profile — gets the ONE actionable instruction instead of a bare valid-values
+// list: import the Beads store into the kernel.
+const REMOVED_BACKENDS = new Set(['beads']);
+
+// The single migrate pointer shared by every removed-backend surface (the resolver's
+// warning and the CLI flag's hard error) so the two can never drift.
+const BEADS_REMOVED_HINT =
+  'the beads backend was removed; run `forge migrate --from beads` to import a Beads store into the kernel';
+
+/**
+ * The migrate-pointer hint for a retired backend value, or null when the value is
+ * not a retired backend (callers then use the generic unknown-backend wording).
+ *
+ * @param {string} value
+ * @returns {string|null}
+ */
+function removedBackendHint(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return REMOVED_BACKENDS.has(normalized) ? BEADS_REMOVED_HINT : null;
+}
+
 /**
  * Read the `issueBackend` key from `<projectRoot>/.forge/config.yaml`, if the
  * file exists and is parseable. Returns `null` when the file is missing, the
@@ -72,14 +96,17 @@ function collectBackendSignal({ deps = {}, env = process.env, projectRoot } = {}
  *   explicit deps.issueBackend > FORGE_ISSUE_BACKEND env > .forge/config.yaml > 'kernel'.
  *
  * An unknown value (from any source) falls back to the default backend and emits
- * a warning via the injected `warn` callback (defaults to console.warn).
+ * a warning via the injected `warn` callback (defaults to console.warn). A RETIRED
+ * value (`beads`) takes the same fallback path but warns with the migrate pointer,
+ * because "unknown backend, valid backends: kernel" would not tell a user carrying
+ * `issueBackend: beads` in config what to actually do about it.
  *
  * @param {object} [options]
  * @param {object} [options.deps]
  * @param {object} [options.env]
  * @param {string} [options.projectRoot]
  * @param {function(string): void} [options.warn]
- * @returns {'kernel'|'beads'}
+ * @returns {'kernel'}
  */
 function resolveIssueBackend({
   deps = {},
@@ -98,6 +125,15 @@ function resolveIssueBackend({
     return normalized;
   }
 
+  const removedHint = removedBackendHint(normalized);
+  if (removedHint) {
+    warn(
+      `Issue backend "${value}" from ${source} is no longer available: ${removedHint}. `
+      + `Falling back to "${DEFAULT_BACKEND}".`,
+    );
+    return DEFAULT_BACKEND;
+  }
+
   warn(
     `Unknown issue backend "${value}" from ${source}; `
     + `falling back to "${DEFAULT_BACKEND}". Valid backends: ${[...VALID_BACKENDS].join(', ')}.`,
@@ -139,7 +175,10 @@ module.exports = {
   hasExplicitBackendSignal,
   shouldUseKernelBroker,
   readConfigBackend,
+  removedBackendHint,
   VALID_BACKENDS,
+  REMOVED_BACKENDS,
+  BEADS_REMOVED_HINT,
   DEFAULT_BACKEND,
   ENV_VAR,
 };

package/lib/kernel/backing-issue.js

@@ -39,7 +39,14 @@ const DEFAULT_IGNORE_GLOBS = Object.freeze(['tmp/*', 'spike/*', 'wip/*', 'throwa
 const AUTO_STUB_LABEL = 'auto-stub';
 // Branch prefixes stripped before deriving a title / probing for an encoded issue id.
 const BRANCH_PREFIX = /^(feat|feature|fix|bugfix|hotfix|chore|refactor|docs|test|spike|wip)\//i;
-// An issue key encoded in a branch slug, e.g. `feat/kap-7-foo` -> `kap-7`.
+// A full Kernel issue id (UUID) named anywhere in the branch, e.g.
+// `feat/18f1988e-...-close-on-merge`. Kernel ids ARE UUIDs, so this is the shape a
+// real branch->issue reference actually takes; kept identical to the UUID_RE that
+// resolveActiveIssueId (lib/workflow/enforce-stage.js) matches, so every resolver
+// agrees on which issue a branch names.
+const ENCODED_UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+// Legacy Beads-era issue key encoded in a branch slug, e.g. `feat/kap-7-foo` -> `kap-7`.
+// Still honored for stores imported via `forge migrate --from beads`.
 const ENCODED_ISSUE_ID = /^([a-z][a-z0-9]*-\d+)\b/i;
 // Regex metacharacters escaped when compiling an ignore glob.
 const GLOB_METACHARS = '.+^${}()|[]\\';
@@ -145,12 +152,17 @@ function deriveTitle(branch) {
 }
 
 /**
- * Extract an issue id encoded in the branch name (e.g. `feat/kap-7-foo` -> `kap-7`).
+ * Extract an issue id named in the branch: a Kernel UUID anywhere in the name
+ * (`feat/18f1988e-...-foo`), else a legacy Beads key at the head of the slug
+ * (`feat/kap-7-foo` -> `kap-7`). The caller VERIFIES the id exists before linking,
+ * so a branch that merely looks like an id never binds to a phantom issue.
  *
  * @param {string} branch
  * @returns {string|null}
  */
 function extractEncodedIssueId(branch) {
+  const uuid = ENCODED_UUID.exec(String(branch));
+  if (uuid) return uuid[0];
   const match = ENCODED_ISSUE_ID.exec(stripPrefix(branch));
   return match ? match[1] : null;
 }

package/lib/kernel/broker.js

@@ -782,6 +782,12 @@ async function buildIssueMutationEvent(driver, operation, args, context, config)
 	const payload = operation === 'comment'
 		? buildCommentPayload(issueId, args)
 		: buildUpdatePayload(flags);
+	// `close` already means the terminal `done` transition. Treat an explicit
+	// `--status done` as that same default close intent so it does not get checked
+	// as the generic (and illegal) open -> done update transition below.
+	if (operation === 'close' && payload.status === 'done') {
+		delete payload.status;
+	}
 	// update/close validate only the supplied taxonomy fields (no mandatory title);
 	// comment carries no taxonomy fields, so it is exempt.
 	if (operation !== 'comment') {
@@ -1177,6 +1183,44 @@ function createLocalBroker(options = {}) {
 			return driver.importIssues(kernel, options, {}, config);
 		},
 
+		// Bulk activity read for `forge insights` (Slice C2). Read-only SELECT over
+		// kernel_events, newest first, bounded by an optional `since` ISO cutoff + `limit`.
+		// Additive: deliberately NOT registered in GUARDED_DRIVER_METHODS (the write-path
+		// contract), so existing driver stubs that never call it stay valid. Imported beads
+		// interactions live here as `beads.interaction.<kind>` events. Creates/migrates nothing.
+		async listRecentEvents(options = {}, context = {}) {
+			requireDriverMethod(driver, 'listRecentKernelEvents');
+			return driver.listRecentKernelEvents(options, context, getConfig());
+		},
+
+		// PR reconcile-ledger read (autonomous-shepherd design §3.4). Read-only SELECT of
+		// the open `pr` rows for a repo (keyed by git_common_dir); creates/migrates nothing.
+		// Consumed later by prime and the reconciler to enumerate PRs under shepherd.
+		async listOpenPrs(gitCommonDir, context = {}) {
+			requireDriverMethod(driver, 'listOpenPrs');
+			return driver.listOpenPrs(gitCommonDir, context, getConfig());
+		},
+
+		// PR reconcile-ledger WRITE path (autonomous-shepherd design §5a). Mirror of the
+		// listOpenPrs wrapper: guard the driver method, delegate with getConfig(). pr rows
+		// are derived reconcile state (a direct idempotent upsert), not the guarded-event
+		// issue path. upsertPr = register/refresh; updatePrVerdict = the one verdict authority
+		// with freshest-head precedence enforced at the write; retirePr = merged/closed.
+		async upsertPr(row, context = {}) {
+			requireDriverMethod(driver, 'upsertPr');
+			return driver.upsertPr(row, context, getConfig());
+		},
+
+		async updatePrVerdict(key, patch = {}, context = {}) {
+			requireDriverMethod(driver, 'updatePrVerdict');
+			return driver.updatePrVerdict(key, patch, context, getConfig());
+		},
+
+		async retirePr(key, patch = {}, context = {}) {
+			requireDriverMethod(driver, 'retirePr');
+			return driver.retirePr(key, patch, context, getConfig());
+		},
+
 		// --- Projection-outbox read/update surface (D16) -----------------------
 		// Additive read/update methods for projection consumers. These never touch
 		// the append/CAS path above (runGuardedEvent / enqueueKernelProjection);

package/lib/kernel/cli-broker-factory.js

@@ -113,7 +113,18 @@ async function buildMigratedKernelIssueDeps(options = {}) {
     databasePath: deps.kernelDatabasePath,
     driver: deps.kernelDriver,
   });
-  await ensureKernelMigrated(broker);
+  const close = async () => {
+    if (typeof deps.kernelDriver.close === 'function') {
+      await deps.kernelDriver.close();
+    }
+  };
+  broker.close = close;
+  try {
+    await ensureKernelMigrated(broker);
+  } catch (error) {
+    try { await close(); } catch { /* preserve the migration failure */ }
+    throw error;
+  }
   return {
     useKernelBroker: true,
     kernelBroker: broker,

package/lib/kernel/close-on-merge.js

@@ -0,0 +1,154 @@
+'use strict';
+
+/**
+ * Close-on-merge linkage (kernel issue 18f1988e).
+ *
+ * The branch->issue linkage backbone shipped (kernel_worktrees rows written by
+ * `forge worktree create` and the auto-file rail), but nothing ever consumed it:
+ * a merged PR closed no kernel issue, so finished work stayed open forever. A
+ * hygiene sweep on 2026-07-25 closed 104 such issues, 61 of them auto-stubs
+ * minted on branch push whose merged PR closed nothing.
+ *
+ * This module is the consumer. Given a branch whose PR is known to be MERGED, it
+ * comments the merge evidence onto the linked kernel issue and closes it.
+ *
+ * Safety properties (each covered by test/kernel/close-on-merge.test.js):
+ *   - LINKED ONLY. The issue comes from the kernel_worktrees linkage registry via
+ *     resolveActiveIssueId — the same authoritative resolver `forge ship` stage
+ *     state uses. An issue is never guessed from the branch/PR title, so a merge
+ *     can only ever close the issue the branch was actually bound to.
+ *   - IDEMPOTENT. The issue's status is read back first; a terminal issue
+ *     (`done` / `cancelled` — the kernel's real terminal vocabulary) is a pure
+ *     no-op that writes neither a comment nor a close. Running clean twice
+ *     closes once.
+ *   - NEVER CLOSES BLIND. An unreadable status is a skip, not an assumption.
+ *   - BEST EFFORT. Every failure path — no kernel, a throwing driver, a rejected
+ *     mutation — resolves to `{ closed: false, reason }`. Nothing throws, so
+ *     `forge clean` still removes worktrees when tracking is broken.
+ *
+ * Writes go through the supported `runIssueOperation` seam (lib/forge-issues.js),
+ * the same path `forge inbox ack` uses, so kernel events/provenance are recorded
+ * exactly as a hand-run `forge comment` / `forge close` would be.
+ *
+ * @module kernel/close-on-merge
+ */
+
+const { resolveActiveIssueId } = require('../workflow/enforce-stage');
+const { isWorkableStatus } = require('./readiness-model');
+
+/**
+ * Render the merge-evidence comment posted onto the issue before it is closed.
+ * Stays honest when the PR could not be resolved: `forge clean` also detects a
+ * merge by git patch-equivalence, with no GitHub data to cite.
+ *
+ * @param {object} params
+ * @param {string} params.branch - Merged branch name
+ * @param {{number: number, title?: string, mergeCommitOid?: string}|null} [params.pr]
+ * @returns {string} Comment body
+ */
+function buildMergeEvidence({ branch, pr }) {
+  const lines = ['Closed automatically: the branch backing this issue was merged.', '', `branch: ${branch}`];
+  if (pr && pr.number) {
+    lines.push(`pull request: #${pr.number}${pr.title ? ` — ${pr.title}` : ''}`);
+    if (pr.mergeCommitOid) lines.push(`merge commit: ${pr.mergeCommitOid}`);
+  } else {
+    lines.push('pull request: no pull request resolved (merge detected from git history)');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Render the `--reason` recorded on the close event.
+ *
+ * @param {object} params
+ * @param {string} params.branch
+ * @param {{number: number}|null} [params.pr]
+ * @returns {string}
+ */
+function buildCloseReason({ branch, pr }) {
+  return pr && pr.number ? `merged in PR #${pr.number}` : `branch ${branch} merged`;
+}
+
+/**
+ * Read an issue's current status through the supported read path.
+ *
+ * @param {Function} runIssueOperation
+ * @param {string} issueId
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>} the status, or null when it could not be read.
+ */
+async function readIssueStatus(runIssueOperation, issueId, projectRoot) {
+  const result = await runIssueOperation('show', [issueId, '--json'], projectRoot);
+  if (!result || result.ok !== true || !result.data) return null;
+  const status = result.data.status;
+  return typeof status === 'string' && status ? status : null;
+}
+
+/** @returns {boolean} whether a mutation envelope reports success. */
+function mutationSucceeded(result) {
+  return Boolean(result && (result.ok === true || result.success === true));
+}
+
+/**
+ * Comment the merge evidence onto the linked kernel issue and close it.
+ * See the module doc for the full contract. NEVER throws.
+ *
+ * @param {object} options
+ * @param {string} options.branch - The merged branch.
+ * @param {string} [options.projectRoot] - Repo root threaded to the issue runner.
+ * @param {{number: number, title?: string, mergeCommitOid?: string}|null} [options.pr]
+ *   Merge evidence from GitHub, when available.
+ * @param {object} options.driver - Kernel driver exposing the worktree linkage registry.
+ * @param {Function} options.runIssueOperation - (operation, args, projectRoot) => envelope.
+ * @param {Function} [options.resolveIssueId] - Override the branch->issue resolver (tests).
+ * @returns {Promise<{closed: boolean, issueId?: string|null, reason?: string,
+ *   commented?: boolean, status?: string, error?: string}>}
+ */
+async function closeLinkedIssueOnMerge(options = {}) {
+  const { branch, projectRoot, pr = null, driver, runIssueOperation } = options;
+  try {
+    if (!branch || typeof branch !== 'string') return { closed: false, reason: 'no-branch' };
+    if (!driver || typeof runIssueOperation !== 'function') {
+      return { closed: false, reason: 'unavailable' };
+    }
+
+    // Linked only — never a title/heuristic match.
+    const resolveIssueId = options.resolveIssueId || resolveActiveIssueId;
+    const issueId = await resolveIssueId(driver, branch);
+    if (!issueId) return { closed: false, reason: 'not-linked' };
+
+    // Idempotency + never-close-blind: read the current status first.
+    const status = await readIssueStatus(runIssueOperation, issueId, projectRoot);
+    if (!status) return { closed: false, reason: 'read-failed', issueId };
+    if (!isWorkableStatus(status)) {
+      return { closed: false, reason: 'already-closed', issueId, status };
+    }
+
+    // Evidence first, so it survives even if the close is rejected.
+    const commentResult = await runIssueOperation(
+      'comment',
+      [issueId, buildMergeEvidence({ branch, pr })],
+      projectRoot,
+    );
+    const commented = mutationSucceeded(commentResult);
+
+    const closeResult = await runIssueOperation(
+      'close',
+      [issueId, '--reason', buildCloseReason({ branch, pr })],
+      projectRoot,
+    );
+    if (!mutationSucceeded(closeResult)) {
+      return { closed: false, reason: 'close-failed', issueId, commented };
+    }
+    return { closed: true, issueId, commented };
+  } catch (error) {
+    // Best-effort: cleanup must never break on tracking.
+    return { closed: false, reason: 'error', error: error && error.message };
+  }
+}
+
+module.exports = {
+  closeLinkedIssueOnMerge,
+  buildMergeEvidence,
+  buildCloseReason,
+};

package/lib/kernel/fs-class.js

@@ -284,7 +284,7 @@ function driveLetterOf(absPath) {
 
 // Bounded exec options for the Windows drive probes. The timeout is the BLOCKER-1
 // fix: execFileSync's try/catch only catches throws, never hangs, so an
-// unresponsive `net use` / PowerShell (e.g. a wedged network redirector) would
+// an unresponsive `net use` probe (e.g. a wedged network redirector) would
 // hang the whole process indefinitely. With a timeout, a hang becomes a throw
 // that the gatherSignals catch turns into driveType='unknown' → warn (never
 // refuse), symmetric with the G1 fail-safe. killSignal forces the child dead.
@@ -310,18 +310,21 @@ function parseNetUseDriveType(stdout, driveLetter) {
 	return null;
 }
 
-// PURE (M5): a non-empty PowerShell DisplayRoot means the PSDrive is backed by a
-// network/remote root. Returns 'network' when non-blank, else null.
-function parseDisplayRoot(stdout) {
-	return String(stdout || '').trim() ? 'network' : null;
-}
-
 // Windows: detect whether a drive letter is a mapped network drive.
-// FAIL-SAFE FALLBACK (locked decision G1, option a): try `net use`, then a
-// PowerShell DisplayRoot fallback; on ANY probe failure (including a timeout-
-// induced throw, per BLOCKER 1) the caller treats the result as 'unknown'.
-// Probes use arg ARRAYS (no shell) so they remain injection-free.
+// The conventional local C: drive is fixed without a subprocess. `net use` is
+// authoritative for other mapped drive letters, while a no-match remains
+// unknown because it does not prove that an SMB/cloud redirector is absent. The unknown
+// result is fail-open (warn), while UNC and cloud path signals still refuse.
+// Do not launch a second shell process for every kernel child. Under a heavily
+// sharded suite those redundant fallback probes contend for host resources and
+// can leave a shard blocked indefinitely.
+// A probe failure still propagates to the gatherer, which maps it to the
+// fail-safe `unknown`/warn classification.
+// The probe uses an arg ARRAY (no shell) so it remains injection-free.
 function defaultProbeDriveType(driveLetter, deps = {}) {
+	const normalizedDriveLetter = String(driveLetter || '').trim().toUpperCase();
+	if (normalizedDriveLetter === 'C:') return 'fixed';
+
 	const exec = deps.execFileSync || execFileSync;
 
 	// Primary: `net use` lists mapped drive letters (and their remote paths).
@@ -330,17 +333,9 @@ function defaultProbeDriveType(driveLetter, deps = {}) {
 		return 'network';
 	}
 
-	// Secondary: PowerShell DisplayRoot — non-empty for network-backed PSDrives.
-	const psLetter = String(driveLetter).replace(':', '');
-	const psCmd =
-		`(Get-PSDrive -Name '${psLetter}' -ErrorAction SilentlyContinue).DisplayRoot`;
-	const psOut = exec('powershell', ['-NoProfile', '-Command', psCmd], WIN_PROBE_EXEC_OPTIONS);
-	if (parseDisplayRoot(psOut) === 'network') {
-		return 'network';
-	}
-
-	// Letter exists, no network backing detected → fixed.
-	return 'fixed';
+	// `net use` completed successfully without listing this non-system letter.
+	// A no-match is not evidence that an SMB/cloud redirector is absent.
+	return 'unknown';
 }
 
 // Linux: read /proc/mounts, return fs type of the longest mountpoint prefixing absPath.
@@ -443,27 +438,49 @@ function isUnsafeFsOverrideActive(env = {}) {
 	return value === '1' || value === 'true';
 }
 
+// The gate runs on every broker instance, and one command builds several
+// (`forge status` and `forge prime` each build four), so an un-memoized advisory
+// printed four times per command. The advisory describes the process's database
+// path, not the broker, so it is emitted once per (tier, class, path) per
+// process. Keyed rather than a single flag so a second path — or a path that
+// reclassifies — is still reported. Warnings only: `refuse` still throws on
+// every call, so deduping can never turn a refusal into a pass.
+const warnedFilesystemKeys = new Set();
+
+function resetFilesystemWarningMemo() {
+	warnedFilesystemKeys.clear();
+}
+
 function assertFilesystemSafeForKernel(dbPath, deps = {}) {
 	const env = deps.env || process.env;
+	// console.warn writes to stderr, which is the contract here: `--json`
+	// consumers parse stdout, so an advisory on stdout would corrupt the envelope.
 	const warn = deps.warn || (msg => console.warn(msg));
 	const classify = deps.classifyFilesystem || classifyFilesystem;
 
 	const classification = classify(dbPath, deps);
 	const remediation = REMEDIATION[classification.remediationKey] || REMEDIATION.unknown;
 
+	const warnOnce = message => {
+		const key = `${classification.riskTier}|${classification.class}|${dbPath}`;
+		if (warnedFilesystemKeys.has(key)) return;
+		warnedFilesystemKeys.add(key);
+		warn(message);
+	};
+
 	if (classification.riskTier === 'safe') {
 		return classification;
 	}
 
 	if (classification.riskTier === 'warn') {
-		warn(`forge kernel filesystem warning (${classification.class}):\n${remediation}`);
+		warnOnce(`forge kernel filesystem warning (${classification.class}):\n${remediation}`);
 		return classification;
 	}
 
 	// refuse
 	const overrideActive = isUnsafeFsOverrideActive(env);
 	if (overrideActive) {
-		warn(
+		warnOnce(
 			`forge kernel filesystem REFUSE downgraded by FORGE_KERNEL_ALLOW_UNSAFE_FS ` +
 			`(${classification.class}) — override active:\n${remediation}`,
 		);
@@ -487,9 +504,9 @@ module.exports = {
 	gatherSignals,
 	classifyFilesystem,
 	assertFilesystemSafeForKernel,
+	resetFilesystemWarningMemo,
 	isUnsafeFsOverrideActive,
 	defaultProbeDriveType,
 	parseNetUseDriveType,
-	parseDisplayRoot,
 	REMEDIATION,
 };

package/lib/kernel/migrations.js

@@ -57,8 +57,8 @@ function renderDropTable(table) {
 // stays the full current schema; the named tables are filtered out of 001 so they are
 // created exactly once by their dedicated migration (both on a fresh DB and, via the
 // ledger, on an existing DB). KEEP IN SYNC with every new table-creating migration.
-//   memories → 005
-const MIGRATION_ADDED_TABLES = ['memories'];
+//   memories → 005 ; pr → 009
+const MIGRATION_ADDED_TABLES = ['memories', 'pr'];
 
 function getInitialKernelSchema() {
 	const schema = getKernelSchema();
@@ -278,6 +278,32 @@ function buildMemoryFtsMigration() {
 	};
 }
 
+// 009: the PR reconcile ledger + verdict store (kernel_pr). Rendered from the schema.js
+// table definition so the DDL never drifts from the registry — mirroring migration 005.
+// A NEW authority table (NOT columns on kernel_worktrees) because a PR can outlive its
+// worktree or have none at all (autonomous-shepherd design §3.1). Excluded from the 001
+// initial schema (MIGRATION_ADDED_TABLES), so a fresh DB creates it exactly once here and
+// an existing DB picks it up through the broker's per-migration ledger. CREATE … IF NOT
+// EXISTS keeps a re-run idempotent; it is a create-table with no data backfill, so no
+// BEGIN IMMEDIATE is needed (broker.js apply-loop caveat does not bite).
+function buildPrLinkageMigration() {
+	const pr = getKernelSchema().tables.find(table => table.name === 'pr');
+	if (!pr) {
+		throw new Error('Kernel schema is missing the pr authority table');
+	}
+	return {
+		id: '009_kernel_pr_linkage',
+		apply: [
+			renderCreateTable(pr),
+			...pr.indexes.map(prIndex => renderCreateIndex(pr, prIndex)),
+		],
+		rollback: [
+			...[...pr.indexes].reverse().map(prIndex => renderDropIndex(prIndex)),
+			renderDropTable(pr),
+		],
+	};
+}
+
 function validateKernelMigrations(migrations) {
 	const ids = new Set();
 	for (const migration of migrations) {
@@ -308,6 +334,7 @@ function buildKernelMigrationPlan(migrations = [
 	buildIssueFidelityColumnsMigration(),
 	buildWorktreeLinkageColumnsMigration(),
 	buildMemoryFtsMigration(),
+	buildPrLinkageMigration(),
 ]) {
 	validateKernelMigrations(migrations);
 
@@ -326,6 +353,7 @@ module.exports = {
 	buildKernelMigrationPlan,
 	buildMemoryFtsMigration,
 	buildMemoryProjectionMigration,
+	buildPrLinkageMigration,
 	buildSchemaMigration,
 	buildWorktreeLinkageColumnsMigration,
 	memoryFtsDdl,

package/lib/kernel/schema.js

@@ -278,6 +278,41 @@ const TABLE_LIST = deepFreeze([
 	], [
 		index('idx_kernel_memories_source_agent', ['source_agent']),
 	]),
+	// The PR reconcile ledger + verdict store (autonomous-shepherd design §3): a
+	// first-class `pr` authority row links a pull request to its issue, worktree and
+	// journal, and records the winning verdict with its freshness discriminators
+	// (head_sha, verdict_source, verdict_at). A PR is the unit of ownership and can
+	// outlive its worktree (or have none — a hand-opened/other-harness PR), so it is a
+	// separate table, NOT columns on kernel_worktrees. git_common_dir keys every open PR
+	// to its repo so all worktrees share one reconcile view. issue_id/worktree_id are
+	// soft nullable links. Created by migration 009 (excluded from the 001 initial schema
+	// via MIGRATION_ADDED_TABLES), so a fresh DB creates it exactly once and an existing
+	// DB picks it up through the broker's per-migration ledger.
+	table('pr', 'authority', [
+		field('id', 'TEXT', { primaryKey: true }),
+		field('git_common_dir', 'TEXT', { notNull: true }),
+		field('repo', 'TEXT', { notNull: true }),
+		field('number', 'INTEGER', { notNull: true }),
+		field('issue_id', 'TEXT'),
+		field('worktree_id', 'TEXT'),
+		field('branch', 'TEXT'),
+		field('head_sha', 'TEXT'),
+		field('verdict', 'TEXT'),
+		field('verdict_source', 'TEXT'),
+		field('verdict_at', 'TEXT'),
+		field('journal_ptr', 'TEXT'),
+		field('state', 'TEXT', { notNull: true, default: "'open'" }),
+		field('registered_at', 'TEXT', { notNull: true }),
+		field('retired_at', 'TEXT'),
+	], [
+		// Covering index for the reconciler's hot read `listOpenPrs` (WHERE
+		// git_common_dir=? AND state='open' ORDER BY repo, number): the trailing
+		// repo/number let SQLite satisfy both the state filter AND the ordering from
+		// this one index, instead of scanning every PR for the common-dir once the
+		// ledger retains merged/closed history. (Codex review, PR #424.)
+		index('idx_pr_common_dir_state_repo_number', ['git_common_dir', 'state', 'repo', 'number']),
+		index('idx_pr_common_dir_repo_number', ['git_common_dir', 'repo', 'number'], { unique: true }),
+	]),
 ]);
 
 const KERNEL_TABLES = deepFreeze(Object.fromEntries(TABLE_LIST.map(candidate => [candidate.name, candidate])));