forge-workflow 0.0.2 → 0.0.4

package/lib/commands/plan.js

@@ -1,5 +1,5 @@
 /**
- * Plan Command - OpenSpec & Beads Integration
+ * Plan Command - Beads Integration
  * Creates implementation plan after research is complete
  *
  * Security: Uses execFileSync instead of exec/execSync to prevent command injection
@@ -123,18 +123,18 @@ function readResearchDoc(featureSlug) {
  * 3. Default to tactical if no clear signals
  *
  * @param {string} researchContent - Research document markdown content
- * @returns {{type: 'tactical'|'strategic', requiresOpenSpec: boolean, reason: string}} Scope analysis result
+ * @returns {{type: 'tactical'|'strategic', requiresDesignDoc: boolean, reason: string}} Scope analysis result
  * @example
  * const scope = detectScope(researchMarkdown);
  * if (scope.type === 'strategic') {
- *   console.log('Requires OpenSpec proposal:', scope.reason);
+ *   console.log('Requires design doc:', scope.reason);
  * }
  */
 function detectScope(researchContent) {
 	if (!researchContent || typeof researchContent !== 'string') {
 		return {
 			type: 'tactical',
-			requiresOpenSpec: false,
+			requiresDesignDoc: false,
 			reason: 'Invalid research content (defaulting to tactical)',
 		};
 	}
@@ -166,7 +166,7 @@ function detectScope(researchContent) {
 		const type = scopeMatch[1].toLowerCase();
 		return {
 			type,
-			requiresOpenSpec: type === 'strategic',
+			requiresDesignDoc: type === 'strategic',
 			reason: `Explicit scope declaration: ${scopeMatch[1]}`,
 		};
 	}
@@ -190,7 +190,7 @@ function detectScope(researchContent) {
 	if (foundKeywords.length > 0) {
 		return {
 			type: 'strategic',
-			requiresOpenSpec: true,
+			requiresDesignDoc: true,
 			reason: `Strategic keywords detected: ${foundKeywords.join(', ')}`,
 		};
 	}
@@ -198,7 +198,7 @@ function detectScope(researchContent) {
 	// Default to tactical (safe fallback)
 	return {
 		type: 'tactical',
-		requiresOpenSpec: false,
+		requiresDesignDoc: false,
 		reason: 'No strategic indicators found (tactical by default)',
 	};
 }
@@ -244,7 +244,7 @@ function createBeadsIssue(featureName, researchPath, scope) {
 			if (!slugValidation.valid) {
 				return { success: false, error: `Cannot generate valid slug from feature name: ${slugValidation.error}` };
 			}
-			description += `\n\nOpenSpec: openspec/changes/${featureSlug}/`;
+			description += `\n\nDesign: docs/plans/${featureSlug}-design.md`;
 		}
 
 		// Execute bd create command using execFileSync for safety (OWASP A03)
@@ -585,12 +585,9 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  * Strategic workflow (architecture changes, >1 day):
  * 1. Read research document
  * 2. Detect scope (strategic)
- * 3. Create Beads issue with OpenSpec link
+ * 3. Create Beads issue with design doc link
  * 4. Create feature branch
- * 5. Generate OpenSpec proposal (proposal.md, tasks.md, design.md)
- * 6. Commit and push proposal
- * 7. Create proposal PR
- * → Next: Wait for proposal approval
+ * → Next: Create design doc, then /dev command
  *
  * @param {string} featureName - Feature name (human-readable, e.g., "Payment Integration")
  * @returns {Promise<{
@@ -598,8 +595,7 @@ function applyYAGNIFilter({ task, tasks, designDoc } = {}) {
  *   scope?: 'tactical'|'strategic',
  *   beadsIssueId?: string,
  *   branchName?: string,
- *   openSpecCreated?: boolean,
- *   proposalPR?: {url: string, number: number},
+ *
  *   summary?: string,
  *   nextCommand?: string,
  *   error?: string

package/lib/commands/recommend.js

@@ -20,10 +20,10 @@ const STAGE_NAMES = {
   research: 'Research',
   plan: 'Plan',
   dev: 'Dev',
-  check: 'Check',
+  validate: 'Validate',
   ship: 'Ship',
   review: 'Review',
-  merge: 'Merge',
+  premerge: 'Premerge',
 };
 
 /**

package/lib/dep-guard/analyzer.js

@@ -0,0 +1,294 @@
+const { scoreImportDependencies } = require('./import-detector.js');
+const { parseTaskFile } = require('./task-parser.js');
+const { scoreContractDependencies } = require('./contract-detector.js');
+const { scoreBehavioralDependencies } = require('./behavior-detector.js');
+const { WEIGHTS: RUBRIC_WEIGHTS, aggregateRubricScores, needsUserEscalation } = require('./rubric.js');
+const { normalizeRepoPath } = require('./path-utils.js');
+
+const CONFIDENCE_THRESHOLD = 0.7;
+const DETECTOR_KEYS = Object.freeze([
+	'importCallChain',
+	'contractDependencies',
+	'behavioralDependencies',
+]);
+
+function createZeroedDetectorMap() {
+	return DETECTOR_KEYS.reduce((result, key) => {
+		result[key] = 0;
+		return result;
+	}, {});
+}
+
+function createEmptyDetectorEvidence() {
+	return DETECTOR_KEYS.reduce((result, key) => {
+		result[key] = [];
+		return result;
+	}, {});
+}
+
+function normalizeContractToken(contract) {
+	if (typeof contract !== 'string') {
+		return null;
+	}
+
+	const separatorIndex = contract.indexOf(':');
+	if (separatorIndex === -1) {
+		return contract;
+	}
+
+	return `${normalizeRepoPath(contract.slice(0, separatorIndex))}${contract.slice(separatorIndex)}`;
+}
+
+function normalizeContractNotes(notes = '') {
+	return notes
+		.split(/\r?\n/)
+		.map((line) => {
+			const marker = ': ';
+			if (!line.startsWith('contracts@') || !line.includes(marker)) {
+				return line;
+			}
+
+			const separatorIndex = line.indexOf(marker);
+			const prefix = line.slice(0, separatorIndex + marker.length);
+			const payload = line.slice(separatorIndex + marker.length);
+			const normalizedPayload = payload
+				.split(/\s+/)
+				.map(normalizeContractToken)
+				.join(' ');
+			return `${prefix}${normalizedPayload}`;
+		})
+		.join('\n');
+}
+
+function normalizeIssue(issue, label) {
+	if (!issue || typeof issue !== 'object') {
+		throw new Error(`${label} is required`);
+	}
+
+	if (!issue.id || typeof issue.id !== 'string') {
+		throw new Error(`${label} id is required`);
+	}
+
+	return {
+		id: issue.id,
+		title: typeof issue.title === 'string' ? issue.title : '',
+		description: typeof issue.description === 'string' ? issue.description : '',
+		status: typeof issue.status === 'string' ? issue.status : '',
+		contracts: Array.isArray(issue.contracts)
+			? issue.contracts.map(normalizeContractToken).filter((contract) => typeof contract === 'string')
+			: [],
+		files: Array.isArray(issue.files)
+			? issue.files
+				.filter((file) => typeof file === 'string')
+				.map((file) => normalizeRepoPath(file))
+			: [],
+		notes: typeof issue.notes === 'string' ? normalizeContractNotes(issue.notes) : '',
+	};
+}
+
+function normalizePhase3Input(input = {}) {
+	const currentIssue = normalizeIssue(input.currentIssue, 'Current issue');
+	const openIssues = Array.isArray(input.openIssues)
+		? input.openIssues.map((issue) => normalizeIssue(issue, 'Open issue'))
+		: [];
+	const taskContext = input.taskContext ?? parseTaskFile(input.taskFile);
+
+	return {
+		currentIssue,
+		openIssues,
+		taskContext,
+		repositoryRoot: typeof input.repositoryRoot === 'string' && input.repositoryRoot
+			? input.repositoryRoot
+			: process.cwd(),
+		thresholds: {
+			confidence: CONFIDENCE_THRESHOLD,
+		},
+	};
+}
+
+function createScaffoldResult(normalizedInput) {
+	const detectorScores = createZeroedDetectorMap();
+
+	return {
+		currentIssue: normalizedInput.currentIssue,
+		taskContext: normalizedInput.taskContext,
+		issues: [],
+		scores: {
+			...detectorScores,
+			rubric: 0,
+		},
+		rubric: {
+			score: 0,
+			threshold: normalizedInput.thresholds.confidence,
+			summary: 'No detector findings yet.',
+			weights: RUBRIC_WEIGHTS,
+			reasons: [],
+		},
+		detectorEvidence: createEmptyDetectorEvidence(),
+		detectorConflicts: [],
+		importCallChain: {
+			score: 0,
+			evidence: [],
+			findings: [],
+		},
+		contractDependencies: {
+			score: 0,
+			evidence: [],
+			findings: [],
+		},
+		behavioralDependencies: {
+			score: 0,
+			evidence: [],
+			findings: [],
+			uncertain: false,
+		},
+		confidence: {
+			score: 1,
+			threshold: normalizedInput.thresholds.confidence,
+			belowThreshold: false,
+			reasons: [],
+		},
+		proposals: [],
+		needsUserDecision: false,
+		metadata: {
+			analyzerVersion: 'phase3-v1-scaffold',
+			parser: '@babel/parser',
+		},
+	};
+}
+
+function inferDetectorType(finding) {
+	if (finding.behavioralSignal) {
+		return 'behavioralDependencies';
+	}
+
+	const firstEvidenceType = finding.evidence?.[0]?.type;
+	if (firstEvidenceType === 'contract') {
+		return 'contractDependencies';
+	}
+
+	return 'importCallChain';
+}
+
+function formatDetectorList(detectorTypes) {
+	const labels = detectorTypes.map((type) => {
+		if (type === 'importCallChain') {
+			return 'import/call-chain evidence';
+		}
+		if (type === 'contractDependencies') {
+			return 'contract evidence';
+		}
+		return 'behavioral evidence';
+	});
+
+	return labels.join(', ');
+}
+
+function buildDependencyProposals(normalizedInput, findings, rubricResult) {
+	if (findings.length === 0) {
+		return [];
+	}
+
+	const groupedFindings = new Map();
+	for (const finding of findings) {
+		const entry = groupedFindings.get(finding.targetIssueId) ?? {
+			targetIssueId: finding.targetIssueId,
+			detectorTypes: new Set(),
+			hasBehavioralUncertainty: false,
+		};
+		entry.detectorTypes.add(inferDetectorType(finding));
+		entry.hasBehavioralUncertainty = entry.hasBehavioralUncertainty || Boolean(finding.uncertain);
+		groupedFindings.set(finding.targetIssueId, entry);
+	}
+
+	return Array.from(groupedFindings.values()).map((entry) => {
+		const detectorTypes = Array.from(entry.detectorTypes);
+		const reasons = [
+			`${entry.targetIssueId} appears to consume or rely on logic being changed in ${normalizedInput.currentIssue.id} through ${formatDetectorList(detectorTypes)}.`,
+		];
+		const cons = [
+			'Adds coordination overhead and may delay the dependent issue.',
+		];
+
+		if (entry.hasBehavioralUncertainty) {
+			reasons.push('Behavioral evidence is heuristic and should be confirmed before applying the dependency.');
+			cons.push('Behavioral evidence is heuristic and may be noisy until a human confirms the dependency.');
+		}
+
+		if (rubricResult.confidence.belowThreshold) {
+			reasons.push(`Overall confidence ${rubricResult.confidence.score.toFixed(2)} is below the review threshold.`);
+		}
+
+		return {
+			action: 'add-dependency',
+			dependentIssueId: entry.targetIssueId,
+			dependsOnIssueId: normalizedInput.currentIssue.id,
+			detectorTypes,
+			requiresApproval: true,
+			confidence: rubricResult.confidence.score,
+			reasons,
+			pros: [
+				'Preserves issue independence claims by sequencing affected work explicitly.',
+				'Reduces merge-order surprises for downstream logic consumers.',
+			],
+			cons,
+		};
+	});
+}
+
+function analyzePhase3Dependencies(input = {}) {
+	const normalizedInput = normalizePhase3Input(input);
+	const result = createScaffoldResult(normalizedInput);
+	const importResult = scoreImportDependencies(normalizedInput);
+	const contractResult = scoreContractDependencies(normalizedInput);
+	const behavioralResult = scoreBehavioralDependencies(normalizedInput);
+	const rubricResult = aggregateRubricScores({
+		importCallChain: importResult,
+		contractDependencies: contractResult,
+		behavioralDependencies: behavioralResult,
+	}, {
+		confidenceThreshold: normalizedInput.thresholds.confidence,
+	});
+
+	result.issues = [
+		...importResult.findings,
+		...contractResult.findings,
+		...behavioralResult.findings,
+	];
+	result.scores.importCallChain = importResult.score;
+	result.scores.contractDependencies = contractResult.score;
+	result.scores.behavioralDependencies = behavioralResult.score;
+	result.scores.rubric = rubricResult.total;
+	result.rubric = rubricResult;
+	result.detectorEvidence.importCallChain = importResult.evidence;
+	result.detectorEvidence.contractDependencies = contractResult.evidence;
+	result.detectorEvidence.behavioralDependencies = behavioralResult.evidence;
+	result.detectorConflicts = rubricResult.detectorConflicts;
+	result.confidence = rubricResult.confidence;
+	result.needsUserDecision = needsUserEscalation(rubricResult);
+	result.proposals = buildDependencyProposals(normalizedInput, result.issues, rubricResult);
+	result.importCallChain = {
+		score: importResult.score,
+		evidence: importResult.evidence,
+		findings: importResult.findings,
+	};
+	result.contractDependencies = {
+		score: contractResult.score,
+		evidence: contractResult.evidence,
+		findings: contractResult.findings,
+	};
+	result.behavioralDependencies = {
+		score: behavioralResult.score,
+		evidence: behavioralResult.evidence,
+		findings: behavioralResult.findings,
+		uncertain: behavioralResult.uncertain,
+	};
+
+	return result;
+}
+
+module.exports = {
+	analyzePhase3Dependencies,
+	DETECTOR_KEYS,
+	normalizePhase3Input,
+};

package/lib/dep-guard/behavior-detector.js

@@ -0,0 +1,98 @@
+const STOP_WORDS = new Set([
+	'the', 'a', 'an', 'and', 'or', 'is', 'in', 'to', 'for', 'of', 'with', 'on',
+	'at', 'by', 'from', 'add', 'fix', 'update', 'implement', 'create', 'remove',
+	'delete', 'make', 'use', 'get', 'set', 'run', 'test', 'check', 'this', 'that',
+	'it', 'be', 'as', 'not', 'no', 'but', 'if', 'do', 'we', 'they', 'are', 'was',
+	'were', 'been', 'have', 'has', 'had', 'will', 'would', 'could', 'should',
+	'may', 'can', 'each', 'every', 'both', 'also', 'into', 'than', 'then', 'when',
+	'where', 'which', 'what', 'how', 'why', 'who', 'its', 'new', 'first', 'last',
+	'same', 'other',
+]);
+
+const BEHAVIOR_TERMS = new Set([
+	'approval', 'behavior', 'confidence', 'default', 'manual', 'ordering',
+	'output', 'policy', 'review', 'rules', 'rule', 'threshold', 'validation',
+	'workflow', 'state',
+]);
+const STRONG_SIGNAL_TERMS = new Set([
+	'approval',
+	'confidence',
+	'manual',
+	'policy',
+	'review',
+	'rule',
+	'rules',
+	'threshold',
+]);
+
+function tokenize(text) {
+	return Array.from(new Set(
+		text
+			.toLowerCase()
+			.split(/[^a-z0-9]+/)
+			.filter((term) => term.length >= 3 && !STOP_WORDS.has(term)),
+	));
+}
+
+function scoreBehavioralDependencies(normalizedInput) {
+	const taskText = normalizedInput.taskContext.tasks
+		.map((task) => task.whatToImplement)
+		.join(' ');
+	const taskTerms = tokenize(taskText).filter((term) => BEHAVIOR_TERMS.has(term));
+
+	if (taskTerms.length === 0) {
+		return {
+			score: 0,
+			findings: [],
+			evidence: [],
+			uncertain: false,
+		};
+	}
+
+	const findings = [];
+	const evidence = [];
+
+	for (const issue of normalizedInput.openIssues) {
+		const issueText = [issue.title, issue.description, issue.notes].filter(Boolean).join(' ');
+		const issueTerms = new Set(tokenize(issueText));
+		const sharedTerms = taskTerms.filter((term) => issueTerms.has(term));
+
+		if (sharedTerms.length < 2) {
+			continue;
+		}
+
+		const strongSignalCount = sharedTerms.filter((term) => STRONG_SIGNAL_TERMS.has(term)).length;
+		const isUncertain = strongSignalCount < 2 || sharedTerms.length < 3;
+		const signal = sharedTerms.some((term) => ['rule', 'rules', 'policy', 'approval'].includes(term))
+			? 'rule-change-overlap'
+			: 'behavior-change-overlap';
+		const issueEvidence = sharedTerms.map((term) => ({
+			type: 'behavior',
+			targetIssueId: issue.id,
+			sharedTerms: sharedTerms,
+			term,
+			scoreContribution: 1,
+		}));
+
+		findings.push({
+			sourceIssueId: normalizedInput.currentIssue.id,
+			targetIssueId: issue.id,
+			score: sharedTerms.length,
+			behavioralSignal: signal,
+			uncertain: isUncertain,
+			evidence: issueEvidence,
+		});
+		evidence.push(...issueEvidence);
+	}
+
+	return {
+		score: findings.reduce((total, finding) => total + finding.score, 0),
+		findings,
+		evidence,
+		uncertain: findings.some((finding) => finding.uncertain),
+	};
+}
+
+module.exports = {
+	scoreBehavioralDependencies,
+};

package/lib/dep-guard/contract-detector.js

@@ -0,0 +1,162 @@
+const { detectContractType, extractTaskContracts } = require('./task-parser.js');
+const { normalizeRepoPath } = require('./path-utils.js');
+
+function isIdentifier(name) {
+	return typeof name === 'string' && /^[A-Za-z_]\w*$/.test(name);
+}
+
+function isCommandContractName(name) {
+	return typeof name === 'string' && /^[A-Za-z_][\w-]*$/.test(name);
+}
+
+function parseContractToken(token) {
+	if (typeof token !== 'string') {
+		return null;
+	}
+
+	const trimmed = token.trim();
+	if (!trimmed) {
+		return null;
+	}
+
+	let annotation = '';
+	let contractTarget = trimmed;
+	const openParenIndex = trimmed.lastIndexOf('(');
+	if (openParenIndex !== -1 && trimmed.endsWith(')')) {
+		annotation = trimmed.slice(openParenIndex + 1, -1);
+		contractTarget = trimmed.slice(0, openParenIndex);
+	}
+
+	const separatorIndex = contractTarget.lastIndexOf(':');
+	if (separatorIndex <= 0 || separatorIndex === contractTarget.length - 1) {
+		return null;
+	}
+
+	const file = normalizeRepoPath(contractTarget.slice(0, separatorIndex));
+	const symbol = contractTarget.slice(separatorIndex + 1);
+	const contractType = detectContractType(symbol, annotation);
+
+	const validSymbol = contractType === 'command-contract'
+		? isCommandContractName(symbol)
+		: isIdentifier(symbol);
+	if (!validSymbol) {
+		return null;
+	}
+
+	return {
+		contract: `${file}:${symbol}(${contractType})`,
+		file,
+		symbol,
+		contractType,
+	};
+}
+
+function parseStoredContractsFromNotes(notes = '') {
+	if (!notes || typeof notes !== 'string') {
+		return [];
+	}
+
+	const contractLines = notes
+		.split(/\r?\n/)
+		.filter((line) => line.startsWith('contracts@') && line.includes(': '));
+	if (contractLines.length === 0) {
+		return [];
+	}
+
+	contractLines.sort((left, right) => left.localeCompare(right));
+	const latestLine = contractLines.at(-1);
+	const latestPayload = latestLine.slice(latestLine.indexOf(': ') + 2);
+
+	return latestPayload
+		.split(/\s+/)
+		.map((token) => token.trim())
+		.filter(Boolean);
+}
+
+function mergeEvidence(evidence) {
+	const seen = new Set();
+	return evidence.filter((item) => {
+		const key = `${item.contract}:${item.storedContract}:${item.targetIssueId}`;
+		if (seen.has(key)) {
+			return false;
+		}
+		seen.add(key);
+		return true;
+	});
+}
+
+function scoreContractDependencies(normalizedInput) {
+	const currentContracts = extractTaskContracts(normalizedInput.taskContext, {
+		repositoryRoot: normalizedInput.repositoryRoot,
+	})
+		.map(parseContractToken)
+		.filter(Boolean);
+
+	if (currentContracts.length === 0) {
+		return {
+			score: 0,
+			findings: [],
+			evidence: [],
+		};
+	}
+
+	const findings = [];
+	const evidence = [];
+
+	for (const issue of normalizedInput.openIssues) {
+		const issueContracts = Array.from(new Set([
+			...issue.contracts,
+			...parseStoredContractsFromNotes(issue.notes),
+		]))
+			.map(parseContractToken)
+			.filter(Boolean);
+
+		const issueEvidence = [];
+		for (const currentContract of currentContracts) {
+			for (const storedContract of issueContracts) {
+				if (
+					currentContract.file !== storedContract.file
+					|| currentContract.symbol !== storedContract.symbol
+					|| currentContract.contractType !== storedContract.contractType
+				) {
+					continue;
+				}
+
+				issueEvidence.push({
+					type: 'contract',
+					sourceIssueId: normalizedInput.currentIssue.id,
+					targetIssueId: issue.id,
+					contract: currentContract.contract,
+					storedContract: storedContract.contract,
+					symbol: currentContract.symbol,
+					contractType: currentContract.contractType,
+					scoreContribution: 1,
+				});
+			}
+		}
+
+		if (issueEvidence.length === 0) {
+			continue;
+		}
+
+		const mergedEvidence = mergeEvidence(issueEvidence);
+		findings.push({
+			sourceIssueId: normalizedInput.currentIssue.id,
+			targetIssueId: issue.id,
+			score: mergedEvidence.length,
+			evidence: mergedEvidence,
+		});
+		evidence.push(...mergedEvidence);
+	}
+
+	return {
+		score: findings.reduce((total, finding) => total + finding.score, 0),
+		findings,
+		evidence: mergeEvidence(evidence),
+	};
+}
+
+module.exports = {
+	parseStoredContractsFromNotes,
+	scoreContractDependencies,
+};