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

package/lib/pr-pull.js

@@ -28,7 +28,7 @@
  * @module pr-pull
  */
 
-const { isFailed, isGreen, runShepherdPass } = require('./pr-shepherd');
+const { isFailed, isGreen } = require('./pr-shepherd');
 const { fenceUntrusted } = require('./untrusted-content');
 
 /** Token caps that keep the payload bounded regardless of PR size. */
@@ -43,6 +43,11 @@ const LOG_FETCH_MULTIPLIER = 3;
 // re-review or a late reviewer comment inside the window means the PR is still
 // in flight. Mirrors the merge-rules `settle_min` idea (default 10 minutes).
 const DEFAULT_SETTLE_WINDOW_MS = 600000;
+const FULL_HEAD_SHA = /^[0-9a-f]{40}$/i;
+
+function normalizeHeadSha(value) {
+  return typeof value === 'string' && FULL_HEAD_SHA.test(value) ? value.toLowerCase() : null;
+}
 
 /**
  * Bot logins whose review threads ARE actionable fixes (their comments tell you
@@ -320,7 +325,7 @@ function isSkipped(check) {
 /** A check still in flight (not green, not failed) — e.g. IN_PROGRESS/QUEUED or
  * a status context with no conclusion yet. */
 function isPending(check) {
-  return !isGreen(check) && !isFailed(check);
+  return !isSkipped(check) && !isGreen(check) && !isFailed(check);
 }
 
 /**
@@ -680,9 +685,12 @@ function buildPullPayload({
 
   return {
     ...prField(pr),
+    // DEPRECATED: `state` is the legacy decision-pass ladder, kept only for
+    // back-compat. It is now a PROJECTION of `verdict` (via verdictToLegacyState),
+    // never independently computed. Consumers MUST read `verdict` — the single,
+    // trustworthy, fail-closed merge vocabulary (never false-clean). Full removal
+    // of `state` is tracked as a follow-up kernel issue.
     state,
-    // `verdict` is the trustworthy, fail-closed merge signal (never false-clean);
-    // `state` remains the legacy decision-pass state for back-compat.
     ...(verdict ? { verdict } : {}),
     ...(evidence ? { evidence } : {}),
     summary,
@@ -862,12 +870,14 @@ function buildVerdictContext(input) {
 /** Rank 1: UNKNOWN (fail-closed) — unreadable input/required set, missing head
  * oid, or a torn read (head moved during the gather). */
 function rankUnknown(v) {
-  const torn = Boolean(v.headOidStart) && Boolean(v.headOidEnd) && v.headOidStart !== v.headOidEnd;
+  const startValid = normalizeHeadSha(v.headOidStart) !== null;
+  const endValid = normalizeHeadSha(v.headOidEnd) !== null;
+  const torn = startValid && endValid && v.headOidStart !== v.headOidEnd;
   v.evidence.tornRead = torn;
   if (v.requiredClass.unreadable && !v.evidence.unreadable.includes('requiredChecks')) {
     v.evidence.unreadable.push('requiredChecks');
   }
-  if (!v.headOidStart && !v.evidence.unreadable.includes('headOid')) {
+  if ((!startValid || !endValid) && !v.evidence.unreadable.includes('headOid')) {
     v.evidence.unreadable.push('headOid');
   }
   return (v.evidence.unreadable.length > 0 || torn) ? 'UNKNOWN' : null;
@@ -993,6 +1003,52 @@ function verdictLabel(verdict) {
 /** The full label reconcile set — one label per canonical verdict. */
 const VERDICT_LABELS = MERGE_VERDICTS.map((v) => `${VERDICT_LABEL_PREFIX}${v.toLowerCase()}`);
 
+/**
+ * The ONE place that maps the canonical 7-enum `verdict` onto the DEPRECATED
+ * legacy `runShepherdPass` ladder (`pr-shepherd.js:34`). `verdict` is the single
+ * consumer-facing vocabulary; the payload's `state` field is a back-compat
+ * PROJECTION of the verdict through this map — never independently computed — so
+ * the two can never disagree. Unknown/empty input fails closed to `UNKNOWN`.
+ *
+ * @param {string} verdict - a canonical MERGE_VERDICTS value.
+ * @returns {string} the deprecated legacy state.
+ */
+function verdictToLegacyState(verdict) {
+  const v = String(verdict || '').toUpperCase();
+  switch (v) {
+    case 'CLEAN-MERGEABLE': return 'MERGE_READY';
+    case 'REVIEW-PENDING': return 'NEEDS_REVIEW';
+    case 'BLOCKED-THREADS': return 'NEEDS_REVIEW';
+    case 'BLOCKED-CHECKS': return 'PENDING';
+    // BEHIND maps to ESCALATE, not PENDING: the legacy runShepherdPass escalated a
+    // behind head (handleBehindBase with --auto-rebase OFF, the default) so a human
+    // rebases or opts into auto-rebase. Mapping it to PENDING would tell a legacy
+    // `state` consumer to keep waiting on a PR that actually needs action.
+    case 'BEHIND': return 'ESCALATE';
+    case 'BLOCKED-CONFLICT': return 'ESCALATE';
+    default: return 'UNKNOWN';
+  }
+}
+
+/**
+ * The back-compat legacy `state` for the `--pull` payload. A terminal GitHub
+ * lifecycle (`MERGED`/`CLOSED`) wins over the merge verdict: the old dry-run
+ * `runShepherdPass` hit `lifecycleOutcome` first (`pr-shepherd.js:403`) and
+ * emitted `MERGED`/`CLOSED` so a legacy consumer stops polling / stops prompting a
+ * human to merge an already-landed PR. `computeVerdict`'s 7-enum has no terminal
+ * value, so we read the lifecycle (`adapter.readState().state`) here; only an open
+ * PR falls through to the verdict projection.
+ *
+ * @param {string} verdict - a canonical MERGE_VERDICTS value.
+ * @param {string} [prLifecycleState] - readState().state: OPEN | MERGED | CLOSED.
+ * @returns {string} the deprecated legacy state.
+ */
+function legacyStateFor(verdict, prLifecycleState) {
+  const lifecycle = String(prLifecycleState || '').toUpperCase();
+  if (lifecycle === 'MERGED' || lifecycle === 'CLOSED') return lifecycle;
+  return verdictToLegacyState(verdict);
+}
+
 /**
  * Run an optional read and SURFACE any failure instead of swallowing it: on
  * throw, record `{ source, error }` into `degraded` (and optionally mark `source`
@@ -1067,7 +1123,6 @@ function gatherFailureExcerpts(runGh, checks, requiredSet, { maxFailures, maxExc
  * @param {string} [ctx.self]  - shepherd's own login
  * @param {object} ctx.adapter - validated pr-state adapter
  * @param {(args: string[]) => string} ctx.runGh - injected `gh` runner (args → stdout)
- * @param {Function} [ctx.runPass] - decision pass (default runShepherdPass), injectable for tests
  * @param {number} [ctx.maxFailures]
  * @param {number} [ctx.maxThreads]
  * @param {number} [ctx.maxExcerptLines]
@@ -1091,9 +1146,14 @@ async function gatherPrSnapshot(ctx) {
 
   // readState is the one REQUIRED read — if it throws, the whole gather fails.
   const state = await adapter.readState(pr);
+  const headOidStart = normalizeHeadSha(state.headSha);
+  if (!headOidStart) unreadable.push('headOid');
+  if (state.providerEvidenceReadable === false) unreadable.push('providerEvidence');
+
   const requiredSet = await safeRead(
     'requiredChecks',
-    () => adapter.readRequiredChecks({ owner, repo, base }),
+    // `pr` is included for diagnostic rollup evidence when protection is unreadable.
+    () => adapter.readRequiredChecks({ owner, repo, base, pr }),
     { degraded, fallback: null },
   );
 
@@ -1119,16 +1179,26 @@ async function gatherPrSnapshot(ctx) {
   // Branch divergence (behind base → needs an update/rebase).
   const div = await safeRead(
     'divergence',
-    () => callIfPresent(adapter, 'readDivergence', { baseRef: ctx.baseRef, cwd }, { behind: 0 }),
-    { degraded, fallback: { behind: 0 } },
+    () => callIfPresent(
+      adapter,
+      'readDivergence',
+      { baseRef: ctx.baseRef, cwd, headRef: state.headSha },
+      { behind: 0 },
+    ),
+    { degraded, unreadable, fallback: { behind: 0 } },
   );
   const behind = div.behind || 0;
 
   // Predicted merge conflicts (which files) — optional adapter capability.
   const conflicts = await safeRead(
     'conflicts',
-    () => callIfPresent(adapter, 'detectConflicts', { baseRef: ctx.baseRef, cwd }, null),
-    { degraded, fallback: null },
+    () => callIfPresent(
+      adapter,
+      'detectConflicts',
+      { baseRef: ctx.baseRef, cwd, headRef: state.headSha },
+      null,
+    ),
+    { degraded, unreadable, fallback: null },
   );
 
   // Bot STATUS COMMENTS (Sonar/Vercel/Netlify/Codecov quality-gate + deployment
@@ -1164,7 +1234,8 @@ async function gatherPrSnapshot(ctx) {
   const headPushKnown = headPushTimeMs != null;
   // Torn-read guard: re-read the head oid at the END of the gather.
   const endState = await safeRead('headEnd', () => adapter.readState(pr), { degraded, unreadable });
-  const headOidEnd = endState ? endState.headSha : state.headSha;
+  const headOidEnd = normalizeHeadSha(endState && endState.headSha);
+  if (!headOidEnd && !unreadable.includes('headOid')) unreadable.push('headOid');
 
   // Actionable NON-HUMAN direct comments (mechanism-detected, suppression-list
   // filtered) and an AUTHOR-AGNOSTIC unresolved-thread count — both independent
@@ -1174,7 +1245,7 @@ async function gatherPrSnapshot(ctx) {
   const unresolvedThreadCount = countUnresolvedThreads(threads);
 
   const { verdict, evidence } = computeVerdict({
-    headOidStart: state.headSha,
+    headOidStart,
     headOidEnd,
     mergeStateStatus: state.mergeStateStatus,
     mergeable: state.mergeable,
@@ -1195,6 +1266,9 @@ async function gatherPrSnapshot(ctx) {
     unreadable,
   });
 
+  // Record the authoritative required-check source (`protection` or null).
+  evidence.requiredSource = adapter.lastRequiredSource || null;
+
   return {
     state, requiredSet, threads, behind, conflicts, issueComments,
     botStatusBlockers, requiredChecks, pendingChecks, draft, reviewDecision,
@@ -1207,7 +1281,6 @@ async function gatherPrSnapshot(ctx) {
 async function gatherPullSignal(ctx) {
   const {
     pr, self, adapter, runGh,
-    runPass = runShepherdPass,
     maxFailures = DEFAULT_MAX_FAILURES,
     maxThreads = DEFAULT_MAX_THREADS,
     maxExcerptLines = DEFAULT_MAX_EXCERPT_LINES,
@@ -1230,12 +1303,12 @@ async function gatherPullSignal(ctx) {
     requiredChecks, pendingChecks, draft, reviewDecision, verdict, evidence, degraded,
   } = snap;
 
-  // Legacy decision pass (READ-ONLY dryRun) for back-compat `state`. Shares the
-  // snapshot's `degraded` so a pass-read failure is still surfaced in the payload.
-  const pass = await safeRead('pass', () => runPass({ ...ctx, adapter, dryRun: true }), {
-    degraded,
-    fallback: { state: 'UNKNOWN', reason: 'Decision pass could not complete — a read failed; see verdict evidence.' },
-  });
+  // `verdict` is the SINGLE consumer-facing vocabulary. The back-compat `state`
+  // field is DERIVED from it (via legacyStateFor) — the read-only `--pull` payload
+  // no longer runs a second decision pass, so the two vocabularies can never
+  // disagree. A terminal lifecycle (MERGED/CLOSED) still wins over the verdict so
+  // legacy consumers see the landed outcome, matching the old dry-run pass.
+  const legacyState = legacyStateFor(verdict, state.state);
 
   const failures = gatherFailureExcerpts(runGh, state.checks, requiredSet, { maxFailures, maxExcerptLines, degraded });
   const reviewThreads = buildReviewThreads(threads, self, { maxThreads });
@@ -1254,7 +1327,7 @@ async function gatherPullSignal(ctx) {
   });
 
   const summary = summarize({
-    state: pass.state,
+    state: legacyState,
     failureCount: failures.length,
     threadCount: reviewThreads.length,
     blockers,
@@ -1262,11 +1335,10 @@ async function gatherPullSignal(ctx) {
 
   return buildPullPayload({
     pr,
-    state: pass.state,
+    state: legacyState,
     verdict,
     evidence,
     degraded,
-    reason: pass.reason,
     summary,
     mergeable: state.mergeable || 'UNKNOWN',
     mergeStateStatus: state.mergeStateStatus || 'UNKNOWN',
@@ -1299,6 +1371,8 @@ module.exports = {
   renderPullSummary,
   buildPullPayload,
   computeVerdict,
+  verdictToLegacyState,
+  legacyStateFor,
   MERGE_VERDICTS,
   VERDICT_LABELS,
   VERDICT_LABEL_PREFIX,

package/lib/pr-shepherd.js

@@ -32,6 +32,7 @@ const { fenceUntrusted } = require('./untrusted-content');
 
 /** Non-erroring terminal states a pass can settle into. */
 const TERMINAL_STATES = ['MERGE_READY', 'ESCALATE', 'PENDING', 'MERGED', 'CLOSED', 'NEEDS_REVIEW'];
+const MERGE_READY_PROVIDER_STATES = new Set(['CLEAN', 'HAS_HOOKS', 'UNSTABLE']);
 
 // Review threads are classified BY MECHANISM, not by a bot-name list: a GitHub
 // review THREAD is opened by a reviewer (a human OR any bot) and stays open until
@@ -72,9 +73,11 @@ function actionableComments(threads, _self) {
   );
 }
 
-const SUCCESS_CONCLUSIONS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+const SUCCESS_CONCLUSIONS = new Set(['SUCCESS']);
 
 function isGreen(check) {
+  if (!Object.prototype.hasOwnProperty.call(check || {}, 'status')
+    || String(check.status || '').toUpperCase() !== 'COMPLETED') return false;
   const c = String(check.conclusion || '').toUpperCase();
   return SUCCESS_CONCLUSIONS.has(c);
 }
@@ -388,13 +391,18 @@ async function runShepherdPass(ctx) {
 
   // Every read goes through the auth guard so 401/403-scope/rate-limit map to
   // the documented PENDING/HARD_STOP states instead of escaping as a generic
-  // failure. Non-auth errors still propagate.
+  // failure. Other read errors are surfaced below as ESCALATE results.
 
   // --- Read PR/CI state FIRST so a merged/closed PR is detected as terminal
   // even when the branch-protection (required-checks) read would fail with an
   // auth/scope error — the scheduler must always get the terminal signal for a
   // landed/closed PR. ---
-  const stateRead = await guardAuth(() => adapter.readState(pr), actions);
+  let stateRead;
+  try {
+    stateRead = await guardAuth(() => adapter.readState(pr), actions);
+  } catch (err) {
+    return result('ESCALATE', { actions, reason: `PR provider state is unreadable: ${err.message}` });
+  }
   if (stateRead.outcome) return stateRead.outcome;
   const startState = stateRead.value;
   const startSha = startState.headSha;
@@ -402,13 +410,24 @@ async function runShepherdPass(ctx) {
   // --- Lifecycle: a merged/closed PR is terminal. ---
   const lifecycle = lifecycleOutcome(startState.state, actions);
   if (lifecycle) return lifecycle;
+  if (startState.providerEvidenceReadable === false) {
+    return result('ESCALATE', {
+      actions,
+      reason: 'PR lifecycle, draft, head, or check-rollup evidence is malformed or incomplete.',
+    });
+  }
 
   // --- Required-checks set (only matters for non-terminal PRs); this is where
   // auth/scope fails fast. ---
-  const requiredRead = await guardAuth(
-    () => adapter.readRequiredChecks({ owner, repo, base }),
-    actions,
-  );
+  let requiredRead;
+  try {
+    requiredRead = await guardAuth(
+      () => adapter.readRequiredChecks({ owner, repo, base }),
+      actions,
+    );
+  } catch (err) {
+    return result('ESCALATE', { actions, reason: `Required-check policy is unreadable: ${err.message}` });
+  }
   if (requiredRead.outcome) return requiredRead.outcome;
   const required = requiredRead.value;
 
@@ -422,7 +441,7 @@ async function runShepherdPass(ctx) {
   }
 
   const divergenceRead = await guardAuth(
-    () => adapter.readDivergence({ baseRef, cwd }),
+    () => adapter.readDivergence({ baseRef, cwd, headRef: startSha }),
     actions,
   );
   if (divergenceRead.outcome) return divergenceRead.outcome;
@@ -472,6 +491,13 @@ async function runShepherdPass(ctx) {
 
   // --- Terminal: all required green + not behind → merge-ready handoff. ---
   if (allRequiredGreen) {
+    const providerMergeState = String(startState.mergeStateStatus || '').toUpperCase();
+    if (!MERGE_READY_PROVIDER_STATES.has(providerMergeState)) {
+      return result('ESCALATE', {
+        actions,
+        reason: `Provider merge state ${providerMergeState || 'UNKNOWN'} does not authorize merge readiness.`,
+      });
+    }
     return result('MERGE_READY', {
       actions,
       reason: 'All required checks are green and the branch is up to date. Handing off to the human to merge in the GitHub UI — the shepherd never merges.',

package/lib/preflight/gates.js

@@ -17,10 +17,11 @@
  */
 
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
-const { execFileSync } = require('node:child_process');
 const nodeFs = require('node:fs');
-const { getAffectedTestFiles } = require('../commands/test');
+const { getTestCandidatesForChangedFile } = require('../commands/test');
+const { selectDocAssertingTests } = require('../doc-assertions');
 
 const IS_WINDOWS = process.platform === 'win32';
 
@@ -37,6 +38,36 @@ function statusSummary(result, okMsg, failMsg) {
     : { ok: false, summary: failMsg };
 }
 
+function compareStringsByCodePoint(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function normalizeChangedFiles(files) {
+  if (!Array.isArray(files)) return Object.freeze([]);
+  return Object.freeze([...new Set(
+    files.map((file) => String(file).replaceAll('\\', '/')).filter((file) => file !== ''),
+  )].sort(compareStringsByCodePoint));
+}
+
+function fingerprintChangedFiles(files) {
+  return crypto.createHash('sha256').update(JSON.stringify(files)).digest('hex');
+}
+
+function selectAffectedTests(projectRoot, changedFiles, fs = nodeFs) {
+  const tests = new Set();
+  for (const file of changedFiles) {
+    for (const candidate of getTestCandidatesForChangedFile(file)) {
+      if (fs.existsSync(path.join(projectRoot, candidate))) tests.add(candidate);
+    }
+  }
+  for (const candidate of selectDocAssertingTests(changedFiles, projectRoot, fs)) {
+    tests.add(candidate);
+  }
+  return [...tests].sort(compareStringsByCodePoint);
+}
+
 /**
  * Gate 1 — ESLint on the change blast radius (or the whole tree with --all).
  * `files === null` means "lint everything" (`eslint .`).
@@ -152,38 +183,50 @@ function runSonar(files, { projectRoot, spawn = spawnSync } = {}) {
  */
 function runAffectedTests({
   projectRoot,
-  changedFiles: _changedFiles,
+  changedFiles,
   spawn = spawnSync,
   resolveTests,
 } = {}) {
+  const inputs = Array.isArray(changedFiles) && Object.isFrozen(changedFiles)
+    ? changedFiles
+    : normalizeChangedFiles(changedFiles);
+  const inputFingerprint = fingerprintChangedFiles(inputs);
   const resolver = typeof resolveTests === 'function'
     ? resolveTests
-    // strict:true so a failed `git diff` THROWS here instead of returning [] —
-    // otherwise a git error would masquerade as "no affected tests" (fast-lane
-    // green), a fail-OPEN. The catch below turns that throw into a closed gate.
-    : () => getAffectedTestFiles(projectRoot, execFileSync, nodeFs, { strict: true });
+    : (files) => selectAffectedTests(projectRoot, files);
   let targets;
   try {
-    targets = resolver() || [];
+    targets = resolver(inputs) || [];
   } catch (err) {
     // A resolver ERROR must NOT masquerade as "no affected tests" (green).
     // We could not determine what to run, so fail closed — never a vacuous pass.
     const reason = err && err.message ? err.message : String(err);
-    return { ok: false, summary: `affected-test resolution failed — fail-closed (${reason})` };
+    return {
+      ok: false,
+      summary: `affected-test resolution failed — fail-closed (${reason})`,
+      inputFingerprint,
+    };
   }
   if (targets.length === 0) {
-    return { ok: true, summary: 'no affected tests resolved (fast lane)' };
+    return {
+      ok: true,
+      summary: 'no affected tests resolved (fast lane)',
+      inputFingerprint,
+    };
   }
   const result = spawn(
     'bun',
     ['test', '--timeout', '15000', ...targets],
     { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
   );
-  return statusSummary(
-    result,
-    `${targets.length} affected test file(s) passed`,
-    'affected tests failed',
-  );
+  return {
+    ...statusSummary(
+      result,
+      `${targets.length} affected test file(s) passed`,
+      'affected tests failed',
+    ),
+    inputFingerprint,
+  };
 }
 
 /**
@@ -198,15 +241,18 @@ function runAffectedTests({
  * @returns {{ name: string, run: () => Promise<{ok:boolean, summary?:string}> }[]}
  */
 function buildGates({ projectRoot, changedFiles = [], runAll = false, deps = {} }) {
+  const normalizedChangedFiles = normalizeChangedFiles(changedFiles);
+  const inputFingerprint = fingerprintChangedFiles(normalizedChangedFiles);
   const eslint = deps.eslint || ((files) => runEslint(files, { projectRoot }));
   const structural = deps.structural || (() => runStructural({ projectRoot }));
   const sonar = deps.sonar || ((files) => runSonar(files, { projectRoot }));
-  const affected = deps.affected || (() => runAffectedTests({ projectRoot, changedFiles }));
+  const affected = deps.affected
+    || ((files) => runAffectedTests({ projectRoot, changedFiles: files }));
 
   // Under --all, scope BOTH lint and sonar to the whole tree (null). Otherwise
   // sonar would receive changedFiles=[] and report a vacuous "no changed files"
   // pass while lint scanned everything — a fail-open hole on the remedy path.
-  const scanTargets = runAll ? null : changedFiles;
+  const scanTargets = runAll ? null : normalizedChangedFiles;
 
   // Affected-tests maps from the change set, which is empty under --all. Running
   // the WHOLE suite here defeats preflight's fast purpose (and hangs on Windows),
@@ -216,8 +262,9 @@ function buildGates({ projectRoot, changedFiles = [], runAll = false, deps = {}
       ok: true,
       skipped: true,
       summary: 'whole-tree mode (--all): affected-test mapping N/A — run the full suite (CI does)',
+      inputFingerprint,
     })
-    : async () => affected();
+    : async () => affected(normalizedChangedFiles);
 
   return [
     { name: 'lint', run: async () => eslint(scanTargets) },

package/lib/preflight/runner.js

@@ -19,6 +19,7 @@
  * @typedef {Object} GateOutcome
  * @property {boolean} ok       - Whether the gate passed.
  * @property {string} [summary] - Short human-readable result line.
+ * @property {string} [inputFingerprint] - Exact input snapshot tested by the gate.
  *
  * @typedef {Object} Gate
  * @property {string} name
@@ -30,6 +31,7 @@
  * @property {boolean} skipped
  * @property {string} summary
  * @property {number} [durationMs]
+ * @property {string} [inputFingerprint]
  */
 
 /**
@@ -66,6 +68,9 @@ async function executeGate(gate) {
     skipped,
     summary: outcome?.summary || '',
     durationMs,
+    ...(typeof outcome?.inputFingerprint === 'string'
+      ? { inputFingerprint: outcome.inputFingerprint }
+      : {}),
   };
 }
 

package/lib/project-memory.js

@@ -1,7 +1,11 @@
 'use strict';
 
+const fs = require('node:fs');
+const path = require('node:path');
 const { resolveKernelDatabasePath } = require('./kernel/cli-broker-factory');
+const { resolveGitCommonDir } = require('./kernel/broker');
 const { createBuiltinSQLiteDriver } = require('./kernel/sqlite-driver');
+const { normalizeRecallHit } = require('./memory-recall');
 
 // Project memory is a Forge read model persisted in the kernel store (kernel_memories),
 // written DIRECTLY rather than through the issue CAS/guarded-event path. The store seam
@@ -30,6 +34,24 @@ function resolveStore(projectRoot, options = {}) {
   return options.store ?? defaultStore(projectRoot, options);
 }
 
+function resolveProjectId(projectRoot, options = {}) {
+  const platform = options.platform || process.platform;
+  const pathImpl = platform === 'win32' ? path.win32 : path.posix;
+  const commonDir = options.gitCommonDir || resolveGitCommonDir(projectRoot, options);
+  const absolute = pathImpl.resolve(projectRoot, commonDir);
+  const realpath = options.realpath || fs.realpathSync.native;
+  let canonical;
+  try {
+    canonical = realpath(absolute);
+  } catch {
+    canonical = absolute;
+  }
+  canonical = canonical.replaceAll('\\', '/');
+  return platform === 'win32'
+    ? canonical.toLowerCase()
+    : canonical;
+}
+
 function assertEntryObject(entry) {
   if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
     throw new TypeError('project memory entry must be an object');
@@ -140,6 +162,22 @@ function searchRanked(projectRoot, query, limit, options = {}) {
   return resolveStore(projectRoot, options).searchMemoriesRanked(query, limit);
 }
 
+// Relevance-only BM25 recall that returns the raw bm25 `score` per entry, so a caller can
+// apply a relevance floor. A no-match/empty query returns [] (no recency fallback). The
+// per-turn memory-recall hook uses this to inject nothing unless a note clearly matches.
+function searchRankedScored(projectRoot, query, limit, options = {}) {
+  const projectId = resolveProjectId(projectRoot, options);
+  const searchOptions = {
+    projectId,
+    excludeKeys: options.excludeKeys || [],
+    ...(options.now ? { now: options.now } : {}),
+    ...(options.busyTimeoutMs !== undefined ? { busyTimeoutMs: options.busyTimeoutMs } : {}),
+  };
+  return resolveStore(projectRoot, options)
+    .searchMemoriesRankedScored(query, limit, searchOptions)
+    .map(hit => normalizeRecallHit(hit, projectId));
+}
+
 // Close and forget every cached default store. The CLI process is short-lived (the OS
 // closes the handle on exit), so this is mainly a lifecycle helper for long-lived hosts and
 // tests — it releases the SQLite/WAL handle before a temp dir is removed.
@@ -162,5 +200,7 @@ module.exports = {
   recent,
   count,
   searchRanked,
+  searchRankedScored,
+  resolveProjectId,
   closeAll,
 };