forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/commands/stage.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * Forge Stage Command (f61601ab)
+ *
+ * Records the REAL workflow phase of an issue into the kernel_stage_runs table so
+ * the phase is queryable — instead of being guessed from status+claim (a
+ * claimed-open issue with a merged PR would otherwise still show "dev"). Mirrors
+ * the worktree-linkage registry: direct kernel writes, idempotent per
+ * (issue_id, stage).
+ *
+ *   forge stage <issue-id> <stage> --start       Open a stage (status=active)
+ *   forge stage <issue-id> <stage> --complete    Close a stage (status=done)
+ *   forge stage <issue-id> --current             Print the current stage
+ *   forge stage <issue-id> --list                Print the full stage history
+ *
+ * `<stage>` is one of the canonical workflow stages (plan|dev|validate|ship|review|verify).
+ * Read the current stage back on `forge show <id>` (data.current_stage).
+ *
+ * @module commands/stage
+ */
+
+const { STAGE_IDS, normalizeStageId } = require('../workflow/stages');
+const { resolveIssueId } = require('../kernel/issue-id-resolver');
+
+const STAGE_FLAGS = ['--start', '--complete', '--list', '--current', '--json'];
+const VALUE_FLAGS = ['--substage'];
+const USAGE = 'Usage: forge stage <issue-id> <stage> --start|--complete   (reads: --current | --list)';
+
+/**
+ * Parse the stage command's own flags out of the raw args (the global flag parser
+ * only recognizes an allowlist, so — like `worktree` — this command extracts its
+ * own). Returns { positional, opts } or { error }.
+ */
+function parseStageArgs(args = []) {
+  const positional = [];
+  const opts = { start: false, complete: false, list: false, current: false, json: false, substage: null };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (typeof arg !== 'string') continue;
+
+    const valueFlag = VALUE_FLAGS.find(flag => arg === flag || arg.startsWith(`${flag}=`));
+    if (valueFlag) {
+      let value;
+      if (arg.startsWith(`${valueFlag}=`)) {
+        value = arg.slice(`${valueFlag}=`.length);
+      } else {
+        value = args[i + 1];
+        i += 1;
+      }
+      if (!value || value.startsWith('--')) {
+        return { error: `Missing value for ${valueFlag}. ${USAGE}` };
+      }
+      opts.substage = value;
+      continue;
+    }
+
+    if (STAGE_FLAGS.includes(arg)) {
+      opts[arg.slice(2)] = true;
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      return { error: `Unknown flag: ${arg}. ${USAGE}` };
+    }
+
+    positional.push(arg);
+  }
+
+  return { positional, opts };
+}
+
+async function resolveDriver(projectRoot, opts) {
+  if (opts._kernelDriver) return opts._kernelDriver;
+  const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
+  return (await buildMigratedKernelIssueDeps({ projectRoot })).kernelDriver;
+}
+
+function render(opts, data, humanLines) {
+  if (opts.json || process.env.FORGE_JSON === '1') {
+    return { success: true, output: JSON.stringify(data, null, 2) };
+  }
+  return { success: true, output: humanLines.join('\n'), ...data };
+}
+
+module.exports = {
+  name: 'stage',
+  description: 'Record or read an issue\'s real workflow stage (stage_runs)',
+  usage: USAGE,
+  flags: {
+    '--start': 'Open a stage run (status=active)',
+    '--complete': 'Complete a stage run (status=done)',
+    '--substage': 'Optional substage label to record',
+    '--current': 'Print the current stage (latest active, else latest completed)',
+    '--list': 'Print the full stage-run history for the issue',
+    '--json': 'Emit machine-readable JSON',
+  },
+
+  /**
+   * @param {string[]} args - Positional + flag args after `stage`
+   * @param {object} _flags - Global parsed flags (unused; this command parses its own)
+   * @param {string} projectRoot - Project root path
+   * @param {object} [opts] - DI options (may inject `_kernelDriver`)
+   * @returns {Promise<object>}
+   */
+  handler: async (args, _flags, projectRoot, opts = {}) => {
+    const parsed = parseStageArgs(args);
+    if (parsed.error) {
+      return { success: false, error: parsed.error };
+    }
+    const { positional, opts: stageOpts } = parsed;
+
+    const issueRef = positional[0];
+    if (!issueRef) {
+      return { success: false, error: `Missing issue id. ${USAGE}` };
+    }
+
+    let driver;
+    try {
+      driver = await resolveDriver(projectRoot, opts);
+    } catch (error) {
+      return { success: false, error: `Kernel unavailable: ${error.message}` };
+    }
+
+    // Resolve prefixes / display handles to a full issue id (same resolver the
+    // issue commands use), so `forge stage 1a2b3c4d dev --start` works.
+    const resolution = await resolveIssueId(
+      issueRef,
+      (needle, limit) => driver.findIssueIdsByPrefix(needle, limit, {}, {}),
+    );
+    if (resolution.error) {
+      return { success: false, error: resolution.error };
+    }
+    const issueId = resolution.id;
+
+    // Read paths -----------------------------------------------------------
+    if (stageOpts.current) {
+      const current = driver.getCurrentStage({ issue_id: issueId }, {});
+      const data = {
+        issue_id: issueId,
+        current_stage: current ? current.stage : null,
+        current_stage_status: current ? current.status : null,
+      };
+      const human = current
+        ? `${issueId}: ${current.stage} (${current.status})`
+        : `${issueId}: no stage recorded`;
+      return render(stageOpts, data, [human]);
+    }
+
+    if (stageOpts.list) {
+      const runs = driver.listStageRuns({ issue_id: issueId }, {});
+      const data = { issue_id: issueId, stage_runs: runs };
+      const human = runs.length === 0
+        ? [`${issueId}: no stage runs`]
+        : runs.map(run => `  ${run.stage.padEnd(9)} ${run.status.padEnd(7)} started ${run.started_at}${run.completed_at ? ` → completed ${run.completed_at}` : ''}`);
+      return render(stageOpts, data, [`${issueId} stage history:`, ...human]);
+    }
+
+    // Write paths ----------------------------------------------------------
+    const stage = normalizeStageId(positional[1]);
+    if (!stage) {
+      return {
+        success: false,
+        error: `Invalid or missing stage "${positional[1] ?? ''}". Expected one of: ${STAGE_IDS.join(', ')}. ${USAGE}`,
+      };
+    }
+
+    if (stageOpts.start && stageOpts.complete) {
+      return { success: false, error: `Pass only one of --start or --complete. ${USAGE}` };
+    }
+    const action = stageOpts.complete ? 'complete' : 'start';
+
+    let row;
+    try {
+      row = driver.recordStageRun(
+        { issue_id: issueId, stage, action, substage: stageOpts.substage || null },
+        {},
+      );
+    } catch (error) {
+      // A FOREIGN KEY failure means the issue id does not exist in the kernel.
+      if (/FOREIGN KEY/i.test(String(error.message))) {
+        return { success: false, error: `Issue ${issueId} not found in the kernel.` };
+      }
+      return { success: false, error: `Failed to record stage: ${error.message}` };
+    }
+
+    const data = { issue_id: issueId, action, stage_run: row };
+    const verb = action === 'complete' ? 'completed' : 'started';
+    return render(stageOpts, data, [`${issueId}: ${verb} stage ${stage} (${row.status})`]);
+  },
+};

