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

package/lib/pr-pull.js

@@ -884,9 +884,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 +961,38 @@ 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()}`);
+
 /**
  * Run an optional read and SURFACE any failure instead of swallowing it: on
  * throw, record `{ source, error }` into `degraded` (and optionally mark `source`
@@ -1262,6 +1299,10 @@ module.exports = {
   renderPullSummary,
   buildPullPayload,
   computeVerdict,
+  MERGE_VERDICTS,
+  VERDICT_LABELS,
+  VERDICT_LABEL_PREFIX,
+  verdictLabel,
   isSkipped,
   isPending,
   buildBotStatusBlockers,

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/upgrade-safety.js

@@ -6,6 +6,8 @@ const path = require('node:path');
 const { lintRuntimeGraphConfig } = require('./core/runtime-graph');
 const { resolvePatchIntentRecords } = require('./patch-intent');
 const { verifyForgeLock, readForgeLock } = require('./forge-lock');
+const { readConfigBackend, resolveIssueBackend } = require('./issue-backend');
+const { detectBeadsJsonlSource } = require('./beads-detect');
 
 function checkStatus(ok) {
   return ok ? 'pass' : 'fail';
@@ -56,7 +58,33 @@ function buildSelfHealCandidates(projectRoot) {
   return candidates;
 }
 
-function buildUpgradeDryRunReport(projectRoot = process.cwd()) {
+function safeConfigBackend(projectRoot) {
+  try {
+    return readConfigBackend(projectRoot);
+  } catch {
+    return null;
+  }
+}
+
+// Detect the 0.0.10 -> current breaking boundary that hides a returning user's
+// issues (kernel issue a5399f3d): a `.beads/*.jsonl` store still present while the
+// default backend has flipped to the Kernel. `needsMigration` is true only when
+// the user has NOT explicitly opted back into Beads — via `.forge/config.yaml`
+// OR `FORGE_ISSUE_BACKEND` — so the advisory respects the SAME env+config opt-in
+// the issue-path nudge does (both resolve through resolveIssueBackend). Uses the
+// single shared detector so the two surfaces cannot drift.
+function buildBeadsMigrationSummary(projectRoot, env = process.env) {
+  const jsonlPresent = detectBeadsJsonlSource(projectRoot) !== null;
+  const configBackend = safeConfigBackend(projectRoot);
+  const backend = resolveIssueBackend({ env, projectRoot, warn: () => {} });
+  return {
+    jsonlPresent,
+    configBackend,
+    needsMigration: jsonlPresent && backend === 'kernel',
+  };
+}
+
+function buildUpgradeDryRunReport(projectRoot = process.cwd(), env = process.env) {
   const root = path.resolve(projectRoot);
   const runtime = lintRuntimeGraphConfig({ projectRoot: root });
   const patchIntent = buildPatchIntentSummary(root);
@@ -66,8 +94,12 @@ function buildUpgradeDryRunReport(projectRoot = process.cwd()) {
   const failedLockEntries = lockReport.results.filter(result => result.status === 'fail');
   const untrustedOptIns = countUntrustedOptIns(lock);
   const lockTrustOk = lockReport.ok && untrustedOptIns === 0;
+  const beadsMigration = buildBeadsMigrationSummary(root, env);
 
   return {
+    // A pending beads -> kernel migration is a guided ADVISORY, not an integrity
+    // failure — it never flips `ok` (scripts keying on it stay stable); it surfaces
+    // as its own prominent "action required" section in the rendered report.
     ok: runtime.ok && patchIntent.ok && lockTrustOk,
     projectRoot: root,
     runtime,
@@ -77,6 +109,7 @@ function buildUpgradeDryRunReport(projectRoot = process.cwd()) {
     lockTrustOk,
     selfHealCandidates,
     failedLockEntries,
+    beadsMigration,
   };
 }
 
@@ -139,6 +172,23 @@ function appendSelfHealResult(lines, selfHealResult) {
   }
 }
 
+function appendBeadsMigration(lines, beadsMigration) {
+  if (!beadsMigration || !beadsMigration.needsMigration) {
+    return;
+  }
+  lines.push(
+    '',
+    'Breaking change since 0.0.10 — action required',
+    'Detected a Beads issue store (.beads/*.jsonl). Forge now defaults to the Kernel',
+    'issue backend, so these issues will NOT appear until migrated (your data is safe',
+    'on disk in the meantime). To migrate:',
+    '  forge migrate --from beads   # import your Beads issues into the Kernel',
+    '  forge setup                  # (re)wire hooks + provision the Kernel store',
+    'Prefer to stay on Beads? Set `issueBackend: beads` in .forge/config.yaml '
+    + '(or FORGE_ISSUE_BACKEND=beads).',
+  );
+}
+
 function renderUpgradeDryRunReport(report, selfHealResult = null) {
   const lines = [
     'Forge upgrade dry-run',
@@ -149,6 +199,7 @@ function renderUpgradeDryRunReport(report, selfHealResult = null) {
     ...readinessLines(report),
   ];
 
+  appendBeadsMigration(lines, report.beadsMigration);
   appendPlannedSelfHeal(lines, report.selfHealCandidates);
   appendSelfHealResult(lines, selfHealResult);
 
@@ -194,6 +245,7 @@ function applySelfHeal(projectRoot, report) {
 module.exports = {
   applySelfHeal,
   buildUpgradeDryRunReport,
+  buildBeadsMigrationSummary,
   buildSelfHealCandidates,
   renderUpgradeDryRunReport,
 };

package/lib/workflow/enforce-stage.js

@@ -68,6 +68,27 @@ function findLatestStageRun(driver, issueId, stage) {
   }
 }
 
+// (Re-)entering an earlier stage invalidates the work that followed it: any
+// DOWNSTREAM stage previously recorded 'done' is reopened to 'active' so a gated
+// stage (ship/review) re-requires a fresh completion (R2 — the dev<->validate
+// rework loop must not let a stale validate=done pass ship). Reuses the idempotent
+// 'start' write, which keeps the row's id + original started_at but clears its
+// done status. Stages the entered stage does not precede (and non-'done' rows) are
+// left untouched, so forward progression records nothing extra.
+function invalidateDownstreamStages(driver, issueId, stageId, warn) {
+  const index = STAGE_PATH.indexOf(stageId);
+  if (index < 0) {
+    return;
+  }
+  for (let next = index + 1; next < STAGE_PATH.length; next += 1) {
+    const downstream = STAGE_PATH[next];
+    const run = findLatestStageRun(driver, issueId, downstream);
+    if (run?.status === 'done') {
+      recordStageRunSafe(driver, issueId, downstream, 'start', warn);
+    }
+  }
+}
+
 // Decide whether entering stageId is allowed given ONLY the kernel's recorded
 // stage history (used when no inline/file workflow state exists):
 //   - Stateless stages (plan/dev/validate/verify) are always re-entrant, so the
@@ -123,7 +144,12 @@ async function resolveActiveIssueId(driver, branch) {
   try {
     if (typeof driver.listWorktrees === 'function') {
       const rows = driver.listWorktrees() || [];
-      const match = rows.find(row => row && row.branch === branch && row.issue_id);
+      // Match only ACTIVE (live) linkage rows, newest first (listWorktrees orders
+      // registered_at DESC). A stale/superseded registration for a reused branch
+      // name must not rebind stage state to the OLD issue (be18881c). Tolerate a
+      // null state for rows written before the state column was populated.
+      const match = rows.find(row => row && row.branch === branch && row.issue_id
+        && (row.state === 'active' || row.state == null));
       if (match) {
         return match.issue_id;
       }
@@ -391,6 +417,7 @@ async function enforceStageEntry({
   const finish = (result) => {
     if (kernelActive) {
       recordStageRunSafe(driver, issueId, stageId, 'start', warn);
+      invalidateDownstreamStages(driver, issueId, stageId, warn);
       result.recordCompletion = () => recordStageRunSafe(driver, issueId, stageId, 'complete', warn);
     }
     return result;
@@ -401,6 +428,14 @@ async function enforceStageEntry({
     return enforceWithFileState(currentState, stageId, flags, args, finish);
   }
 
+  // B1 — strict mode is the explicit opt-in to the legacy fail-closed behavior:
+  // require prior stages / authoritative state. The default (unset) degrades to a
+  // loud warning and seeds the kernel so future gating gets real data. A recorded
+  // history that CONTRADICTS (e.g. validate started-but-not-done) still throws in
+  // both modes — that rework protection lives in enforceWithKernelState below and
+  // is never weakened by this flag.
+  const strict = process.env.FORGE_STAGE_GATE === 'strict';
+
   // No inline/file state: the kernel is authoritative. Gate on recorded stage
   // completions (tolerant read) so `ship` is reachable from a pure-CLI
   // plan->dev->validate progression with no .forge-state.json.
@@ -409,15 +444,37 @@ async function enforceStageEntry({
     if (decided) {
       return decided;
     }
+    // enforceWithKernelState returned null → the kernel has an issue linked but
+    // NO recorded predecessor (a contradiction would have thrown above). Degrade
+    // to warn + seed unless strict: allow the stage and let finish() record it so
+    // future gating has real history.
+    if (!strict) {
+      warn(
+        `[forge] no recorded workflow history for issue ${issueId} — allowing '${stageId}' ` +
+        `and recording it in the kernel. Set FORGE_STAGE_GATE=strict to require prior stages.`
+      );
+      return finish({ allowed: true, stage: stageId, workflowState: null, degradedGate: 'kernel-empty' });
+    }
   }
 
   if (STATELESS_ENTRY_STAGES.has(stageId)) {
     return finish({ allowed: true, stage: stageId, workflowState: null });
   }
 
+  // No workflow state AND no kernel-linked issue for this branch. Degrade to warn
+  // unless strict so incremental adoption (fresh setup, in-flight branch, manual
+  // commit) is not blocked.
+  if (!strict) {
+    warn(
+      `[forge] no workflow state and no kernel-linked issue for this branch — stage gate skipped for '${stageId}'. ` +
+      `Link an issue with 'forge worktree create <slug>' to enable stage tracking.`
+    );
+    return finish({ allowed: true, stage: stageId, workflowState: null, degradedGate: 'no-kernel-context' });
+  }
+
   throw new Error(
     `Stage ${stageId} requires authoritative workflow state. ` +
-    `Provide --workflow-state or restore ${WORKFLOW_STATE_FILENAME} before continuing.`
+    `Provide --workflow-state or restore ${WORKFLOW_STATE_FILENAME} before continuing (or unset FORGE_STAGE_GATE).`
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-workflow",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "Local runtime control plane for AI-assisted engineering workflows, gates, evidence, and all AI agents",
   "bin": {
     "forge": "bin/forge.js",
@@ -59,7 +59,7 @@
     "globals": "^17.3.0",
     "js-yaml": "^5.1.0",
     "lefthook": "^2.1.4",
-    "typescript": "5.4.5"
+    "typescript": "7.0.2"
   },
   "keywords": [
     "ai",

package/scripts/pr-auto-actions.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * pr-auto-actions — the pr-monitor workflow's bridge from the `--pull --json`
+ * verdict payload to Tier-2 auto-action DECISIONS. Reads the payload file the
+ * monitor already wrote (default `pull.json`), asks lib/pr-monitor/auto-actions
+ * (the single, unit-tested decision core) what is safe to do, and emits the
+ * flags to `$GITHUB_OUTPUT` (or stdout locally) for the workflow's action steps.
+ *
+ * This script performs NO GitHub writes and takes NO action — it only decides.
+ * The workflow owns the visible `gh` calls and the per-head-SHA idempotency
+ * markers. Fails CLOSED: an unreadable/malformed payload or any thrown error
+ * yields `update_branch=false` / `rerun=false`.
+ *
+ * Usage: node scripts/pr-auto-actions.js [pull.json] [isFork]
+ *   isFork: "true" when the PR head is a cross-repository fork (skips update).
+ *
+ * @module scripts/pr-auto-actions
+ */
+
+const fs = require('node:fs');
+
+const { decideAutoActions } = require('../lib/pr-monitor/auto-actions');
+
+/**
+ * Append `key=value` lines to `$GITHUB_OUTPUT` when set, else print them. Values
+ * are single-line (booleans / csv / short reasons) so no multiline escaping is
+ * needed; newlines are stripped defensively.
+ *
+ * @param {Record<string,string>} outputs
+ */
+function emitOutputs(outputs) {
+  const target = process.env.GITHUB_OUTPUT;
+  const text = Object.entries(outputs)
+    .map(([k, val]) => `${k}=${String(val).replace(/[\r\n]+/g, ' ')}`)
+    .join('\n') + '\n';
+  if (target) fs.appendFileSync(target, text);
+  else process.stdout.write(text);
+}
+
+/** Read + parse the payload file, returning null (fail-closed) on any error. */
+function readPayload(path) {
+  try {
+    return JSON.parse(fs.readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function main(argv) {
+  const path = argv[2] || 'pull.json';
+  const isFork = String(argv[3] || '').toLowerCase() === 'true';
+
+  const payload = readPayload(path);
+  if (!payload) {
+    // Fail closed: no readable verdict payload → take no action.
+    emitOutputs({
+      update_branch: 'false', update_reason: `no readable payload at ${path}`,
+      rerun: 'false', rerun_run_ids: '', rerun_reason: `no readable payload at ${path}`,
+    });
+    console.log(`auto-actions: no readable payload at ${path} — no action (fail closed)`);
+    return 0;
+  }
+
+  const { updateBranch, rerunFlaky } = decideAutoActions(payload, { isFork });
+  emitOutputs({
+    update_branch: updateBranch.should ? 'true' : 'false',
+    update_reason: updateBranch.reason,
+    rerun: rerunFlaky.should ? 'true' : 'false',
+    rerun_run_ids: (rerunFlaky.runIds || []).join(','),
+    rerun_reason: rerunFlaky.reason,
+  });
+  console.log(`auto-actions: update_branch=${updateBranch.should} (${updateBranch.reason})`);
+  console.log(`auto-actions: rerun=${rerunFlaky.should} (${rerunFlaky.reason})`);
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    process.exit(main(process.argv));
+  } catch (err) {
+    // Absolute fail-closed backstop: never let this script red-X the monitor.
+    emitOutputs({
+      update_branch: 'false', update_reason: `error: ${(err && err.message) || err}`,
+      rerun: 'false', rerun_run_ids: '', rerun_reason: `error: ${(err && err.message) || err}`,
+    });
+    console.log(`auto-actions: error — no action (fail closed): ${(err && err.message) || err}`);
+    process.exit(0);
+  }
+}
+
+module.exports = { emitOutputs, readPayload, main };

package/scripts/pr-verdict-label.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * pr-verdict label emitter — maps a canonical merge verdict (from
+ * `forge shepherd <pr> --pull --json`, lib/pr-pull.js) to its single
+ * `pr-verdict:*` label and emits `label` + `all_labels` to `$GITHUB_OUTPUT`
+ * (or stdout locally) for the pr-monitor workflow's reconcile step.
+ *
+ * SINGLE SOURCE: the verdict value and the label vocabulary both come from
+ * lib/pr-pull.js — this script computes NO verdict of its own, so the label can
+ * never disagree with `--pull`. Fails closed to `unknown` on empty input.
+ * Performs NO GitHub writes (the workflow owns the visible `gh` calls).
+ *
+ * Usage: node scripts/pr-verdict-label.js <VERDICT>
+ *
+ * @module scripts/pr-verdict-label
+ */
+
+const fs = require('node:fs');
+
+const { verdictLabel, VERDICT_LABELS } = require('../lib/pr-pull');
+
+/**
+ * Append `key=value` lines to `$GITHUB_OUTPUT` when set, else print them.
+ *
+ * @param {Record<string,string>} outputs
+ */
+function emitOutputs(outputs) {
+  const target = process.env.GITHUB_OUTPUT;
+  const text = Object.entries(outputs).map(([k, val]) => `${k}=${val}`).join('\n') + '\n';
+  if (target) fs.appendFileSync(target, text);
+  else process.stdout.write(text);
+}
+
+function main(argv) {
+  // Fail closed: a missing/empty verdict arg maps to the `unknown` label rather
+  // than erroring — the workflow must still land a label on every pass.
+  const verdict = argv[2] || 'UNKNOWN';
+  const label = verdictLabel(verdict);
+  emitOutputs({ label, all_labels: VERDICT_LABELS.join(',') });
+  console.log(`pr-verdict label: ${label} (verdict ${verdict})`);
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = { emitOutputs, main };