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

package/lib/pr-monitor/shepherd-lease.js

@@ -37,7 +37,9 @@ const crypto = require('node:crypto');
 const { resolveGitCommonDir } = require('../kernel/broker');
 
 /** A wedged owner whose heartbeat is older than this (ms) is reclaimable. */
-const STALE_MS = 30000;
+// Must exceed the longest synchronous daemon read (`gh pr list`, 30s) with
+// enough margin that a blocked event loop cannot be reclaimed mid-read.
+const STALE_MS = 90000;
 const LOCK_FILE_MODE = 0o600;
 
 /**
@@ -229,6 +231,12 @@ function release(projectRoot, { gitCommonDir, token, pid = process.pid } = {}) {
   }
 }
 
+/** True only while this exact pid+token still owns the shared lease. */
+function owns(projectRoot, { gitCommonDir, token, pid = process.pid } = {}) {
+  const held = readLock(lockFilePath(projectRoot, { gitCommonDir }));
+  return Boolean(held && ownsLock(held, { token, pid }));
+}
+
 module.exports = {
   STALE_MS,
   lockFilePath,
@@ -240,4 +248,5 @@ module.exports = {
   stopHeartbeat,
   updateWatchers,
   release,
+  owns,
 };

package/lib/pr-monitor/watch-lifecycle.js

@@ -20,6 +20,7 @@ const path = require('node:path');
 const { spawn, execFileSync } = require('node:child_process');
 
 const journal = require('./journal');
+const brokerMod = require('../kernel/broker');
 
 /** Absolute path to the forge CLI entrypoint (this file is lib/pr-monitor/). */
 function forgeBin() {
@@ -66,7 +67,18 @@ function startPrWatcherDetached(opts = {}) {
 
     const slug = resolveSlug({ cwd, exec: opts.exec });
     if (slug) {
-      const dir = journalMod.journalDir({ root: cwd, repo: slug, pr: prNumber });
+      let gitCommonDir = opts.gitCommonDir;
+      if (!gitCommonDir) {
+        try {
+          const resolveGitCommonDir = opts.resolveGitCommonDir || brokerMod.resolveGitCommonDir;
+          gitCommonDir = resolveGitCommonDir(cwd, { warn: () => {} });
+        } catch {
+          /* unavailable common-dir keeps the legacy per-root journal fallback */
+        }
+      }
+      const dir = journalMod.journalDir({
+        root: cwd, gitCommonDir, repo: slug, pr: prNumber,
+      });
       if (journalMod.watcherRunning(dir)) return { started: false, reason: 'already-running' };
     }
 

package/lib/pr-pull.js

@@ -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);
 }
 
 /**
@@ -865,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;
@@ -1139,10 +1146,13 @@ 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',
-    // `pr` lets the adapter fall back to the rollup `isRequired` set when branch
-    // protection is unreadable (the Actions token can't read protection).
+    // `pr` is included for diagnostic rollup evidence when protection is unreadable.
     () => adapter.readRequiredChecks({ owner, repo, base, pr }),
     { degraded, fallback: null },
   );
@@ -1169,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
@@ -1214,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
@@ -1224,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,
@@ -1245,9 +1266,7 @@ async function gatherPrSnapshot(ctx) {
     unreadable,
   });
 
-  // Record which source answered the required-checks read (`protection` |
-  // `rollup` | null) so the source is visible in the verdict evidence — the
-  // rollup source is the CI path where branch protection is unreadable.
+  // Record the authoritative required-check source (`protection` or null).
   evidence.requiredSource = adapter.lastRequiredSource || null;
 
   return {

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');
@@ -144,7 +166,16 @@ function searchRanked(projectRoot, query, limit, options = {}) {
 // 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 = {}) {
-  return resolveStore(projectRoot, options).searchMemoriesRankedScored(query, limit);
+  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
@@ -170,5 +201,6 @@ module.exports = {
   count,
   searchRanked,
   searchRankedScored,
+  resolveProjectId,
   closeAll,
 };