forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/commands/plan.js

@@ -11,6 +11,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const { resolveIssueBackend } = require('../issue-backend');
+const { runIssueOperation } = require('../forge-issues');
 
 // Constants for security
 // Note: cwd is resolved at call-time via getExecOptions() to avoid stale require-time snapshots
@@ -22,6 +24,21 @@ function getExecOptions() {
 const MAX_SLUG_LENGTH = 100;
 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".
+ *
+ * @param {string} [backend] - Resolved issue backend ('kernel' | 'beads').
+ * @returns {string} Display label ('Kernel', 'Beads', or a neutral 'Issue').
+ * @private
+ */
+function issueBackendLabel(backend) {
+	if (backend === 'beads') return 'Beads';
+	if (backend === 'kernel') return 'Kernel';
+	return 'Issue';
+}
+
 /**
  * Validate feature slug format
  * Ensures slug matches expected pattern and doesn't contain path traversal
@@ -58,6 +75,33 @@ function validateFeatureSlug(slug) {
 	return { valid: true };
 }
 
+/**
+ * Build the issue description shared by both issue backends (kernel and beads).
+ * Strategic scope appends a design-doc pointer derived from a sanitized slug.
+ *
+ * @param {string} featureName
+ * @param {string} researchPath
+ * @param {'tactical'|'strategic'} scope
+ * @returns {{description: string}|{error: string}}
+ * @private
+ */
+function buildFeatureIssueDescription(featureName, researchPath, scope) {
+	let description = `Research: ${researchPath}`;
+
+	if (scope === 'strategic') {
+		// Sanitize derived slug: keep only safe characters (OWASP A03)
+		const featureSlug = featureName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/(?:^-+|-+$)/g, '').slice(0, MAX_SLUG_LENGTH);  // NOSONAR S5852 - non-overlapping anchors, no backtracking
+		const slugValidation = validateFeatureSlug(featureSlug);
+		if (!slugValidation.valid) {
+			return { error: `Cannot generate valid slug from feature name: ${slugValidation.error}` };
+		}
+		const dateSlug = new Date().toISOString().slice(0, 10);
+		description += `\n\nDesign: docs/work/${dateSlug}-${featureSlug}/plan.md`;
+	}
+
+	return { description };
+}
+
 /**
  * Read research document from file
  *
@@ -235,17 +279,11 @@ function createBeadsIssue(featureName, researchPath, scope) {
 	}
 
 	try {
-		let description = `Research: ${researchPath}`;
-
-		if (scope === 'strategic') {
-			// Sanitize derived slug: keep only safe characters (OWASP A03)
-			const featureSlug = featureName.toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/(?:^-+|-+$)/g, '').slice(0, MAX_SLUG_LENGTH);  // NOSONAR S5852 - non-overlapping anchors, no backtracking
-			const slugValidation = validateFeatureSlug(featureSlug);
-			if (!slugValidation.valid) {
-				return { success: false, error: `Cannot generate valid slug from feature name: ${slugValidation.error}` };
-			}
-			description += `\n\nDesign: docs/plans/${featureSlug}-design.md`;
+		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
@@ -294,9 +332,337 @@ function createBeadsIssue(featureName, researchPath, scope) {
 	}
 }
 
+/**
+ * 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.
+ *
+ * @param {string} featureName
+ * @param {string} researchPath
+ * @param {'tactical'|'strategic'} scope
+ * @param {object} [options]
+ * @param {string} [options.projectRoot] - Repo root for the kernel store (defaults to cwd)
+ * @param {object} [options.kernelBroker] - Pre-built kernel broker (optional)
+ * @param {Function} [options.runIssueOperation] - Injectable runner (tests)
+ * @returns {Promise<{success: boolean, issueId?: string, description?: string, error?: string}>}
+ */
+const PLAN_ISSUE_UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+
+/**
+ * Parse plan's own args: extract a `--issue <id>` / `--issue=<id>` selector and
+ * return the remaining positional feature name. The global flag parser only
+ * recognizes an allowlist, so — like `stage`/`worktree` — plan extracts its own.
+ *
+ * @param {string[]} args
+ * @returns {{ featureName: string|undefined, issueId: string|null }}
+ * @private
+ */
+function parsePlanArgs(args = []) {
+	let issueId = null;
+	let issueFlagSeen = false;
+	const positional = [];
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === '--issue') {
+			issueFlagSeen = true;
+			const next = i + 1 < args.length ? args[i + 1] : null;
+			// A following flag (or nothing) is NOT a value — treat as a missing value
+			// (F5) so we never silently fall back to CREATE a duplicate issue.
+			if (typeof next === 'string' && !next.startsWith('-')) {
+				issueId = next;
+				i += 1;
+			}
+			continue;
+		}
+		if (typeof arg === 'string' && arg.startsWith('--issue=')) {
+			issueFlagSeen = true;
+			issueId = arg.slice('--issue='.length) || null;
+			continue;
+		}
+		positional.push(arg);
+	}
+	return { featureName: positional[0], issueId, issueFlagError: issueFlagSeen && !issueId };
+}
+
+/**
+ * Link an EXISTING issue instead of creating a new one (B4). Verifies the issue
+ * exists via `issue show` so `plan --issue <id>` links the claim-first flow's
+ * issue rather than forking a duplicate.
+ *
+ * @param {string} issueId
+ * @param {object} [options]
+ * @returns {Promise<{success: boolean, issueId?: string, error?: string}>}
+ * @private
+ */
+async function linkExistingIssue(issueId, options = {}) {
+	if (!issueId || typeof issueId !== 'string') {
+		return { success: false, error: 'An issue id is required to link an existing issue' };
+	}
+
+	const run = options.runIssueOperation || runIssueOperation;
+	const projectRoot = options.projectRoot || process.cwd();
+	const issueBackend = options.issueBackend || 'kernel';
+
+	try {
+		const result = await run(
+			'show',
+			[issueId],
+			projectRoot,
+			{
+				issueBackend,
+				useKernelBroker: issueBackend !== 'beads',
+				kernelBroker: options.kernelBroker,
+			},
+		);
+
+		if (!result || result.ok === false || result.success === false) {
+			const message = result?.error || 'issue not found';
+			return { success: false, error: `Issue ${issueId} not found: ${message}` };
+		}
+
+		const resolvedId = result?.data?.id ?? result?.issueId ?? result?.id ?? issueId;
+		return { success: true, issueId: resolvedId };
+	} catch (error) {
+		return { success: false, error: `Failed to look up issue ${issueId}: ${error.message}` };
+	}
+}
+
+/**
+ * Read the current git branch (empty string when detached / not a repo).
+ * @private
+ */
+function getCurrentBranch() {
+	try {
+		return execFileSync('git', ['branch', '--show-current'], { ...getExecOptions(), stdio: 'pipe' }).trim();  // NOSONAR S4036 - hardcoded CLI command, developer tool context
+	} catch {
+		return '';
+	}
+}
+
+function isDefaultBranch(name) {
+	return name === '' || name === 'main' || name === 'master';
+}
+
+/**
+ * When linking an existing issue, reuse the current feature branch instead of
+ * forking a second branch (B4). Only creates a fresh `feat/<slug>` branch when
+ * still sitting on a default branch.
+ *
+ * @param {string} featureSlug
+ * @returns {{success: boolean, branchName?: string, reused?: boolean, error?: string}}
+ * @private
+ */
+function reuseOrCreateFeatureBranch(featureSlug) {
+	const current = getCurrentBranch();
+	if (!isDefaultBranch(current)) {
+		return { success: true, branchName: current, reused: true };
+	}
+	return createFeatureBranch(featureSlug);
+}
+
+/** Read `git rev-parse --git-common-dir` (null on failure). @private */
+function getGitCommonDir(cwd) {
+	try {
+		return execFileSync('git', ['rev-parse', '--git-common-dir'], { ...getExecOptions(), cwd, stdio: 'pipe' }).trim();  // NOSONAR S4036 - hardcoded CLI command, developer tool context
+	} catch {
+		return null;
+	}
+}
+
+/** An already-resolved kernel driver (tests / commandOpts), or null. @private */
+function injectedPlanDriver(options = {}) {
+	return options.kernelDriver || options.driver || null;
+}
+
+/**
+ * Run `fn(driver)` with a kernel driver: an injected one (tests / commandOpts)
+ * when present, otherwise a throwaway migrated driver built from the project
+ * root and CLOSED afterwards, so it never leaves an open DB handle (which would
+ * lock the dir on Windows). `plan` is NOT an issue command, so
+ * `resolveCommandOpts` gives it no driver — building here is what lets the
+ * branch->issue registry be consulted in the real CLI (both the F4c conflict
+ * read and the F1 linkage write). `fn(null)` when the kernel is unavailable.
+ * @private
+ */
+async function withPlanDriver(options, fn) {
+	const injected = injectedPlanDriver(options);
+	if (injected) {
+		return fn(injected);
+	}
+
+	let driver;
+	try {
+		const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+		const deps = await buildMigratedKernelIssueDeps({ projectRoot: options.projectRoot || process.cwd() });
+		driver = deps.kernelDriver || null;
+	} catch {
+		return fn(null);
+	}
+	try {
+		return fn(driver);
+	} finally {
+		if (driver && typeof driver.close === 'function') driver.close();
+	}
+}
+
+/**
+ * Which issue the CURRENT branch is already bound to: the kernel worktree
+ * registry (authoritative) first, then a UUID encoded in the branch name.
+ * @private
+ */
+function currentBranchIssueFromDriver(driver, currentBranch) {
+	if (driver && typeof driver.listWorktrees === 'function') {
+		try {
+			const rows = driver.listWorktrees() || [];
+			// 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
+		}
+	}
+	const encoded = PLAN_ISSUE_UUID_RE.exec(currentBranch || '');
+	return encoded ? encoded[0] : null;
+}
+
+/**
+ * Refuse to link issue B onto a branch already bound to issue A (F4c): otherwise
+ * plan would link B while stage read/writes flow to A (split state). Consults the
+ * kernel worktree registry (via a built driver when the CLI supplies none) so a
+ * plan-created slug branch — whose name lacks a UUID — is still caught.
+ * @returns {Promise<string|null>} an error message when there is a conflict.
+ * @private
+ */
+async function detectBranchIssueConflict(options, explicitIssueId) {
+	const current = getCurrentBranch();
+	if (isDefaultBranch(current)) return null;
+	const boundIssue = await withPlanDriver(options, driver => currentBranchIssueFromDriver(driver, current));
+	if (boundIssue && boundIssue !== explicitIssueId) {
+		return `Current branch ${current} is already bound to issue ${boundIssue}; refusing to link ${explicitIssueId} (split state). Switch branches or link the matching issue.`;
+	}
+	return null;
+}
+
+/**
+ * Persist the branch->issue linkage into the kernel worktree registry (F1) so a
+ * plan-created branch resolves to its issue for kernel-authoritative stage
+ * state. Best-effort, kernel-only. @private
+ */
+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 {
+			driver.registerWorktree({
+				git_common_dir: getGitCommonDir(cwd) || cwd,
+				path: cwd,
+				branch,
+				actor: null,
+				issue_id: issueId,
+				work_folder: null,
+				registered_at: new Date().toISOString(),
+				state: 'active',
+			});
+		} 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.
+ *
+ * @returns {Promise<{success: boolean, issueId?: string, error?: string}>}
+ * @private
+ */
+async function resolveTrackingIssue({ explicitIssueId, issueBackend, featureName, researchPath, scope, options }) {
+	if (explicitIssueId) {
+		return linkExistingIssue(explicitIssueId, { ...options, issueBackend });
+	}
+	if (issueBackend === 'kernel') {
+		return createKernelIssue(featureName, researchPath, scope, options);
+	}
+	return createBeadsIssue(featureName, researchPath, scope);
+}
+
+async function createKernelIssue(featureName, researchPath, scope, options = {}) {
+	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'`,
+		};
+	}
+
+	const built = buildFeatureIssueDescription(featureName, researchPath, scope);
+	if (built.error) {
+		return { success: false, error: built.error };
+	}
+	const description = built.description;
+
+	const run = options.runIssueOperation || runIssueOperation;
+	const projectRoot = options.projectRoot || process.cwd();
+
+	try {
+		const result = await run(
+			'create',
+			[`--title=${featureName}`, `--description=${description}`, '--type=feature', '--priority=2'],
+			projectRoot,
+			{ issueBackend: 'kernel', useKernelBroker: true, kernelBroker: options.kernelBroker },
+		);
+
+		// The kernel returns the issue-command contract ({ ok, data: { id } }); a failure
+		// is { ok:false, error }. Guard both the contract shape and any { success:false }.
+		if (!result || result.ok === false || result.success === false) {
+			const message = result?.error || 'Kernel issue creation failed';
+			return { success: false, error: `Failed to create kernel issue: ${message}` };
+		}
+
+		const issueId = result?.data?.id ?? result?.issueId ?? result?.id;
+		if (!issueId) {
+			return {
+				success: false,
+				error: 'Failed to extract issue ID from kernel create result',
+			};
+		}
+
+		return { success: true, issueId, description };
+	} catch (error) {
+		return {
+			success: false,
+			error: `Failed to create kernel issue: ${error.message}`,
+		};
+	}
+}
+
 /**
  * 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
  *
@@ -326,14 +692,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,
@@ -596,13 +967,18 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  * @returns {Promise<{
  *   success: boolean,
  *   scope?: 'tactical'|'strategic',
+ *   issueBackend?: 'kernel'|'beads',
+ *   issueId?: string,
  *   beadsIssueId?: string,
  *   branchName?: string,
  *
  *   summary?: string,
  *   nextCommand?: string,
  *   error?: string
- * }>} Execution result
+ * }>} 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).
  * @example
  * const result = await executePlan('Payment Integration');
  * if (result.success) {
@@ -610,7 +986,7 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  *   console.log('Next:', result.nextCommand);
  * }
  */
