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

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. */
@@ -680,9 +680,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,
@@ -884,9 +887,14 @@ function rankConflict(v) {
   return null;
 }
 
-/** Rank 3: branch behind base. */
+/** Rank 3: branch behind base. Gate on GitHub's actual blocking state
+ * (mergeStateStatus=BEHIND — set only when branch protection requires branches be
+ * up to date), NOT a raw compareCommits behind-count: a count>0 is often stale or
+ * non-blocking (strict-up-to-date not required), so escalating on it falsely
+ * labels a mergeable PR `behind` (issue 5291f2d2). The count is still surfaced in
+ * `evidence.behind`/blockers as WHY — it just no longer drives the verdict. */
 function rankBehind(v) {
-  return (v.mss === 'BEHIND' || v.behind > 0) ? 'BEHIND' : null;
+  return (v.mss === 'BEHIND') ? 'BEHIND' : null;
 }
 
 /** Rank 4: checks — failing/missing/skipped/pending REQUIRED checks, a failing
@@ -956,6 +964,84 @@ function computeVerdict(input) {
   return { verdict: rankClean(v), evidence: v.evidence };
 }
 
+/**
+ * The canonical verdict enum — every value `computeVerdict` can return, highest
+ * priority first (mirrors VERDICT_RANKS + rankClean). This is the SINGLE source
+ * for the `pr-verdict:*` label set the pr-monitor workflow reconciles, so the
+ * label and `forge shepherd <pr> --pull --json` can never drift: both are this
+ * same verdict.
+ */
+const MERGE_VERDICTS = [
+  'UNKNOWN', 'BLOCKED-CONFLICT', 'BEHIND', 'BLOCKED-CHECKS', 'BLOCKED-THREADS',
+  'REVIEW-PENDING', 'CLEAN-MERGEABLE',
+];
+
+/** Prefix for the single `pr-verdict:*` label a PR carries at a time. */
+const VERDICT_LABEL_PREFIX = 'pr-verdict:';
+
+/**
+ * Map a canonical verdict to its lowercased `pr-verdict:*` label
+ * (e.g. `BLOCKED-CHECKS` -> `pr-verdict:blocked-checks`). Unknown/empty input
+ * fails closed to the `unknown` label.
+ *
+ * @param {string} verdict
+ * @returns {string}
+ */
+function verdictLabel(verdict) {
+  const v = String(verdict || '').toUpperCase();
+  const known = MERGE_VERDICTS.includes(v) ? v : 'UNKNOWN';
+  return `${VERDICT_LABEL_PREFIX}${known.toLowerCase()}`;
+}
+
+/** 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`
@@ -1030,7 +1116,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]
@@ -1056,7 +1141,9 @@ async function gatherPrSnapshot(ctx) {
   const state = await adapter.readState(pr);
   const requiredSet = await safeRead(
     'requiredChecks',
-    () => adapter.readRequiredChecks({ owner, repo, base }),
+    // `pr` lets the adapter fall back to the rollup `isRequired` set when branch
+    // protection is unreadable (the Actions token can't read protection).
+    () => adapter.readRequiredChecks({ owner, repo, base, pr }),
     { degraded, fallback: null },
   );
 
@@ -1158,6 +1245,11 @@ 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.
+  evidence.requiredSource = adapter.lastRequiredSource || null;
+
   return {
     state, requiredSet, threads, behind, conflicts, issueComments,
     botStatusBlockers, requiredChecks, pendingChecks, draft, reviewDecision,
@@ -1170,7 +1262,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,
@@ -1193,12 +1284,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 });
@@ -1217,7 +1308,7 @@ async function gatherPullSignal(ctx) {
   });
 
   const summary = summarize({
-    state: pass.state,
+    state: legacyState,
     failureCount: failures.length,
     threadCount: reviewThreads.length,
     blockers,
@@ -1225,11 +1316,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',
@@ -1262,6 +1352,12 @@ module.exports = {
   renderPullSummary,
   buildPullPayload,
   computeVerdict,
+  verdictToLegacyState,
+  legacyStateFor,
+  MERGE_VERDICTS,
+  VERDICT_LABELS,
+  VERDICT_LABEL_PREFIX,
+  verdictLabel,
   isSkipped,
   isPending,
   buildBotStatusBlockers,

package/lib/project-memory.js

@@ -140,6 +140,13 @@ 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 = {}) {
+  return resolveStore(projectRoot, options).searchMemoriesRankedScored(query, limit);
+}
+
 // 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 +169,6 @@ module.exports = {
   recent,
   count,
   searchRanked,
+  searchRankedScored,
   closeAll,
 };

package/lib/release-readiness.js

@@ -1754,7 +1754,7 @@ function auditArtifactBlocker(projectRoot, audit) {
     return {
       id: 'd20-audit-artifact-current',
       title: 'D20 bd call-site kill-list artifact is not current',
-      detail: `Regenerate ${AUDIT_ARTIFACT}; current status: ${auditArtifact.reason}.`,
+      detail: `Regenerate ${AUDIT_ARTIFACT} in one command: \`forge release regen-audit\` (then commit it). Current status: ${auditArtifact.reason}.`,
       evidence: auditArtifact.evidence,
     };
   }
@@ -2074,6 +2074,21 @@ function renderAuditGroup(audit, group) {
   ];
 }
 
+// Rewrite the tracked kill-list artifact from a live re-scan. This is the exact
+// one-liner (`forge release regen-audit`) the d20 staleness blocker points at:
+// every Beads-removal PR shifts the census, so rather than hand-editing the
+// artifact (and red-failing CI cross-platform until it matches byte-for-byte),
+// a developer regenerates it in one command and commits the diff. `options`
+// forwards to auditBdCallSites so the write uses the same scan roots the gate
+// compares against.
+function writeAuditArtifact(projectRoot, options = {}) {
+  const audit = auditBdCallSites(projectRoot, options);
+  const artifactPath = absolutePath(projectRoot, AUDIT_ARTIFACT);
+  fs.mkdirSync(path.dirname(artifactPath), { recursive: true });
+  fs.writeFileSync(artifactPath, renderBdCallSiteAuditMarkdown(audit), 'utf8');
+  return { path: AUDIT_ARTIFACT, audit };
+}
+
 module.exports = {
   AUDIT_ARTIFACT,
   GROUPS,
@@ -2083,6 +2098,7 @@ module.exports = {
   canonicalizeAuditArtifact,
   renderBdCallSiteAuditMarkdown,
   renderReadinessReport,
+  writeAuditArtifact,
   // Exposed for the premerge-de-stage certification tests.
   premergeEmbeddedGateStatus,
   premergeEmbeddedGateBlocker,

package/lib/rules-sync.js

@@ -48,6 +48,10 @@ const CURSOR_RULE_FILES = {
   security: 'security-scanning.mdc',
   documentation: 'documentation.mdc',
   'kernel-tracking': 'kernel-tracking.mdc',
+  // The using-forge dispatch pointer as an always-apply Cursor rule — Cursor's native
+  // always-on carrier for the skill auto-trigger bootstrap (parallels the Claude SessionStart
+  // hook and the committed AGENTS.md for Codex). Thin pointer; full policy stays in the skill.
+  'using-forge': 'using-forge.mdc',
 };
 
 const CANONICAL_RULE_NAMES = Object.keys(CURSOR_RULE_FILES);

package/lib/runtime-health.js

@@ -172,17 +172,6 @@ function invokesForgeHook(line) {
   });
 }
 
-function invokesBeadsHook(line, hookName) {
-  const tokens = commandTokens(line);
-  return tokens.some((token, index) => (
-    commandName(token) === 'bd'
-    && toText(tokens[index + 1]).toLowerCase() === 'hooks'
-    && toText(tokens[index + 2]).toLowerCase() === 'run'
-    && toText(tokens[index + 3]).toLowerCase() === hookName
-    && isExecutingTokenPosition(tokens, index)
-  ));
-}
-
 function createDiagnostic(code, subject, message, repair, severity = 'hard-stop') {
   return {
     code,
@@ -216,7 +205,7 @@ function isUsableWindowsShellCandidate(candidate, options = {}) {
 function checkHookInstallation(projectRoot, options = {}) {
   const exec = options._exec || defaultExecFileSync;
   const platform = options.platform || process.platform;
-  const expectedRelativeHooksPaths = ['.lefthook/hooks', '.beads/hooks'];
+  const expectedRelativeHooksPaths = ['.lefthook/hooks'];
   const requiredHooks = ['pre-commit', 'pre-push'];
 
   function resolveGitRoot() {
@@ -269,23 +258,10 @@ function checkHookInstallation(projectRoot, options = {}) {
       const content = fs.readFileSync(filePath, 'utf8');
       const runsLefthook = hasExecutableHookCommand(content, invokesLefthook);
       const runsForgeHook = hasExecutableHookCommand(content, invokesForgeHook);
-      const runsBeadsHook = hasExecutableHookCommand(content, (line) => invokesBeadsHook(line, hookName));
 
       if (runsLefthook) return { active: true, provider: 'lefthook' };
       if (runsForgeHook) return { active: true, provider: 'forge' };
 
-      if (runsBeadsHook) {
-        const chainedHookPath = path.join(gitRoot, '.beads', 'hooks', hookName);
-        if (path.resolve(chainedHookPath) !== normalizedFilePath && fs.existsSync(chainedHookPath)) {
-          const chained = classifyHookFile(chainedHookPath, hookName, visited);
-          if (chained.active) {
-            return { active: true, provider: `beads->${chained.provider}` };
-          }
-        }
-
-        return { active: false, provider: 'beads-unverified' };
-      }
-
       return { active: false, provider: 'unknown' };
     } catch {
       return { active: false, provider: 'missing' };
@@ -333,7 +309,7 @@ function checkHookInstallation(projectRoot, options = {}) {
         state: 'inactive',
         verification: 'core.hooksPath',
         hooksPath,
-        message: `Git core.hooksPath is set to "${hooksPath}", not ".lefthook/hooks" or ".beads/hooks".`
+        message: `Git core.hooksPath is set to "${hooksPath}", not ".lefthook/hooks".`
       };
     }
   } catch {
@@ -488,9 +464,11 @@ function normalizeProjectRoot(projectRoot) {
 // shared resolver (env > .forge/config.yaml > default 'kernel'). Never throws and
 // never warns from the health path.
 function resolveHealthIssueBackend(options, projectRoot) {
-  if (options.issueBackend === 'kernel' || options.issueBackend === 'beads') {
+  if (options.issueBackend === 'kernel') {
     return options.issueBackend;
   }
+  // Anything else — including the retired `beads` value — falls through to the
+  // shared resolver, which answers 'kernel' for every unrecognized selector.
   return resolveIssueBackend({
     deps: options.backendDeps || {},
     env: options.env || process.env,
@@ -540,25 +518,16 @@ function checkRuntimeHealth(projectRoot, options = {}) {
   }
 
   if (!bd.available) {
-    if (issueBackend === 'beads') {
-      // Beads is the active issue backend, so bd is a genuine hard prerequisite.
-      diagnostics.push(createDiagnostic(
-        'BD_MISSING',
-        'bd',
-        'bd is required for stage-entry workflow checks when the beads issue backend is selected.'
-      ));
-    } else {
-      // Kernel is the default issue backend and needs no bd binary, so a missing bd
-      // must NOT hard-stop stage entry (the "no Beads install required" contract).
-      // Surface it as a non-blocking advisory instead.
-      advisories.push(createDiagnostic(
-        'BD_MISSING',
-        'bd',
-        'bd is not installed. The kernel issue backend does not require it; install bd only if you switch to the beads backend.',
-        undefined,
-        'advisory'
-      ));
-    }
+    // The kernel is the only issue backend and needs no bd binary, so bd is never a
+    // prerequisite and a missing bd must NOT hard-stop stage entry (the "no Beads
+    // install required" contract). It stays a non-blocking advisory.
+    advisories.push(createDiagnostic(
+      'BD_MISSING',
+      'bd',
+      'bd is not installed. Forge does not require it — the kernel issue backend is the only backend.',
+      undefined,
+      'advisory'
+    ));
   }
 
   if (!gh.available) {