forge-workflow 0.0.10 → 0.1.0-beta.3

package/bin/forge-cmd.js

@@ -15,6 +15,7 @@ const HANDLERS = {
 	dev: require('../lib/commands/dev'),
 	validate: require('../lib/commands/validate'),
 	ship: require('../lib/commands/ship'),
+	shepherd: require('../lib/commands/shepherd'),
 };
 
 const VALID_COMMANDS = [
@@ -25,10 +26,50 @@ const VALID_COMMANDS = [
 	'check', // backward-compat alias for validate
 	'ship',
 	'review',
+	'shepherd',
 	'merge',
 	'verify',
 ];
 
+function findWorkPlanDoc(dir, slug) {
+	if (!fs.existsSync(dir)) return null;
+
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const entryPath = `${dir}/${entry.name}`;
+		if (entry.isDirectory()) {
+			const found = findWorkPlanDoc(entryPath, slug);
+			if (found) return found;
+		}
+		if (entry.isFile() && (entry.name === 'plan.md' || entry.name === 'design.md' || entry.name === 'tasks.md')) {
+			const workDirName = dir.split(/[\\/]/).pop() || '';
+			const workSlug = workDirName.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+			if (workSlug === slug) {
+				return entryPath;
+			}
+		}
+	}
+
+	return null;
+}
+
+function legacyPlanMatchesSlug(fileName, slug) {
+	const legacySlug = fileName
+		.replace(/\.md$/, '')
+		.replace(/^\d{4}-\d{2}-\d{2}-/, '')
+		.replace(/-(?:design|plan|tasks|decisions)$/, '');
+	return legacySlug === slug;
+}
+
+function findPlanDocForBranch(branch) {
+	const slug = branch.replace(/^(feat|fix|docs|refactor)\//, '');
+	const workPlan = findWorkPlanDoc('docs/work', slug);
+	if (workPlan) return workPlan;
+
+	if (!fs.existsSync('docs/plans')) return null;
+	const legacy = fs.readdirSync('docs/plans').find(f => f.endsWith('.md') && legacyPlanMatchesSlug(f, slug));
+	return legacy ? `docs/plans/${legacy}` : null;
+}
+
 const COMMAND_DESCRIPTIONS = {
 	status: 'Detect current workflow stage (1-7)',
 	plan: 'Create branch + Beads + design doc',
@@ -37,6 +78,7 @@ const COMMAND_DESCRIPTIONS = {
 	check: 'Alias for validate (deprecated — use validate)',
 	ship: 'Auto-generate PR body and create PR',
 	review: 'Aggregate all review feedback',
+	shepherd: 'Run one bounded monitor pass over a PR (never merges)',
 	merge: 'Update docs, merge PR, cleanup',
 	verify: 'Final documentation verification',
 };
@@ -45,6 +87,7 @@ const REQUIRED_ARGS = {
 	plan: ['feature-slug'],
 	ship: ['feature-slug', 'title'],
 	review: [],
+	shepherd: ['pr'],
 	merge: [],
 	// Other commands don't require arguments
 	status: [],
@@ -54,6 +97,14 @@ const REQUIRED_ARGS = {
 	verify: [],
 };
 
+// Allowed flags per command. Commands listed here have their flags strictly
+// validated — an unknown flag is rejected rather than silently forwarded
+// (e.g. a typo like `--auto-reabse` must not run shepherd with default
+// behaviour). Commands NOT listed here keep their permissive flag handling.
+const ALLOWED_FLAGS = {
+	shepherd: ['--auto-rebase', '--bundle', '--pull', '--json'],
+};
+
 /**
  * Parse command line arguments
  * @param {string[]} argv - Process arguments
@@ -127,6 +178,26 @@ function validateArgs(command, args) {
 	const required = REQUIRED_ARGS[command] || [];
 	const positionalArgs = args.filter(a => !a.startsWith('--'));
 
+	// `--json` has no standalone meaning for shepherd — it only toggles the JSON
+	// rendering of the `--bundle` or `--pull` gather. Without one of those it would
+	// silently fall back to the human-readable pass output, so reject it loudly.
+	if (command === 'shepherd' && args.includes('--json')
+		&& !args.includes('--bundle') && !args.includes('--pull')) {
+		return {
+			valid: false,
+			error: "Error: '--json' is only supported with 'forge shepherd <pr> --bundle --json' or '--pull --json'",
+		};
+	}
+
+	// `--bundle` and `--pull` are mutually exclusive output modes — shepherd.js returns on
+	// `--pull` first, so accepting both would silently drop the bundle. Fail fast.
+	if (command === 'shepherd' && args.includes('--bundle') && args.includes('--pull')) {
+		return {
+			valid: false,
+			error: "Error: 'forge shepherd <pr>' accepts '--bundle' OR '--pull', not both",
+		};
+	}
+
 	if (required.length > 0 && positionalArgs.length < required.length) {
 		const missing = required.slice(positionalArgs.length);
 		return {
@@ -144,6 +215,19 @@ function validateArgs(command, args) {
 		}
 	}
 
+	// Reject unknown flags for commands with a strict flag allow-list, so typos
+	// fail loudly instead of running with default behaviour.
+	const allowedFlags = ALLOWED_FLAGS[command];
+	if (allowedFlags) {
+		const unknownFlag = args.find(a => a.startsWith('--') && !allowedFlags.includes(a));
+		if (unknownFlag) {
+			return {
+				valid: false,
+				error: `Error: Unknown flag '${unknownFlag}' for 'forge ${command}'\n\nAllowed flags: ${allowedFlags.join(', ') || '(none)'}`,
+			};
+		}
+	}
+
 	return { valid: true };
 }
 
@@ -208,8 +292,15 @@ async function main() { // NOSONAR S3776
 	// Execute command
 	try {
 		const quotedArgs = args.map(a => `"${a.replaceAll('"', '\\"')}"`);  // NOSONAR S7780 - intentional backslash escape for console quoting
-		console.log(`Executing: forge ${command}${quotedArgs.length > 0 ? ' ' + quotedArgs.join(' ') : ''}`);
-		console.log('');
+		// `forge shepherd <pr> --bundle` / `--pull` emit a machine-consumable JSON
+		// payload on stdout (the monitor/agent parses it). Suppress the human banner
+		// + blank line in those modes so stdout stays valid standalone JSON.
+		const quietJsonMode = command === 'shepherd'
+			&& (args.includes('--bundle') || args.includes('--pull'));
+		if (!quietJsonMode) {
+			console.log(`Executing: forge ${command}${quotedArgs.length > 0 ? ' ' + quotedArgs.join(' ') : ''}`);
+			console.log('');
+		}
 
 		let result;
 		const positionalArgs = args.filter(a => !a.startsWith('--'));
@@ -223,11 +314,7 @@ async function main() { // NOSONAR S3776
 			const context = {
 				branch,
 				researchDoc: fs.existsSync('docs/research') ? fs.readdirSync('docs/research').find(f => f.endsWith('.md')) : null,
-				plan: (() => {
-					if (!fs.existsSync('docs/plans')) return null;
-					const slug = branch.replace(/^(feat|fix|docs|refactor)\//, '');
-					return fs.readdirSync('docs/plans').find(f => f.endsWith('.md') && f.includes(slug)) || null;
-				})(),
+				plan: findPlanDocForBranch(branch),
 				tests: (() => { try { return fs.readdirSync('test').filter(f => f.endsWith('.test.js')); } catch (error_) { void error_; return []; } })(), // NOSONAR S2486 - intentional: missing test dir
 			};
 			const stageResult = HANDLERS.status.detectStage(context);
@@ -237,7 +324,7 @@ async function main() { // NOSONAR S3776
 			result = await HANDLERS.plan.executePlan(positionalArgs[0]);
 			if (result.success) {
 				console.log(`✓ Plan created: ${result.summary || result.branchName || ''}`);
-				if (result.beadsIssueId) console.log(`  Beads: ${result.beadsIssueId}`);
+				if (result.issueId) console.log(`  ${HANDLERS.plan.issueBackendLabel(result.issueBackend)}: ${result.issueId}`);
 			} else {
 				console.error(`✗ Plan failed: ${result.error}`);
 				process.exit(1);
@@ -284,13 +371,34 @@ async function main() { // NOSONAR S3776
 				process.exit(1);
 			}
 
+		} else if (command === 'shepherd') {
+			result = await HANDLERS.shepherd.handler(args, {}, process.cwd());
+			if (result.pull !== undefined) {
+				// --pull: emit the compact "why it failed + what to fix" payload as
+				// JSON only, so an agent consumes ONE payload instead of running
+				// gh/GraphQL by hand.
+				console.log(JSON.stringify(result.pull, null, 2));
+			} else if (result.bundle !== undefined) {
+				// --bundle: emit the gathered PR-state bundle as JSON only, so the
+				// output is machine-consumable by the monitor/fixer-agent.
+				console.log(JSON.stringify(result.bundle, null, 2));
+			} else if (result.success) {
+				console.log(`✓ shepherd: ${result.state}`);
+				if (result.reason) console.log(`  ${result.reason}`);
+			} else {
+				console.error(`✗ shepherd: ${result.state || 'failed'}`);
+				if (result.error) console.error(`  ${result.error}`);
+				if (result.reason) console.error(`  ${result.reason}`);
+				process.exit(1);
+			}
+
 		} else {
 			// review, merge, verify - not yet implemented as automated CLI commands
 			// These stages require interactive AI assistance
 			const prRef = positionalArgs[0] ? ` ${positionalArgs[0]}` : '';
 			console.log(`ℹ️  '${command}' is a guided workflow stage.`);
 			console.log(`   Use your AI agent with the /${command}${prRef} slash command for interactive execution.`);
-			console.log(`   See .claude/commands/${command}.md for the full workflow guide.`);
+			console.log(`   See skills/${command}/SKILL.md for the full workflow guide.`);
 		}
 
 		process.exit(0);
@@ -314,4 +422,7 @@ module.exports = {
 	validateArgs,
 	validateSlug,
 	getHelpText,
+	findWorkPlanDoc,
+	findPlanDocForBranch,
+	ALLOWED_FLAGS,
 };

package/bin/forge-preflight.js

@@ -20,6 +20,30 @@ const fs = require("node:fs");
 // Validation results
 let checks = [];
 
+function hasDesignDocUnder(dir) {
+  if (!fs.existsSync(dir)) return false;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const entryPath = `${dir}/${entry.name}`;
+    if (entry.isDirectory() && hasDesignDocUnder(entryPath)) {
+      return true;
+    }
+    if (entry.isFile() && entry.name === "plan.md") {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function hasPlanDesignDoc() {
+  const legacyPlansDir = "docs/plans";
+  const hasLegacyDesign = fs.existsSync(legacyPlansDir)
+    && fs.readdirSync(legacyPlansDir).some((f) => f.endsWith("-plan.md"));
+
+  return hasLegacyDesign || hasDesignDocUnder("docs/work");
+}
+
 function check(label, condition, message) {
   const passed = typeof condition === "function" ? condition() : condition;
   checks.push({ label, passed, message: passed ? "✓" : `✗ ${message}` });
@@ -130,15 +154,12 @@ function validateDev() {
     "Plan file exists",
     () => {
       try {
-        const plansDir = "docs/plans";
-        if (!fs.existsSync(plansDir)) return false;
-        const plans = fs.readdirSync(plansDir).filter((f) => f.endsWith("-design.md"));
-        return plans.length > 0;
+        return hasPlanDesignDoc();
       } catch {
         return false;
       }
     },
-    "No plan file found in docs/plans/. Run: /plan",
+    "No plan file found in docs/work/. Run: /plan",
   );
 
   check(