package/lib/commands/stale.js

@@ -0,0 +1,5 @@
+'use strict';
+
+const { createIssueSubcommand } = require('./_issue');
+
+module.exports = createIssueSubcommand('stale');

package/lib/commands/status.js

@@ -9,8 +9,12 @@ const {
 } = require('../workflow/state');
 const { STAGE_IDS } = require('../workflow/stages');
 const { detectWorktree } = require('../detect-worktree');
-const { readBeadsSnapshot } = require('../status/beads-snapshot');
-const { formatZeroArgStatus } = require('../status/presenter');
+const { readStatusSnapshot } = require('../status/snapshot');
+const {
+	buildPersonalStatusJson,
+	formatRunNextLines,
+	formatZeroArgStatus,
+} = require('../status/presenter');
 const {
 	loadState,
 	extractWorkflowStateFromComments,
@@ -18,6 +22,12 @@ const {
 } = require('../workflow/state-manager');
 const { secureExecFileSync } = require('../shell-utils.js');
 
+// Lifecycle progression used for status display. Stage 8 'Merge' is the merge
+// EVENT (a human GitHub action — Forge exposes no `merge` command) that lands after
+// the review stage and before post-merge /verify. Pre-merge doc/CI/handoff checks
+// are an embedded gate inside /ship and /review, not a standalone stage, so this
+// ladder never gains a premerge stage. (AUTHORITATIVE_STAGE_NAMES below still maps
+// the legacy 'premerge' id purely so historical workflow state round-trips.)
 const WORKFLOW_STAGES = {
 	1: { name: 'Fresh Start', nextCommand: 'research' },
 	2: { name: 'Research', nextCommand: 'research' },
@@ -30,6 +40,10 @@ const WORKFLOW_STAGES = {
 	9: { name: 'Verification', nextCommand: 'verify' },
 };
 
+// Legacy read-path name map. `premerge` is retired as a standalone stage (it is now
+// an embedded gate in /ship and /review) but is intentionally KEPT here so a stored
+// `currentStage: 'premerge'` from a schemaVersion 1 workflow still resolves a name
+// on read — deleting it would break upgraders (see test/status-command.test.js).
 const AUTHORITATIVE_STAGE_NAMES = {
 	plan: 'Planning',
 	dev: 'Development',
@@ -329,10 +343,15 @@ function detectStage(context) {
 
 function parseStatusInputs(args = [], flags = {}) {
 	const statusArgs = Array.isArray(args) ? args : [];
+	const firstDefined = (...values) => values.find(value => value !== undefined && value !== null);
 	const getNextValue = (flagName) => {
 		const index = statusArgs.indexOf(flagName);
 		if (index !== -1 && index + 1 < statusArgs.length) {
-			return statusArgs[index + 1];
+			const candidate = statusArgs[index + 1];
+			if (typeof candidate === 'string' && candidate.startsWith('--')) {
+				return null;
+			}
+			return candidate;
 		}
 		return null;
 	};
@@ -343,10 +362,23 @@ function parseStatusInputs(args = [], flags = {}) {
 	};
 
 	return {
-		issueId: flags.issueId || flags['--issue-id'] || getInlineValue('--issue-id') || getNextValue('--issue-id'),
-		workflowState: flags.workflowState || flags['--workflow-state'] || getInlineValue('--workflow-state') || getNextValue('--workflow-state'),
-		bdComments: flags.bdComments || flags['--bd-comments'] || getInlineValue('--bd-comments') || getNextValue('--bd-comments'),
-		projectRoot: flags.projectRoot || flags['--project-root'] || getInlineValue('--project-root') || getNextValue('--project-root') || null,
+		issueId: firstDefined(flags.issueId, flags['--issue-id'], getInlineValue('--issue-id'), getNextValue('--issue-id')),
+		issueBackend: firstDefined(flags.issueBackend, flags['--issue-backend'], getInlineValue('--issue-backend'), getNextValue('--issue-backend')) || null,
+		workflowState: firstDefined(flags.workflowState, flags['--workflow-state'], getInlineValue('--workflow-state'), getNextValue('--workflow-state')),
+		bdComments: firstDefined(flags.bdComments, flags['--bd-comments'], getInlineValue('--bd-comments'), getNextValue('--bd-comments')),
+		projectRoot: firstDefined(flags.projectRoot, flags['--project-root'], getInlineValue('--project-root'), getNextValue('--project-root')) || null,
+		json: flags.json === true || flags['--json'] === true || statusArgs.includes('--json'),
+		full: flags.full === true || flags['--full'] === true || statusArgs.includes('--full'),
+		now: firstDefined(flags.now, flags['--now'], getInlineValue('--now'), getNextValue('--now')),
+		staleAfterDays: firstDefined(
+			flags.staleAfterDays,
+			flags['--stale-after-days'],
+			flags['--staleAfterDays'],
+			getInlineValue('--stale-after-days'),
+			getInlineValue('--staleAfterDays'),
+			getNextValue('--stale-after-days'),
+			getNextValue('--staleAfterDays')
+		),
 	};
 }
 
@@ -408,17 +440,104 @@ function readIssueDetails(issueId, projectRoot = process.cwd()) {
 	}
 }
 
+function stripDatePrefix(value) {
+	const datePrefixLength = 11;
+	const datePrefix =
+		value.length > datePrefixLength &&
+		value[4] === '-' &&
+		value[7] === '-' &&
+		value[10] === '-';
+	return datePrefix ? value.slice(datePrefixLength) : value;
+}
+
+function trimTrailingPathPunctuation(value) {
+	const trailingPunctuation = '.,;:';
+	let end = value.length;
+	while (end > 0 && trailingPunctuation.includes(value[end - 1])) {
+		end -= 1;
+	}
+	return value.slice(0, end);
+}
+
+function stripMarkdownSuffixes(value) {
+	let stripped = value.endsWith('.md') ? value.slice(0, -3) : value;
+	for (const suffix of ['-design', '-plan', '-tasks', '-decisions']) {
+		if (stripped.endsWith(suffix)) {
+			stripped = stripped.slice(0, -suffix.length);
+			break;
+		}
+	}
+	return stripped;
+}
+
+function extractSlugFromDesignPath(candidatePath) {
+	const parts = trimTrailingPathPunctuation(candidatePath).replaceAll('\\', '/').split('/').filter(Boolean);
+	const docsIndex = parts.indexOf('docs');
+	if (docsIndex === -1) {
+		return '';
+	}
+	const root = parts[docsIndex + 1];
+
+	if (root === 'plans') {
+		const fileName = parts[docsIndex + 2] || '';
+		return stripDatePrefix(stripMarkdownSuffixes(fileName));
+	}
+
+	if (root === 'work') {
+		return stripDatePrefix(parts[docsIndex + 2] || '');
+	}
+
+	return '';
+}
+
+function isPathCandidateChar(char) {
+	return (
+		(char >= 'a' && char <= 'z') ||
+		(char >= 'A' && char <= 'Z') ||
+		(char >= '0' && char <= '9') ||
+		char === '/' ||
+		char === '\\' ||
+		char === '.' ||
+		char === '-' ||
+		char === '_'
+	);
+}
+
+function extractPathCandidates(text) {
+	const candidates = [];
+	let index = 0;
+
+	while (index < text.length) {
+		const hasForwardPath = text.startsWith('docs/', index);
+		const hasBackwardPath = text.startsWith('docs\\', index);
+
+		if (!hasForwardPath && !hasBackwardPath) {
+			index += 1;
+			continue;
+		}
+
+		let end = index;
+		while (end < text.length && isPathCandidateChar(text[end])) {
+			end += 1;
+		}
+		candidates.push(text.slice(index, end));
+		index = end;
+	}
+
+	return candidates;
+}
+
 function extractDesignSlugs(design) {
 	if (typeof design !== 'string' || design.trim() === '') {
 		return [];
 	}
 
 	const slugs = new Set();
-	const pattern = /docs[\\/]+plans[\\/]+\d{4}-\d{2}-\d{2}-([a-z0-9-]+?)-(?:design|tasks|decisions)\.md/g;
-	let match = pattern.exec(design);
-	while (match) {
-		slugs.add(match[1]);
-		match = pattern.exec(design);
+	for (const candidate of extractPathCandidates(design)) {
+		const slug = extractSlugFromDesignPath(candidate);
+		if (slug) {
+			slugs.add(slug);
+		}
 	}
 
 	return [...slugs];
@@ -450,7 +569,8 @@ function discoverCurrentIssue(snapshot, context, projectRoot = process.cwd()) {
 			return hydratedIssues.get(issue.id);
 		}
 
-		const details = issue.design && issue.comments ? issue : readIssueDetails(issue.id, projectRoot);
+		const hasSufficientDetails = Boolean(issue.comments) && Boolean(issue.design);
+		const details = hasSufficientDetails ? issue : readIssueDetails(issue.id, projectRoot);
 		const hydratedIssue = details ? { ...issue, ...details } : issue;
 		hydratedIssues.set(issue.id, hydratedIssue);
 		return hydratedIssue;
@@ -578,11 +698,8 @@ function collectCompletedChecks(result) {
 function formatAuthoritativeStatus(result) {
 	const completedStages = result.workflowState.completedStages.map(stageId => stageId);
 	const allowedCommands = result.nextStages.map(stageId => '/' + stageId).join(', ');
-	const nextLines = [`Run now: /${result.runCommand}`];
+	const nextLines = formatRunNextLines(result);
 
-	if (result.nextCommand) {
-		nextLines.push(`Next after this: /${result.nextCommand}`);
-	}
 	if (allowedCommands) {
 		nextLines.push(`Allowed after this: ${allowedCommands}`);
 	}
@@ -633,7 +750,12 @@ function formatStatus(result) {
 
 module.exports = {
 	name: 'status',
-	description: 'Intelligent stage detection with confidence scoring',
+	description: 'One-glance orientation: where you are, what to run next, and your work',
+	usage: 'forge status [--full] [--json]',
+	flags: {
+		'--full': 'Also show blocked, stale, and recently completed issues',
+		'--json': 'Emit the machine-readable status envelope',
+	},
 	handler: async (args, flags, projectRoot) => {
 		const inputs = parseStatusInputs(args, flags);
 		const isZeroArgStatus = !inputs.issueId && !inputs.workflowState && !inputs.bdComments;
@@ -647,7 +769,16 @@ module.exports = {
 
 		if (isZeroArgStatus) {
 			context = detectRepoContext(effectiveProjectRoot);
-			snapshot = readBeadsSnapshot(effectiveProjectRoot);
+			// Read from the active issue backend (Kernel by default; Beads only when
+			// explicitly selected). Previously hard-wired to the retired Beads
+			// issues.jsonl, which is empty on a kernel-default repo — so the flagship
+			// view showed "Ready: none" despite a populated kernel (bug 40f35797).
+			snapshot = await readStatusSnapshot(effectiveProjectRoot, {
+				now: inputs.now,
+				staleAfterDays: inputs.staleAfterDays,
+				issueBackend: inputs.issueBackend,
+				env: process.env,
+			});
 			const discoveredIssue = discoverCurrentIssue(snapshot, context, effectiveProjectRoot);
 			if (discoveredIssue) {
 				inputs.issueId = discoveredIssue.id;
@@ -660,23 +791,29 @@ module.exports = {
 		if (isZeroArgStatus) {
 			if (workflowState) {
 				const result = buildAuthoritativeStatus(workflowState);
+				const output = inputs.json
+					? JSON.stringify(buildPersonalStatusJson({ context, snapshot, workflowResult: result }), null, 2)
+					: formatZeroArgStatus({ context, snapshot, workflowResult: result, full: inputs.full });
 				return {
 					success: true,
 					context,
 					snapshot,
 					issueId: inputs.issueId,
-					output: formatZeroArgStatus({ context, snapshot, workflowResult: result }),
+					output,
 					...result,
 				};
 			}
 
+			const output = inputs.json
+				? JSON.stringify(buildPersonalStatusJson({ context, snapshot }), null, 2)
+				: formatZeroArgStatus({ context, snapshot, full: inputs.full });
 			return {
 				success: true,
 				context,
 				snapshot,
 				issueId: inputs.issueId,
 				missingWorkflowState: true,
-				output: formatZeroArgStatus({ context, snapshot }),
+				output,
 				...(fallbackReason ? { fallbackReason } : {}),
 			};
 		}

package/lib/commands/sync.js

@@ -1,73 +1,61 @@
 'use strict';
 
-const { execFileSync } = require('node:child_process');
-
-function isRecoverableBeadsSyncError(error) {
-  const message = error?.message ?? String(error ?? '');
-  return (
-    message.includes('failed to open database') ||
-    message.includes('database not found') ||
-    message.includes('no beads configuration found') ||
-    message.includes('remote \'origin\' not found') ||
-    message.includes('remote "origin" not found')
-  );
-}
+const { createSyncBackend } = require('../sync-backend');
 
 /**
  * Forge Sync Command
- * Syncs Beads issue data by running dolt pull + push.
- * Uses execFileSync (not execSync) to prevent command injection (OWASP A03).
+ * Syncs Kernel issue state with the configured sync backend.
+ *
+ * The local kernel is single-machine authority, so the default `local-noop`
+ * backend is a graceful no-op that names the model instead of moving data.
+ * Selecting `git-jsonl`/`server` (a future swap) is a backend change with zero
+ * call-site churn — see docs/work/2026-06-26-sync-authority/plan.md.
  *
  * @module commands/sync
  */
 module.exports = {
   name: 'sync',
-  description: 'Sync Beads issue data (dolt pull + push)',
+  description: 'Sync Kernel issue state with the configured sync backend (local-noop until a server/remote is configured)',
   usage: 'forge sync',
   flags: {},
 
   /**
-   * Run beads dolt pull + push to sync issue data.
+   * Resolve a SyncBackend (default `local-noop`) and run its one-shot sync.
    * @param {string[]} _args - Positional arguments (unused)
    * @param {object} _flags - CLI flags (unused)
-   * @param {string} _projectRoot - Project root path (unused)
+   * @param {string} projectRoot - Project root path (used for backend resolution)
    * @param {object} [opts] - Options for dependency injection
-   * @param {Function} [opts._exec] - Override for execFileSync (testing)
+   * @param {object} [opts._backend] - Override for the resolved SyncBackend (testing)
+   * @param {object} [opts.deps] - Explicit backend selection (precedence over env/config)
+   * @param {object} [opts.env] - Environment override (testing)
    * @returns {Promise<{success: boolean, synced: boolean, message?: string, error?: string}>}
    */
-  handler: async (_args, _flags, _projectRoot, opts = {}) => {
-    const exec = opts._exec || execFileSync;
-
-    // Step 1: Check if bd binary exists
+  handler: async (_args, _flags, projectRoot, opts = {}) => {
+    let backend;
     try {
-      exec('bd', ['--version'], { stdio: 'pipe' });
-    } catch { /* intentional: bd not installed, skip sync gracefully */ // NOSONAR S2486
-      return {
-        success: true,
-        synced: false,
-        message: 'Beads not installed — nothing to sync',
-      };
+      backend = opts._backend || createSyncBackend({
+        projectRoot,
+        deps: opts.deps,
+        env: opts.env,
+      });
+    } catch (resolveErr) {
+      return { success: false, synced: false, error: resolveErr.message };
     }
 
-    // Step 2: Run dolt pull + push
+    let result;
     try {
-      exec('bd', ['dolt', 'pull'], { stdio: 'pipe' });
-      exec('bd', ['dolt', 'push'], { stdio: 'pipe' });
+      result = await backend.sync({ ...opts, projectRoot });
     } catch (syncErr) {
-      if (isRecoverableBeadsSyncError(syncErr)) {
-        return {
-          success: true,
-          synced: false,
-          message: 'Beads is installed but not initialized for sync in this worktree — skipping sync',
-        };
-      }
-      return {
-        success: false,
-        synced: false,
-        error: syncErr.message,
-      };
+      console.error(`forge sync failed: ${syncErr.message}`);
+      return { success: false, synced: false, error: syncErr.message };
     }
-
-    return { success: true, synced: true };
+    // Surface the outcome to the user — otherwise `forge sync` runs silently and
+    // a user can't tell whether it synced, no-op'd (local-noop), or failed.
+    if (result && result.message) {
+      console.log(result.message);
+    } else if (result && !result.success && result.error) {
+      console.error(`forge sync failed: ${result.error}`);
+    }
+    return result;
   },
 };

package/lib/commands/team.js

@@ -1,6 +1,7 @@
 const { existsSync } = require('node:fs');
 const { execFileSync } = require('node:child_process');
 const path = require('node:path');
+const { getPackageRoot } = require('../package-root');
 
 // Resolve bash binary from fixed, known locations only (no PATH search).
 // SonarCloud S4036: PATH must not be searched for OS commands.
@@ -22,7 +23,9 @@ function _resolveBash() {
 }
 
 function handleTeam(args) {
-  const scriptPath = path.join(__dirname, '..', '..', 'scripts', 'forge-team', 'index.sh');
+  // Route through the asset root so `forge team` finds the script in BOTH channels:
+  // the on-disk package (npm/npx) and a compiled binary (extracted embed dir).
+  const scriptPath = path.join(getPackageRoot(), 'scripts', 'forge-team', 'index.sh');
   const bashPath = _resolveBash();
 
   try {