forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/commands/control.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * `forge control <gate-id|rail-id> <mandatory|optional|permission>`
+ * `forge control status [--json]`
+ *
+ * Tri-state control for the gate/rail CONFIG registry (`gate.*` / `rail.*`) —
+ * this sets *declared* intent, NOT runtime enforcement. Setting a state writes
+ * the SAME resolver-consumed field `forge gate` writes
+ * (`workflow.gates.<id>.enabled`); there is deliberately NO parallel `controls:`
+ * key, because a key the resolver never reads would be doubly-fake. The tri-state
+ * is the vocabulary; `enabled` is the stored truth (state is derived at read
+ * time). IMPORTANT: as of 2026-07-15 no runtime consumer denies on these flags —
+ * real enforcement lives independently (lefthook TDD hook, fail-closed
+ * validate/preflight, enforce-stage order+completion). See the guarantee matrix.
+ *
+ * For MCP servers / rules / skills it REFUSES with a clear "presence-only, not
+ * enforceable" message pointing at docs/reference/control-plane-guarantees.md,
+ * rather than pretend a control it cannot honor.
+ *
+ * `status` renders the all-surface read view with enforcement-locus badges
+ * (724356ea) so the UI never implies enforcement a surface lacks.
+ */
+
+const path = require('node:path');
+const { setConfigOverride } = require('../config-writer');
+const { getDefaultRuntimeGraph, getResolvedRuntimeGraph } = require('../core/runtime-graph');
+const {
+  classifySurface,
+  isControllable,
+  describeControl,
+  planControl,
+  GUARANTEE_DOC,
+} = require('../control-plane');
+
+function usage() {
+  return [
+    'Usage: forge control <gate-id|rail-id> <mandatory|optional|permission>',
+    '       forge control status [--json]',
+    '',
+    `Tri-state control for the gate/rail registry. These flags are DECLARED intent`,
+    `— today no runtime consumer denies on them (see the guarantee matrix). MCP/`,
+    `rules/skills are presence-only and refused — see ${GUARANTEE_DOC}.`,
+  ].join('\n');
+}
+
+// The known toggleable set is gates PLUS unlocked rails — exactly the surface
+// `forge gate` governs. Combined lookup because gate.* / rail.* namespaces are
+// disjoint. Used to validate an id BEFORE writing (never mid-run).
+function knownPrimitive(id) {
+  const graph = getDefaultRuntimeGraph();
+  return [...graph.gates, ...graph.rails].find(primitive => primitive.id === id);
+}
+
+function resolvedControls(projectRoot) {
+  const graph = getResolvedRuntimeGraph({ projectRoot });
+  return [...graph.gates, ...graph.rails].map(describeControl);
+}
+
+function renderStatus(records) {
+  const lines = ['Control plane — enforcement-locus per surface (honest to today wiring):', ''];
+  for (const rec of records) {
+    const state = rec.state ? ` [${rec.state}]` : '';
+    lines.push(`- ${rec.id}${state}  ${rec.badge}  (${rec.locus})`);
+  }
+  lines.push('');
+  lines.push(`No flag above is a wired runtime deny yet: real enforcement lives in`);
+  lines.push(`the lefthook TDD hook, fail-closed validate/preflight, and enforce-stage`);
+  lines.push(`order+completion — all independent of these flags. MCP/rules/skills are`);
+  lines.push(`presence-only (advisory) and not controllable here. See ${GUARANTEE_DOC}.`);
+  return `${lines.join('\n')}\n`;
+}
+
+function statusCommand(projectRoot, json) {
+  const records = resolvedControls(projectRoot);
+  if (json) {
+    return { success: true, output: `${JSON.stringify({ items: records }, null, 2)}\n` };
+  }
+  return { success: true, output: renderStatus(records) };
+}
+
+function setCommand(id, state, projectRoot) {
+  // Advisory surfaces (and unknown namespaces) are refused up front with the
+  // guarantee-matrix pointer — nothing is written.
+  if (!isControllable(id)) {
+    const plan = planControl({ id }, state);
+    return { success: false, error: plan.error };
+  }
+
+  // Validate the id is a real primitive BEFORE writing (mirrors `forge gate`).
+  const primitive = knownPrimitive(id);
+  if (!primitive) {
+    return {
+      success: false,
+      error: `Unknown ${classifySurface(id)} '${id}'. Run 'forge control status' to list controllable surfaces.`,
+    };
+  }
+
+  const plan = planControl({ id, locked: primitive.locked === true }, state);
+  if (!plan.ok) {
+    return { success: false, error: plan.error };
+  }
+
+  const { configPath } = setConfigOverride(
+    projectRoot,
+    ['workflow', 'gates', id, 'enabled'],
+    plan.enabled,
+  );
+  const where = path.relative(projectRoot, configPath) || configPath;
+  return {
+    success: true,
+    output: `set '${id}' to ${state} (workflow.gates.${id}.enabled=${plan.enabled}) in ${where}`,
+  };
+}
+
+async function handler(args, flags = {}, projectRoot = process.cwd()) {
+  const [first, second] = args;
+
+  if (first === 'status') {
+    // Reject junk after `status` (only the optional --json flag is allowed) so a
+    // typo like `forge control status enabled` errors instead of silently
+    // ignoring the extra token.
+    const extra = args.slice(1).filter(arg => arg !== '--json');
+    if (extra.length > 0) {
+      return {
+        success: false,
+        error: `Unexpected argument(s) for status: ${extra.join(', ')}.\n${usage()}`,
+      };
+    }
+    return statusCommand(projectRoot, flags.json === true || args.includes('--json'));
+  }
+
+  if (!first) {
+    return { success: false, error: usage() };
+  }
+  if (!second) {
+    return { success: false, error: `Missing state.\n${usage()}` };
+  }
+
+  return setCommand(first, second, projectRoot);
+}
+
+module.exports = {
+  name: 'control',
+  description: 'Set tri-state control (mandatory/optional/permission) for a gate or rail',
+  usage: usage(),
+  handler,
+};

