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

package/lib/commands/plan.js

@@ -1,5 +1,5 @@
 /**
- * Plan Command - Beads Integration
+ * Plan Command - Kernel Issue Integration
  * Creates implementation plan after research is complete
  *
  * Security: Uses execFileSync instead of exec/execSync to prevent command injection
@@ -26,15 +26,14 @@ const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
 
 /**
  * Human-readable label for the issue backend that created an issue.
- * Keeps printed output backend-accurate so kernel-created issues are not
- * mislabeled as "Beads".
+ * The kernel is the only backend; anything unresolved prints a neutral label
+ * rather than naming a store the issue did not come from.
  *
- * @param {string} [backend] - Resolved issue backend ('kernel' | 'beads').
- * @returns {string} Display label ('Kernel', 'Beads', or a neutral 'Issue').
+ * @param {string} [backend] - Resolved issue backend ('kernel').
+ * @returns {string} Display label ('Kernel' or a neutral 'Issue').
  * @private
  */
 function issueBackendLabel(backend) {
-	if (backend === 'beads') return 'Beads';
 	if (backend === 'kernel') return 'Kernel';
 	return 'Issue';
 }
@@ -76,7 +75,7 @@ function validateFeatureSlug(slug) {
 }
 
 /**
- * Build the issue description shared by both issue backends (kernel and beads).
+ * Build the issue description used when creating the kernel tracking issue.
  * Strategic scope appends a design-doc pointer derived from a sanitized slug.
  *
  * @param {string} featureName
@@ -247,98 +246,12 @@ function detectScope(researchContent) {
 	};
 }
 
-/**
- * Create Beads issue for the feature
- * Executes `bd create` command with appropriate description based on scope
- *
- * Security: Uses execFileSync (not exec) to prevent command injection
- *
- * @param {string} featureName - Feature name (human-readable)
- * @param {string} researchPath - Research document path (e.g., "docs/research/feature.md")
- * @param {'tactical'|'strategic'} scope - Scope type
- * @returns {{success: boolean, issueId?: string, description?: string, error?: string}} Beads creation result
- * @example
- * const result = createBeadsIssue('Payment Integration', 'docs/research/payment.md', 'strategic');
- * if (result.success) {
- *   console.log('Created issue:', result.issueId);
- * }
- */
-function createBeadsIssue(featureName, researchPath, scope) {
-	if (!featureName || !researchPath) {
-		return {
-			success: false,
-			error: 'Feature name and research path are required',
-		};
-	}
-
-	if (scope !== 'tactical' && scope !== 'strategic') {
-		return {
-			success: false,
-			error: `Invalid scope '${scope}'. Must be 'tactical' or 'strategic'`,
-		};
-	}
-
-	try {
-		const built = buildFeatureIssueDescription(featureName, researchPath, scope);
-		if (built.error) {
-			return { success: false, error: built.error };
-		}
-		const description = built.description;
-
-		// Execute bd create command using execFileSync for safety (OWASP A03)
-		const result = execFileSync(  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
-			'bd',  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
-			['create', `--title=${featureName}`, `--description=${description}`, '--type=feature', '--priority=2'],
-			getExecOptions()
-		);
-
-		// Extract issue ID from output (format: "Created issue: forge-xxx" or "forge-xxx.N" for dotted sub-IDs).
-		// Character class is [a-z0-9] (not [a-zA-Z0-9]) because the /i flag makes A-Z redundant.
-		const createPattern = /Created issue:\s*(forge-[a-z0-9]+(?:\.[a-z0-9]+)*)/i;
-		const fallbackPattern = /(forge-[a-z0-9]+(?:\.[a-z0-9]+)*)/i;
-		const match = createPattern.exec(result) || fallbackPattern.exec(result);
-
-		if (!match) {
-			return {
-				success: false,
-				error: 'Failed to extract issue ID from bd create output\n\nEnsure beads is installed: bunx beads init',
-			};
-		}
-
-		return {
-			success: true,
-			issueId: match[1],
-			description,
-		};
-	} catch (error) {
-		// Check for timeout
-		if (error.killed && error.signal === 'SIGTERM') {
-			return {
-				success: false,
-				error: 'Beads command timed out after 2 minutes.',
-			};
-		}
-
-		// Provide actionable error message
-		const bdNotFound = error.message.includes('ENOENT') || error.message.includes('not found');
-		const errorMsg = bdNotFound
-			? 'beads (bd) command not found. Install with: bunx beads init'
-			: `Failed to create Beads issue: ${error.message}`;
-
-		return {
-			success: false,
-			error: errorMsg,
-		};
-	}
-}
-
 /**
  * Create an issue via the Forge Kernel backend (bd-free).
  *
  * Mirrors `forge issue create` on the kernel: routes through runIssueOperation with
  * the kernel broker instead of shelling out to `bd create`. Used by `forge plan` when
- * the resolved issue backend is the kernel (the default), so planning needs no Beads
- * install. The beads path (createBeadsIssue) is preserved for backend=beads.
+ * the kernel is the only issue backend, so planning needs no bd binary installed.
  *
  * @param {string} featureName
  * @param {string} researchPath
@@ -413,7 +326,7 @@ async function linkExistingIssue(issueId, options = {}) {
 			projectRoot,
 			{
 				issueBackend,
-				useKernelBroker: issueBackend !== 'beads',
+				useKernelBroker: true,
 				kernelBroker: options.kernelBroker,
 			},
 		);
@@ -517,7 +430,12 @@ function currentBranchIssueFromDriver(driver, currentBranch) {
 	if (driver && typeof driver.listWorktrees === 'function') {
 		try {
 			const rows = driver.listWorktrees() || [];
-			const match = rows.find(row => row && row.branch === currentBranch && row.issue_id);
+			// Only an ACTIVE (live) linkage row binds the branch: a superseded/stale
+			// registration for a reused branch name must not trigger a false split-state
+			// conflict against the OLD issue (R4/be18881c). Tolerate a null state for
+			// rows written before the state column was populated.
+			const match = rows.find(row => row && row.branch === currentBranch && row.issue_id
+				&& (row.state === 'active' || row.state == null));
 			if (match) return match.issue_id;
 		} catch {
 			// fall through to branch-name parsing
@@ -553,6 +471,9 @@ async function detectBranchIssueConflict(options, explicitIssueId) {
 async function registerBranchIssueLinkage(options, branch, issueId) {
 	if (!branch || !issueId) return;
 	const cwd = options.projectRoot || process.cwd();
+	// F6 defaultStageWarn pattern: write to stderr so a dropped linkage never
+	// pollutes machine-readable stdout, yet leaves a trace even under FORGE_JSON=1.
+	const warn = options.warn || (message => process.stderr.write(`${message}\n`));
 	await withPlanDriver(options, driver => {
 		if (!driver || typeof driver.registerWorktree !== 'function') return;
 		try {
@@ -566,16 +487,19 @@ async function registerBranchIssueLinkage(options, branch, issueId) {
 				registered_at: new Date().toISOString(),
 				state: 'active',
 			});
-		} catch {
-			// best-effort: linkage failure must not fail plan
+		} catch (error) {
+			// Best-effort: linkage failure must not fail plan, but it must NOT be
+			// silent (R3) — otherwise ship later fail-closes with no signal at plan
+			// time about the dropped branch->issue linkage.
+			warn(`[forge] could not register branch->issue linkage for ${branch} -> ${issueId}: ${error.message}`);
 		}
 	});
 }
 
 /**
- * Resolve the tracking issue for a plan: LINK an explicit issue, else CREATE via
- * the active backend (the kernel default needs no Beads). Extracted to avoid a
- * nested ternary in executePlan.
+ * Resolve the tracking issue for a plan: LINK an explicit issue, else CREATE in
+ * the kernel (the only issue backend — planning needs no bd binary). Extracted to
+ * avoid a nested ternary in executePlan.
  *
  * @returns {Promise<{success: boolean, issueId?: string, error?: string}>}
  * @private
@@ -584,10 +508,7 @@ async function resolveTrackingIssue({ explicitIssueId, issueBackend, featureName
 	if (explicitIssueId) {
 		return linkExistingIssue(explicitIssueId, { ...options, issueBackend });
 	}
-	if (issueBackend === 'kernel') {
-		return createKernelIssue(featureName, researchPath, scope, options);
-	}
-	return createBeadsIssue(featureName, researchPath, scope);
+	return createKernelIssue(featureName, researchPath, scope, options);
 }
 
 async function createKernelIssue(featureName, researchPath, scope, options = {}) {
@@ -648,7 +569,10 @@ async function createKernelIssue(featureName, researchPath, scope, options = {})
 
 /**
  * Create feature branch
- * Creates and checks out a new git branch following feat/<slug> convention
+ * Creates a new git branch following feat/<slug> convention WITHOUT switching
+ * the shared checkout's HEAD (uses `git branch`, not `git checkout -b`).
+ * Switching HEAD in the shared working tree corrupts concurrent agents
+ * (kernel issue aa14966c); isolated work happens in a dedicated worktree.
  *
  * Security: Uses execFileSync with array args to prevent command injection
  *
@@ -678,14 +602,19 @@ function createFeatureBranch(featureSlug) {
 			execFileSync('git', ['rev-parse', '--verify', branchName], { ...getExecOptions(), stdio: 'pipe' });  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
 			return {
 				success: false,
-				error: `Branch ${branchName} already exists\n\nSwitch to it with: git checkout ${branchName}`,
+				error: `Branch ${branchName} already exists\n\nWork on it in an isolated checkout: forge worktree create ${featureSlug}\n(or, working solo: git switch ${branchName})`,
 			};
 		} catch {
 			// Branch doesn't exist, continue (expected case)
 		}
 
-		// Create and checkout branch
-		execFileSync('git', ['checkout', '-b', branchName], getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		// Create the branch WITHOUT switching the shared checkout's HEAD.
+		// Historically this used `git checkout -b`, which flipped the shared
+		// working tree onto the new branch and corrupted concurrent agents
+		// (kernel issue aa14966c). `git branch` creates the ref at the current
+		// HEAD without touching the working tree; isolated work happens in a
+		// dedicated worktree (`forge worktree create`), never the shared tree.
+		execFileSync('git', ['branch', branchName], getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
 
 		return {
 			success: true,
@@ -933,14 +862,14 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  * Tactical workflow (quick fixes, <1 day):
  * 1. Read research document
  * 2. Detect scope (tactical)
- * 3. Create Beads issue
+ * 3. Create kernel issue
  * 4. Create feature branch
  * → Next: /dev command
  *
  * Strategic workflow (architecture changes, >1 day):
  * 1. Read research document
  * 2. Detect scope (strategic)
- * 3. Create Beads issue with design doc link
+ * 3. Create kernel issue with design doc link
  * 4. Create feature branch
  * → Next: Create design doc, then /dev command
  *
@@ -948,7 +877,7 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  * @returns {Promise<{
  *   success: boolean,
  *   scope?: 'tactical'|'strategic',
- *   issueBackend?: 'kernel'|'beads',
+ *   issueBackend?: 'kernel',
  *   issueId?: string,
  *   beadsIssueId?: string,
  *   branchName?: string,
@@ -956,10 +885,10 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  *   summary?: string,
  *   nextCommand?: string,
  *   error?: string
- * }>} Execution result. `issueId` is the created issue id under the active
- *   backend; `issueBackend` names that backend. `beadsIssueId` is a deprecated
- *   alias of `issueId` kept for backward compatibility (it does NOT imply the
- *   issue came from Beads — on the kernel path it holds the kernel issue id).
+ * }>} Execution result. `issueId` is the created kernel issue id, and
+ *   `issueBackend` names the backend ('kernel'). `beadsIssueId` is a deprecated
+ *   alias of `issueId` kept for output-shape compatibility — it never implied a
+ *   Beads store and now always holds the kernel issue id.
  * @example
  * const result = await executePlan('Payment Integration');
  * if (result.success) {
@@ -976,7 +905,7 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 	}
 
 	// Resolve the active issue backend (explicit opts > env > .forge/config.yaml >
-	// default 'kernel'). Kernel is bd-free, so planning works with no Beads install.
+	// default 'kernel'). The kernel is bd-free, so planning needs no bd binary.
 	const issueBackend = resolveIssueBackend({
 		deps: options,
 		env: options.env || process.env,
@@ -1012,8 +941,7 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 
 		// Step 3: Resolve the tracking issue. `--issue <id>` LINKS an existing issue
 		// (claim-first flow) instead of creating a duplicate (B4). Otherwise create
-		// via the active backend — kernel (default) routes through the kernel broker
-		// (no bd); beads preserves the bd path.
+		// through the kernel broker (no bd binary involved).
 		const explicitIssueId = options.issue || options.issueId || null;
 
 		// F4c: never link issue B onto a branch already bound to issue A.
@@ -1061,11 +989,17 @@ async function executePlan(featureName, options = {}) { // NOSONAR S3776
 			scope: scope.type,
 			issueBackend,
 			issueId: issue.issueId,
-			// Deprecated alias of issueId, retained for backward compatibility. It does
-			// NOT imply the Beads backend — on the kernel path it holds the kernel id.
+			// Deprecated alias of issueId, retained for output-shape compatibility.
+			// It never implied a Beads store and now always holds the kernel id.
 			beadsIssueId: issue.issueId,
 			branchName: branch.branchName,
 			linked: Boolean(explicitIssueId),
+			// A FRESH branch was created (HEAD did NOT move — aa14966c). Stage
+			// commands resolve the CHECKED-OUT branch, so the user must enter an
+			// isolated checkout on this branch before /dev, or stage state resolves
+			// against the default branch (no linkage → ship dead-ends). When the
+			// branch was reused, HEAD is already on it and /dev works directly.
+			branchCreated: !branch.reused,
 			summary: explicitIssueId
 				? `Plan linked to existing issue ${issue.issueId} (${scope.type} scope)`
 				: `Plan created for ${featureName} (${scope.type} scope)`,
@@ -1104,7 +1038,20 @@ module.exports = {
 		const lines = [`${header}: ${result.summary || result.branchName || featureName}`];
 		if (result.issueId) lines.push(`${issueBackendLabel(result.issueBackend)}: ${result.issueId}`);
 		if (result.branchName) lines.push(`Branch: ${result.branchName}`);
-		if (result.nextCommand) lines.push(`Next: ${result.nextCommand}`);
+		if (result.branchCreated) {
+			// A fresh branch was created but HEAD was NOT switched (aa14966c). Stage
+			// commands (/dev, /validate, /ship) resolve the CHECKED-OUT branch — from
+			// the shared tree that is still the default branch, which has no
+			// branch->issue linkage, so ship would dead-end. Direct the user into an
+			// isolated checkout on the new branch first.
+			const slug = String(result.branchName).replace(/^feat\//, '');
+			lines.push('Next: work on this branch in an isolated checkout (HEAD stays put in the shared tree):');
+			lines.push(`  forge worktree create ${slug}    # concurrent-safe; checks out the existing ${result.branchName}`);
+			lines.push(`  # or, working solo:  git switch ${result.branchName}`);
+			lines.push(`Then run ${result.nextCommand || '/dev'} from that checkout.`);
+		} else if (result.nextCommand) {
+			lines.push(`Next: ${result.nextCommand}`);
+		}
 
 		return {
 			...result,
@@ -1113,7 +1060,6 @@ module.exports = {
 	},
 	readResearchDoc,
 	detectScope,
-	createBeadsIssue,
 	createKernelIssue,
 	createFeatureBranch,
 	extractDesignDecisions,
@@ -1122,4 +1068,6 @@ module.exports = {
 	applyYAGNIFilter,
 	executePlan,
 	issueBackendLabel,
+	registerBranchIssueLinkage,
+	currentBranchIssueFromDriver,
 };

package/lib/commands/pr.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const ship = require('./ship');
+const preflight = require('./preflight');
+const shepherd = require('./shepherd');
+const merge = require('./merge');
+const { stripGlobalFlags } = require('../global-flags');
+
+// One memorable surface over the EXISTING pull-request commands (kernel issue
+// 6ab3f30c): every subcommand delegates to the standalone ship/preflight/shepherd/
+// merge handlers — the same code, not a reimplementation. The standalone
+// `forge ship`/`preflight`/`shepherd`/`merge` commands remain registered as
+// back-compat aliases (see lib/commands/_aliases.js), so nothing that already
+// calls them breaks. `pr ship` is the canonical PR-creation form; bare `ship`
+// stays a visible shortcut.
+//
+// Delegates are referenced by MODULE (not a pre-bound `.handler`) so the routed
+// handler is resolved at dispatch time — dispatch always reaches whatever the
+// command module currently exports, keeping the standalone command the single
+// source of truth for its own behaviour.
+const SUBCOMMANDS = {
+  ship: {
+    module: ship,
+    summary: 'Create a pull request from validated feature work (= forge ship)',
+  },
+  preflight: {
+    module: preflight,
+    summary: 'Fast deterministic-gate parity with CI (= forge preflight; supports --all)',
+  },
+  shepherd: {
+    module: shepherd,
+    summary: 'Run one bounded monitor pass over a PR (= forge shepherd; --bundle/--pull/--json, events, watch)',
+  },
+  merge: {
+    module: merge,
+    summary: 'Opt-in conditional auto-merge, OFF by default (= forge merge --auto <pr>)',
+  },
+};
+
+const usage = 'Usage: forge pr <ship|preflight|shepherd|merge> [args]';
+
+function renderHelp() {
+  const width = Math.max(...Object.keys(SUBCOMMANDS).map(name => name.length));
+  const lines = [
+    usage,
+    '',
+    'Subcommands:',
+    ...Object.entries(SUBCOMMANDS).map(
+      ([name, { summary }]) => `  ${name.padEnd(width)}  ${summary}`
+    ),
+    '',
+    'Back-compat: forge ship / forge preflight / forge shepherd / forge merge remain available as aliases.',
+  ];
+  return lines.join('\n');
+}
+
+async function handler(args, flags, projectRoot, opts) {
+  // The subcommand is the first positional token; global flags (e.g. `-p <dir>`) are stripped
+  // first so they never masquerade as the subcommand.
+  const positional = stripGlobalFlags(args).find(arg => !arg.startsWith('-'));
+
+  if (!positional || positional === 'help' || args.includes('--help') || args.includes('-h')) {
+    return { success: true, output: renderHelp() };
+  }
+
+  const sub = SUBCOMMANDS[positional];
+  if (!sub) {
+    return {
+      success: false,
+      error: `Unknown pr subcommand: ${positional}\n\n${renderHelp()}`,
+    };
+  }
+
+  // Forward everything EXCEPT the consumed subcommand token to the delegate, preserving
+  // every remaining token (including flags like `--pull`/`--json`/`--bundle`, and the
+  // `events`/`watch` shepherd sub-shapes) so passthrough stays byte-identical.
+  const idx = args.indexOf(positional);
+  const childArgs = idx >= 0 ? [...args.slice(0, idx), ...args.slice(idx + 1)] : args;
+  return sub.module.handler(childArgs, flags, projectRoot, opts);
+}
+
+module.exports = {
+  name: 'pr',
+  description:
+    'Unified pull-request surface: forge pr ship|preflight|shepherd|merge (wraps ship/preflight/shepherd/merge)',
+  usage,
+  handler,
+};

package/lib/commands/prime.js

@@ -2,6 +2,7 @@
 
 const {
   buildPrime,
+  collectPrimeLiveState,
   runOrientationCommand,
 } = require('../orientation');
 
@@ -9,5 +10,11 @@ module.exports = {
   name: 'prime',
   description: 'Emit session-entry bounded orientation for agents',
   usage: 'Usage: forge prime [--budget N] [--json]',
-  handler: (args, _flags, projectRoot) => runOrientationCommand(buildPrime, args, projectRoot),
+  // Async: prime leads with LIVE state (stage / claims / ready / gates / one adoption nudge),
+  // which needs a best-effort (non-throwing) kernel read before the synchronous build assembles
+  // it into the bounded orientation. All existing prime output/flags are unchanged.
+  handler: async (args, _flags, projectRoot) => {
+    const liveState = await collectPrimeLiveState(projectRoot);
+    return runOrientationCommand(buildPrime, args, projectRoot, { liveState });
+  },
 };

package/lib/commands/push.js

@@ -4,6 +4,8 @@ const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const forgeToken = require('../../scripts/check-forge-token');
+const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
+const { autoShepherdRailEnabled } = require('./ship');
 
 const isWindows = process.platform === 'win32';
 
@@ -110,6 +112,57 @@ async function autoFileBackingIssueForPush(projectRoot, execFn, deps = {}) {
   }
 }
 
+/**
+ * Resolve the OPEN PR number for the current branch via `gh pr view`. Returns
+ * null when there is no PR, gh is unavailable, or anything errors (fail-open).
+ * NEVER throws.
+ *
+ * @param {function} execFn - execFileSync or mock
+ * @returns {number|null}
+ */
+function resolveOpenPrNumber(execFn) {
+	try {
+		const out = execFn('gh', ['pr', 'view', '--json', 'number', '-q', '.number'], {
+			encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'],
+		});
+		const n = Number.parseInt(String(out).trim(), 10);
+		return Number.isInteger(n) && n > 0 ? n : null;
+	} catch (_err) { /* intentional: no open PR / gh missing → arm nothing */ // NOSONAR S2486
+		return null;
+	}
+}
+
+/**
+ * Best-effort, NON-BLOCKING arm of the constant PR watcher after a successful
+ * push, when an OPEN PR exists for the current branch. This closes the gap where
+ * PRs not born from `forge ship` (gh pr create, the GitHub UI, an earlier push)
+ * never got a watcher. Gated by the default-ON `rail.auto_shepherd`, idempotent
+ * via the watch loop's own PID/journal lock, and reusing the same
+ * `startPrWatcherDetached` as ship. MUST NEVER throw into or fail the push: a
+ * disabled rail, no PR, a gh error, or a spawn error all degrade to
+ * `{ armed: false }`.
+ *
+ * @param {object} params
+ * @returns {{ armed: boolean, reason?: string, prNumber?: number }}
+ */
+function maybeArmWatcherAfterPush({
+	projectRoot,
+	execFn,
+	startWatcher = startPrWatcherDetached,
+	railEnabled = autoShepherdRailEnabled,
+	prLookup = resolveOpenPrNumber,
+}) {
+	try {
+		if (!railEnabled(projectRoot)) return { armed: false, reason: 'rail.auto_shepherd disabled' };
+		const prNumber = prLookup(execFn);
+		if (!prNumber) return { armed: false, reason: 'no-open-pr' };
+		const res = startWatcher({ prNumber, cwd: projectRoot });
+		return { armed: !!(res && res.started), reason: res && res.reason, prNumber };
+	} catch (err) {
+		return { armed: false, reason: err.message };
+	}
+}
+
 /**
  * Run branch protection check as a subprocess.
  * @param {function} execFn - execFileSync or mock
@@ -247,6 +300,17 @@ module.exports = {
 			};
 		}
 
+		// Arm the constant PR watcher for this branch's open PR (best-effort,
+		// gated by rail.auto_shepherd, never fails the push). Covers PRs not born
+		// from `forge ship`.
+		maybeArmWatcherAfterPush({
+			projectRoot,
+			execFn,
+			startWatcher: deps?.startWatcher,
+			railEnabled: deps?.railEnabled,
+			prLookup: deps?.prLookup,
+		});
+
 		return {
 			success: true,
 			quickMode,
@@ -259,5 +323,7 @@ module.exports = {
 	// Exposed for unit tests; not part of the CLI surface.
 	_internal: {
 		autoFileBackingIssueForPush,
+		maybeArmWatcherAfterPush,
+		resolveOpenPrNumber,
 	},
 };