@rengler33/prov 0.1.1

package/dist/commands/plan.js

@@ -0,0 +1,1307 @@
+/**
+ * prov plan commands implementation.
+ *
+ * Commands for managing implementation plans:
+ * - plan create: Create a new plan from specs and constraints
+ * - plan show: Display plan details
+ * - plan validate: Validate plan completeness
+ *
+ * @see req:cli:plan-create
+ * @see req:cli:plan-show
+ * @see req:cli:plan-validate
+ */
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve, relative, extname, dirname } from 'node:path';
+import { isInitialized, loadGraph, saveGraph } from '../storage.js';
+import { addPlanToGraph } from '../graph.js';
+import { parseYaml, computeHash, toYaml } from '../hash.js';
+import { output, error, success, warn, resolveFormat } from '../output.js';
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validate plan ID format: plan:{name}:v{number}
+ */
+function isValidPlanId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^plan:[a-z0-9-]+:v\d+$/.test(id);
+}
+/**
+ * Validate decision ID format: dec:{plan}:{name}
+ */
+function isValidDecisionId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^dec:[a-z0-9-]+:[a-z0-9-]+$/.test(id);
+}
+/**
+ * Validate step ID format: step:{plan}:{number}
+ */
+function isValidStepId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^step:[a-z0-9-]+:\d+$/.test(id);
+}
+/**
+ * Validate spec ID format.
+ */
+function isValidSpecId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^spec:[a-z0-9-]+:v\d+$/.test(id);
+}
+/**
+ * Validate constraint ID format.
+ */
+function isValidConstraintId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^constraint:[a-z0-9-]+:v\d+$/.test(id);
+}
+/**
+ * Validate requirement ID format.
+ */
+function isValidRequirementId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^req:[a-z0-9-]+(:[a-z0-9-]+)?$/.test(id);
+}
+/**
+ * Validate invariant ID format.
+ */
+function isValidInvariantId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^inv:[a-z0-9-]+:[a-z0-9-]+$/.test(id);
+}
+/**
+ * Validate source reference ID (spec or constraint).
+ */
+function isValidSourceId(id) {
+    return isValidSpecId(id) || isValidConstraintId(id);
+}
+/**
+ * Validate hash format.
+ */
+function isValidHash(hash) {
+    if (typeof hash !== 'string')
+        return false;
+    return /^sha256:[a-f0-9]+$/.test(hash);
+}
+/**
+ * Validate entity status.
+ */
+function isValidStatus(status) {
+    return status === 'draft' || status === 'active' || status === 'deprecated' || status === 'archived';
+}
+/**
+ * Validate step status.
+ */
+function isValidStepStatus(status) {
+    return status === 'pending' || status === 'in_progress' || status === 'completed' || status === 'blocked';
+}
+/**
+ * Validate a raw plan object and convert to typed Plan.
+ */
+function validatePlan(raw, _filePath) {
+    const errors = [];
+    // Required fields
+    if (raw.id === undefined || raw.id === null) {
+        errors.push('Missing required field: id');
+    }
+    else if (!isValidPlanId(raw.id)) {
+        errors.push(`Invalid plan ID format: ${String(raw.id)} (expected plan:{name}:v{number})`);
+    }
+    if (raw.version === undefined || raw.version === null) {
+        errors.push('Missing required field: version');
+    }
+    else if (typeof raw.version !== 'string') {
+        errors.push(`Invalid version type: expected string, got ${typeof raw.version}`);
+    }
+    if (raw.title === undefined || raw.title === null) {
+        errors.push('Missing required field: title');
+    }
+    else if (typeof raw.title !== 'string') {
+        errors.push(`Invalid title type: expected string, got ${typeof raw.title}`);
+    }
+    if (raw.status !== undefined && !isValidStatus(raw.status)) {
+        errors.push(`Invalid status: ${String(raw.status)} (expected draft|active|deprecated|archived)`);
+    }
+    if (raw.sources === undefined || raw.sources === null) {
+        errors.push('Missing required field: sources');
+    }
+    else if (!Array.isArray(raw.sources)) {
+        errors.push(`Invalid sources type: expected array, got ${typeof raw.sources}`);
+    }
+    if (raw.decisions !== undefined && !Array.isArray(raw.decisions)) {
+        errors.push(`Invalid decisions type: expected array, got ${typeof raw.decisions}`);
+    }
+    if (raw.steps === undefined || raw.steps === null) {
+        errors.push('Missing required field: steps');
+    }
+    else if (!Array.isArray(raw.steps)) {
+        errors.push(`Invalid steps type: expected array, got ${typeof raw.steps}`);
+    }
+    if (errors.length > 0) {
+        return { errors };
+    }
+    // Validate sources
+    const sources = [];
+    for (let i = 0; i < raw.sources.length; i++) {
+        const rawSource = raw.sources[i];
+        if (!isValidSourceId(rawSource.id)) {
+            errors.push(`Source ${i}: invalid ID format: ${String(rawSource.id)}`);
+            continue;
+        }
+        if (!isValidHash(rawSource.hash)) {
+            errors.push(`Source ${i}: invalid hash format: ${String(rawSource.hash)}`);
+            continue;
+        }
+        sources.push({
+            id: rawSource.id,
+            hash: rawSource.hash,
+        });
+    }
+    // Validate decisions
+    const decisions = [];
+    const decisionIds = new Set();
+    if (raw.decisions !== undefined) {
+        for (let i = 0; i < raw.decisions.length; i++) {
+            const rawDec = raw.decisions[i];
+            if (rawDec.id === undefined || rawDec.id === null) {
+                errors.push(`Decision ${i}: missing required field: id`);
+                continue;
+            }
+            if (!isValidDecisionId(rawDec.id)) {
+                errors.push(`Decision ${i}: invalid ID format: ${String(rawDec.id)} (expected dec:{plan}:{name})`);
+                continue;
+            }
+            const decIdStr = rawDec.id;
+            if (decisionIds.has(decIdStr)) {
+                errors.push(`Decision ${i}: duplicate ID: ${decIdStr}`);
+                continue;
+            }
+            decisionIds.add(decIdStr);
+            if (rawDec.question === undefined || typeof rawDec.question !== 'string') {
+                errors.push(`Decision ${decIdStr}: missing or invalid question`);
+                continue;
+            }
+            if (rawDec.choice === undefined || typeof rawDec.choice !== 'string') {
+                errors.push(`Decision ${decIdStr}: missing or invalid choice`);
+                continue;
+            }
+            if (rawDec.rationale === undefined || typeof rawDec.rationale !== 'string') {
+                errors.push(`Decision ${decIdStr}: missing or invalid rationale`);
+                continue;
+            }
+            // Validate traces_to
+            const tracesTo = [];
+            if (rawDec.traces_to !== undefined) {
+                if (!Array.isArray(rawDec.traces_to)) {
+                    errors.push(`Decision ${decIdStr}: traces_to must be an array`);
+                }
+                else {
+                    for (const target of rawDec.traces_to) {
+                        if (!isValidRequirementId(target) && !isValidInvariantId(target)) {
+                            errors.push(`Decision ${decIdStr}: invalid traces_to target: ${String(target)}`);
+                        }
+                        else {
+                            tracesTo.push(target);
+                        }
+                    }
+                }
+            }
+            decisions.push({
+                id: decIdStr,
+                question: rawDec.question,
+                choice: rawDec.choice,
+                rationale: rawDec.rationale,
+                tracesTo,
+            });
+        }
+    }
+    // Validate steps
+    const steps = [];
+    const stepIds = new Set();
+    for (let i = 0; i < raw.steps.length; i++) {
+        const rawStep = raw.steps[i];
+        if (rawStep.id === undefined || rawStep.id === null) {
+            errors.push(`Step ${i}: missing required field: id`);
+            continue;
+        }
+        if (!isValidStepId(rawStep.id)) {
+            errors.push(`Step ${i}: invalid ID format: ${String(rawStep.id)} (expected step:{plan}:{number})`);
+            continue;
+        }
+        const stepIdStr = rawStep.id;
+        if (stepIds.has(stepIdStr)) {
+            errors.push(`Step ${i}: duplicate ID: ${stepIdStr}`);
+            continue;
+        }
+        stepIds.add(stepIdStr);
+        if (rawStep.number === undefined || typeof rawStep.number !== 'number') {
+            errors.push(`Step ${stepIdStr}: missing or invalid number`);
+            continue;
+        }
+        if (rawStep.action === undefined || typeof rawStep.action !== 'string') {
+            errors.push(`Step ${stepIdStr}: missing or invalid action`);
+            continue;
+        }
+        if (rawStep.status !== undefined && !isValidStepStatus(rawStep.status)) {
+            errors.push(`Step ${stepIdStr}: invalid status: ${String(rawStep.status)}`);
+            continue;
+        }
+        // Validate traces_to
+        // Steps can trace to decisions, requirements, or invariants they implement
+        const tracesTo = [];
+        if (rawStep.traces_to !== undefined) {
+            if (!Array.isArray(rawStep.traces_to)) {
+                errors.push(`Step ${stepIdStr}: traces_to must be an array`);
+            }
+            else {
+                for (const target of rawStep.traces_to) {
+                    if (!isValidDecisionId(target) && !isValidRequirementId(target) && !isValidInvariantId(target)) {
+                        errors.push(`Step ${stepIdStr}: invalid traces_to target: ${String(target)}`);
+                    }
+                    else {
+                        tracesTo.push(target);
+                    }
+                }
+            }
+        }
+        // Validate dependencies
+        let dependencies;
+        if (rawStep.dependencies !== undefined) {
+            if (!Array.isArray(rawStep.dependencies)) {
+                errors.push(`Step ${stepIdStr}: dependencies must be an array`);
+            }
+            else {
+                dependencies = [];
+                for (const dep of rawStep.dependencies) {
+                    if (!isValidStepId(dep)) {
+                        errors.push(`Step ${stepIdStr}: invalid dependency: ${String(dep)}`);
+                    }
+                    else {
+                        dependencies.push(dep);
+                    }
+                }
+            }
+        }
+        // Validate artifacts
+        let artifacts;
+        if (rawStep.artifacts !== undefined) {
+            if (!Array.isArray(rawStep.artifacts)) {
+                errors.push(`Step ${stepIdStr}: artifacts must be an array`);
+            }
+            else {
+                artifacts = [];
+                for (const artifact of rawStep.artifacts) {
+                    if (typeof artifact !== 'string') {
+                        errors.push(`Step ${stepIdStr}: artifact must be a string`);
+                    }
+                    else {
+                        artifacts.push(artifact);
+                    }
+                }
+            }
+        }
+        // Build step object - use Object.assign to avoid exactOptionalPropertyTypes issues
+        const step = Object.assign({
+            id: stepIdStr,
+            number: rawStep.number,
+            action: rawStep.action,
+            tracesTo,
+        }, rawStep.description !== undefined ? { description: rawStep.description } : null, dependencies !== undefined && dependencies.length > 0 ? { dependencies } : null, artifacts !== undefined && artifacts.length > 0 ? { artifacts } : null, rawStep.status !== undefined ? { status: rawStep.status } : null);
+        steps.push(step);
+    }
+    if (errors.length > 0) {
+        return { errors };
+    }
+    const plan = {
+        id: raw.id,
+        version: raw.version,
+        title: raw.title,
+        status: raw.status ?? 'draft',
+        sources,
+        decisions,
+        steps,
+    };
+    return { plan, errors: [] };
+}
+// ============================================================================
+// File Discovery
+// ============================================================================
+/**
+ * Find all plan files in the plan directory.
+ */
+function findPlanFiles(projectRoot) {
+    const planDir = join(projectRoot, 'plan');
+    const files = [];
+    if (!existsSync(planDir)) {
+        return files;
+    }
+    function walkDir(dir) {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+            const fullPath = join(dir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walkDir(fullPath);
+            }
+            else {
+                const ext = extname(entry).toLowerCase();
+                if (ext === '.yaml' || ext === '.yml') {
+                    // Include files with .plan. in the name or in plan directory
+                    if (entry.includes('.plan.') || dir.includes('/plan')) {
+                        files.push(fullPath);
+                    }
+                }
+            }
+        }
+    }
+    walkDir(planDir);
+    return files.sort();
+}
+/**
+ * Load and parse a plan file.
+ */
+function loadPlanFile(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf8');
+        const raw = parseYaml(content);
+        if (raw === null || typeof raw !== 'object') {
+            return { errors: ['File does not contain a valid YAML object'] };
+        }
+        return validatePlan(raw, filePath);
+    }
+    catch (err) {
+        return {
+            errors: [`Failed to parse YAML: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+}
+// ============================================================================
+// plan create Command
+// ============================================================================
+/**
+ * Execute the plan create command.
+ *
+ * Creates a new plan scaffold based on the specified specs and constraints.
+ *
+ * @see req:cli:plan-create
+ */
+export function runPlanCreate(globalOpts, options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            success: false,
+            error: 'prov is not initialized. Run "prov init" first.',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Load graph to get specs and constraints
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            success: false,
+            error: loadResult.error ?? 'Failed to load graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Resolve source references
+    const sources = [];
+    const allRequirements = [];
+    const allInvariants = [];
+    // Process --from specs
+    for (const specIdStr of options.from) {
+        const specId = specIdStr;
+        const node = graph.getNode(specId);
+        if (node === undefined || node.type !== 'spec') {
+            const result = {
+                success: false,
+                error: `Spec not found: ${specIdStr}`,
+            };
+            if (fmt === 'json') {
+                output(result, { format: 'json' });
+            }
+            else if (fmt === 'yaml') {
+                output(result, { format: 'yaml' });
+            }
+            else {
+                error(result.error);
+            }
+            process.exit(1);
+        }
+        sources.push({
+            id: specId,
+            hash: node.hash,
+        });
+        // Collect requirements for tracing
+        const spec = node.data;
+        for (const req of spec.requirements) {
+            allRequirements.push(req.id);
+        }
+    }
+    // Process --with constraints
+    if (options.with !== undefined) {
+        for (const constraintIdStr of options.with) {
+            const constraintId = constraintIdStr;
+            const node = graph.getNode(constraintId);
+            if (node === undefined || node.type !== 'constraint') {
+                const result = {
+                    success: false,
+                    error: `Constraint not found: ${constraintIdStr}`,
+                };
+                if (fmt === 'json') {
+                    output(result, { format: 'json' });
+                }
+                else if (fmt === 'yaml') {
+                    output(result, { format: 'yaml' });
+                }
+                else {
+                    error(result.error);
+                }
+                process.exit(1);
+            }
+            sources.push({
+                id: constraintId,
+                hash: node.hash,
+            });
+            // Collect invariants for tracing
+            const constraint = node.data;
+            for (const inv of constraint.invariants) {
+                allInvariants.push(inv.id);
+            }
+        }
+    }
+    // Generate plan name from first spec
+    const firstSpecId = options.from[0];
+    const planName = firstSpecId.replace(/^spec:/, '').replace(/:v\d+$/, '');
+    const planId = `plan:${planName}:v1`;
+    // Create scaffold plan with placeholder steps
+    const plan = {
+        id: planId,
+        version: '1.0.0',
+        title: `Implementation plan for ${planName}`,
+        status: 'draft',
+        sources,
+        decisions: [],
+        steps: allRequirements.map((reqId, index) => ({
+            id: `step:${planName}:${index + 1}`,
+            number: index + 1,
+            action: `Implement ${reqId}`,
+            tracesTo: [reqId],
+            status: 'pending',
+        })),
+    };
+    // Compute hash
+    const hash = computeHash(plan);
+    const planWithHash = { ...plan, hash };
+    // Determine output file
+    let outputFile = options.output;
+    if (outputFile === undefined) {
+        const planDir = join(projectRoot, 'plan');
+        if (!existsSync(planDir)) {
+            mkdirSync(planDir, { recursive: true });
+        }
+        outputFile = join(planDir, `${planName}.plan.yaml`);
+    }
+    else {
+        outputFile = resolve(projectRoot, outputFile);
+        const dir = dirname(outputFile);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    // Convert plan to YAML and write to file
+    const yamlContent = toYaml({
+        id: plan.id,
+        version: plan.version,
+        title: plan.title,
+        status: plan.status,
+        sources: plan.sources.map((s) => ({ id: s.id, hash: s.hash })),
+        decisions: plan.decisions.map((d) => ({
+            id: d.id,
+            question: d.question,
+            choice: d.choice,
+            rationale: d.rationale,
+            traces_to: d.tracesTo,
+        })),
+        steps: plan.steps.map((s) => ({
+            id: s.id,
+            number: s.number,
+            action: s.action,
+            ...(s.description !== undefined ? { description: s.description } : {}),
+            traces_to: s.tracesTo,
+            ...(s.dependencies !== undefined ? { dependencies: s.dependencies } : {}),
+            ...(s.artifacts !== undefined ? { artifacts: s.artifacts } : {}),
+            ...(s.status !== undefined ? { status: s.status } : {}),
+        })),
+    });
+    writeFileSync(outputFile, yamlContent, 'utf8');
+    // Add plan to graph
+    addPlanToGraph(graph, planWithHash);
+    // Save graph
+    const saveResult = saveGraph(graph, projectRoot);
+    if (!saveResult.success) {
+        const result = {
+            success: false,
+            error: saveResult.error ?? 'Failed to save graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const result = {
+        success: true,
+        planId: plan.id,
+        hash,
+        stepCount: plan.steps.length,
+        decisionCount: plan.decisions.length,
+        outputFile: relative(projectRoot, outputFile),
+    };
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        success(`Created plan ${plan.id} (${plan.steps.length} steps)`);
+        process.stdout.write(`  Output: ${relative(projectRoot, outputFile)}\n`);
+    }
+}
+// ============================================================================
+// plan show Command
+// ============================================================================
+/**
+ * Execute the plan show command.
+ *
+ * @see req:cli:plan-show
+ */
+export function runPlanShow(globalOpts, planIdStr, _options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            success: false,
+            error: 'prov is not initialized. Run "prov init" first.',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Load graph
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            success: false,
+            error: loadResult.error ?? 'Failed to load graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Find the plan
+    const planId = planIdStr;
+    const node = graph.getNode(planId);
+    if (node === undefined || node.type !== 'plan') {
+        const result = {
+            success: false,
+            error: `Plan not found: ${planIdStr}`,
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const plan = node.data;
+    const planData = {
+        id: plan.id,
+        version: plan.version,
+        title: plan.title,
+        status: plan.status,
+        sources: [...plan.sources],
+        decisions: plan.decisions.map((d) => ({
+            id: d.id,
+            question: d.question,
+            choice: d.choice,
+        })),
+        steps: plan.steps.map((s) => ({
+            id: s.id,
+            number: s.number,
+            action: s.action,
+            status: s.status ?? 'pending',
+            tracesTo: [...s.tracesTo],
+        })),
+    };
+    if (node.hash !== undefined) {
+        planData.hash = node.hash;
+    }
+    const result = {
+        success: true,
+        plan: planData,
+    };
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        // Table format for terminal
+        process.stdout.write(`\n${plan.title}\n`);
+        process.stdout.write(`${'─'.repeat(plan.title.length)}\n`);
+        process.stdout.write(`ID:      ${plan.id}\n`);
+        process.stdout.write(`Version: ${plan.version}\n`);
+        process.stdout.write(`Status:  ${plan.status}\n`);
+        process.stdout.write(`Hash:    ${node.hash ?? 'N/A'}\n`);
+        if (plan.sources.length > 0) {
+            process.stdout.write(`\nSources:\n`);
+            for (const source of plan.sources) {
+                process.stdout.write(`  - ${source.id} (${source.hash})\n`);
+            }
+        }
+        if (plan.decisions.length > 0) {
+            process.stdout.write(`\nDecisions:\n`);
+            for (const dec of plan.decisions) {
+                process.stdout.write(`  ${dec.id}:\n`);
+                process.stdout.write(`    Q: ${dec.question}\n`);
+                process.stdout.write(`    A: ${dec.choice}\n`);
+            }
+        }
+        if (plan.steps.length > 0) {
+            process.stdout.write(`\nSteps:\n`);
+            const columns = [
+                { header: '#', key: 'number', minWidth: 3, align: 'right' },
+                { header: 'Action', key: 'action', maxWidth: 50 },
+                { header: 'Status', key: 'status', minWidth: 10 },
+                { header: 'Traces To', key: 'tracesTo', maxWidth: 30 },
+            ];
+            const rows = plan.steps.map((s) => ({
+                number: s.number,
+                action: s.action,
+                status: s.status ?? 'pending',
+                tracesTo: s.tracesTo.join(', '),
+            }));
+            output(rows, { format: 'table', columns });
+        }
+    }
+}
+// ============================================================================
+// plan validate Command
+// ============================================================================
+/**
+ * Execute the plan validate command.
+ *
+ * Validates plan completeness and consistency.
+ *
+ * @see req:cli:plan-validate
+ */
+export function runPlanValidate(globalOpts, _options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            valid: false,
+            issues: [{ severity: 'error', message: 'prov is not initialized. Run "prov init" first.' }],
+            plansChecked: 0,
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.issues[0].message);
+        }
+        process.exit(1);
+    }
+    // Load graph
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            valid: false,
+            issues: [{ severity: 'error', message: loadResult.error ?? 'Failed to load graph' }],
+            plansChecked: 0,
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.issues[0].message);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Find all plan files and validate them
+    const planFiles = findPlanFiles(projectRoot);
+    const issues = [];
+    const validPlans = [];
+    // Validate each plan file
+    for (const filePath of planFiles) {
+        const relPath = relative(projectRoot, filePath);
+        const { plan, errors } = loadPlanFile(filePath);
+        if (errors.length > 0) {
+            for (const err of errors) {
+                issues.push({
+                    severity: 'error',
+                    message: `${relPath}: ${err}`,
+                });
+            }
+            continue;
+        }
+        if (plan !== undefined) {
+            validPlans.push(plan);
+        }
+    }
+    // Cross-validate plans against graph
+    const planNodes = graph.getNodesByType('plan');
+    const graphPlanIds = new Set(planNodes.map((n) => n.id));
+    const filePlanIds = new Set(validPlans.map((p) => p.id));
+    // Check for plans in graph but missing files
+    for (const node of planNodes) {
+        if (!filePlanIds.has(node.id)) {
+            issues.push({
+                severity: 'warning',
+                planId: node.id,
+                message: `Plan ${node.id} is in graph but has no corresponding file`,
+            });
+        }
+    }
+    // Check for plans in files but not in graph
+    for (const plan of validPlans) {
+        if (!graphPlanIds.has(plan.id)) {
+            issues.push({
+                severity: 'warning',
+                planId: plan.id,
+                message: `Plan ${plan.id} has a file but is not tracked in graph`,
+            });
+        }
+    }
+    // Validate plan completeness
+    for (const plan of validPlans) {
+        // Check that all sources exist in graph
+        for (const source of plan.sources) {
+            const sourceNode = graph.getNode(source.id);
+            if (sourceNode === undefined) {
+                issues.push({
+                    severity: 'error',
+                    planId: plan.id,
+                    message: `Source ${source.id} not found in graph`,
+                });
+            }
+            else if (sourceNode.hash !== source.hash) {
+                issues.push({
+                    severity: 'warning',
+                    planId: plan.id,
+                    message: `Source ${source.id} has changed since plan creation (hash mismatch)`,
+                });
+            }
+        }
+        // Check that all requirements are covered by steps
+        const coveredReqs = new Set();
+        for (const step of plan.steps) {
+            for (const target of step.tracesTo) {
+                if (target.startsWith('req:')) {
+                    coveredReqs.add(target);
+                }
+            }
+        }
+        // Get all requirements from sources
+        for (const source of plan.sources) {
+            if (source.id.startsWith('spec:')) {
+                const specNode = graph.getNode(source.id);
+                if (specNode !== undefined && specNode.type === 'spec') {
+                    const spec = specNode.data;
+                    for (const req of spec.requirements) {
+                        if (!coveredReqs.has(req.id)) {
+                            issues.push({
+                                severity: 'warning',
+                                planId: plan.id,
+                                message: `Requirement ${req.id} is not covered by any step`,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        // Check step dependencies
+        const stepIds = new Set(plan.steps.map((s) => s.id));
+        for (const step of plan.steps) {
+            if (step.dependencies !== undefined) {
+                for (const dep of step.dependencies) {
+                    if (!stepIds.has(dep)) {
+                        issues.push({
+                            severity: 'error',
+                            planId: plan.id,
+                            message: `Step ${step.id} depends on non-existent step ${dep}`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // Sort issues by severity then plan
+    issues.sort((a, b) => {
+        if (a.severity !== b.severity) {
+            return a.severity === 'error' ? -1 : 1;
+        }
+        return (a.planId ?? '').localeCompare(b.planId ?? '');
+    });
+    const hasErrors = issues.some((i) => i.severity === 'error');
+    const result = {
+        valid: !hasErrors,
+        issues,
+        plansChecked: validPlans.length,
+    };
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        if (issues.length === 0) {
+            success(`Validated ${validPlans.length} plan(s) - no issues found`);
+            return;
+        }
+        // Display issues
+        for (const issue of issues) {
+            const prefix = issue.severity === 'error' ? 'ERROR' : 'WARN';
+            const planPart = issue.planId !== undefined ? ` [${issue.planId}]` : '';
+            process.stdout.write(`${prefix}${planPart}: ${issue.message}\n`);
+        }
+        process.stdout.write('\n');
+        const errorCount = issues.filter((i) => i.severity === 'error').length;
+        const warnCount = issues.filter((i) => i.severity === 'warning').length;
+        if (errorCount > 0) {
+            error(`Found ${errorCount} error(s) and ${warnCount} warning(s)`);
+        }
+        else {
+            warn(`Found ${warnCount} warning(s)`);
+        }
+    }
+    if (hasErrors) {
+        process.exit(1);
+    }
+}
+/**
+ * Execute the plan next command.
+ *
+ * Returns the next unimplemented step in the plan.
+ *
+ * @see req:agent:step-execution
+ */
+export function runPlanNext(globalOpts, planIdStr, _options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            success: false,
+            error: 'prov is not initialized. Run "prov init" first.',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Load graph
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            success: false,
+            error: loadResult.error ?? 'Failed to load graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Find the plan
+    const planId = planIdStr;
+    const node = graph.getNode(planId);
+    if (node === undefined || node.type !== 'plan') {
+        const result = {
+            success: false,
+            error: `Plan not found: ${planIdStr}`,
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const plan = node.data;
+    // Find next step (first non-completed step that's not blocked)
+    const completedSteps = new Set(plan.steps.filter((s) => s.status === 'completed').map((s) => s.id));
+    let nextStep;
+    for (const step of plan.steps) {
+        if (step.status === 'completed')
+            continue;
+        if (step.status === 'blocked')
+            continue;
+        // Check dependencies
+        if (step.dependencies !== undefined) {
+            const hasUnmetDeps = step.dependencies.some((depId) => !completedSteps.has(depId));
+            if (hasUnmetDeps)
+                continue;
+        }
+        // This is the next available step
+        nextStep = step;
+        break;
+    }
+    if (nextStep === undefined) {
+        const result = {
+            success: true,
+            planId,
+            message: 'All steps completed or blocked',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            success('All steps are completed or blocked');
+        }
+        return;
+    }
+    const stepEntry = {
+        id: nextStep.id,
+        number: nextStep.number,
+        action: nextStep.action,
+        status: nextStep.status ?? 'pending',
+        tracesTo: [...nextStep.tracesTo],
+    };
+    const result = {
+        success: true,
+        planId,
+        step: stepEntry,
+    };
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        process.stdout.write(`\nNext step for ${planId}\n`);
+        process.stdout.write(`${'─'.repeat(40)}\n`);
+        process.stdout.write(`Step ${nextStep.number}: ${nextStep.action}\n`);
+        if (nextStep.description !== undefined) {
+            process.stdout.write(`\n${nextStep.description}\n`);
+        }
+        process.stdout.write(`\nTraces to: ${nextStep.tracesTo.join(', ')}\n`);
+        process.stdout.write('\n');
+    }
+}
+/**
+ * Execute the plan remaining command.
+ *
+ * Lists all unimplemented steps in the plan.
+ *
+ * @see req:cli:plan-remaining
+ */
+export function runPlanRemaining(globalOpts, planIdStr, _options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            success: false,
+            error: 'prov is not initialized. Run "prov init" first.',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Load graph
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            success: false,
+            error: loadResult.error ?? 'Failed to load graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Find the plan
+    const planId = planIdStr;
+    const node = graph.getNode(planId);
+    if (node === undefined || node.type !== 'plan') {
+        const result = {
+            success: false,
+            error: `Plan not found: ${planIdStr}`,
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const plan = node.data;
+    // Filter to non-completed steps
+    const remainingSteps = plan.steps
+        .filter((s) => s.status !== 'completed')
+        .map((s) => ({
+        id: s.id,
+        number: s.number,
+        action: s.action,
+        status: s.status ?? 'pending',
+        tracesTo: [...s.tracesTo],
+    }));
+    const completedCount = plan.steps.filter((s) => s.status === 'completed').length;
+    const result = {
+        success: true,
+        planId,
+        remainingSteps,
+        totalSteps: plan.steps.length,
+        completedSteps: completedCount,
+    };
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        process.stdout.write(`\nRemaining steps for ${planId}\n`);
+        process.stdout.write(`${'─'.repeat(40)}\n`);
+        process.stdout.write(`Progress: ${completedCount}/${plan.steps.length} completed\n\n`);
+        if (remainingSteps.length === 0) {
+            success('All steps completed!');
+            return;
+        }
+        const columns = [
+            { header: '#', key: 'number', minWidth: 3, align: 'right' },
+            { header: 'Action', key: 'action', maxWidth: 50 },
+            { header: 'Status', key: 'status', minWidth: 12 },
+        ];
+        const rows = remainingSteps.map((s) => ({
+            number: s.number,
+            action: s.action,
+            status: s.status,
+        }));
+        output(rows, { format: 'table', columns });
+        process.stdout.write('\n');
+    }
+}
+/**
+ * Execute the plan progress command.
+ *
+ * Shows completion percentage and breakdown for a plan.
+ *
+ * @see req:agent:step-execution
+ */
+export function runPlanProgress(globalOpts, planIdStr, _options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            success: false,
+            error: 'prov is not initialized. Run "prov init" first.',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Load graph
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            success: false,
+            error: loadResult.error ?? 'Failed to load graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Find the plan
+    const planId = planIdStr;
+    const node = graph.getNode(planId);
+    if (node === undefined || node.type !== 'plan') {
+        const result = {
+            success: false,
+            error: `Plan not found: ${planIdStr}`,
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const plan = node.data;
+    // Count by status
+    const breakdown = {
+        pending: 0,
+        inProgress: 0,
+        completed: 0,
+        blocked: 0,
+    };
+    for (const step of plan.steps) {
+        const status = step.status ?? 'pending';
+        if (status === 'pending')
+            breakdown.pending++;
+        else if (status === 'in_progress')
+            breakdown.inProgress++;
+        else if (status === 'completed')
+            breakdown.completed++;
+        else if (status === 'blocked')
+            breakdown.blocked++;
+    }
+    const totalSteps = plan.steps.length;
+    const percentComplete = totalSteps > 0 ? Math.round((breakdown.completed / totalSteps) * 100) : 100;
+    const result = {
+        success: true,
+        planId,
+        progress: {
+            totalSteps,
+            completedSteps: breakdown.completed,
+            percentComplete,
+            breakdown,
+        },
+    };
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        process.stdout.write(`\nProgress for ${planId}\n`);
+        process.stdout.write(`${'─'.repeat(40)}\n\n`);
+        // Progress bar
+        const barWidth = 30;
+        const filledWidth = Math.round((percentComplete / 100) * barWidth);
+        const emptyWidth = barWidth - filledWidth;
+        const bar = '\u2588'.repeat(filledWidth) + '\u2591'.repeat(emptyWidth);
+        process.stdout.write(`[${bar}] ${percentComplete}%\n\n`);
+        // Breakdown
+        process.stdout.write(`Completed:   ${breakdown.completed}\n`);
+        process.stdout.write(`In Progress: ${breakdown.inProgress}\n`);
+        process.stdout.write(`Pending:     ${breakdown.pending}\n`);
+        process.stdout.write(`Blocked:     ${breakdown.blocked}\n`);
+        process.stdout.write(`${'─'.repeat(20)}\n`);
+        process.stdout.write(`Total:       ${totalSteps}\n\n`);
+    }
+}
+//# sourceMappingURL=plan.js.map