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

package/lib/harness-capability-matrix.js

@@ -33,7 +33,7 @@ const SOURCE_ROWS = [
   ['S4', 'Cursor MCP', 'https://docs.cursor.com/context/model-context-protocol', 'Cursor connects external tools and data sources through MCP using stdio, SSE, and streamable HTTP transports.'],
   ['S5', 'Codex skills', 'https://developers.openai.com/codex/skills', 'Codex skills package instructions, resources, and scripts; Codex scans .agents/skills from cwd up to the repo root for repo-scope discovery. Forge installs the global $CODEX_HOME/skills from the canonical skills/ source AND commits the repo-local .agents/skills mirror (kept in sync with skills/ by a pre-commit hook + drift gate) for teammate-clone discovery.'],
   ['S6', 'Codex MCP', 'https://developers.openai.com/codex/mcp', 'Codex configures MCP servers in config.toml and supports plugin-provided MCP servers.'],
-  ['S7', 'Codex hooks', 'https://developers.openai.com/codex/hooks', 'Codex hooks run deterministic scripts during lifecycle events.'],
+  ['S7', 'Codex hooks', 'https://developers.openai.com/codex/hooks', 'Codex hooks run deterministic scripts during lifecycle events; they live in GLOBAL $CODEX_HOME/config.toml so project setup does not render them. Codex instead reads the committed project-local AGENTS.md every session, which is the always-on carrier for Forge instruction/policy including the using-forge skill-dispatch pointer (see S9).'],
   ['S8', 'Codex plugins and marketplaces', 'https://developers.openai.com/codex/plugins/build', 'Codex plugins can package skills, apps, MCP servers, hooks, and marketplace metadata.'],
   ['S9', 'AGENTS.md standard', 'https://agents.md/', 'AGENTS.md provides repository instructions for coding agents.'],
   ['S10', 'Cursor Agent Skills', 'https://docs.cursor.com/en/agent/skills', 'Cursor reads on-demand Agent Skills from .cursor/skills/<name>/SKILL.md; Forge populates them at setup from the canonical skills/ source.'],
@@ -41,7 +41,7 @@ const SOURCE_ROWS = [
   ['S12', 'Cursor ignore files', 'https://cursor.com/docs/reference/ignore-file', 'Cursor reads project-local .cursorignore (blocks AI access + indexing) and .cursorindexingignore (index-only), gitignore-style; .gitignore and common secret/lock files are ignored by default.'],
   ['S13', 'Codex sandbox and approvals config', 'https://developers.openai.com/codex/config-reference', 'Codex config.toml sets sandbox_mode (read-only/workspace-write/danger-full-access) and approval_policy (untrusted/on-request/never); a project-local .codex/config.toml is honored ONLY when the project is trusted in the GLOBAL $CODEX_HOME/config.toml (projects.<path>.trust_level).'],
   ['S14', 'Claude Code hooks', 'https://code.claude.com/docs/en/hooks', 'Claude Code hooks live in .claude/settings.json under a `hooks` block; a PreToolUse matcher group (e.g. "Write|Edit"/"Bash") runs a command that can deny the tool call via hookSpecificOutput.permissionDecision.'],
-  ['S15', 'Cursor hooks', 'https://cursor.com/docs/hooks', 'Cursor 1.7+ reads project-local .cursor/hooks.json ({ version: 1, hooks }); only before* events (beforeShellExecution/beforeReadFile/beforeMCPExecution) can deny — there is no pre-edit deny event, so afterFileEdit is observational.'],
+  ['S15', 'Cursor hooks', 'https://cursor.com/docs/hooks', 'Cursor 1.7+ reads project-local .cursor/hooks.json ({ version: 1, hooks }); only before* events (beforeShellExecution/beforeReadFile/beforeMCPExecution) can deny — there is no pre-edit deny event, so afterFileEdit is observational. Cursor hooks are therefore NOT the session-context path: Cursor auto-injects always-apply .cursor/rules/*.mdc (alwaysApply:true) every session (see S3), which is the always-on carrier for the using-forge skill-dispatch pointer.'],
   ['S16', 'Hermes Agent event hooks', 'https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/', 'Hermes (NousResearch) shell hooks are declared in a `hooks:` block in the GLOBAL ~/.hermes/config.yaml; each matcher/command entry runs as a subprocess over a JSON-stdin/stdout wire protocol, and a pre_tool_call hook CAN deny a tool call ({action:block, message} — it also accepts the Claude-Code {decision:block, reason} shape).'],
 ];
 

package/lib/hook-renderer.js

@@ -80,6 +80,9 @@ const FORGE_INBOX_CONTEXT_MARKER = 'hooks inbox-pickup';
 // Forge UserPromptSubmit group is already recognized via the inbox marker, but this keeps
 // the shepherd-events command independently identifiable (symmetry with the other tiers).
 const FORGE_SHEPHERD_EVENTS_MARKER = 'hooks shepherd-events';
+// The memory-recall context hook (UserPromptSubmit tier). Its own idempotency marker so a
+// re-render recognizes and REPLACES the Forge-owned entry in place rather than duplicating it.
+const FORGE_MEMORY_RECALL_MARKER = 'hooks memory-recall';
 // The capture-on-exit context hook (PreCompact + Stop tier). A THIRD context marker so a
 // re-merge recognizes + replaces the Forge-owned PreCompact/Stop entries in place. Both
 // events share this one marker (they differ only by a --trigger suffix on the command).
@@ -91,16 +94,33 @@ const FORGE_SHEPHERD_EVENTS_MARKER = 'hooks shepherd-events';
 // the merge replaces exactly Forge's group and preserves the user's.
 const FORGE_CAPTURE_CONTEXT_MARKER = `${FORGE_CLI} hooks capture`;
 
-// Per-harness SessionStart context-injection capability. Honest capability matrix —
-// only Claude exposes a native session-start surface that can inject additionalContext.
-// Cursor's 1.7 hooks are deny-oriented (no session-start context surface); Codex and
-// Hermes hooks live in GLOBAL home config that project setup never writes. We NEVER
-// fake parity: each non-Claude harness carries an explicit, tested skip reason.
+// Per-harness SessionStart HOOK-render capability. This constant governs ONE thing: whether
+// Forge renders a harness-native SessionStart *hook* that injects additionalContext. Only Claude
+// exposes that surface, so only Claude is rendered:true. Every other harness is rendered:false
+// with an HONEST reason naming WHERE the same dispatch bootstrap is delivered instead — because
+// the bootstrap is NOT Claude-only, it just travels a different always-on surface per harness
+// (see BOOTSTRAP_DELIVERY below): Cursor auto-applies an always-on rule (.cursor/rules/*.mdc,
+// alwaysApply:true); Codex reads the committed project-local AGENTS.md every session; Hermes
+// consumes it through the forge CLI (forge prime/orient + forge skill for). We NEVER fake parity
+// and NEVER branch on harness identity at runtime — delivery is keyed by SURFACE TYPE.
 const SESSION_START_SUPPORT = Object.freeze({
   claude: Object.freeze({ rendered: true }),
-  cursor: Object.freeze({ rendered: false, reason: 'no-session-start-surface' }),
-  codex: Object.freeze({ rendered: false, reason: 'global-config' }),
-  hermes: Object.freeze({ rendered: false, reason: 'global-config' }),
+  cursor: Object.freeze({ rendered: false, reason: 'delivered-via-rule-surface' }),
+  codex: Object.freeze({ rendered: false, reason: 'delivered-via-agents-md' }),
+  hermes: Object.freeze({ rendered: false, reason: 'delivered-via-cli-fallback' }),
+});
+
+// Where the using-forge dispatch BOOTSTRAP reaches each harness EVERY session. Data, not
+// identity-branching: the parity gate iterates this so no harness is silently left with no
+// auto-surface. Only Claude's is a native SessionStart hook; the rest are equally always-on
+// surfaces (a Cursor always-apply rule, the committed AGENTS.md for Codex, the forge CLI as an
+// honest fallback for Hermes). All four ALSO carry the full using-forge SKILL.md via the synced
+// skill mirrors. 'cli-fallback' is the explicit honest-fallback marker (no faked native surface).
+const BOOTSTRAP_DELIVERY = Object.freeze({
+  claude: 'session-start-hook',
+  cursor: 'always-apply-rule',
+  codex: 'agents-md',
+  hermes: 'cli-fallback',
 });
 
 // Per-harness UserPromptSubmit context-injection capability (the near-real-time inbox
@@ -179,6 +199,22 @@ const FORGE_HOOK_CONTRACT = Object.freeze({
       lifecycle: 'user-prompt-submit',
       command: `${FORGE_CLI} hooks inbox-pickup`,
     }),
+    Object.freeze({
+      id: 'memory-recall',
+      kind: 'context',
+      cliAction: 'memory-recall',
+      // QUERY-RELEVANT MEMORY (tier-2): on each prompt, ranks stored memories by BM25
+      // relevance to the submitted prompt (read from the hook's own stdin) and injects the
+      // survivors, gated by a relevance floor + anaphora guard + cross-turn dedupe + a hard
+      // token budget. Complements the recency digest at SessionStart, which answers a
+      // different question (what's newest, not what's relevant to THIS turn). Reads the
+      // user's OWN kernel memory via a supported hook and its own stdin input — it NEVER
+      // injects into a running session's stdin and never drives the agent (Anthropic Usage
+      // Policy). Kill-switch: `forge gate disable rail.memory_recall`.
+      enforces: 'Memory recall: on each UserPromptSubmit, inject query-relevant stored memories ranked by BM25 against the submitted prompt, gated by a relevance floor, an anaphora guard, cross-turn dedupe, and a hard token budget (compact to avoid additionalContext accumulation). Additive and FAIL-OPEN — nothing relevant, a disabled rail, or any error injects nothing and never blocks a prompt.',
+      lifecycle: 'user-prompt-submit',
+      command: `${FORGE_CLI} hooks memory-recall`,
+    }),
     Object.freeze({
       id: 'shepherd-events',
       kind: 'context',
@@ -295,15 +331,18 @@ function renderClaudeHooks(contract) {
     // Surfaces pending targeted dashboard instruction comments (fenced kernel DATA) on each
     // prompt; the command emits { hookSpecificOutput.additionalContext }. Reads the user's
     // own kernel data via a supported hook — NEVER stdin injection (Anthropic Usage Policy).
-    // Both UserPromptSubmit context hooks share ONE Forge-owned group (inbox-pickup +
-    // PR-shepherd deltas). Claude runs every hook in the group and appends each hook's
-    // additionalContext; keeping them in one group means a re-merge replaces the pair
-    // atomically (the group is Forge-owned via either marker). Both are compact + fail-open.
+    // The UserPromptSubmit context hooks share ONE Forge-owned group (inbox-pickup nudge,
+    // PR-shepherd deltas, and query-relevant memory recall). Claude runs every hook in the
+    // group and appends each hook's additionalContext; keeping them in one group means a
+    // re-merge replaces the set atomically (the group is Forge-owned via any of their
+    // markers). All three are compact + fail-open. (memory-recall reads its own hook stdin
+    // for the prompt — that is its supported input, not session-stdin injection.)
     UserPromptSubmit: [
       {
         hooks: [
           { type: 'command', command: harnessCommand(contract, 'inbox-pickup', 'claude') },
           { type: 'command', command: harnessCommand(contract, 'shepherd-events', 'claude') },
+          { type: 'command', command: harnessCommand(contract, 'memory-recall', 'claude') },
         ],
       },
     ],
@@ -398,6 +437,7 @@ function isForgeCommand(command) {
       || command.includes(FORGE_CONTEXT_MARKER)
       || command.includes(FORGE_INBOX_CONTEXT_MARKER)
       || command.includes(FORGE_SHEPHERD_EVENTS_MARKER)
+      || command.includes(FORGE_MEMORY_RECALL_MARKER)
       || command.includes(FORGE_CAPTURE_CONTEXT_MARKER));
 }
 
@@ -523,8 +563,10 @@ module.exports = {
   FORGE_HOOK_MARKER,
   FORGE_CONTEXT_MARKER,
   FORGE_INBOX_CONTEXT_MARKER,
+  FORGE_MEMORY_RECALL_MARKER,
   FORGE_CAPTURE_CONTEXT_MARKER,
   SESSION_START_SUPPORT,
+  BOOTSTRAP_DELIVERY,
   USER_PROMPT_SUBMIT_SUPPORT,
   SESSION_END_SUPPORT,
   sessionStartCapability,

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/broker.js

@@ -1177,6 +1177,34 @@ function createLocalBroker(options = {}) {
 			return driver.importIssues(kernel, options, {}, config);
 		},
 
+		// 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/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])));

package/lib/kernel/sqlite-driver.js

@@ -2070,6 +2070,30 @@ function searchMemoryRowsRanked(runtime, db, query, limit) {
 	).map(memoryRowToEntry);
 }
 
+// Relevance-ONLY BM25 recall that exposes the raw bm25 score on each entry. The
+// per-turn auto-recall hook needs the score to apply a relevance FLOOR (inject nothing
+// when nothing clears the bar) — ordinal rank can't express "nothing was relevant".
+// Unlike searchMemoryRowsRanked, a no-match (or empty) query returns [] with NO recency
+// fallback: the whole point is to avoid surfacing recent-but-irrelevant notes. bm25()
+// returns more-negative for stronger matches, so rows come back best (lowest) first.
+function searchMemoryRowsRankedScored(runtime, db, query, limit) {
+	const capped = Number.isInteger(limit) && limit > 0 ? limit : 20;
+	const match = buildMemoryFtsMatch(query);
+	if (!match) {
+		return [];
+	}
+	return allParams(
+		runtime,
+		db,
+		`SELECT m.*, bm25(kernel_memories_fts) AS __score FROM kernel_memories m
+			JOIN kernel_memories_fts ON kernel_memories_fts.rowid = m.rowid
+			WHERE kernel_memories_fts MATCH ?
+			ORDER BY bm25(kernel_memories_fts)
+			LIMIT ?`,
+		[match, capped],
+	).map(row => ({ ...memoryRowToEntry(row), score: row.__score }));
+}
+
 function closeDatabase(db) {
 	if (db && typeof db.close === 'function') {
 		db.close();
@@ -2181,6 +2205,124 @@ function createDriver(runtime, configuredDatabasePath) {
 				[`${escaped}%`, limit],
 			);
 		},
+		// Open PRs under shepherd for one repo (autonomous-shepherd design §3.4): the
+		// reconciler's "open PRs in this repo" read, keyed by git_common_dir so every
+		// worktree shares one view. Parameterized (git_common_dir is a filesystem path —
+		// never interpolate it), covered by idx_pr_common_dir_state_repo_number. Ordered so
+		// the result is deterministic. `context` is part of the broker contract but unused
+		// by this direct SELECT (prefixed `_` for eslint no-unused-vars).
+		async listOpenPrs(gitCommonDir, _context = {}, config = {}) {
+			return allParams(
+				runtime, getDatabase(config),
+				"SELECT * FROM kernel_pr WHERE git_common_dir = ? AND state = 'open' ORDER BY repo ASC, number ASC",
+				[gitCommonDir],
+			);
+		},
+		// --- kernel_pr WRITE path (autonomous-shepherd design §5a). pr rows are DERIVED
+		// reconcile state (reconstructable from GitHub), not audit-critical issue authority,
+		// so they take a DIRECT idempotent upsert — NOT the event-sourced guarded path
+		// (applyAcceptedIssueMutation). All target the physical `kernel_pr` table (matching
+		// the listOpenPrs read) and are parameterized (git_common_dir/branch/head_sha are
+		// externally-influenced values — never interpolate). `context` is part of the broker
+		// contract but unused by these direct writes (prefixed `_` for eslint no-unused-vars).
+		//
+		// Register/refresh a PR row keyed by (git_common_dir, repo, number). Idempotent via
+		// ON CONFLICT on the unique idx_pr_common_dir_repo_number: a re-upsert updates the
+		// mutable columns and coalesces soft links (a later null never clobbers an existing
+		// issue_id/worktree_id). registered_at is set on INSERT only; state defaults 'open'.
+		async upsertPr(row, _context = {}, config = {}) {
+			const id = row.id || randomUUID();
+			const registeredAt = row.registered_at || new Date().toISOString();
+			const state = row.state || 'open';
+			runParams(
+				runtime, getDatabase(config),
+				`INSERT INTO kernel_pr
+					(id, git_common_dir, repo, number, issue_id, worktree_id, branch, head_sha, journal_ptr, state, registered_at)
+				 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+				 ON CONFLICT(git_common_dir, repo, number) DO UPDATE SET
+					head_sha = excluded.head_sha,
+					branch = excluded.branch,
+					issue_id = coalesce(excluded.issue_id, kernel_pr.issue_id),
+					worktree_id = coalesce(excluded.worktree_id, kernel_pr.worktree_id),
+					-- journal_ptr is a soft link: coalesce it (like issue_id/worktree_id) so a
+					-- head-only refresh that omits journalPtr never severs the ledger↔journal
+					-- link with NULL. (Codex review, PR #426.)
+					journal_ptr = coalesce(excluded.journal_ptr, kernel_pr.journal_ptr),
+					-- REOPEN semantics: upsertPr is only ever called for PRs GitHub reports as
+					-- OPEN, so re-registering a previously retired row (a reopened PR) must flip
+					-- it back to open and clear retired_at — else listOpenPrs (state='open') would
+					-- keep the reopened PR invisible forever. (Codex review, PR #426.)
+					state = 'open',
+					retired_at = NULL,
+					-- A new commit INVALIDATES the prior verdict: when the head advances to a
+					-- different non-null sha, clear verdict/source/at so a verdict computed
+					-- against the OLD head is never presented as fresh for the new head (and the
+					-- freshest-head guard in updatePrVerdict keeps intact evidence). IS NOT is the
+					-- null-safe distinctness test; a headless refresh (excluded.head_sha NULL)
+					-- never clears. (Codex review, PR #426.)
+					verdict = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict END,
+					verdict_source = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict_source END,
+					verdict_at = CASE WHEN excluded.head_sha IS NOT NULL AND excluded.head_sha IS NOT kernel_pr.head_sha THEN NULL ELSE kernel_pr.verdict_at END`,
+				[
+					id,
+					row.git_common_dir,
+					row.repo,
+					row.number,
+					row.issue_id ?? null,
+					row.worktree_id ?? null,
+					row.branch ?? null,
+					row.head_sha ?? null,
+					row.journal_ptr ?? null,
+					state,
+					registeredAt,
+				],
+			);
+			return { ok: true, id };
+		},
+		// The ONE verdict authority WRITE (design §1.2 rule 2) — FRESHEST-HEAD-SHA
+		// PRECEDENCE enforced in the WHERE so a verdict computed against a SUPERSEDED head is
+		// DISCARDED, not written (kills stale 9d35c14b at the write). A non-local (Actions
+		// backstop) write lands only when its head_sha matches the row's current head (or the
+		// row has none yet); a `local` verdict is computed live against the current head and
+		// is always authoritative, so it bypasses the head match.
+		async updatePrVerdict(key, patch = {}, _context = {}, config = {}) {
+			const headSha = patch.head_sha ?? null;
+			const source = patch.verdict_source ?? null;
+			runParams(
+				runtime, getDatabase(config),
+				`UPDATE kernel_pr SET verdict = ?, verdict_source = ?, verdict_at = ?, head_sha = ?
+				 WHERE git_common_dir = ? AND repo = ? AND number = ?
+					AND (head_sha IS NULL OR head_sha = ? OR ? = 'local')`,
+				[
+					patch.verdict ?? null,
+					source,
+					patch.verdict_at ?? null,
+					headSha,
+					key.git_common_dir,
+					key.repo,
+					key.number,
+					headSha,
+					source,
+				],
+			);
+			return { ok: true };
+		},
+		// Retire a PR row (merged/closed): flip state + stamp retired_at so it drops out of
+		// the open-PR read while the reconcile history is retained.
+		async retirePr(key, patch = {}, _context = {}, config = {}) {
+			runParams(
+				runtime, getDatabase(config),
+				'UPDATE kernel_pr SET state = ?, retired_at = ? WHERE git_common_dir = ? AND repo = ? AND number = ?',
+				[
+					patch.state ?? 'closed',
+					patch.retired_at ?? new Date().toISOString(),
+					key.git_common_dir,
+					key.repo,
+					key.number,
+				],
+			);
+			return { ok: true };
+		},
 		// --- Event-store primitives (Wave 2) — composed by broker.runGuardedEvent.
 		// `context` is part of the broker contract but unused by these direct SQL
 		// reads/writes (prefixed `_` for eslint no-unused-vars).
@@ -2313,6 +2455,14 @@ function createDriver(runtime, configuredDatabasePath) {
 			ensureMemorySchema(database);
 			return searchMemoryRowsRanked(runtime, database, query, limit);
 		},
+		// Relevance-only BM25 recall that also returns the raw bm25 `score` per entry, so a
+		// caller can apply a relevance floor. A no-match/empty query returns [] (no recency
+		// fallback). Used by the per-turn memory-recall hook.
+		searchMemoriesRankedScored(query, limit, config = {}) {
+			const database = getDatabase(config);
+			ensureMemorySchema(database);
+			return searchMemoryRowsRankedScored(runtime, database, query, limit);
+		},
 		// The newest `limit` entries (default recall with no query). `options.agents` scopes
 		// the read to a source_agent allow-list (e.g. human `remember` notes only).
 		recentMemories(limit, options = {}, config = {}) {