forge-workflow 0.0.2 → 0.0.3

package/lib/dep-guard/rubric.js

@@ -0,0 +1,120 @@
+const WEIGHTS = {
+	importCallChain: 3,
+	contractDependencies: 3,
+	behavioralDependencies: 2,
+};
+
+const CONFLICT_MESSAGES = {
+	materialDisagreement: 'Detector scores disagree materially across dependency categories.',
+	behavioralUncertainty: 'Behavioral signals are heuristic and need manual review.',
+};
+const MAX_DETECTOR_STRENGTH = 3;
+const MAX_TOTAL = Object.values(WEIGHTS)
+	.reduce((sum, weight) => sum + (weight * MAX_DETECTOR_STRENGTH), 0);
+
+function aggregateRubricScores(detectors, options = {}) {
+	const confidenceThreshold = options.confidenceThreshold ?? 0.7;
+	const dimensions = {};
+	let total = 0;
+	let hasMaterialDisagreement = false;
+	let hasUncertainty = false;
+
+	for (const [name, weight] of Object.entries(WEIGHTS)) {
+		const raw = detectors[name]?.score ?? 0;
+		const normalized = Math.min(raw, MAX_DETECTOR_STRENGTH);
+		const weighted = normalized * weight;
+		dimensions[name] = { raw, normalized, weighted };
+		total += weighted;
+		if (detectors[name]?.uncertain) {
+			hasUncertainty = true;
+		}
+	}
+
+	if (total === 0) {
+		return {
+			result: 'PASS',
+			score: 0,
+			total: 0,
+			dimensions,
+			weights: { ...WEIGHTS },
+			confidence: {
+				score: 1,
+				threshold: confidenceThreshold,
+				belowThreshold: false,
+				reasons: [],
+			},
+			detectorConflicts: [],
+			summary: 'No detector findings yet.',
+			reasons: [],
+		};
+	}
+
+	const rawScores = Object.values(dimensions).map((dimension) => dimension.raw);
+	const nonZeroScores = rawScores.filter((score) => score > 0);
+	const detectorConflicts = [];
+
+	if (nonZeroScores.length >= 2 && (Math.max(...nonZeroScores) - Math.min(...nonZeroScores) >= 2)) {
+		hasMaterialDisagreement = true;
+		detectorConflicts.push(CONFLICT_MESSAGES.materialDisagreement);
+	}
+
+	if (hasUncertainty) {
+		detectorConflicts.push(CONFLICT_MESSAGES.behavioralUncertainty);
+	}
+
+	let confidenceScore = total / MAX_TOTAL;
+	if (hasMaterialDisagreement) {
+		confidenceScore -= 0.2;
+	}
+	if (hasUncertainty) {
+		confidenceScore -= 0.15;
+	}
+	confidenceScore = Math.max(0, Math.min(1, confidenceScore));
+	const belowThreshold = confidenceScore < confidenceThreshold;
+
+	const reasons = [];
+	if (detectorConflicts.length > 0) {
+		reasons.push(...detectorConflicts);
+	}
+	if (belowThreshold) {
+		reasons.push(`Confidence ${confidenceScore.toFixed(2)} is below the ${(confidenceThreshold * 100).toFixed(0)}% threshold.`);
+	}
+
+	let result = 'PASS';
+	if (detectorConflicts.length > 0) {
+		result = 'INCONCLUSIVE';
+	} else if (belowThreshold) {
+		result = 'WEAK';
+	}
+
+	return {
+		result,
+		score: total,
+		total,
+		dimensions,
+		weights: { ...WEIGHTS },
+		confidence: {
+			score: confidenceScore,
+			threshold: confidenceThreshold,
+			belowThreshold,
+			reasons,
+		},
+		detectorConflicts,
+		summary: reasons.join(' ') || 'Detector findings are consistent.',
+		reasons,
+	};
+}
+
+function needsUserEscalation(rubricResult) {
+	return (
+		rubricResult.result === 'INCONCLUSIVE'
+		|| rubricResult.confidence.belowThreshold
+		|| rubricResult.detectorConflicts.length > 0
+	);
+}
+
+module.exports = {
+	WEIGHTS,
+	aggregateRubricScores,
+	needsUserEscalation,
+};

package/lib/dep-guard/task-parser.js