-async function executePlan(featureName) { // NOSONAR S3776
+async function executePlan(featureName, options = {}) { // NOSONAR S3776
 	if (!featureName || typeof featureName !== 'string') {
 		return {
 			success: false,
@@ -618,6 +994,15 @@ async function executePlan(featureName) { // 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.
+	const issueBackend = resolveIssueBackend({
+		deps: options,
+		env: options.env || process.env,
+		projectRoot: options.projectRoot,
+		warn: () => {},
+	});
+
 	const featureSlug = featureName.toLowerCase()
 		.replaceAll(/[^a-z0-9-]/g, '-')
 		.split('-').filter(Boolean).join('-');
@@ -644,17 +1029,37 @@ async function executePlan(featureName) { // NOSONAR S3776
 		// Step 2: Detect scope (tactical vs strategic)
 		const scope = detectScope(research.content);
 
-		// Step 3: Create Beads issue
-		const beads = createBeadsIssue(featureName, research.path, scope.type);
-		if (!beads.success) {
+		// 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.
+		const explicitIssueId = options.issue || options.issueId || null;
+
+		// F4c: never link issue B onto a branch already bound to issue A.
+		if (explicitIssueId) {
+			const conflict = await detectBranchIssueConflict({ ...options, issueBackend }, explicitIssueId);
+			if (conflict) {
+				return { success: false, error: conflict };
+			}
+		}
+
+		const issue = await resolveTrackingIssue({
+			explicitIssueId, issueBackend, featureName, researchPath: research.path, scope: scope.type, options,
+		});
+		if (!issue.success) {
 			return {
 				success: false,
-				error: `Failed to create Beads issue: ${beads.error}`,
+				error: explicitIssueId
+					? `Failed to link issue: ${issue.error}`
+					: `Failed to create issue: ${issue.error}`,
 			};
 		}
 
-		// Step 4: Create feature branch
-		const branch = createFeatureBranch(featureSlug);
+		// Step 4: Resolve the feature branch. When linking, reuse the current
+		// feature branch instead of forking a second branch (B4).
+		const branch = explicitIssueId
+			? reuseOrCreateFeatureBranch(featureSlug)
+			: createFeatureBranch(featureSlug);
 		if (!branch.success) {
 			return {
 				success: false,
@@ -662,13 +1067,33 @@ async function executePlan(featureName) { // NOSONAR S3776
 			};
 		}
 
+		// F1: persist the branch->issue linkage so a plan-created branch resolves
+		// to its issue for kernel-authoritative stage state (dev/validate/ship).
+		// Kernel-only, best-effort.
+		if (issueBackend === 'kernel') {
+			await registerBranchIssueLinkage({ ...options, issueBackend }, branch.branchName, issue.issueId);
+		}
+
 		// Build result summary
 		const result = {
 			success: true,
 			scope: scope.type,
-			beadsIssueId: beads.issueId,
+			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.
+			beadsIssueId: issue.issueId,
 			branchName: branch.branchName,
-			summary: `Plan created for ${featureName} (${scope.type} scope)`,
+			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)`,
 			// Strategic path: /propose not yet implemented — falls through to /dev until it is
 			nextCommand: '/dev',
 		};
@@ -685,16 +1110,39 @@ async function executePlan(featureName) { // NOSONAR S3776
 module.exports = {
 	name: 'plan',
 	description: 'Create implementation plan from researched feature context',
-	handler: async (args) => {
-		const result = await executePlan(args[0]);
+	handler: async (args, _flags, projectRoot, opts = {}) => {
+		const { featureName, issueId, issueFlagError } = parsePlanArgs(args);
+			// F5: `--issue` with no value must ERROR, never silently create a duplicate.
+			if (issueFlagError) {
+				return { success: false, error: '--issue requires a value (an existing issue id to link).' };
+			}
+		const result = await executePlan(featureName, {
+			...opts,
+			projectRoot,
+			issue: issueId ?? opts.issue ?? opts.issueId,
+		});
 		if (!result.success) {
 			return result;
 		}
 
-		const lines = [`Plan created: ${result.summary || result.branchName || args[0]}`];
-		if (result.beadsIssueId) lines.push(`Beads: ${result.beadsIssueId}`);
+		const header = result.linked ? 'Plan linked' : 'Plan created';
+		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,
@@ -704,10 +1152,14 @@ module.exports = {
 	readResearchDoc,
 	detectScope,
 	createBeadsIssue,
+	createKernelIssue,
 	createFeatureBranch,
 	extractDesignDecisions,
 	extractTasksFromResearch,
 	detectDRYViolation,
 	applyYAGNIFilter,
 	executePlan,
+	issueBackendLabel,
+	registerBranchIssueLinkage,
+	currentBranchIssueFromDriver,
 };