forge-workflow 0.0.10 → 0.1.0-beta.2

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 {

package/lib/commands/test.js

@@ -27,6 +27,18 @@ const LOCKFILE_MAP = [
 
 const DEFAULT_TIMEOUT = 120000;
 const BEADS_CHECK_TIMEOUT = 3000;
+const DIRECT_TEST_CANDIDATES = Object.freeze({
+	'bin/forge.js': [
+		'test/cli-flags.test.js',
+		'test/forge-cli-registry.test.js',
+		'test/setup-github-sync.test.js',
+		'test/setup-runtime-flags.test.js',
+	],
+	'lib/lefthook-check.js': ['test/lefthook-check.test.js', 'test/runtime-health.test.js'],
+	'lib/runtime-health.js': ['test/runtime-health.test.js'],
+	'lib/upgrade-safety.js': ['test/commands/upgrade.test.js'],
+	'scripts/test.js': ['test/scripts/test-runner.test.js'],
+});
 
 /**
  * Detect the package manager by checking which lockfile exists.
@@ -115,7 +127,17 @@ function getChangedFiles(execFileSync, options = {}) {
 			encoding: 'utf8',
 			timeout: 5000,
 		}).trim();
-	} catch (_e) { // NOSONAR S2486
+	} catch (err) { // NOSONAR S2486
+		// A git-diff FAILURE is NOT the same as "no files changed": we could not
+		// determine the change set at all. Callers that must fail closed (preflight)
+		// pass { strict: true } so the error surfaces instead of masquerading as an
+		// empty list. The default path keeps the historical empty-list fallback that
+		// `forge test --affected` and the pre-push mapping rely on to run the full
+		// suite, so their semantics are unchanged.
+		if (options.strict) {
+			const reason = err && err.message ? err.message : String(err);
+			throw new Error(`git diff failed while computing changed files: ${reason}`);
+		}
 		/* intentional: git diff failed, no affected files to report */
 		return [];
 	}
@@ -152,22 +174,29 @@ function getAffectedTestFiles(projectRoot, execFileSync, fs = defaultFs, options
 function getTestCandidatesForChangedFile(file) {
 	if (!file) return [];
 
-	if (file === 'lib/lefthook-check.js') {
-		return ['test/lefthook-check.test.js', 'test/runtime-health.test.js'];
-	}
-
-	if (file === 'lib/runtime-health.js') {
-		return ['test/runtime-health.test.js'];
-	}
-
-	if (file === 'scripts/test.js') {
-		return ['test/scripts/test-runner.test.js'];
+	const directCandidates = DIRECT_TEST_CANDIDATES[file];
+	if (directCandidates) {
+		return directCandidates;
 	}
 
 	if (file.startsWith('test/') && file.endsWith('.test.js')) {
 		return [file];
 	}
 
+	if (file === 'README.md'
+		|| file === 'QUICKSTART.md'
+		|| file === 'CHANGELOG.md'
+		|| file === 'AGENTS.md'
+		|| file === 'DEVELOPMENT.md'
+		|| file === 'docs/INDEX.md'
+		|| file === 'docs/PROJECT_DESIGN.md'
+		|| file.startsWith('docs/forge/')
+		|| file.startsWith('docs/guides/')
+		|| file.startsWith('docs/reference/')
+		|| file.startsWith('docs/work/')) {
+		return ['test/docs-consistency.test.js'];
+	}
+
 	if (file.startsWith('lib/') && file.endsWith('.js')) {
 		const relative = file.slice('lib/'.length);
 		return [`test/${relative.replace(/\.js$/, '.test.js')}`];
@@ -196,26 +225,13 @@ function getTestCandidatesForChangedFile(file) {
 		];
 	}
 
-	if (file.startsWith('.claude/commands/') && file.endsWith('.md')) {
-		return [
-			'test/command-sync-check.test.js',
-			'test/structural/command-sync.test.js',
-		];
-	}
-
 	if (file.startsWith('.forge/')
 		|| file.startsWith('.cursor/')
-		|| file.startsWith('.cline/')
-		|| file.startsWith('.roo/')
-		|| file.startsWith('.kilocode/')
-		|| file.startsWith('.opencode/')
-		|| file.startsWith('.codex/skills/')
-		|| file.startsWith('.github/prompts/')) {
+		|| file.startsWith('.codex/')) {
 		return [
 			'test/agent-gaps.test.js',
-			'test/command-sync-check.test.js',
 			'test/scripts/check-agents.test.js',
-			'test/structural/command-sync.test.js',
+			'test/structural/skills-sync-drift.test.js',
 		];
 	}
 
@@ -227,7 +243,7 @@ module.exports = {
 	getAffectedTestFiles,
 	getTestCandidatesForChangedFile,
 	name: 'test',
-	description: 'Run tests with smart defaults (timeout, Beads skip, affected-only)',
+	description: 'Run tests with smart defaults (timeout, affected-only)',
 	usage: 'forge test [--affected]',
 	flags: {
 		'--affected': 'Run only tests for changed files',

package/lib/commands/update.js

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

package/lib/commands/upgrade.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const {
+  applySelfHeal,
+  buildUpgradeDryRunReport,
+  renderUpgradeDryRunReport,
+} = require('../upgrade-safety');
+
+function hasArg(args, name) {
+  return Array.isArray(args) && args.includes(name);
+}
+
+const usage = 'Usage: forge upgrade [--dry-run] [--self-heal]';
+
+async function handler(args, flags, projectRoot) {
+  const dryRun = flags?.dryRun === true || flags?.['dry-run'] === true || hasArg(args, '--dry-run');
+  const selfHeal = flags?.selfHeal === true || flags?.['self-heal'] === true || hasArg(args, '--self-heal');
+
+  if (!dryRun && !selfHeal) {
+    return {
+      success: false,
+      error: usage,
+    };
+  }
+
+  const report = buildUpgradeDryRunReport(projectRoot);
+  const selfHealResult = selfHeal ? applySelfHeal(report.projectRoot, report) : null;
+  const output = renderUpgradeDryRunReport(report, selfHealResult);
+  const success = report.ok && !selfHealResult?.refused;
+
+  return {
+    success,
+    output,
+    error: success ? undefined : output,
+  };
+}
+
+module.exports = {
+  name: 'upgrade',
+  description: 'Preview and self-heal safe Forge upgrade readiness',
+  usage,
+  flags: {
+    '--dry-run': 'Preview upgrade readiness without writing files',
+    '--self-heal': 'Apply safe metadata repairs only; does not snapshot or restore',
+  },
+  handler,
+};