@@ -0,0 +1,318 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { normalizeRepoPath } = require('./path-utils.js');
+
+function ensureTaskFile(taskFile) {
+	if (!taskFile || typeof taskFile !== 'string') {
+		throw new Error('Task file path is required');
+	}
+
+	const absolutePath = path.resolve(taskFile);
+	if (!fs.existsSync(absolutePath)) {
+		throw new Error(`Task file does not exist: ${absolutePath}`);
+	}
+
+	return absolutePath;
+}
+
+function parseFilesLine(value) {
+	if (!value) {
+		return [];
+	}
+
+	return value
+		.split(',')
+		.map((file) => file.replaceAll('`', '').trim())
+		.filter(Boolean);
+}
+
+function flushTask(tasks, currentTask) {
+	if (!currentTask) {
+		return;
+	}
+
+	tasks.push({
+		number: currentTask.number,
+		title: currentTask.title,
+		files: currentTask.files,
+		whatToImplement: currentTask.whatToImplement.trim(),
+		expectedOutput: currentTask.expectedOutput.trim(),
+	});
+}
+
+function isIdentifierStart(character) {
+	return /[A-Za-z_]/.test(character);
+}
+
+function isIdentifierPart(character) {
+	return /\w/.test(character);
+}
+
+function extractSymbols(text) {
+	const symbols = new Set();
+	let searchIndex = 0;
+
+	while (searchIndex < text.length) {
+		const callIndex = text.indexOf('()', searchIndex);
+		if (callIndex === -1) {
+			break;
+		}
+
+		let startIndex = callIndex - 1;
+		while (startIndex >= 0 && isIdentifierPart(text[startIndex])) {
+			startIndex -= 1;
+		}
+
+		const symbol = text.slice(startIndex + 1, callIndex);
+		if (symbol && isIdentifierStart(symbol[0])) {
+			symbols.add(symbol);
+		}
+
+		searchIndex = callIndex + 2;
+	}
+
+	for (const match of text.match(/`([^`\r\n]+)`/g) ?? []) {
+		const token = match.slice(1, -1).trim();
+		if (!token || /[/.\\\s]/.test(token)) {
+			continue;
+		}
+
+		if (/^[A-Za-z_][A-Za-z0-9_-]*$/.test(token)) {
+			symbols.add(token);
+		}
+	}
+
+	return Array.from(symbols);
+}
+
+function detectContractType(symbol, annotation = '') {
+	if (annotation === 'data-format' || annotation === 'command-contract' || annotation === 'return-shape') {
+		return annotation;
+	}
+
+	if (/Schema$|Format$/i.test(symbol)) {
+		return 'data-format';
+	}
+
+	if (/Contract$/i.test(symbol)) {
+		return 'command-contract';
+	}
+
+	if (symbol.includes('-')) {
+		return 'command-contract';
+	}
+
+	if (/Shape$/i.test(symbol)) {
+		return 'return-shape';
+	}
+
+	return 'modified';
+}
+
+function extractContractMentions(text) {
+	const mentions = new Map();
+	for (const symbol of extractSymbols(text)) {
+		mentions.set(symbol, {
+			symbol,
+			annotation: text.includes(`${symbol}()`) ? 'modified' : detectContractType(symbol),
+		});
+	}
+
+	for (const match of text.match(/\b[A-Za-z_]\w*(?:Schema|Format|Contract|Shape)\b/g) ?? []) {
+		if (mentions.has(match)) {
+			continue;
+		}
+
+		mentions.set(match, {
+			symbol: match,
+			annotation: detectContractType(match),
+		});
+	}
+
+	return Array.from(mentions.values());
+}
+
+function escapeRegExp(value) {
+	return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+}
+
+function resolveRepositoryFile(repositoryRoot, filePath) {
+	if (!repositoryRoot || !filePath || path.isAbsolute(filePath)) {
+		return null;
+	}
+
+	const absoluteRoot = path.resolve(repositoryRoot);
+	const absolutePath = path.resolve(absoluteRoot, filePath);
+	const relativePath = path.relative(absoluteRoot, absolutePath);
+	if (
+		relativePath === ''
+		|| relativePath.startsWith(`..${path.sep}`)
+		|| relativePath === '..'
+		|| path.isAbsolute(relativePath)
+	) {
+		return null;
+	}
+
+	return absolutePath;
+}
+
+function fileContainsSymbol(repositoryRoot, filePath, symbol) {
+	const absolutePath = resolveRepositoryFile(repositoryRoot, filePath);
+	if (!absolutePath) {
+		return false;
+	}
+
+	if (!fs.existsSync(absolutePath)) {
+		return false;
+	}
+
+	const content = fs.readFileSync(absolutePath, 'utf8');
+	if (/^[A-Za-z_]\w*$/.test(symbol)) {
+		return new RegExp(String.raw`\b${escapeRegExp(symbol)}\b`).test(content);
+	}
+
+	return content.includes(symbol);
+}
+
+function resolveMentionFiles(task, mention, repositoryRoot) {
+	const files = task.files ?? [];
+	if (files.length === 0) {
+		return [];
+	}
+
+	if (!repositoryRoot) {
+		return files.map((file) => normalizeRepoPath(file));
+	}
+
+	const matchingFiles = files
+		.filter((file) => fileContainsSymbol(repositoryRoot, file, mention.symbol))
+		.map((file) => normalizeRepoPath(file));
+	return matchingFiles;
+}
+
+function extractTaskContracts(taskContext, options = {}) {
+	if (!taskContext || !Array.isArray(taskContext.tasks)) {
+		return [];
+	}
+
+	const contracts = new Set();
+	const repositoryRoot = options.repositoryRoot;
+
+	for (const task of taskContext.tasks) {
+		const mentions = extractContractMentions(task.whatToImplement ?? '');
+		for (const mention of mentions) {
+			for (const file of resolveMentionFiles(task, mention, repositoryRoot)) {
+				contracts.add(`${file}:${mention.symbol}(${mention.annotation})`);
+			}
+		}
+	}
+
+	return Array.from(contracts).sort((left, right) => left.localeCompare(right));
+}
+
+function isTaskHeader(line) {
+	return line.startsWith('## Task ');
+}
+
+function parseTaskHeader(line) {
+	if (!isTaskHeader(line)) {
+		return null;
+	}
+
+	const prefixLength = '## Task '.length;
+	const separatorIndex = line.indexOf(':', prefixLength);
+	if (separatorIndex === -1) {
+		return null;
+	}
+
+	const numberText = line.slice(prefixLength, separatorIndex).trim();
+	if (!numberText || Array.from(numberText).some((character) => character < '0' || character > '9')) {
+		return null;
+	}
+
+	const title = line.slice(separatorIndex + 1).trim();
+	if (!title) {
+		return null;
+	}
+
+	return {
+		number: Number(numberText),
+		title,
+	};
+}
+
+function parseTaskField(currentTask, line, currentField) {
+	if (line.startsWith('File(s):')) {
+		currentTask.files = parseFilesLine(line.slice('File(s):'.length).trim());
+		return null;
+	}
+
+	if (line.startsWith('What to implement:')) {
+		currentTask.whatToImplement = line.slice('What to implement:'.length).trim();
+		return 'whatToImplement';
+	}
+
+	if (line.startsWith('Expected output:')) {
+		currentTask.expectedOutput = line.slice('Expected output:'.length).trim();
+		return 'expectedOutput';
+	}
+
+	if (line === 'TDD steps:' || line === '---') {
+		return null;
+	}
+
+	if (currentField && line.trim()) {
+		currentTask[currentField] = `${currentTask[currentField]} ${line.trim()}`.trim();
+	}
+
+	return currentField;
+}
+
+function parseTaskFile(taskFile) {
+	const absolutePath = ensureTaskFile(taskFile);
+	const content = fs.readFileSync(absolutePath, 'utf8');
+	const lines = content.split(/\r?\n/);
+	const tasks = [];
+	let currentTask = null;
+	let currentField = null;
+
+	for (const rawLine of lines) {
+		const line = rawLine.trimEnd();
+		const taskHeader = parseTaskHeader(line);
+
+		if (taskHeader) {
+			flushTask(tasks, currentTask);
+			currentTask = {
+				number: taskHeader.number,
+				title: taskHeader.title,
+				files: [],
+				whatToImplement: '',
+				expectedOutput: '',
+			};
+			currentField = null;
+			continue;
+		}
+
+		if (!currentTask) {
+			continue;
+		}
+
+		currentField = parseTaskField(currentTask, line, currentField);
+	}
+
+	flushTask(tasks, currentTask);
+
+	return {
+		path: absolutePath,
+		taskCount: tasks.length,
+		tasks,
+	};
+}
+
+module.exports = {
+	detectContractType,
+	extractContractMentions,
+	extractSymbols,
+	extractTaskContracts,
+	parseTaskFile,
+};

package/lib/plugin-catalog.js

@@ -24,10 +24,10 @@ const STAGES = Object.freeze({
   RESEARCH: 'research',
   PLAN: 'plan',
   DEV: 'dev',
-  CHECK: 'check',
+  VALIDATE: 'validate',
   SHIP: 'ship',
   REVIEW: 'review',
-  MERGE: 'merge',
+  PREMERGE: 'premerge',
 });
 
 const BUDGET_MODES = Object.freeze({
@@ -101,16 +101,6 @@ const CATALOG = Object.freeze({
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -g @beads/bd' },
   },
-  openspec: {
-    name: 'OpenSpec',
-    type: 'cli',
-    tier: 'free',
-    stage: 'plan',
-    description: 'Spec-driven development proposals',
-    detectWhen: [],
-    install: { method: 'npm', cmd: 'bun add -g @fission-ai/openspec' },
-  },
-
   // ── Dev ──
   'typescript-lsp': {
     name: 'TypeScript LSP',
@@ -155,7 +145,7 @@ const CATALOG = Object.freeze({
     name: 'ESLint',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'JavaScript/TypeScript linting',
     detectWhen: ['file:eslint.config.js', 'dep:eslint'],
     install: { method: 'npm', cmd: 'bun add -D eslint', dev: true },
@@ -164,7 +154,7 @@ const CATALOG = Object.freeze({
     name: 'Biome',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Fast formatter and linter',
     detectWhen: ['file:biome.json'],
     install: { method: 'npm', cmd: 'bun add -D @biomejs/biome', dev: true },
@@ -173,7 +163,7 @@ const CATALOG = Object.freeze({
     name: 'Prettier',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Opinionated code formatter',
     detectWhen: ['file:.prettierrc'],
     install: { method: 'npm', cmd: 'bun add -D prettier', dev: true },
@@ -182,7 +172,7 @@ const CATALOG = Object.freeze({
     name: 'ESLint Security Plugin',
     type: 'config',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Security-focused ESLint rules',
     detectWhen: ['dep:express', 'dep:fastify'],
     install: { method: 'npm', cmd: 'bun add -D eslint-plugin-security', dev: true },
@@ -191,7 +181,7 @@ const CATALOG = Object.freeze({
     name: 'SonarCloud Analysis',
     type: 'skill',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'Code quality and security analysis via SonarCloud REST API',
     detectWhen: [],
     install: {
@@ -204,7 +194,7 @@ const CATALOG = Object.freeze({
     name: 'Sonar Scanner',
     type: 'cli',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'SonarCloud/SonarQube CLI scanner',
     detectWhen: ['file:sonar-project.properties'],
     install: { method: 'npm', cmd: 'bun add -D sonarqube-scanner', dev: true },
@@ -214,7 +204,7 @@ const CATALOG = Object.freeze({
     name: 'CodeQL',
     type: 'cli',
     tier: 'free-public',
-    stage: 'check',
+    stage: 'validate',
     description: 'Semantic code analysis by GitHub',
     detectWhen: [],
     install: { method: 'binary', cmd: 'GitHub-provided (github.com/github/codeql-action)' },
@@ -224,7 +214,7 @@ const CATALOG = Object.freeze({
     name: 'npm audit',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Dependency vulnerability scanning',
     detectWhen: [],
     install: { method: 'npm', cmd: 'built-in (bun pm audit)' },
@@ -233,7 +223,7 @@ const CATALOG = Object.freeze({
     name: 'Vitest',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Vite-native test runner',
     detectWhen: ['dep:vitest', 'file:vitest.config.ts'],
     install: { method: 'npm', cmd: 'bun add -D vitest', dev: true },
@@ -242,7 +232,7 @@ const CATALOG = Object.freeze({
     name: 'Jest',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Delightful JavaScript testing',
     detectWhen: ['dep:jest', 'file:jest.config.js'],
     install: { method: 'npm', cmd: 'bun add -D jest', dev: true },
@@ -251,7 +241,7 @@ const CATALOG = Object.freeze({
     name: 'Playwright',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'End-to-end browser testing',
     detectWhen: ['dep:@playwright/test'],
     install: { method: 'npm', cmd: 'bun add -D @playwright/test', dev: true },
@@ -260,7 +250,7 @@ const CATALOG = Object.freeze({
     name: 'c8',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Native V8 code coverage',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D c8', dev: true },
@@ -269,7 +259,7 @@ const CATALOG = Object.freeze({
     name: 'Stryker',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Mutation testing for JavaScript',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D @stryker-mutator/core', dev: true },
@@ -278,7 +268,7 @@ const CATALOG = Object.freeze({
     name: 'Oxlint',
     type: 'cli',
     tier: 'free',
-    stage: 'check',
+    stage: 'validate',
     description: 'Blazing-fast Rust-based linter',
     detectWhen: [],
     install: { method: 'npm', cmd: 'bun add -D oxlint', dev: true },
@@ -341,7 +331,7 @@ const CATALOG = Object.freeze({
     name: 'Changesets',
     type: 'cli',
     tier: 'free',
-    stage: 'merge',
+    stage: 'premerge',
     description: 'Versioning and changelog management',
     detectWhen: ['file:package.json'],
     install: { method: 'npm', cmd: 'bun add -D @changesets/cli', dev: true },
@@ -350,7 +340,7 @@ const CATALOG = Object.freeze({
     name: 'Release Please',
     type: 'config',
     tier: 'free',
-    stage: 'merge',
+    stage: 'premerge',
     description: 'Automated release PRs by Google',
     detectWhen: [],
     install: { method: 'config', cmd: 'GitHub Action (google-github-actions/release-please-action)' },

package/lib/workflow-profiles.js

@@ -12,29 +12,26 @@
 const PROFILES = {
   critical: {
     name: 'Critical (Maximum Rigor)',
-    stages: ['/status', '/research', '/plan', '/dev', '/validate', '/ship', '/review', '/merge', '/verify'],
+    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge', '/verify'],
     tdd: 'strict',
     research: 'required',
-    openspec: 'required-strategic',
     description: 'Security, auth, payments, data integrity, breaking changes',
     keywords: ['auth', 'security', 'payment', 'crypto', 'password', 'token', 'session', 'data-migration', 'breaking']
   },
 
   standard: {
     name: 'Standard (Full Workflow)',
-    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/merge'],
+    stages: ['/status', '/plan', '/dev', '/validate', '/ship', '/review', '/premerge'],
     tdd: 'required',
     research: 'optional',
-    openspec: 'strategic',
     description: 'Most features and non-critical enhancements'
   },
 
   simple: {
     name: 'Simple (Streamlined)',
-    stages: ['/dev', '/validate', '/ship', '/merge'],
+    stages: ['/dev', '/validate', '/ship', '/premerge'],
     tdd: 'recommended',
     research: 'skip',
-    openspec: 'no',
     description: 'UI tweaks, small improvements, minor fixes'
   },
 
@@ -43,26 +40,23 @@ const PROFILES = {
     stages: ['/dev', '/validate', '/ship'],
     tdd: 'required',  // Must reproduce bug
     research: 'skip',
-    openspec: 'no',
     description: 'Production bugs, urgent fixes',
     keywords: ['urgent', 'production', 'emergency', 'hotfix', 'critical']
   },
 
   docs: {
     name: 'Docs (Documentation Only)',
-    stages: ['/verify', '/ship', '/merge'],
+    stages: ['/verify', '/ship', '/premerge'],
     tdd: 'no',
     research: 'no',
-    openspec: 'no',
     description: 'Documentation updates, README changes'
   },
 
   refactor: {
     name: 'Refactor (Behavior-Preserving)',
-    stages: ['/plan', '/dev', '/validate', '/ship', '/merge'],
+    stages: ['/plan', '/dev', '/validate', '/ship', '/premerge'],
     tdd: 'strict',  // Must preserve behavior
     research: 'optional',
-    openspec: 'architectural',
     description: 'Code cleanup, optimization, behavior-preserving improvements'
   }
 };