sdd-mcp-server 3.5.0 → 4.0.0

package/dist/application/services/WorkflowEngineService.js

@@ -10,351 +10,531 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
+var WorkflowEngineService_1;
+import path from 'node:path';
 import { injectable, inject } from 'inversify';
-import { v4 as uuidv4 } from 'uuid';
 import { TYPES } from '../../infrastructure/di/types.js';
-import { WorkflowPhase } from '../../domain/types.js';
-import { WorkflowStateMachine } from '../../domain/workflow/WorkflowStateMachine.js';
+import { WorkflowPhase, } from '../../domain/types.js';
 import { ProjectService } from './ProjectService.js';
 import { TemplateService } from './TemplateService.js';
 import { ContextCompactionService } from './ContextCompactionService.js';
+import { SpecPathResolver, validateFeatureName } from './SpecPathResolver.js';
 let WorkflowEngineService = class WorkflowEngineService {
+    static { WorkflowEngineService_1 = this; }
     projectRepository;
     projectService;
     templateService;
     contextCompactionService;
     logger;
-    validation;
-    stateMachine;
-    constructor(projectRepository, projectService, templateService, contextCompactionService, logger, validation) {
+    fileSystem;
+    static featureLocks = new Map();
+    constructor(projectRepository, projectService, templateService, contextCompactionService, logger, fileSystem) {
         this.projectRepository = projectRepository;
         this.projectService = projectService;
         this.templateService = templateService;
         this.contextCompactionService = contextCompactionService;
         this.logger = logger;
-        this.validation = validation;
-        this.stateMachine = new WorkflowStateMachine();
+        this.fileSystem = fileSystem;
     }
-    async progressToNextPhase(projectId, triggeredBy) {
-        const correlationId = uuidv4();
-        this.logger.info('Progressing project to next phase', {
-            correlationId,
-            projectId,
-            triggeredBy
-        });
-        const project = await this.projectRepository.findById(projectId);
-        if (!project) {
-            return {
-                success: false,
-                message: `Project not found: ${projectId}`
-            };
-        }
-        const nextPhase = this.stateMachine.getNextPhase(project.phase);
-        if (!nextPhase) {
+    async approve(request) {
+        return this.withFeatureLock(request.projectRoot, request.featureName, async () => {
+            const { featureRoot, specPath, spec } = await this.readDiskSpec(request.projectRoot, request.featureName);
+            const approvals = this.readApprovals(spec);
+            const current = approvals[request.phase];
+            if (!current.generated) {
+                throw new Error(`Cannot approve ${request.phase}: phase document has not been generated`);
+            }
+            const phaseIndex = ['requirements', 'design', 'tasks'].indexOf(request.phase);
+            for (const prior of ['requirements', 'design', 'tasks'].slice(0, phaseIndex)) {
+                if (!approvals[prior].approved)
+                    throw new Error(`Cannot approve ${request.phase}: ${prior} is not approved`);
+            }
+            if (!this.fileSystem)
+                throw new Error('FileSystemPort is required for disk-addressed workflow operations');
+            const resolver = new SpecPathResolver(this.fileSystem);
+            for (const selectedPhase of ['requirements', 'design', 'tasks'].slice(0, phaseIndex + 1)) {
+                const documentPath = path.join(featureRoot, `${selectedPhase}.md`);
+                await resolver.assertContained(featureRoot, documentPath);
+                if (!(await this.fileSystem.exists(documentPath))) {
+                    throw new Error(`Cannot approve ${request.phase}: required document is missing: ${selectedPhase}.md`);
+                }
+            }
+            const review = this.readReviewState(spec);
+            if (request.phase === 'tasks' && review.required && !review.reviewed) {
+                throw new Error('Cannot approve tasks: test-case review is required');
+            }
+            if (!current.approved) {
+                approvals[request.phase] = { ...current, approved: true };
+                const prospective = {
+                    ...spec,
+                    updated_at: new Date().toISOString(),
+                    phase: `${request.phase}-approved`,
+                    approvals,
+                    ready_for_implementation: request.phase === 'tasks',
+                };
+                await this.writeSpecAtomic(specPath, prospective);
+                await this.synchronizeRepository(featureRoot, approvals);
+            }
+            const handoff = await this.publishHandoff(request.projectRoot, request.featureName);
             return {
-                success: false,
-                message: `Project is already at final phase: ${project.phase}`
+                featureName: request.featureName,
+                phase: request.phase,
+                approved: true,
+                canProgressToNext: request.phase !== 'tasks' || !review.required || review.reviewed,
+                handoff,
             };
-        }
-        return await this.transitionToPhase(projectId, nextPhase, triggeredBy);
+        });
     }
-    async transitionToPhase(projectId, targetPhase, triggeredBy) {
-        const correlationId = uuidv4();
-        this.logger.info('Transitioning project to phase', {
-            correlationId,
-            projectId,
-            targetPhase,
-            triggeredBy
+    async reviewTestCases(request) {
+        return this.withFeatureLock(request.projectRoot, request.featureName, async () => {
+            const { specPath, spec } = await this.readDiskSpec(request.projectRoot, request.featureName);
+            const approvals = this.readApprovals(spec);
+            const review = this.readReviewState(spec);
+            if (!review.required)
+                throw new Error('Test-case review is not configured for this feature');
+            if (!approvals.tasks.generated)
+                throw new Error('Cannot review test cases before tasks are generated');
+            if (!review.reviewed) {
+                const checkpointsValue = spec.checkpoints;
+                const checkpoints = checkpointsValue && typeof checkpointsValue === 'object'
+                    ? checkpointsValue
+                    : {};
+                const key = 'test_cases' in checkpoints ? 'test_cases' : 'testCases';
+                const testValue = checkpoints[key];
+                const test = testValue && typeof testValue === 'object' ? testValue : {};
+                const prospective = {
+                    ...spec,
+                    updated_at: new Date().toISOString(),
+                    checkpoints: {
+                        ...checkpoints,
+                        [key]: { ...test, required: true, reviewed: true, reviewed_at: new Date().toISOString() },
+                    },
+                };
+                await this.writeSpecAtomic(specPath, prospective);
+            }
+            const handoff = await this.publishHandoff(request.projectRoot, request.featureName);
+            return { featureName: request.featureName, reviewed: true, canApproveTasks: true, handoff };
         });
-        const project = await this.projectRepository.findById(projectId);
-        if (!project) {
-            return {
-                success: false,
-                message: `Project not found: ${projectId}`
-            };
-        }
-        if (project.phase === targetPhase) {
-            return {
-                success: true,
-                updatedProject: project,
-                message: `Project is already in ${targetPhase} phase`
-            };
-        }
-        const result = await this.stateMachine.executeTransition(project, targetPhase, triggeredBy);
-        if (!result.success) {
-            this.logger.warn('Phase transition failed', {
-                correlationId,
-                projectId,
-                fromPhase: project.phase,
-                targetPhase,
-                error: result.error
+    }
+    async rollback(request) {
+        return this.withFeatureLock(request.projectRoot, request.featureName, async () => {
+            const { specPath, spec } = await this.readDiskSpec(request.projectRoot, request.featureName);
+            const approvals = this.readApprovals(spec);
+            const rolledBackPhase = ([...['requirements', 'design', 'tasks']].reverse())
+                .find((phase) => approvals[phase].approved);
+            if (!rolledBackPhase)
+                throw new Error('Feature has no approved phase to roll back');
+            const phaseIndex = ['requirements', 'design', 'tasks'].indexOf(rolledBackPhase);
+            for (const phase of ['requirements', 'design', 'tasks'].slice(phaseIndex)) {
+                approvals[phase] = { ...approvals[phase], approved: false };
+            }
+            const prior = phaseIndex > 0 ? ['requirements', 'design', 'tasks'][phaseIndex - 1] : undefined;
+            await this.writeSpecAtomic(specPath, {
+                ...spec,
+                updated_at: new Date().toISOString(),
+                phase: prior ? `${prior}-approved` : 'init',
+                approvals,
+                ready_for_implementation: false,
+                rollback_triggered_by: request.triggeredBy,
             });
-            return {
-                success: false,
-                message: result.error || 'Phase transition failed',
-                auditEntry: result.auditEntry
-            };
-        }
-        // Save updated project
-        if (result.updatedProject) {
-            await this.projectRepository.save(result.updatedProject);
-            // Generate phase-specific deliverables if needed
-            await this.generatePhaseDeliverables(result.updatedProject, targetPhase);
-        }
-        this.logger.info('Phase transition completed successfully', {
-            correlationId,
-            projectId,
-            fromPhase: project.phase,
-            targetPhase
+            await this.contextCompactionService.invalidateCanonicalHandoff(request);
+            const handoff = await this.publishHandoff(request.projectRoot, request.featureName);
+            return { featureName: request.featureName, rolledBackPhase, handoff };
         });
-        const nextSteps = this.getNextSteps(result.updatedProject || project, targetPhase);
+    }
+    async initializeFeature(request) {
+        return this.withFeatureLock(request.projectRoot, request.featureName, async () => {
+            if (!this.fileSystem)
+                throw new Error('FileSystemPort is required for disk-addressed workflow operations');
+            validateFeatureName(request.featureName);
+            const absoluteProject = path.resolve(request.projectRoot);
+            const resolver = new SpecPathResolver(this.fileSystem);
+            const canonicalProject = this.fileSystem.realpath
+                ? await this.fileSystem.realpath(absoluteProject)
+                : absoluteProject;
+            await resolver.assertContained(canonicalProject, path.join(canonicalProject, '.spec'));
+            await this.fileSystem.mkdir(path.join(canonicalProject, '.spec', 'specs'));
+            const resolved = await resolver.resolve(canonicalProject, request.featureName);
+            if (await this.fileSystem.exists(resolved.featureRoot)) {
+                throw new Error(`Feature already exists: ${request.featureName}`);
+            }
+            const project = await this.projectService.createProject(request.featureName, resolved.projectRoot, request.language, { reviewTestCases: request.reviewTestCases });
+            try {
+                const rendered = await this.templateService.generateSpecJson(project);
+                const parsed = JSON.parse(rendered);
+                await this.writeSpecAtomic(path.join(resolved.featureRoot, 'spec.json'), parsed);
+                return project;
+            }
+            catch (error) {
+                await this.projectRepository.delete(project.id);
+                throw error;
+            }
+        });
+    }
+    async listFeatureStatuses(request) {
+        if (!this.fileSystem)
+            throw new Error('FileSystemPort is required for disk-addressed workflow operations');
+        const absoluteProject = path.resolve(request.projectRoot);
+        const specsRoot = path.join(absoluteProject, '.spec', 'specs');
+        if (!(await this.fileSystem.exists(specsRoot)))
+            return [];
+        const resolver = new SpecPathResolver(this.fileSystem);
+        await resolver.assertContained(absoluteProject, specsRoot);
+        const names = (await this.fileSystem.readdir(specsRoot)).sort();
+        const results = [];
+        for (const featureName of names) {
+            const candidate = path.join(specsRoot, featureName);
+            const stat = await this.fileSystem.stat(candidate);
+            if (!stat.isDirectory())
+                continue;
+            const project = await this.loadProject({ projectRoot: absoluteProject, featureName });
+            results.push({ featureName: project.name, phase: project.phase });
+        }
+        return results;
+    }
+    async getFeatureStatus(request) {
+        const { projectRoot, spec } = await this.readDiskSpec(request.projectRoot, request.featureName);
+        const project = await this.hydrateProject(projectRoot, request.featureName, spec);
+        const approvals = this.readApprovals(spec);
+        const review = this.readReviewState(spec);
+        const progression = this.resolveProgression(approvals, review, project.phase);
         return {
-            success: true,
-            updatedProject: result.updatedProject,
-            message: `Project successfully transitioned to ${targetPhase} phase`,
-            auditEntry: result.auditEntry,
-            nextSteps
+            featureName: project.name,
+            phase: project.phase,
+            currentPhase: project.phase,
+            nextPhase: progression.nextPhase,
+            canProgress: progression.nextPhase !== undefined && progression.blockers.length === 0,
+            blockers: progression.blockers,
+            testCases: review,
         };
     }
-    async rollbackToPreviousPhase(projectId, triggeredBy) {
-        const correlationId = uuidv4();
-        this.logger.info('Rolling back project to previous phase', {
-            correlationId,
-            projectId,
-            triggeredBy
+    async loadProject(request) {
+        const { projectRoot, spec } = await this.readDiskSpec(request.projectRoot, request.featureName);
+        return this.hydrateProject(projectRoot, request.featureName, spec);
+    }
+    async generatePhase(request) {
+        return this.withFeatureLock(request.projectRoot, request.featureName, async () => {
+            const fileSystem = this.requireAtomicFileSystem();
+            const { projectRoot, featureRoot, specPath, spec } = await this.readDiskSpec(request.projectRoot, request.featureName);
+            const approvals = this.readApprovals(spec);
+            this.assertPhaseCanBeGenerated(request.phase, approvals);
+            const project = await this.hydrateProject(projectRoot, request.featureName, spec);
+            const content = await this.renderPhase(project, request.phase);
+            await this.persistPhaseDocument(fileSystem, featureRoot, request.phase, content, approvals[request.phase].generated);
+            const prospective = this.buildGeneratedSpec(spec, request);
+            await this.writeSpecAtomic(specPath, prospective);
+            await this.synchronizeRepository(featureRoot, this.readApprovals(prospective));
+            return `${this.phaseTitle(request.phase)} document generated for project "${request.featureName}"`;
         });
-        const project = await this.projectRepository.findById(projectId);
-        if (!project) {
-            return {
-                success: false,
-                message: `Project not found: ${projectId}`
-            };
-        }
-        const previousPhase = this.stateMachine.getPreviousPhase(project.phase);
-        if (!previousPhase) {
-            return {
-                success: false,
-                message: `Project is already at initial phase: ${project.phase}`
+    }
+    async beginImplementation(request) {
+        return this.withFeatureLock(request.projectRoot, request.featureName, async () => {
+            const { featureRoot, specPath, spec } = await this.readDiskSpec(request.projectRoot, request.featureName);
+            const approvals = this.readApprovals(spec);
+            const review = this.readReviewState(spec);
+            if (!approvals.tasks.approved)
+                throw new Error('Cannot begin implementation: tasks are not approved');
+            if (review.required && !review.reviewed) {
+                throw new Error('Cannot begin implementation: test-case review is required');
+            }
+            if (spec.phase === WorkflowPhase.IMPLEMENTATION && spec.ready_for_implementation === true) {
+                return { featureName: request.featureName, phase: WorkflowPhase.IMPLEMENTATION, ready: true };
+            }
+            const prospective = {
+                ...spec,
+                updated_at: new Date().toISOString(),
+                phase: WorkflowPhase.IMPLEMENTATION,
+                ready_for_implementation: true,
             };
+            await this.writeSpecAtomic(specPath, prospective);
+            await this.synchronizeRepository(featureRoot, approvals);
+            return { featureName: request.featureName, phase: WorkflowPhase.IMPLEMENTATION, ready: true };
+        });
+    }
+    requireAtomicFileSystem() {
+        if (!this.fileSystem?.writeFileAtomic) {
+            throw new Error('FileSystemPort.writeFileAtomic is required for workflow persistence');
         }
-        const result = await this.stateMachine.executeTransition(project, previousPhase, triggeredBy);
-        if (!result.success) {
-            this.logger.warn('Phase rollback failed', {
-                correlationId,
-                projectId,
-                fromPhase: project.phase,
-                targetPhase: previousPhase,
-                error: result.error
-            });
-            return {
-                success: false,
-                message: result.error || 'Phase rollback failed',
-                auditEntry: result.auditEntry
-            };
+        return this.fileSystem;
+    }
+    assertPhaseCanBeGenerated(phase, approvals) {
+        const phases = ['requirements', 'design', 'tasks'];
+        for (const prior of phases.slice(0, phases.indexOf(phase))) {
+            if (!approvals[prior].approved) {
+                throw new Error(`Cannot generate ${phase}: ${prior} is not approved`);
+            }
         }
-        // Save updated project
-        if (result.updatedProject) {
-            await this.projectRepository.save(result.updatedProject);
-            // Reset approvals for rolled back phase
-            await this.resetPhaseApprovals(result.updatedProject, project.phase);
+        if (approvals[phase].approved) {
+            throw new Error(`Cannot generate ${phase}: phase is already approved`);
         }
-        this.logger.info('Phase rollback completed successfully', {
-            correlationId,
-            projectId,
-            fromPhase: project.phase,
-            targetPhase: previousPhase
-        });
-        return {
-            success: true,
-            updatedProject: result.updatedProject,
-            message: `Project rolled back to ${previousPhase} phase`,
-            auditEntry: result.auditEntry
-        };
     }
-    async updateApprovalStatus(projectId, phase, approval, triggeredBy) {
-        const correlationId = uuidv4();
-        this.logger.info('Updating approval status', {
-            correlationId,
-            projectId,
-            phase,
-            approval,
-            triggeredBy
-        });
-        const updatedProject = await this.projectService.updateApprovalStatus(projectId, phase, approval);
-        // Update spec.json file
-        const specContent = await this.templateService.generateSpecJson(updatedProject);
-        await this.templateService.writeProjectFile(updatedProject, 'spec.json', specContent);
-        let handoffResult;
-        if (approval.approved) {
-            handoffResult = await this.contextCompactionService.generatePhaseHandoff(updatedProject, phase);
+    async persistPhaseDocument(fileSystem, featureRoot, phase, content, alreadyGenerated) {
+        const resolver = new SpecPathResolver(fileSystem);
+        const documentPath = path.join(featureRoot, `${phase}.md`);
+        await resolver.assertContained(featureRoot, documentPath);
+        if (!(await fileSystem.exists(documentPath))) {
+            await fileSystem.writeFileAtomic(documentPath, content);
+            return;
         }
-        // Check if project can progress to next phase
-        const nextPhase = this.stateMachine.getNextPhase(updatedProject.phase);
-        let canProgressToNext = false;
-        if (nextPhase) {
-            const validation = this.stateMachine.canTransition(updatedProject, nextPhase);
-            canProgressToNext = validation.allowed;
+        const existing = await fileSystem.readFile(documentPath);
+        if (alreadyGenerated || existing !== content) {
+            throw new Error(`Cannot generate ${phase}: phase document already exists`);
         }
-        const message = approval.approved
-            ? `${phase} phase approved and ready for progression`
-            : `${phase} phase approval status updated`;
-        const messageWithHandoff = handoffResult
-            ? `${message}. Compact handoff: ${handoffResult.path} (${handoffResult.estimate.reductionPercentage}% estimated context reduction, ~${handoffResult.estimate.sourceTokens} -> ~${handoffResult.estimate.compactTokens} tokens)`
-            : message;
-        this.logger.info('Approval status updated successfully', {
-            correlationId,
-            projectId,
-            phase,
-            canProgressToNext
-        });
-        return {
-            success: true,
-            updatedProject,
-            message: messageWithHandoff,
-            canProgressToNext
-        };
     }
-    async getWorkflowStatus(projectId) {
-        const project = await this.projectRepository.findById(projectId);
-        if (!project) {
-            return null;
+    buildGeneratedSpec(spec, request) {
+        const approvalRecord = spec.approvals && typeof spec.approvals === 'object'
+            ? spec.approvals
+            : {};
+        const prospective = {
+            ...spec,
+            updated_at: new Date().toISOString(),
+            phase: `${request.phase}-generated`,
+            approvals: {
+                ...approvalRecord,
+                [request.phase]: { generated: true, approved: false },
+            },
+            ready_for_implementation: false,
+        };
+        if (request.phase !== 'tasks' || typeof request.reviewTestCases !== 'boolean') {
+            return prospective;
         }
-        return {
-            project,
-            progress: this.stateMachine.getPhaseProgress(project),
-            auditTrail: this.stateMachine.getAuditTrail(projectId),
-            integrity: this.stateMachine.validateWorkflowIntegrity(project),
-            validTransitions: this.stateMachine.getValidTransitions(project.phase)
+        const options = spec.workflow_options && typeof spec.workflow_options === 'object'
+            ? spec.workflow_options
+            : {};
+        const checkpoints = spec.checkpoints && typeof spec.checkpoints === 'object'
+            ? spec.checkpoints
+            : {};
+        const checkpointKey = 'test_cases' in checkpoints ? 'test_cases' : 'testCases';
+        const existingTest = checkpoints[checkpointKey] && typeof checkpoints[checkpointKey] === 'object'
+            ? checkpoints[checkpointKey]
+            : {};
+        prospective.workflow_options = {
+            ...options,
+            review_test_cases: request.reviewTestCases,
         };
+        prospective.checkpoints = {
+            ...checkpoints,
+            [checkpointKey]: {
+                ...existingTest,
+                required: request.reviewTestCases,
+                reviewed: !request.reviewTestCases,
+            },
+        };
+        return prospective;
     }
-    async validateWorkflowState(projectId) {
-        const status = await this.getWorkflowStatus(projectId);
-        if (!status) {
-            return {
-                isValid: false,
-                violations: ['Project not found'],
-                recommendations: [],
-                canProgress: false
-            };
+    async renderPhase(project, phase) {
+        if (phase === 'requirements')
+            return this.templateService.generateRequirementsTemplate(project);
+        if (phase === 'design')
+            return this.templateService.generateDesignTemplate(project);
+        return this.templateService.generateTasksTemplate(project);
+    }
+    phaseTitle(phase) {
+        if (phase === 'requirements')
+            return 'Requirements';
+        if (phase === 'design')
+            return 'Design';
+        return 'Tasks';
+    }
+    async hydrateProject(projectRoot, featureName, spec) {
+        const persistedName = typeof spec.feature_name === 'string'
+            ? spec.feature_name
+            : typeof spec.name === 'string'
+                ? spec.name
+                : undefined;
+        if (persistedName !== undefined && persistedName !== featureName) {
+            throw new Error(`Feature metadata name does not match directory: ${featureName}`);
         }
-        const integrity = status.integrity;
-        const progress = status.progress;
-        return {
-            isValid: integrity.isValid,
-            violations: integrity.violations,
-            recommendations: integrity.recommendations,
-            canProgress: progress.canProgress,
-            nextPhase: progress.nextPhase
+        const approvals = this.readApprovals(spec);
+        const review = this.readReviewState(spec);
+        const existing = (await this.projectRepository.list()).find((candidate) => candidate.name === featureName);
+        const project = {
+            id: existing?.id ?? `disk:${featureName}`,
+            name: featureName,
+            path: projectRoot,
+            phase: this.readWorkflowPhase(spec, approvals),
+            metadata: {
+                createdAt: this.readDate(spec.created_at ?? spec.createdAt),
+                updatedAt: this.readDate(spec.updated_at ?? spec.updatedAt),
+                language: typeof spec.language === 'string' ? spec.language : 'en',
+                approvals,
+                workflowOptions: { reviewTestCases: review.required },
+                checkpoints: { testCases: review },
+            },
         };
+        await this.projectRepository.save(project);
+        return project;
     }
-    async generatePhaseDeliverables(project, phase) {
+    readDate(value) {
+        if (typeof value === 'string' || value instanceof Date) {
+            const parsed = new Date(value);
+            if (!Number.isNaN(parsed.getTime()))
+                return parsed;
+        }
+        return new Date(0);
+    }
+    readWorkflowPhase(spec, approvals) {
+        const phase = typeof spec.phase === 'string' ? spec.phase : '';
+        if (phase.startsWith('implementation'))
+            return WorkflowPhase.IMPLEMENTATION;
+        if (phase.startsWith('tasks') || approvals.tasks.generated)
+            return WorkflowPhase.TASKS;
+        if (phase.startsWith('design') || approvals.design.generated)
+            return WorkflowPhase.DESIGN;
+        if (phase.startsWith('requirements') || approvals.requirements.generated)
+            return WorkflowPhase.REQUIREMENTS;
+        return WorkflowPhase.INIT;
+    }
+    resolveProgression(approvals, review, currentPhase) {
+        if (currentPhase === WorkflowPhase.IMPLEMENTATION)
+            return { blockers: [] };
+        if (!approvals.requirements.generated)
+            return { nextPhase: WorkflowPhase.REQUIREMENTS, blockers: [] };
+        if (!approvals.requirements.approved) {
+            return { nextPhase: WorkflowPhase.DESIGN, blockers: ['Requirements must be approved'] };
+        }
+        if (!approvals.design.generated)
+            return { nextPhase: WorkflowPhase.DESIGN, blockers: [] };
+        if (!approvals.design.approved) {
+            return { nextPhase: WorkflowPhase.TASKS, blockers: ['Design must be approved'] };
+        }
+        if (!approvals.tasks.generated)
+            return { nextPhase: WorkflowPhase.TASKS, blockers: [] };
+        if (!approvals.tasks.approved) {
+            return { nextPhase: WorkflowPhase.IMPLEMENTATION, blockers: ['Tasks must be approved'] };
+        }
+        if (review.required && !review.reviewed) {
+            return { nextPhase: WorkflowPhase.IMPLEMENTATION, blockers: ['Test cases must be reviewed'] };
+        }
+        return { nextPhase: WorkflowPhase.IMPLEMENTATION, blockers: [] };
+    }
+    async withFeatureLock(projectRoot, featureName, operation) {
+        const key = `${path.resolve(projectRoot)}\0${featureName}`;
+        const previous = WorkflowEngineService_1.featureLocks.get(key) ?? Promise.resolve();
+        let release = () => undefined;
+        const gate = new Promise((resolve) => { release = resolve; });
+        const current = previous.then(() => gate);
+        WorkflowEngineService_1.featureLocks.set(key, current);
+        await previous;
         try {
-            switch (phase) {
-                case WorkflowPhase.REQUIREMENTS:
-                    if (!project.metadata.approvals.requirements.generated) {
-                        const content = await this.templateService.generateRequirementsTemplate(project);
-                        await this.templateService.writeProjectFile(project, 'requirements.md', content);
-                        await this.projectService.updateApprovalStatus(project.id, 'requirements', { generated: true });
-                    }
-                    break;
-                case WorkflowPhase.DESIGN:
-                    if (!project.metadata.approvals.design.generated) {
-                        const content = await this.templateService.generateDesignTemplate(project);
-                        await this.templateService.writeProjectFile(project, 'design.md', content);
-                        await this.projectService.updateApprovalStatus(project.id, 'design', { generated: true });
-                    }
-                    break;
-                case WorkflowPhase.TASKS:
-                    if (!project.metadata.approvals.tasks.generated) {
-                        const content = await this.templateService.generateTasksTemplate(project);
-                        await this.templateService.writeProjectFile(project, 'tasks.md', content);
-                        await this.projectService.updateApprovalStatus(project.id, 'tasks', { generated: true });
-                    }
-                    break;
-            }
+            return await operation();
         }
-        catch (error) {
-            this.logger.error('Failed to generate phase deliverables', error, {
-                projectId: project.id,
-                phase
-            });
+        finally {
+            release();
+            if (WorkflowEngineService_1.featureLocks.get(key) === current) {
+                WorkflowEngineService_1.featureLocks.delete(key);
+            }
         }
     }
-    async resetPhaseApprovals(project, rolledBackFromPhase) {
-        // Reset approvals for the phase we're rolling back from
-        const resetApprovals = {};
-        switch (rolledBackFromPhase) {
-            case WorkflowPhase.REQUIREMENTS:
-                resetApprovals.requirements = { approved: false };
-                break;
-            case WorkflowPhase.DESIGN:
-                resetApprovals.design = { approved: false };
-                break;
-            case WorkflowPhase.TASKS:
-                resetApprovals.tasks = { approved: false };
-                break;
-            case WorkflowPhase.IMPLEMENTATION:
-                // No approvals to reset for implementation phase
-                break;
+    async readDiskSpec(projectRoot, featureName) {
+        if (!this.fileSystem)
+            throw new Error('FileSystemPort is required for disk-addressed workflow operations');
+        const resolver = new SpecPathResolver(this.fileSystem);
+        const resolved = await resolver.resolve(projectRoot, featureName);
+        const specPath = path.join(resolved.featureRoot, 'spec.json');
+        await resolver.assertContained(resolved.featureRoot, specPath);
+        if (!(await this.fileSystem.exists(specPath)))
+            throw new Error(`Feature metadata not found: ${featureName}`);
+        let parsed;
+        try {
+            parsed = JSON.parse(await this.fileSystem.readFile(specPath));
+        }
+        catch {
+            throw new Error(`Feature metadata is malformed: ${featureName}`);
         }
-        for (const [phase, approval] of Object.entries(resetApprovals)) {
-            await this.projectService.updateApprovalStatus(project.id, phase, approval);
+        if (!parsed || typeof parsed !== 'object')
+            throw new Error(`Feature metadata is invalid: ${featureName}`);
+        const record = parsed;
+        const persistedName = typeof record.feature_name === 'string'
+            ? record.feature_name
+            : typeof record.name === 'string'
+                ? record.name
+                : undefined;
+        if (persistedName !== undefined && persistedName !== featureName) {
+            throw new Error(`Feature metadata name does not match directory: ${featureName}`);
         }
+        return { projectRoot: resolved.projectRoot, featureRoot: resolved.featureRoot, specPath, spec: record };
     }
-    getNextSteps(project, currentPhase) {
-        const steps = [];
-        switch (currentPhase) {
-            case WorkflowPhase.INIT:
-                steps.push('Run sdd-requirements to generate requirements document');
-                break;
-            case WorkflowPhase.REQUIREMENTS:
-                if (!project.metadata.approvals.requirements.approved) {
-                    steps.push('Review and approve requirements document');
-                    steps.push('Run sdd-design after requirements approval');
-                }
-                else {
-                    steps.push('Run sdd-design to generate technical design');
-                }
-                break;
-            case WorkflowPhase.DESIGN:
-                if (!project.metadata.approvals.design.approved) {
-                    steps.push('Review and approve design document');
-                    steps.push('Run sdd-tasks after design approval');
-                }
-                else {
-                    steps.push('Run sdd-tasks to generate implementation tasks');
-                }
-                break;
-            case WorkflowPhase.TASKS:
-                if (!project.metadata.approvals.tasks.approved) {
-                    steps.push('Review and approve task breakdown');
-                    if (project.metadata.checkpoints?.testCases.required && !project.metadata.checkpoints.testCases.reviewed) {
-                        steps.push('Review TDD test cases and run sdd-review-test-cases');
-                    }
-                    steps.push('Begin implementation after tasks approval');
-                }
-                else {
-                    steps.push('Begin implementation following the task breakdown');
-                    steps.push('Use sdd-quality-check for code reviews');
-                }
-                break;
-            case WorkflowPhase.IMPLEMENTATION:
-                steps.push('Continue implementation following approved tasks');
-                steps.push('Use sdd-quality-check for ongoing code quality');
-                steps.push('Update task completion status as you progress');
-                break;
+    readApprovals(spec) {
+        const value = spec.approvals;
+        if (!value || typeof value !== 'object')
+            throw new Error('Feature metadata has no approval state');
+        const record = value;
+        const result = {};
+        for (const phase of ['requirements', 'design', 'tasks']) {
+            const phaseValue = record[phase];
+            const state = phaseValue && typeof phaseValue === 'object' ? phaseValue : {};
+            result[phase] = { generated: state.generated === true, approved: state.approved === true };
         }
-        return steps;
+        return result;
+    }
+    readReviewState(spec) {
+        const checkpointsValue = spec.checkpoints;
+        const checkpoints = checkpointsValue && typeof checkpointsValue === 'object'
+            ? checkpointsValue
+            : {};
+        const testValue = checkpoints.test_cases ?? checkpoints.testCases;
+        const test = testValue && typeof testValue === 'object' ? testValue : {};
+        const optionsValue = spec.workflow_options ?? spec.workflowOptions;
+        const options = optionsValue && typeof optionsValue === 'object' ? optionsValue : {};
+        return {
+            required: test.required === true || options.review_test_cases === true || options.reviewTestCases === true,
+            reviewed: test.reviewed === true,
+        };
+    }
+    async writeSpecAtomic(specPath, spec) {
+        if (!this.fileSystem?.writeFileAtomic)
+            throw new Error('FileSystemPort.writeFileAtomic is required for workflow persistence');
+        await this.fileSystem.writeFileAtomic(specPath, `${JSON.stringify(spec, null, 2)}\n`);
+    }
+    async publishHandoff(projectRoot, featureName) {
+        try {
+            const result = await this.contextCompactionService.loadContext({ projectRoot, featureName, mode: 'compact' });
+            return {
+                status: 'published',
+                path: path.join(projectRoot, '.spec', 'specs', featureName, 'context', 'handoff.md'),
+                fingerprint: result.fingerprint,
+                payloadEstimatedTokens: result.payloadEstimatedTokens,
+            };
+        }
+        catch (error) {
+            try {
+                await this.contextCompactionService.invalidateCanonicalHandoff({ projectRoot, featureName });
+            }
+            catch {
+                // A missing cache is already invalid; publication remains repairable.
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger.warn('Workflow state committed but handoff publication failed', { featureName, message });
+            return {
+                status: 'pending-regeneration',
+                warning: { code: 'HandoffPublicationFailed', message },
+            };
+        }
+    }
+    async synchronizeRepository(featureRoot, approvals) {
+        const projects = await this.projectRepository.list();
+        const existing = projects.find((project) => project.name === path.basename(featureRoot));
+        if (!existing)
+            return;
+        await this.projectRepository.save({
+            ...existing,
+            metadata: {
+                ...existing.metadata,
+                updatedAt: new Date(),
+                approvals,
+            },
+        });
     }
 };
-WorkflowEngineService = __decorate([
+WorkflowEngineService = WorkflowEngineService_1 = __decorate([
     injectable(),
     __param(0, inject(TYPES.ProjectRepository)),
     __param(1, inject(TYPES.ProjectService)),
     __param(2, inject(TYPES.TemplateService)),
     __param(3, inject(TYPES.ContextCompactionService)),
     __param(4, inject(TYPES.LoggerPort)),
-    __param(5, inject(TYPES.ValidationPort)),
+    __param(5, inject(TYPES.FileSystemPort)),
     __metadata("design:paramtypes", [Object, ProjectService,
         TemplateService,
         ContextCompactionService, Object, Object])