package/lib/commands/create.js

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

package/lib/commands/dev.js

@@ -11,6 +11,7 @@
 const { execFileSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
+const { recordAndLabelSubagentAuditEvent } = require('../audit-evidence');
 
 function getExecOptions() {
 	return { encoding: 'utf8', cwd: process.cwd(), timeout: 120000 };
@@ -380,21 +381,24 @@ async function executeDev(featureName, options = {}) {
 			// Use --phase flag to explicitly specify GREEN or REFACTOR.
 			currentPhase = detectTDDPhase({ sourceFiles, testFiles, testsPassing });
 
-			return {
+			const result = {
 				success: true,
 				detectedPhase: currentPhase,
 				autoDetected: true,
 				guidance: getTDDGuidance(currentPhase),
 				summary: `Default ${currentPhase} phase (use --phase flag for explicit phase control)`,
 			};
+
+			return withDevAuditEvidence(featureName, currentPhase, result, options);
 		}
 
 		// Validate REFACTOR requires passing tests
 		if (phase === 'REFACTOR' && testsPassing === false) {
-			return {
+			const result = {
 				success: false,
 				error: 'Cannot proceed to REFACTOR phase: tests are failing. Complete GREEN phase first.',
 			};
+			return withDevAuditEvidence(featureName, currentPhase, result, options);
 		}
 
 		// Execute based on phase
@@ -409,7 +413,8 @@ async function executeDev(featureName, options = {}) {
 			result.summary = 'Write failing tests for the feature';
 		} else if (currentPhase === 'GREEN') {
 			// Run tests to check status
-			const testResults = await runTests();
+			const runPhaseTests = options.runTests || runTests;
+			const testResults = await runPhaseTests();
 			result.testResults = testResults;
 			result.success = testResults.success; // Reflect actual test outcome
 			if (!testResults.success) {
@@ -422,7 +427,7 @@ async function executeDev(featureName, options = {}) {
 			result.summary = 'Improve code quality while keeping tests green';
 		}
 
-		return result;
+		return withDevAuditEvidence(featureName, currentPhase, result, options);
 	} catch (error) {
 		return {
 			success: false,
@@ -431,6 +436,74 @@ async function executeDev(featureName, options = {}) {
 	}
 }
 
+function withDevAuditEvidence(featureName, phase, result, options = {}) {
+	if (!options.audit) {
+		return result;
+	}
+
+	const auditEvent = {
+		issueId: options.issueId,
+		phase,
+		taskTitle: `forge dev ${featureName}`,
+		prompt: `forge dev ${featureName} ${phase}`,
+		response: result.success === false
+			? result.error || result.summary || result.guidance || ''
+			: result.summary || result.error || result.guidance || '',
+		verdict: result.success === false ? 'FAIL' : 'PASS',
+		metadata: {
+			featureName,
+			phase,
+			detectedPhase: result.detectedPhase,
+			nextPhase: result.nextPhase,
+			autoDetected: Boolean(result.autoDetected),
+			success: result.success !== false,
+		},
+	};
+
+	try {
+		const auditEvidence = emitImplementerAuditEvidence(auditEvent, options.auditOptions || {});
+		if (auditEvidence.record?.success === false) {
+			const auditError = auditEvidence.record.error || 'bd audit record failed';
+			return {
+				...result,
+				success: false,
+				error: result.success === false ? result.error : `Audit evidence persistence failed: ${auditError}`,
+				auditEvidence,
+			};
+		}
+
+		return {
+			...result,
+			auditEvidence,
+		};
+	} catch (error) {
+		if (isAuditCommandUnavailableError(error)) {
+			return {
+				...result,
+				auditEvidence: {
+					success: false,
+					skipped: true,
+					error: error.message,
+				},
+			};
+		}
+
+		return {
+			...result,
+			success: false,
+			error: result.success === false ? result.error : `Audit evidence persistence failed: ${error.message}`,
+			auditEvidence: {
+				success: false,
+				error: error.message,
+			},
+		};
+	}
+}
+
+function isAuditCommandUnavailableError(error) {
+	return error?.code === 'ENOENT' || /\bbd\b.*not found/i.test(error?.message || '');
+}
+
 /**
  * Decision gate route constants
  *
@@ -557,12 +630,109 @@ function verifyTaskCompletion(taskTitle, ownedFiles, opts = {}) {
 	return { committed: true, autoCommitted: true, commitSha, hasChanges: true };
 }
 
+function emitDevSubagentAuditEvidence(role, phase, event = {}, options = {}) {
+	const safeEvent = event && typeof event === 'object' ? event : {};
+	return recordAndLabelSubagentAuditEvent({
+		...safeEvent,
+		command: 'dev',
+		role,
+		phase: phase || safeEvent.phase,
+	}, options);
+}
+
+function emitImplementerAuditEvidence(event, options = {}) {
+	return emitDevSubagentAuditEvidence('implementer', event?.phase || 'GREEN', event, options);
+}
+
+function emitSpecReviewerAuditEvidence(event, options = {}) {
+	return emitDevSubagentAuditEvidence('spec_reviewer', 'SPEC', event, options);
+}
+
+function emitQualityReviewerAuditEvidence(event, options = {}) {
+	return emitDevSubagentAuditEvidence('quality_reviewer', 'QUALITY', event, options);
+}
+
+function isMissingDevFlagValue(value) {
+	return value === undefined || value === '' || (typeof value === 'string' && value.startsWith('--'));
+}
+
+function missingDevFlagValue(name, parsedArgs, flags) {
+	return { args: parsedArgs, flags, error: `${name} requires a value` };
+}
+
+function consumeSeparatedDevFlag(name, key, rawArgs, index, parsedArgs, flags) {
+	const value = rawArgs[index + 1];
+	if (isMissingDevFlagValue(value)) {
+		return missingDevFlagValue(name, parsedArgs, flags);
+	}
+
+	flags[key] = value;
+	return { consumed: 2 };
+}
+
+function consumeEqualsDevFlag(prefix, name, key, arg, parsedArgs, flags) {
+	const value = arg.slice(prefix.length);
+	if (value === '') {
+		return missingDevFlagValue(name, parsedArgs, flags);
+	}
+
+	flags[key] = value;
+	return { consumed: 1 };
+}
+
+function consumeDevFlag(rawArgs, index, parsedArgs, flags) {
+	const arg = rawArgs[index];
+	if (arg === '--issue-id') {
+		return consumeSeparatedDevFlag('--issue-id', 'issueId', rawArgs, index, parsedArgs, flags);
+	}
+	if (typeof arg === 'string' && arg.startsWith('--issue-id=')) {
+		return consumeEqualsDevFlag('--issue-id=', '--issue-id', 'issueId', arg, parsedArgs, flags);
+	}
+	if (arg === '--phase') {
+		return consumeSeparatedDevFlag('--phase', 'phase', rawArgs, index, parsedArgs, flags);
+	}
+	if (typeof arg === 'string' && arg.startsWith('--phase=')) {
+		return consumeEqualsDevFlag('--phase=', '--phase', 'phase', arg, parsedArgs, flags);
+	}
+
+	return { consumed: 0 };
+}
+
+function parseDevHandlerInput(rawArgs = [], rawFlags = {}) {
+	const parsedArgs = [];
+	const flags = { ...rawFlags };
+	if (flags['issue-id'] && !flags.issueId) {
+		flags.issueId = flags['issue-id'];
+	}
+
+	for (let i = 0; i < rawArgs.length; i++) {
+		const consumed = consumeDevFlag(rawArgs, i, parsedArgs, flags);
+		if (consumed.error) {
+			return consumed;
+		}
+		if (consumed.consumed > 0) {
+			i += consumed.consumed - 1;
+			continue;
+		}
+		parsedArgs.push(rawArgs[i]);
+	}
+
+	return { args: parsedArgs, flags };
+}
+
 module.exports = {
 	name: 'dev',
 	description: 'Run the TDD development stage with phase guidance',
 	handler: async (args, flags = {}) => {
-		const featureName = args[0] || 'feature';
-		const phaseInput = flags.phase || args[1];
+		const parsed = parseDevHandlerInput(args, flags);
+		if (parsed.error) {
+			return {
+				success: false,
+				error: parsed.error,
+			};
+		}
+		const featureName = parsed.args[0] || 'feature';
+		const phaseInput = parsed.flags.phase || parsed.args[1];
 		const phase = typeof phaseInput === 'string' ? phaseInput.toUpperCase() : undefined;
 		if (phase && !['RED', 'GREEN', 'REFACTOR'].includes(phase)) {
 			return {
@@ -571,7 +741,12 @@ module.exports = {
 			};
 		}
 
-		const result = await executeDev(featureName, phase ? { phase } : {});
+		const result = await executeDev(featureName, {
+			...(phase ? { phase } : {}),
+			audit: true,
+			issueId: parsed.flags.issueId,
+			auditOptions: parsed.flags.auditOptions,
+		});
 		if (!result.success) {
 			return result;
 		}
@@ -591,6 +766,9 @@ module.exports = {
 	generateCommitMessage,
 	identifyParallelWork,
 	executeDev,
+	emitImplementerAuditEvidence,
+	emitSpecReviewerAuditEvidence,
+	emitQualityReviewerAuditEvidence,
 	calculateDecisionRoute,
 	DECISION_ROUTES,
 	verifyTaskCompletion,