forge-workflow 0.0.4 → 0.0.6

package/lib/commands/dev.js

@@ -1,513 +1,571 @@
-/**
- * Dev Command - TDD Cycle Management
- * Guides developers through RED-GREEN-REFACTOR cycles
- *
- * Security: Uses execFileSync for test execution to prevent command injection
- * TDD Discipline: Enforces test-first development and validates phase transitions
- *
- * @module commands/dev
- */
-
-const { execFileSync } = require('node:child_process');
-const fs = require('node:fs');
-const path = require('node:path');
-
-function getExecOptions() {
-	return { encoding: 'utf8', cwd: process.cwd(), timeout: 120000 };
-}
-
-/**
- * Detect current TDD phase based on project context
- *
- * Detection logic:
- * - RED: Tests exist, no implementation OR implementation exists but tests failing
- * - GREEN: Implementation exists, tests failing
- * - REFACTOR: Implementation exists, tests passing
- *
- * @param {{sourceFiles: string[], testFiles: string[], testsPassing?: boolean}} context - Project context
- * @returns {'RED'|'GREEN'|'REFACTOR'} Current TDD phase
- * @example
- * const phase = detectTDDPhase({ sourceFiles: ['lib/feature.js'], testFiles: ['test/feature.test.js'], testsPassing: true });
- * console.log(phase); // 'REFACTOR'
- */
-function detectTDDPhase(context) {
-	const { sourceFiles = [], testFiles = [], testsPassing } = context;
-
-	const hasTests = testFiles.length > 0;
-	const hasImplementation = sourceFiles.length > 0;
-
-	// RED: Tests exist but no implementation, or tests are failing
-	if (hasTests && !hasImplementation) {
-		return 'RED';
-	}
-
-	// GREEN: Tests failing with implementation
-	if (hasTests && hasImplementation && testsPassing === false) {
-		return 'GREEN';
-	}
-
-	// REFACTOR: Tests passing
-	if (hasTests && hasImplementation && testsPassing === true) {
-		return 'REFACTOR';
-	}
-
-	// Default to RED (write tests first)
-	return 'RED';
-}
-
-/**
- * Identify source and test file pairs
- * Maps source files to their corresponding test files
- *
- * Conventions:
- * - lib/commands/feature.js → test/commands/feature.test.js
- * - src/utils/helper.js → test/utils/helper.test.js
- *
- * @param {string[]} files - List of file paths
- * @returns {{length: number, pairs?: Array<{source: string, test: string}>, orphanedTests?: string[], orphanedSources?: string[]}} File pair analysis
- * @example
- * const result = identifyFilePairs(['lib/feature.js', 'test/feature.test.js']);
- * console.log(result.pairs); // [{ source: 'lib/feature.js', test: 'test/feature.test.js' }]
- */
-function identifyFilePairs(files) {
-	const testFiles = files.filter(f => f.includes('test') && f.endsWith('.test.js'));
-	const sourceFiles = files.filter(f => !f.includes('test') && f.endsWith('.js'));
-
-	const pairs = [];
-	const orphanedTests = [];
-	const orphanedSources = [];
-
-	// Match test files to source files
-	testFiles.forEach(testFile => {
-		// Convert test/commands/feature.test.js → lib/commands/feature.js
-		const sourceFile = testFile
-			.replace(/^test\//, 'lib/')
-			.replace(/\.test\.js$/, '.js');
-
-		if (sourceFiles.includes(sourceFile)) {
-			pairs.push({ source: sourceFile, test: testFile });
-		} else {
-			orphanedTests.push(testFile);
-		}
-	});
-
-	// Find source files without tests
-	sourceFiles.forEach(sourceFile => {
-		const testFile = sourceFile
-			.replace(/^(lib|src)\//, 'test/')
-			.replace(/\.js$/, '.test.js');
-
-		if (!testFiles.includes(testFile)) {
-			orphanedSources.push(sourceFile);
-		}
-	});
-
-	return {
-		length: pairs.length,
-		pairs: pairs.length > 0 ? pairs : undefined,
-		orphanedTests: orphanedTests.length > 0 ? orphanedTests : undefined,
-		orphanedSources: orphanedSources.length > 0 ? orphanedSources : undefined,
-	};
-}
-
-/**
- * Run tests using bun test
- * Executes specified test file or all tests
- *
- * @param {string} [testFile] - Optional specific test file to run
- * @returns {Promise<{success: boolean, passed?: number, failed?: number, duration?: number, totalTests?: number, error?: string}>} Test execution result
- * @example
- * const result = await runTests('test/commands/feature.test.js');
- * console.log(`${result.passed}/${result.passed + result.failed} tests passed`);
- */
-async function runTests(testFile) {
-	try {
-		const args = ['test'];
-		if (testFile) {
-			// Check if test file exists
-			if (!fs.existsSync(testFile)) {
-				return {
-					success: false,
-					error: `Test file not found: ${testFile}\n\nEnsure the file exists and path is correct.`,
-				};
-			}
-			args.push(testFile);
-		}
-
-		const startTime = Date.now();
-		const result = execFileSync('bun', args, getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
-		const duration = Date.now() - startTime;
-
-		// Parse bun test output
-		// Format: "X pass\nY fail\nRan Z tests"
-		const passMatch = /(\d+) pass/.exec(result);  // NOSONAR S5852 - bounded \d+ pattern, no backtracking
-		const failMatch = /(\d+) fail/.exec(result);  // NOSONAR S5852 - bounded \d+ pattern, no backtracking
-		const totalMatch = /Ran (\d+) tests/.exec(result);
-
-		const passed = passMatch ? parseInt(passMatch[1], 10) : 0;
-		const failed = failMatch ? parseInt(failMatch[1], 10) : 0;
-		const totalTests = totalMatch ? parseInt(totalMatch[1], 10) : passed + failed;
-
-		return {
-			success: failed === 0,
-			passed,
-			failed,
-			totalTests,
-			duration,
-		};
-	} catch (error) {
-		// Check for timeout
-		if (error.killed && error.signal === 'SIGTERM') {
-			return {
-				success: false,
-				error: 'Test execution timed out after 2 minutes',
-			};
-		}
-
-		// bun test exits non-zero when tests fail but stdout still contains results
-		// Parse stdout to extract pass/fail counts before falling back to generic error
-		if (error.stdout) {
-			const output = error.stdout;
-			const passMatch = /(\d+) pass/.exec(output);  // NOSONAR S5852 - bounded \d+ pattern, no backtracking
-			const failMatch = /(\d+) fail/.exec(output);  // NOSONAR S5852 - bounded \d+ pattern, no backtracking
-			const totalMatch = /Ran (\d+) tests/.exec(output);
-
-			if (passMatch || failMatch) {
-				const passed = passMatch ? Number.parseInt(passMatch[1], 10) : 0;
-				const failed = failMatch ? Number.parseInt(failMatch[1], 10) : 0;
-				const totalTests = totalMatch ? Number.parseInt(totalMatch[1], 10) : passed + failed;
-				return {
-					success: false,
-					passed,
-					failed,
-					totalTests,
-					error: `${failed} test${failed === 1 ? '' : 's'} failed`,
-				};
-			}
-		}
-
-		// Test execution failed (command not found or other error)
-		const bunNotFound = error.message.includes('ENOENT') || error.message.includes('not found');
-		const errorMsg = bunNotFound
-			? 'bun command not found. Ensure bun is installed and in PATH'
-			: `Test execution failed: ${error.message}`;
-
-		return {
-			success: false,
-			error: errorMsg,
-		};
-	}
-}
-
-/**
- * Get phase-specific TDD guidance
- * Provides actionable guidance for each TDD phase
- *
- * @param {'RED'|'GREEN'|'REFACTOR'} phase - Current TDD phase
- * @returns {string} Phase-specific guidance
- * @example
- * const guidance = getTDDGuidance('RED');
- * console.log(guidance); // "RED Phase: Write a failing test..."
- */
-function getTDDGuidance(phase) {
-	const guidance = {
-		RED: `RED Phase: Write a failing test
-
-1. Write test BEFORE implementation
-2. Test should fail (red)
-3. Verify test fails for the right reason
-4. Commit with "test: ..." message
-
-Next: GREEN phase (implement to make test pass)`,
-
-		GREEN: `GREEN Phase: Make the test pass
-
-1. Write MINIMAL code to pass the test
-2. Don't worry about perfection
-3. Focus on making tests green
-4. Commit with "feat: ..." or "implement: ..." message
-
-Next: REFACTOR phase (improve code quality)`,
-
-		REFACTOR: `REFACTOR Phase: Improve code quality
-
-1. Maintain passing tests throughout refactoring
-2. Extract duplicates, improve names, add docs
-3. Run tests frequently while refactoring
-4. Commit with "refactor: ..." message
-
-Next: RED phase (next feature) or done`,
-	};
-
-	return guidance[phase] || 'Unknown phase';
-}
-
-/**
- * Generate commit message for TDD phase
- * Creates standardized commit messages for each phase
- *
- * @param {{phase: 'RED'|'GREEN'|'REFACTOR', files: string[], testCount?: number, feature?: string, improvements?: string[]}} context - Commit context
- * @returns {string} Generated commit message
- * @example
- * const message = generateCommitMessage({ phase: 'RED', files: ['test/feature.test.js'], testCount: 15 });
- * console.log(message); // "test: add feature tests (RED)\n\n15 tests written"
- */
-function generateCommitMessage(context) {
-	const { phase, files, testCount, feature, improvements } = context;
-
-	if (phase === 'RED') {
-		const fileNames = files.map(f => path.basename(f)).join(', ');
-		return `test: add ${feature || 'feature'} tests (RED)
-
-${testCount || files.length} tests written
-Files: ${fileNames}
-
-Tests are failing as expected (RED phase)`;
-	}
-
-	if (phase === 'GREEN') {
-		const fileNames = files.map(f => path.basename(f)).join(', ');
-		return `feat: implement ${feature || 'feature'} (GREEN)
-
-Implementation complete, tests passing
-Files: ${fileNames}
-
-GREEN phase complete`;
-	}
-
-	if (phase === 'REFACTOR') {
-		const improvementList = improvements && improvements.length > 0
-			? '\n\n' + improvements.map(i => `- ${i}`).join('\n')
-			: '';
-		return `refactor: improve ${feature || 'code'} (REFACTOR)${improvementList}
-
-Code quality improvements while maintaining test coverage
-Tests remain green throughout refactoring`;
-	}
-
-	return `${phase}: ${feature || 'changes'}`;
-}
-
-/**
- * Identify independent features that can be worked on in parallel
- * Analyzes dependencies to find parallelizable work
- *
- * @param {Array<{name: string, files: string[], dependencies: string[]}>} features - Feature list with dependencies
- * @returns {{length: number, includes?: (name: string) => boolean, error?: string} | string[]} Parallel-safe features or error
- * @example
- * const parallel = identifyParallelWork([
- *   { name: 'feature-a', files: ['lib/a.js'], dependencies: [] },
- *   { name: 'feature-b', files: ['lib/b.js'], dependencies: [] }
- * ]);
- * console.log(parallel); // ['feature-a', 'feature-b']
- */
-function identifyParallelWork(features) {
-	// Check for circular dependencies
-	const visited = new Set();
-	const recStack = new Set();
-
-	function hasCycle(feature) {
-		if (!visited.has(feature.name)) {
-			visited.add(feature.name);
-			recStack.add(feature.name);
-
-			for (const dep of feature.dependencies) {
-				const depFeature = features.find(f => f.name === dep);
-				if (depFeature) {
-					if (!visited.has(dep) && hasCycle(depFeature)) {
-						return true;
-					} else if (recStack.has(dep)) {
-						return true;
-					}
-				}
-			}
-		}
-		recStack.delete(feature.name);
-		return false;
-	}
-
-	// Check for circular dependencies
-	for (const feature of features) {
-		if (hasCycle(feature)) {
-			return {
-				error: 'Circular dependency detected in features',
-			};
-		}
-	}
-
-	// Find features with no dependencies
-	const parallelFeatures = features
-		.filter(f => f.dependencies.length === 0)
-		.map(f => f.name);
-
-	return parallelFeatures;
-}
-
-/**
- * Execute dev command workflow
- * Main orchestrator for TDD development
- *
- * @param {string} featureName - Feature name
- * @param {{phase?: 'RED'|'GREEN'|'REFACTOR', testsPassing?: boolean}} [options] - Execution options
- * @returns {Promise<{success: boolean, phase?: string, detectedPhase?: string, guidance?: string, testResults?: object, summary?: string, nextPhase?: string, error?: string}>} Execution result
- * @example
- * const result = await executeDev('payment-integration', { phase: 'RED' });
- * console.log(result.guidance);
- */
-async function executeDev(featureName, options = {}) {
-	if (!featureName || typeof featureName !== 'string') {
-		return {
-			success: false,
-			error: 'Feature name is required and must be a string',
-		};
-	}
-
-	const { phase, testsPassing } = options;
-
-	try {
-		// If no phase specified, auto-detect
-		let currentPhase = phase;
-		if (!currentPhase) {
-			// Scan actual project directories to detect phase
-			const readDirSafe = (dir) => {
-				try { return fs.readdirSync(dir).filter(f => f.endsWith('.js')); }
-				catch (_e) { return []; }
-			};
-			const sourceFiles = readDirSafe('lib/commands');
-			const testFiles = readDirSafe('test/commands');
-			// Note: testsPassing is undefined here, so detectTDDPhase defaults to RED.
-			// RED is the safe default when pass/fail state is unknown (write tests first).
-			// Use --phase flag to explicitly specify GREEN or REFACTOR.
-			currentPhase = detectTDDPhase({ sourceFiles, testFiles, testsPassing });
-
-			return {
-				success: true,
-				detectedPhase: currentPhase,
-				autoDetected: true,
-				guidance: getTDDGuidance(currentPhase),
-				summary: `Default ${currentPhase} phase (use --phase flag for explicit phase control)`,
-			};
-		}
-
-		// Validate REFACTOR requires passing tests
-		if (phase === 'REFACTOR' && testsPassing === false) {
-			return {
-				success: false,
-				error: 'Cannot proceed to REFACTOR phase: tests are failing. Complete GREEN phase first.',
-			};
-		}
-
-		// Execute based on phase
-		const result = {
-			success: true,
-			phase: currentPhase,
-			guidance: getTDDGuidance(currentPhase),
-		};
-
-		if (currentPhase === 'RED') {
-			result.nextPhase = 'GREEN';
-			result.summary = 'Write failing tests for the feature';
-		} else if (currentPhase === 'GREEN') {
-			// Run tests to check status
-			const testResults = await runTests();
-			result.testResults = testResults;
-			result.success = testResults.success; // Reflect actual test outcome
-			if (!testResults.success) {
-				result.error = testResults.error || 'Tests failed';
-			}
-			result.nextPhase = 'REFACTOR';
-			result.summary = 'Implement feature to make tests pass';
-		} else if (currentPhase === 'REFACTOR') {
-			result.nextPhase = null; // Cycle complete
-			result.summary = 'Improve code quality while keeping tests green';
-		}
-
-		return result;
-	} catch (error) {
-		return {
-			success: false,
-			error: `Failed to execute dev command: ${error.message}`,
-		};
-	}
-}
-
-/**
- * Decision gate route constants
- *
- * Routes used by the /dev workflow decision gate:
- * - PROCEED: Score 0-3, implementer makes the decision and documents it
- * - SPEC-REVIEWER: Score 4-7, route to spec reviewer subagent
- * - BLOCKED: Score 8+ or mandatory override, surface to developer
- */
-const DECISION_ROUTES = {
-	PROCEED: 'PROCEED',
-	SPEC_REVIEWER: 'SPEC-REVIEWER',
-	BLOCKED: 'BLOCKED',
-};
-
-/**
- * Calculate the decision gate route based on a 7-dimension scoring rubric
- *
- * Each dimension is scored 0 (No), 1 (Possibly), or 2 (Yes):
- * 1. Files affected beyond the current task?
- * 2. Changes a function signature or public export?
- * 3. Changes a shared module used by other tasks?
- * 4. Changes or touches persistent data or schema?
- * 5. Changes user-visible behavior not discussed in design doc?
- * 6. Affects auth, permissions, or data exposure? (security — mandatory override if scored 2)
- * 7. Hard to reverse without cascading changes to other files?
- *
- * Score routing:
- * - 0-3:  PROCEED
- * - 4-7:  SPEC-REVIEWER
- * - 8+:   BLOCKED
- *
- * Mandatory override: dimension 6 (index 5) scored 2 → always BLOCKED
- *
- * @param {number} score - Total score (0-14)
- * @param {number[]} dimensions - Array of 7 scores (each 0, 1, or 2)
- * @returns {{route: string, score: number, mandatoryOverride?: boolean}} Routing result
- * @example
- * const result = calculateDecisionRoute(2, [1, 1, 0, 0, 0, 0, 0]);
- * console.log(result.route); // 'PROCEED'
- *
- * const securityBlocked = calculateDecisionRoute(2, [0, 0, 0, 0, 0, 2, 0]);
- * console.log(securityBlocked.route); // 'BLOCKED'
- * console.log(securityBlocked.mandatoryOverride); // true
- */
-function calculateDecisionRoute(score, dimensions) {
-	// Mandatory override: security dimension (dimension 6, zero-indexed as index 5) scored 2
-	const securityScore = Array.isArray(dimensions) ? dimensions[5] : undefined;
-	if (securityScore === 2) {
-		return { route: DECISION_ROUTES.BLOCKED, score, mandatoryOverride: true };
-	}
-
-	// Derive authoritative total from dimensions when available to prevent score/dimensions drift
-	const effectiveScore =
-		Array.isArray(dimensions) && dimensions.length === 7
-			? dimensions.reduce((a, b) => a + b, 0)
-			: score;
-
-	// Score-based routing
-	if (effectiveScore <= 3) {
-		return { route: DECISION_ROUTES.PROCEED, score: effectiveScore };
-	}
-
-	if (effectiveScore <= 7) {
-		return { route: DECISION_ROUTES.SPEC_REVIEWER, score: effectiveScore };
-	}
-
-	return { route: DECISION_ROUTES.BLOCKED, score: effectiveScore };
-}
-
-module.exports = {
-	detectTDDPhase,
-	identifyFilePairs,
-	runTests,
-	getTDDGuidance,
-	generateCommitMessage,
-	identifyParallelWork,
-	executeDev,
-	calculateDecisionRoute,
-	DECISION_ROUTES,
-};
+/**
+ * Dev Command - TDD Cycle Management
+ * Guides developers through RED-GREEN-REFACTOR cycles
+ *
+ * Security: Uses execFileSync for test execution to prevent command injection
+ * TDD Discipline: Enforces test-first development and validates phase transitions
+ *
+ * @module commands/dev
+ */
+
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function getExecOptions() {
+	return { encoding: 'utf8', cwd: process.cwd(), timeout: 120000 };
+}
+
+/**
+ * Detect current TDD phase based on project context
+ *
+ * Detection logic:
+ * - RED: Tests exist, no implementation OR implementation exists but tests failing
+ * - GREEN: Implementation exists, tests failing
+ * - REFACTOR: Implementation exists, tests passing
+ *
+ * @param {{sourceFiles: string[], testFiles: string[], testsPassing?: boolean}} context - Project context
+ * @returns {'RED'|'GREEN'|'REFACTOR'} Current TDD phase
+ * @example
+ * const phase = detectTDDPhase({ sourceFiles: ['lib/feature.js'], testFiles: ['test/feature.test.js'], testsPassing: true });
+ * console.log(phase); // 'REFACTOR'
+ */
+function detectTDDPhase(context) {
+	const { sourceFiles = [], testFiles = [], testsPassing } = context;
+
+	const hasTests = testFiles.length > 0;
+	const hasImplementation = sourceFiles.length > 0;
+
+	// RED: Tests exist but no implementation, or tests are failing
+	if (hasTests && !hasImplementation) {
+		return 'RED';
+	}
+
+	// GREEN: Tests failing with implementation
+	if (hasTests && hasImplementation && testsPassing === false) {
+		return 'GREEN';
+	}
+
+	// REFACTOR: Tests passing
+	if (hasTests && hasImplementation && testsPassing === true) {
+		return 'REFACTOR';
+	}
+
+	// Default to RED (write tests first)
+	return 'RED';
+}
+
+/**
+ * Identify source and test file pairs
+ * Maps source files to their corresponding test files
+ *
+ * Conventions:
+ * - lib/commands/feature.js → test/commands/feature.test.js
+ * - src/utils/helper.js → test/utils/helper.test.js
+ *
+ * @param {string[]} files - List of file paths
+ * @returns {{length: number, pairs?: Array<{source: string, test: string}>, orphanedTests?: string[], orphanedSources?: string[]}} File pair analysis
+ * @example
+ * const result = identifyFilePairs(['lib/feature.js', 'test/feature.test.js']);
+ * console.log(result.pairs); // [{ source: 'lib/feature.js', test: 'test/feature.test.js' }]
+ */
+function identifyFilePairs(files) {
+	const testFiles = files.filter(f => f.includes('test') && f.endsWith('.test.js'));
+	const sourceFiles = files.filter(f => !f.includes('test') && f.endsWith('.js'));
+
+	const pairs = [];
+	const orphanedTests = [];
+	const orphanedSources = [];
+
+	// Match test files to source files
+	testFiles.forEach(testFile => {
+		// Convert test/commands/feature.test.js → lib/commands/feature.js
+		const sourceFile = testFile
+			.replace(/^test\//, 'lib/')
+			.replace(/\.test\.js$/, '.js');
+
+		if (sourceFiles.includes(sourceFile)) {
+			pairs.push({ source: sourceFile, test: testFile });
+		} else {
+			orphanedTests.push(testFile);
+		}
+	});
+
+	// Find source files without tests
+	sourceFiles.forEach(sourceFile => {
+		const testFile = sourceFile
+			.replace(/^(lib|src)\//, 'test/')
+			.replace(/\.js$/, '.test.js');
+
+		if (!testFiles.includes(testFile)) {
+			orphanedSources.push(sourceFile);
+		}
+	});
+
+	return {
+		length: pairs.length,
+		pairs: pairs.length > 0 ? pairs : undefined,
+		orphanedTests: orphanedTests.length > 0 ? orphanedTests : undefined,
+		orphanedSources: orphanedSources.length > 0 ? orphanedSources : undefined,
+	};
+}
+
+/**
+ * Run tests using bun test
+ * Executes specified test file or all tests
+ *
+ * @param {string} [testFile] - Optional specific test file to run
+ * @returns {Promise<{success: boolean, passed?: number, failed?: number, duration?: number, totalTests?: number, error?: string}>} Test execution result
+ * @example
+ * const result = await runTests('test/commands/feature.test.js');
+ * console.log(`${result.passed}/${result.passed + result.failed} tests passed`);
+ */
+async function runTests(testFile) {
+	try {
+		const args = ['test'];
+		if (testFile) {
+			// Check if test file exists
+			if (!fs.existsSync(testFile)) {
+				return {
+					success: false,
+					error: `Test file not found: ${testFile}\n\nEnsure the file exists and path is correct.`,
+				};
+			}
+			args.push(testFile);
+		}
+
+		const startTime = Date.now();
+		const result = execFileSync('bun', args, getExecOptions());  // NOSONAR S4036 - hardcoded CLI command, no user input, developer tool context
+		const duration = Date.now() - startTime;
+
+		// Parse bun test output
+		// Format: "X pass\nY fail\nRan Z tests"
+		const passMatch = /(\d+) pass/.exec(result);  // NOSONAR S5852 - bounded \d+ pattern, no backtracking
+		const failMatch = /(\d+) fail/.exec(result);  // NOSONAR S5852 - bounded \d+ pattern, no backtracking
+		const totalMatch = /Ran (\d+) tests/.exec(result);
+
+		const passed = passMatch ? parseInt(passMatch[1], 10) : 0;
+		const failed = failMatch ? parseInt(failMatch[1], 10) : 0;
+		const totalTests = totalMatch ? parseInt(totalMatch[1], 10) : passed + failed;
+
+		return {
+			success: failed === 0,
+			passed,
+			failed,
+			totalTests,
+			duration,
+		};
+	} catch (error) {
+		// Check for timeout
+		if (error.killed && error.signal === 'SIGTERM') {
+			return {
+				success: false,
+				error: 'Test execution timed out after 2 minutes',
+			};
+		}
+
+		// bun test exits non-zero when tests fail but stdout still contains results
+		// Parse stdout to extract pass/fail counts before falling back to generic error
+		if (error.stdout) {
+			const output = error.stdout;
+			const passMatch = /(\d+) pass/.exec(output);  // NOSONAR S5852 - bounded \d+ pattern, no backtracking
+			const failMatch = /(\d+) fail/.exec(output);  // NOSONAR S5852 - bounded \d+ pattern, no backtracking
+			const totalMatch = /Ran (\d+) tests/.exec(output);
+
+			if (passMatch || failMatch) {
+				const passed = passMatch ? Number.parseInt(passMatch[1], 10) : 0;
+				const failed = failMatch ? Number.parseInt(failMatch[1], 10) : 0;
+				const totalTests = totalMatch ? Number.parseInt(totalMatch[1], 10) : passed + failed;
+				return {
+					success: false,
+					passed,
+					failed,
+					totalTests,
+					error: `${failed} test${failed === 1 ? '' : 's'} failed`,
+				};
+			}
+		}
+
+		// Test execution failed (command not found or other error)
+		const bunNotFound = error.message.includes('ENOENT') || error.message.includes('not found');
+		const errorMsg = bunNotFound
+			? 'bun command not found. Ensure bun is installed and in PATH'
+			: `Test execution failed: ${error.message}`;
+
+		return {
+			success: false,
+			error: errorMsg,
+		};
+	}
+}
+
+/**
+ * Get phase-specific TDD guidance
+ * Provides actionable guidance for each TDD phase
+ *
+ * @param {'RED'|'GREEN'|'REFACTOR'} phase - Current TDD phase
+ * @returns {string} Phase-specific guidance
+ * @example
+ * const guidance = getTDDGuidance('RED');
+ * console.log(guidance); // "RED Phase: Write a failing test..."
+ */
+function getTDDGuidance(phase) {
+	const guidance = {
+		RED: `RED Phase: Write a failing test
+
+1. Write test BEFORE implementation
+2. Test should fail (red)
+3. Verify test fails for the right reason
+4. Commit with "test: ..." message
+
+Next: GREEN phase (implement to make test pass)`,
+
+		GREEN: `GREEN Phase: Make the test pass
+
+1. Write MINIMAL code to pass the test
+2. Don't worry about perfection
+3. Focus on making tests green
+4. Commit with "feat: ..." or "implement: ..." message
+
+Next: REFACTOR phase (improve code quality)`,
+
+		REFACTOR: `REFACTOR Phase: Improve code quality
+
+1. Maintain passing tests throughout refactoring
+2. Extract duplicates, improve names, add docs
+3. Run tests frequently while refactoring
+4. Commit with "refactor: ..." message
+
+Next: RED phase (next feature) or done`,
+	};
+
+	return guidance[phase] || 'Unknown phase';
+}
+
+/**
+ * Generate commit message for TDD phase
+ * Creates standardized commit messages for each phase
+ *
+ * @param {{phase: 'RED'|'GREEN'|'REFACTOR', files: string[], testCount?: number, feature?: string, improvements?: string[]}} context - Commit context
+ * @returns {string} Generated commit message
+ * @example
+ * const message = generateCommitMessage({ phase: 'RED', files: ['test/feature.test.js'], testCount: 15 });
+ * console.log(message); // "test: add feature tests (RED)\n\n15 tests written"
+ */
+function generateCommitMessage(context) {
+	const { phase, files, testCount, feature, improvements } = context;
+
+	if (phase === 'RED') {
+		const fileNames = files.map(f => path.basename(f)).join(', ');
+		return `test: add ${feature || 'feature'} tests (RED)
+
+${testCount || files.length} tests written
+Files: ${fileNames}
+
+Tests are failing as expected (RED phase)`;
+	}
+
+	if (phase === 'GREEN') {
+		const fileNames = files.map(f => path.basename(f)).join(', ');
+		return `feat: implement ${feature || 'feature'} (GREEN)
+
+Implementation complete, tests passing
+Files: ${fileNames}
+
+GREEN phase complete`;
+	}
+
+	if (phase === 'REFACTOR') {
+		const improvementList = improvements && improvements.length > 0
+			? '\n\n' + improvements.map(i => `- ${i}`).join('\n')
+			: '';
+		return `refactor: improve ${feature || 'code'} (REFACTOR)${improvementList}
+
+Code quality improvements while maintaining test coverage
+Tests remain green throughout refactoring`;
+	}
+
+	return `${phase}: ${feature || 'changes'}`;
+}
+
+/**
+ * Identify independent features that can be worked on in parallel
+ * Analyzes dependencies to find parallelizable work
+ *
+ * @param {Array<{name: string, files: string[], dependencies: string[]}>} features - Feature list with dependencies
+ * @returns {{length: number, includes?: (name: string) => boolean, error?: string} | string[]} Parallel-safe features or error
+ * @example
+ * const parallel = identifyParallelWork([
+ *   { name: 'feature-a', files: ['lib/a.js'], dependencies: [] },
+ *   { name: 'feature-b', files: ['lib/b.js'], dependencies: [] }
+ * ]);
+ * console.log(parallel); // ['feature-a', 'feature-b']
+ */
+function identifyParallelWork(features) {
+	// Check for circular dependencies
+	const visited = new Set();
+	const recStack = new Set();
+
+	function hasCycle(feature) {
+		if (!visited.has(feature.name)) {
+			visited.add(feature.name);
+			recStack.add(feature.name);
+
+			for (const dep of feature.dependencies) {
+				const depFeature = features.find(f => f.name === dep);
+				if (depFeature) {
+					if (!visited.has(dep) && hasCycle(depFeature)) {
+						return true;
+					} else if (recStack.has(dep)) {
+						return true;
+					}
+				}
+			}
+		}
+		recStack.delete(feature.name);
+		return false;
+	}
+
+	// Check for circular dependencies
+	for (const feature of features) {
+		if (hasCycle(feature)) {
+			return {
+				error: 'Circular dependency detected in features',
+			};
+		}
+	}
+
+	// Find features with no dependencies
+	const parallelFeatures = features
+		.filter(f => f.dependencies.length === 0)
+		.map(f => f.name);
+
+	return parallelFeatures;
+}
+
+/**
+ * Execute dev command workflow
+ * Main orchestrator for TDD development
+ *
+ * @param {string} featureName - Feature name
+ * @param {{phase?: 'RED'|'GREEN'|'REFACTOR', testsPassing?: boolean}} [options] - Execution options
+ * @returns {Promise<{success: boolean, phase?: string, detectedPhase?: string, guidance?: string, testResults?: object, summary?: string, nextPhase?: string, error?: string}>} Execution result
+ * @example
+ * const result = await executeDev('payment-integration', { phase: 'RED' });
+ * console.log(result.guidance);
+ */
+async function executeDev(featureName, options = {}) {
+	if (!featureName || typeof featureName !== 'string') {
+		return {
+			success: false,
+			error: 'Feature name is required and must be a string',
+		};
+	}
+
+	const { phase, testsPassing } = options;
+
+	try {
+		// If no phase specified, auto-detect
+		let currentPhase = phase;
+		if (!currentPhase) {
+			// Scan actual project directories to detect phase
+			const readDirSafe = (dir) => {
+				try { return fs.readdirSync(dir).filter(f => f.endsWith('.js')); }
+				catch (_e) { return []; }
+			};
+			const sourceFiles = readDirSafe('lib/commands');
+			const testFiles = readDirSafe('test/commands');
+			// Note: testsPassing is undefined here, so detectTDDPhase defaults to RED.
+			// RED is the safe default when pass/fail state is unknown (write tests first).
+			// Use --phase flag to explicitly specify GREEN or REFACTOR.
+			currentPhase = detectTDDPhase({ sourceFiles, testFiles, testsPassing });
+
+			return {
+				success: true,
+				detectedPhase: currentPhase,
+				autoDetected: true,
+				guidance: getTDDGuidance(currentPhase),
+				summary: `Default ${currentPhase} phase (use --phase flag for explicit phase control)`,
+			};
+		}
+
+		// Validate REFACTOR requires passing tests
+		if (phase === 'REFACTOR' && testsPassing === false) {
+			return {
+				success: false,
+				error: 'Cannot proceed to REFACTOR phase: tests are failing. Complete GREEN phase first.',
+			};
+		}
+
+		// Execute based on phase
+		const result = {
+			success: true,
+			phase: currentPhase,
+			guidance: getTDDGuidance(currentPhase),
+		};
+
+		if (currentPhase === 'RED') {
+			result.nextPhase = 'GREEN';
+			result.summary = 'Write failing tests for the feature';
+		} else if (currentPhase === 'GREEN') {
+			// Run tests to check status
+			const testResults = await runTests();
+			result.testResults = testResults;
+			result.success = testResults.success; // Reflect actual test outcome
+			if (!testResults.success) {
+				result.error = testResults.error || 'Tests failed';
+			}
+			result.nextPhase = 'REFACTOR';
+			result.summary = 'Implement feature to make tests pass';
+		} else if (currentPhase === 'REFACTOR') {
+			result.nextPhase = null; // Cycle complete
+			result.summary = 'Improve code quality while keeping tests green';
+		}
+
+		return result;
+	} catch (error) {
+		return {
+			success: false,
+			error: `Failed to execute dev command: ${error.message}`,
+		};
+	}
+}
+
+/**
+ * Decision gate route constants
+ *
+ * Routes used by the /dev workflow decision gate:
+ * - PROCEED: Score 0-3, implementer makes the decision and documents it
+ * - SPEC-REVIEWER: Score 4-7, route to spec reviewer subagent
+ * - BLOCKED: Score 8+ or mandatory override, surface to developer
+ */
+const DECISION_ROUTES = {
+	PROCEED: 'PROCEED',
+	SPEC_REVIEWER: 'SPEC-REVIEWER',
+	BLOCKED: 'BLOCKED',
+};
+
+/**
+ * Calculate the decision gate route based on a 7-dimension scoring rubric
+ *
+ * Each dimension is scored 0 (No), 1 (Possibly), or 2 (Yes):
+ * 1. Files affected beyond the current task?
+ * 2. Changes a function signature or public export?
+ * 3. Changes a shared module used by other tasks?
+ * 4. Changes or touches persistent data or schema?
+ * 5. Changes user-visible behavior not discussed in design doc?
+ * 6. Affects auth, permissions, or data exposure? (security — mandatory override if scored 2)
+ * 7. Hard to reverse without cascading changes to other files?
+ *
+ * Score routing:
+ * - 0-3:  PROCEED
+ * - 4-7:  SPEC-REVIEWER
+ * - 8+:   BLOCKED
+ *
+ * Mandatory override: dimension 6 (index 5) scored 2 → always BLOCKED
+ *
+ * @param {number} score - Total score (0-14)
+ * @param {number[]} dimensions - Array of 7 scores (each 0, 1, or 2)
+ * @returns {{route: string, score: number, mandatoryOverride?: boolean}} Routing result
+ * @example
+ * const result = calculateDecisionRoute(2, [1, 1, 0, 0, 0, 0, 0]);
+ * console.log(result.route); // 'PROCEED'
+ *
+ * const securityBlocked = calculateDecisionRoute(2, [0, 0, 0, 0, 0, 2, 0]);
+ * console.log(securityBlocked.route); // 'BLOCKED'
+ * console.log(securityBlocked.mandatoryOverride); // true
+ */
+function calculateDecisionRoute(score, dimensions) {
+	// Mandatory override: security dimension (dimension 6, zero-indexed as index 5) scored 2
+	const securityScore = Array.isArray(dimensions) ? dimensions[5] : undefined;
+	if (securityScore === 2) {
+		return { route: DECISION_ROUTES.BLOCKED, score, mandatoryOverride: true };
+	}
+
+	// Derive authoritative total from dimensions when available to prevent score/dimensions drift
+	const effectiveScore =
+		Array.isArray(dimensions) && dimensions.length === 7
+			? dimensions.reduce((a, b) => a + b, 0)
+			: score;
+
+	// Score-based routing
+	if (effectiveScore <= 3) {
+		return { route: DECISION_ROUTES.PROCEED, score: effectiveScore };
+	}
+
+	if (effectiveScore <= 7) {
+		return { route: DECISION_ROUTES.SPEC_REVIEWER, score: effectiveScore };
+	}
+
+	return { route: DECISION_ROUTES.BLOCKED, score: effectiveScore };
+}
+
+/**
+ * Verify task completion and auto-commit changes if needed.
+ *
+ * Checks for uncommitted changes, stages only scoped files, commits,
+ * and returns the result. NEVER uses `git add -A` or `git add .`.
+ *
+ * Security: Uses execFileSync only (OWASP A03 — no shell injection).
+ *
+ * @param {string} taskTitle - The task title for the commit message
+ * @param {string[]|null|undefined} ownedFiles - Files this task owns (scoped staging). If falsy, stages tracked modified files only.
+ * @param {object} [opts] - Options
+ * @param {Function} [opts._exec] - Injected execFileSync for testing
+ * @returns {{committed: boolean, autoCommitted: boolean, commitSha: string|null, hasChanges: boolean}}
+ * @example
+ * const result = verifyTaskCompletion('add login form', ['lib/auth.js'], { _exec: mockExec });
+ */
+function verifyTaskCompletion(taskTitle, ownedFiles, opts = {}) {
+	const run = opts._exec || execFileSync;
+
+	// 1. Check for uncommitted changes
+	const status = run('git', ['status', '--porcelain']).toString().trim();
+
+	if (!status) {
+		return { committed: false, autoCommitted: false, commitSha: null, hasChanges: false };
+	}
+
+	// There are changes
+	let filesToStage = [];
+
+	if (ownedFiles && ownedFiles.length > 0) {
+		// 2. Stage only owned files — NEVER git add -A
+		filesToStage = ownedFiles;
+	} else {
+		// 3. Stage only tracked modified files from git diff --name-only
+		const diffOutput = run('git', ['diff', '--name-only']).toString().trim();
+		if (diffOutput) {
+			filesToStage = diffOutput.split('\n').filter(Boolean);
+		}
+	}
+
+	// If no files to stage, skip commit
+	if (filesToStage.length === 0) {
+		return { committed: false, autoCommitted: false, commitSha: null, hasChanges: true };
+	}
+
+	// Stage scoped files
+	run('git', ['add', ...filesToStage]);
+
+	// 4. Commit with standardized message
+	run('git', ['commit', '-m', `feat(task): ${taskTitle}`]);
+
+	// 5. Get commit sha
+	const commitSha = run('git', ['log', '-1', '--format=%H']).toString().trim();
+
+	return { committed: true, autoCommitted: true, commitSha, hasChanges: true };
+}
+
+module.exports = {
+	detectTDDPhase,
+	identifyFilePairs,
+	runTests,
+	getTDDGuidance,
+	generateCommitMessage,
+	identifyParallelWork,
+	executeDev,
+	calculateDecisionRoute,
+	DECISION_ROUTES,
+	verifyTaskCompletion,
+};