sdd-mcp-server 5.3.0 → 5.5.0

package/dist/application/services/WorkflowEngineService.js

@@ -19,7 +19,7 @@ import { TYPES } from '../../infrastructure/di/types.js';
 import { WorkflowPhase, } from '../../domain/types.js';
 import { ContextCompactionService, } from './ContextCompactionService.js';
 import { InvalidFeatureNameError, SpecPathResolver, validateFeatureName } from './SpecPathResolver.js';
-import { WorkflowValidationService } from './WorkflowValidationService.js';
+import { WorkflowValidationService, taskAcceptanceCriteria } from './WorkflowValidationService.js';
 import { GovernanceError } from './WorkflowErrors.js';
 import { FilesystemLockCompromisedError, withFilesystemLock } from '../../utils/withFilesystemLock.js';
 const PHASES = ['requirements', 'design', 'tasks'];
@@ -76,7 +76,10 @@ let WorkflowEngineService = class WorkflowEngineService {
         const initializationLock = path.join(resolved.specsRoot, `.${request.featureName}.init.lock`);
         await resolver.assertContained(resolved.specsRoot, initializationLock);
         return withFilesystemLock(initializationLock, async (lease) => {
-            if (await this.fileSystem.exists(resolved.featureRoot)) {
+            // Older versions left empty feature directories behind; reuse those, never populated ones.
+            const occupied = await this.fileSystem.exists(resolved.featureRoot)
+                && (await this.fileSystem.readdir(resolved.featureRoot)).length > 0;
+            if (occupied) {
                 throw new GovernanceError('StateInvariantViolation', `Feature already exists: ${request.featureName}`);
             }
             await this.fileSystem.mkdir(resolved.featureRoot);
@@ -125,14 +128,14 @@ let WorkflowEngineService = class WorkflowEngineService {
             const record = spec.approvals[request.phase];
             this.assertPriorApproved(request.phase, spec.approvals);
             if (record.approved)
-                throw new GovernanceError('PhaseNotApproved', `${request.phase} is already approved`);
+                throw new GovernanceError('PhaseNotApproved', `${request.phase} is already approved. Reload status and continue with the next phase.`);
             if (record.revision !== request.expectedRevision)
-                throw new GovernanceError('RevisionConflict', `Expected revision ${request.expectedRevision}, found ${record.revision}`);
+                throw new GovernanceError('RevisionConflict', `Expected revision ${request.expectedRevision}, found ${record.revision}. Reload status and submit again with the current revision.`);
             const artifactPath = path.join(featureRoot, `${request.phase}.md`);
             const priorArtifact = await this.readOptional(artifactPath);
             const observedHash = priorArtifact === null ? null : sha256(priorArtifact);
             if (observedHash !== request.expectedArtifactSha256) {
-                throw new GovernanceError('ArtifactDrift', `${request.phase}.md changed since it was observed`, { observedArtifactSha256: observedHash });
+                throw new GovernanceError('ArtifactDrift', `${request.phase}.md changed since it was observed. Reread the artifact and submit again with its current content.`, { observedArtifactSha256: observedHash });
             }
             if (request.phase === 'tasks') {
                 if (typeof request.reviewTestCases !== 'boolean')
@@ -172,27 +175,27 @@ let WorkflowEngineService = class WorkflowEngineService {
             await this.assertNoApprovedArtifactDrift(featureRoot, spec);
             const record = spec.approvals[request.phase];
             if (!record.generated)
-                throw new GovernanceError('PhaseNotApproved', `${request.phase} has not been submitted`);
+                throw new GovernanceError('PhaseNotApproved', `${request.phase} has not been submitted. Submit the phase artifact before approval.`);
             if (record.revision !== request.expectedRevision)
-                throw new GovernanceError('RevisionConflict', 'The reviewed revision is stale');
+                throw new GovernanceError('RevisionConflict', 'The reviewed revision is stale. Reload status and review the current revision.');
             if (record.artifactSha256 !== request.expectedArtifactSha256)
-                throw new GovernanceError('ArtifactDrift', 'The reviewed artifact hash is stale');
+                throw new GovernanceError('ArtifactDrift', 'The reviewed artifact hash is stale. Reload status and review the current artifact.');
             const artifact = await this.requireArtifact(featureRoot, request.phase);
             if (sha256(artifact) !== record.artifactSha256)
-                throw new GovernanceError('ArtifactDrift', `${request.phase}.md differs from the submitted artifact`);
+                throw new GovernanceError('ArtifactDrift', `${request.phase}.md differs from the submitted artifact. Inspect the changed artifact, then revise it in its phase Skill.`);
             this.assertPriorApproved(request.phase, spec.approvals);
             if (record.validation.status !== 'passed' && record.validation.status !== 'legacy-accepted')
-                throw new GovernanceError('PhaseValidationFailed', `${request.phase} did not pass validation`, { blockers: record.validation.blockers });
+                throw new GovernanceError('PhaseValidationFailed', `${request.phase} did not pass validation. Fix the listed blockers and submit the phase again.`, { blockers: record.validation.blockers });
             if (record.validation.status === 'passed') {
                 const upstream = await this.readUpstream(featureRoot, request.phase);
                 const validation = this.validate(request.phase, artifact, upstream.requirements, upstream.design);
                 if (validation.status !== 'passed')
-                    throw new GovernanceError('PhaseValidationFailed', `${request.phase} no longer validates`, { blockers: validation.blockers });
+                    throw new GovernanceError('PhaseValidationFailed', `${request.phase} no longer validates. Fix the listed blockers and submit the phase again.`, { blockers: validation.blockers });
             }
             const checkpoint = spec.checkpoints.test_cases;
             if (request.phase === 'tasks' && spec.workflow_options.review_test_cases === true &&
                 (!checkpoint.reviewed || checkpoint.reviewed_revision !== record.revision || checkpoint.reviewed_artifact_sha256 !== record.artifactSha256)) {
-                throw new GovernanceError('PhaseNotApproved', 'The current tasks revision requires explicit test-case review');
+                throw new GovernanceError('PhaseNotApproved', 'The current tasks revision requires explicit test-case review. Record the test-case review decision before approving tasks.');
             }
             if (!record.approved) {
                 spec.approvals[request.phase] = { ...record, approved: true };
@@ -211,18 +214,18 @@ let WorkflowEngineService = class WorkflowEngineService {
             if (spec.workflow_options.review_test_cases !== true)
                 throw new GovernanceError('StateInvariantViolation', 'Test-case review is not required');
             if (!tasks.generated)
-                throw new GovernanceError('PhaseNotApproved', 'Tasks are not ready for test-case review');
+                throw new GovernanceError('PhaseNotApproved', 'Tasks are not generated yet. Submit the tasks phase before test-case review.');
             if (tasks.revision !== request.expectedTasksRevision)
-                throw new GovernanceError('RevisionConflict', 'The tasks review revision is stale');
+                throw new GovernanceError('RevisionConflict', 'The tasks review revision is stale. Reload status and review the current tasks revision.');
             if (tasks.artifactSha256 !== request.expectedArtifactSha256 || sha256(await this.requireArtifact(featureRoot, 'tasks')) !== request.expectedArtifactSha256)
-                throw new GovernanceError('ArtifactDrift', 'The tasks artifact changed before review');
+                throw new GovernanceError('ArtifactDrift', 'The tasks artifact changed before review. Reload status and review the current tasks artifact.');
             const checkpoint = spec.checkpoints.test_cases;
             const alreadyReviewed = checkpoint.reviewed
                 && checkpoint.reviewed_revision === tasks.revision
                 && checkpoint.reviewed_artifact_sha256 === tasks.artifactSha256;
             if (!alreadyReviewed) {
                 if (tasks.validation.status !== 'passed' || !spec.approvals.design.approved || tasks.approved)
-                    throw new GovernanceError('PhaseNotApproved', 'Tasks are not ready for test-case review');
+                    throw new GovernanceError('PhaseNotApproved', 'Tasks are not ready for test-case review. Submit passing tasks after design approval and before tasks approval.');
                 spec.checkpoints.test_cases = { required: true, reviewed: true, reviewed_at: new Date().toISOString(), reviewed_revision: tasks.revision, reviewed_artifact_sha256: tasks.artifactSha256 };
                 spec.updated_at = new Date().toISOString();
                 await commitSpec(spec);
@@ -236,13 +239,13 @@ let WorkflowEngineService = class WorkflowEngineService {
             await this.assertNoApprovedArtifactDrift(featureRoot, spec);
             const tasksRecord = spec.approvals.tasks;
             if (!tasksRecord.approved)
-                throw new GovernanceError('PhaseNotApproved', 'Tasks are not approved');
+                throw new GovernanceError('PhaseNotApproved', 'Tasks are not approved. Approve the tasks phase before starting implementation.');
             if (sha256(await this.requireArtifact(featureRoot, 'tasks')) !== tasksRecord.artifactSha256)
-                throw new GovernanceError('ArtifactDrift', 'Approved tasks artifact has drifted');
+                throw new GovernanceError('ArtifactDrift', 'Approved tasks artifact has drifted. Inspect the changed artifact, then revise it in the tasks phase Skill.');
             if (spec.workflow_options.review_test_cases === true) {
                 const cp = spec.checkpoints.test_cases;
                 if (!cp.reviewed || cp.reviewed_revision !== tasksRecord.revision || cp.reviewed_artifact_sha256 !== tasksRecord.artifactSha256)
-                    throw new GovernanceError('PhaseNotApproved', 'Tasks review checkpoint is stale');
+                    throw new GovernanceError('PhaseNotApproved', 'Tasks review checkpoint is stale. Record test-case review for the current tasks revision.');
             }
             if (!spec.implementation) {
                 const content = await this.requireArtifact(featureRoot, 'tasks');
@@ -251,12 +254,12 @@ let WorkflowEngineService = class WorkflowEngineService {
                         return this.parseLegacyTasks(content);
                     const current = this.validator.parseTasks(content);
                     if (current.status !== 'passed') {
-                        throw new GovernanceError('PhaseValidationFailed', 'Approved tasks no longer satisfy the executable task contract', { blockers: current.blockers });
+                        throw new GovernanceError('PhaseValidationFailed', 'Approved tasks no longer satisfy the executable task contract. Fix the listed blockers in the tasks phase Skill.', { blockers: current.blockers });
                     }
                     return Object.entries(current.tasks).map(([id, task]) => ({ id, ...task }));
                 })();
                 if (parsed.length === 0)
-                    throw new GovernanceError('LegacyTaskConflict', 'Tasks artifact contains no executable leaf tasks');
+                    throw new GovernanceError('LegacyTaskConflict', 'Tasks artifact contains no executable leaf tasks. Add at least one executable task in the tasks phase Skill.');
                 const taskStates = {};
                 for (const task of parsed) {
                     taskStates[task.id] = {
@@ -282,15 +285,15 @@ let WorkflowEngineService = class WorkflowEngineService {
             await this.assertNoApprovedArtifactDrift(featureRoot, spec);
             const implementation = spec.implementation;
             if (!implementation)
-                throw new GovernanceError('TaskTransitionInvalid', 'Implementation has not started');
+                throw new GovernanceError('TaskTransitionInvalid', 'Implementation has not started. Start implementation before changing task state.');
             if (implementation.revision !== request.expectedRevision)
-                throw new GovernanceError('RevisionConflict', 'Implementation revision is stale');
+                throw new GovernanceError('RevisionConflict', 'Implementation revision is stale. Reload status and submit again with the current revision.');
             const task = implementation.tasks[request.taskNumber];
             if (!task)
-                throw new GovernanceError('TaskTransitionInvalid', `Unknown task ${request.taskNumber}`);
+                throw new GovernanceError('TaskTransitionInvalid', `Unknown task ${request.taskNumber}. Use a task number from the approved tasks artifact.`);
             const incomplete = task.dependencies.filter((dependency) => implementation.tasks[dependency]?.status !== 'completed');
             if (request.action === 'start' && incomplete.length > 0)
-                throw new GovernanceError('TaskDependencyIncomplete', 'Task dependencies are incomplete', { dependencies: incomplete });
+                throw new GovernanceError('TaskDependencyIncomplete', 'Task dependencies are incomplete. Complete the listed dependency tasks first.', { dependencies: incomplete });
             const prior = task.status;
             if (request.action === 'start') {
                 if (prior === 'pending')
@@ -321,7 +324,7 @@ let WorkflowEngineService = class WorkflowEngineService {
                     this.invalidTransition(request.action, prior);
                 const artifacts = this.normalizeArtifacts(request.affectedArtifacts ?? []);
                 if (task.planned_artifacts.length > 0 && artifacts.length === 0)
-                    throw new GovernanceError('TaskTransitionInvalid', 'At least one observed artifact is required');
+                    throw new GovernanceError('TaskTransitionInvalid', 'At least one observed artifact is required. Name the changed artifacts when completing the task.');
                 task.status = 'completed';
                 task.evidence.verification = this.evidence(request.evidence);
                 task.observed_artifacts = artifacts;
@@ -375,6 +378,47 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         return statuses;
     }
+    /**
+     * Read-only view for advisory checks. Never commits state, publishes a handoff, or creates
+     * files for an unknown feature (the lock helper would create the feature directory).
+     */
+    async readAdvisorySnapshot(request) {
+        validateFeatureName(request.featureName);
+        if (!this.fileSystem)
+            throw new GovernanceError('StateInvariantViolation', 'FileSystemPort is required');
+        const specPath = path.join(path.resolve(request.projectRoot), '.spec', 'specs', request.featureName, 'spec.json');
+        if (!(await this.fileSystem.exists(specPath))) {
+            throw new GovernanceError('StateInvariantViolation', `Feature metadata not found: ${request.featureName}`);
+        }
+        return this.withLockedFeature(request.projectRoot, request.featureName, false, async ({ featureRoot, spec }) => {
+            const artifact = (name) => this.readOptional(path.join(featureRoot, `${name}.md`));
+            const record = spec.approvals[request.phase];
+            const content = await artifact(request.phase);
+            const requirementsContent = request.phase === 'requirements' ? null : await artifact('requirements');
+            const designContent = request.phase === 'tasks' ? await artifact('design') : null;
+            const tasksContent = spec.implementation ? (request.phase === 'tasks' ? content : await artifact('tasks')) : null;
+            const criteria = taskAcceptanceCriteria(tasksContent ?? '');
+            return {
+                featureName: request.featureName,
+                description: spec.description,
+                phase: request.phase,
+                revision: record.revision,
+                recordedSha256: record.artifactSha256,
+                observedSha256: content === null ? undefined : sha256(content),
+                validationStatus: record.validation.status,
+                content: content ?? '',
+                requirementsContent: requirementsContent ?? undefined,
+                designContent: designContent ?? undefined,
+                implementation: spec.implementation && {
+                    revision: spec.implementation.revision,
+                    tasks: Object.fromEntries(Object.entries(spec.implementation.tasks).map(([id, task]) => [
+                        id,
+                        { status: task.status, tddRequired: task.tdd_required, acceptanceCriteria: criteria[id] ?? '' },
+                    ])),
+                },
+            };
+        });
+    }
     async loadProject(request) {
         return this.withLockedFeature(request.projectRoot, request.featureName, false, async ({ projectRoot, spec }) => this.hydrateProject(projectRoot, request.featureName, spec));
     }
@@ -390,6 +434,10 @@ let WorkflowEngineService = class WorkflowEngineService {
             throw new GovernanceError('StateInvariantViolation', 'FileSystemPort is required');
         const resolver = new SpecPathResolver(this.fileSystem);
         const resolved = await resolver.resolve(projectRoot, featureName);
+        // The lock helper creates its parent directory; never let it materialize a missing feature.
+        if (!(await this.fileSystem.exists(resolved.featureRoot))) {
+            throw new GovernanceError('StateInvariantViolation', `Feature metadata not found: ${featureName}`);
+        }
         const lockPath = path.join(resolved.featureRoot, '.workflow.lock');
         await resolver.assertContained(resolved.featureRoot, lockPath);
         return withFilesystemLock(lockPath, async (lease) => {
@@ -428,12 +476,12 @@ let WorkflowEngineService = class WorkflowEngineService {
             && (!Number.isInteger(raw.schema_version)
                 || raw.schema_version < 1
                 || raw.schema_version > 4)) {
-            throw new GovernanceError('LegacyStateConflict', `Unsupported workflow schema: ${String(raw.schema_version)}`);
+            throw new GovernanceError('LegacyStateConflict', `Unsupported workflow schema: ${String(raw.schema_version)}. Restore a supported workflow state file.`);
         }
         const accepted = new Set(['init', 'requirements-generated', 'requirements-approved', 'design-generated', 'design-approved', 'tasks-generated', 'tasks-approved', 'implementation-ready', 'implementation', 'completed', 'implementation-completed']);
         const legacyPhase = typeof raw.phase === 'string' ? raw.phase : 'init';
         if (!accepted.has(legacyPhase))
-            throw new GovernanceError('LegacyStateConflict', `Unknown legacy phase: ${legacyPhase}`);
+            throw new GovernanceError('LegacyStateConflict', `Unknown legacy phase: ${legacyPhase}. Correct the phase in the workflow state file.`);
         const legacyApprovals = raw.approvals && typeof raw.approvals === 'object' ? raw.approvals : {};
         const approvals = {};
         for (const phase of PHASES) {
@@ -441,10 +489,10 @@ let WorkflowEngineService = class WorkflowEngineService {
             const generated = value.generated === true;
             const approved = value.approved === true;
             if (approved && !generated)
-                throw new GovernanceError('LegacyStateConflict', `${phase} is approved but not generated`);
+                throw new GovernanceError('LegacyStateConflict', `${phase} is approved but not generated. Correct the approval records in the workflow state file.`);
             const artifact = this.readOptionalSync(path.join(featureRoot, `${phase}.md`));
             if (generated && artifact === null)
-                throw new GovernanceError('LegacyStateConflict', `Generated ${phase} artifact is missing`);
+                throw new GovernanceError('LegacyStateConflict', `Generated ${phase} artifact is missing. Restore the artifact file or correct the workflow state file.`);
             approvals[phase] = {
                 generated,
                 approved,
@@ -482,14 +530,14 @@ let WorkflowEngineService = class WorkflowEngineService {
         const completedRank = legacyPhase === 'completed' || legacyPhase === 'implementation-completed';
         const implementationRank = ['implementation-ready', 'implementation', 'completed', 'implementation-completed'].includes(legacyPhase);
         if (implementationRank && (!approvals.tasks.approved || (choice === true && !reviewed)))
-            throw new GovernanceError('LegacyStateConflict', 'Legacy implementation rank does not satisfy tasks governance');
+            throw new GovernanceError('LegacyStateConflict', 'Legacy implementation rank does not satisfy tasks governance. Approve and review the tasks phase first.');
         const description = typeof raw.description === 'string' ? raw.description : '';
         const language = typeof raw.language === 'string' ? raw.language : 'en';
         if (description.length > 20_000) {
-            throw new GovernanceError('LegacyStateConflict', 'Legacy description exceeds the schema-v5 limit');
+            throw new GovernanceError('LegacyStateConflict', 'Legacy description exceeds the schema-v5 limit. Shorten the description in the workflow state file.');
         }
         if (!['en', 'ja', 'zh-TW'].includes(language)) {
-            throw new GovernanceError('LegacyStateConflict', `Unsupported legacy language: ${language}`);
+            throw new GovernanceError('LegacyStateConflict', `Unsupported legacy language: ${language}. Use a supported language in the workflow state file.`);
         }
         const updatedAt = typeof raw.updated_at === 'string'
             ? raw.updated_at
@@ -511,10 +559,10 @@ let WorkflowEngineService = class WorkflowEngineService {
         if (implementationRank) {
             const tasks = this.parseLegacyTasks(this.readOptionalSync(path.join(featureRoot, 'tasks.md')) ?? '');
             if (tasks.length === 0)
-                throw new GovernanceError('LegacyTaskConflict', 'Legacy tasks contain no leaves');
+                throw new GovernanceError('LegacyTaskConflict', 'Legacy tasks contain no leaves. Add at least one executable task to the tasks artifact.');
             spec.implementation = { revision: 1, tasks_revision: approvals.tasks.revision, legacy_imported: true, tasks: Object.fromEntries(tasks.map((task) => [task.id, { title: task.title, tdd_required: task.tddRequired, dependencies: [], status: task.completed ? 'completed' : 'pending', evidence: {}, planned_artifacts: [], observed_artifacts: [] }])) };
             if (completedRank && !this.allComplete(spec.implementation))
-                throw new GovernanceError('LegacyStateConflict', 'Completed legacy phase has unchecked tasks');
+                throw new GovernanceError('LegacyStateConflict', 'Completed legacy phase has unchecked tasks. Complete the unchecked tasks or correct the legacy phase.');
         }
         return spec;
     }
@@ -592,7 +640,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             const content = await this.readOptional(path.join(featureRoot, `${phase}.md`));
             const observedArtifactSha256 = content === null ? undefined : sha256(content);
             if (observedArtifactSha256 !== record.artifactSha256) {
-                throw new GovernanceError('ArtifactDrift', `Approved ${phase}.md differs from revision ${record.revision}`, { phase, observedArtifactSha256 });
+                throw new GovernanceError('ArtifactDrift', `Approved ${phase}.md differs from revision ${record.revision}. Inspect the changed artifact, then revise it in its phase Skill.`, { phase, observedArtifactSha256 });
             }
         }
     }
@@ -607,7 +655,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             nextArtifact,
         ];
         if (endpoints.some((value) => Buffer.byteLength(value, 'utf8') > JOURNAL_LIMIT)) {
-            throw new GovernanceError('RecoveryConflict', 'Submission endpoint exceeds the journal size limit');
+            throw new GovernanceError('RecoveryConflict', 'Submission endpoint exceeds the journal size limit. Shorten the artifact and submit again.');
         }
         const journal = {
             schema_version: 1,
@@ -631,7 +679,7 @@ let WorkflowEngineService = class WorkflowEngineService {
                 await this.replaceCas(journalPath, journalBytes, null, assertHeld);
             }
             catch (rollbackError) {
-                throw new GovernanceError('RecoveryConflict', 'Submission failed and CAS rollback could not safely restore prior bytes', { cause: errorSummary(error), rollback: errorSummary(rollbackError) });
+                throw new GovernanceError('RecoveryConflict', 'Submission failed and CAS rollback could not safely restore prior bytes. Inspect the spec files before retrying.', { cause: errorSummary(error), rollback: errorSummary(rollbackError) });
             }
             throw error;
         }
@@ -643,7 +691,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         if (await this.fileSystem.exists(journalPath)) {
             const journalStats = await stat(journalPath);
             if (!journalStats.isFile() || journalStats.size > JOURNAL_FILE_LIMIT) {
-                throw new GovernanceError('RecoveryConflict', 'Submission journal exceeds its raw size limit');
+                throw new GovernanceError('RecoveryConflict', 'Submission journal exceeds its raw size limit. Inspect the journal and spec files, then restore a known state.');
             }
         }
         const raw = await this.readOptional(journalPath);
@@ -654,10 +702,10 @@ let WorkflowEngineService = class WorkflowEngineService {
             journal = JSON.parse(raw);
         }
         catch {
-            throw new GovernanceError('RecoveryConflict', 'Submission journal is malformed');
+            throw new GovernanceError('RecoveryConflict', 'Submission journal is malformed. Inspect the journal and spec files, then restore a known state.');
         }
         if (journal.schema_version !== 1) {
-            throw new GovernanceError('RecoveryConflict', 'Submission journal schema is unsupported');
+            throw new GovernanceError('RecoveryConflict', 'Submission journal schema is unsupported. Inspect the journal and spec files, then restore a known state.');
         }
         const priorSpec = decode(journal.spec?.prior);
         const nextSpec = decode(journal.spec?.next);
@@ -670,10 +718,10 @@ let WorkflowEngineService = class WorkflowEngineService {
         const currentArtifact = await this.readOptional(artifactPath);
         const convergeNext = currentSpec === nextSpec;
         if (currentSpec !== priorSpec && !convergeNext) {
-            throw new GovernanceError('RecoveryConflict', 'Current spec bytes match neither journal endpoint');
+            throw new GovernanceError('RecoveryConflict', 'Current spec bytes match neither journal endpoint. Inspect the spec file and restore a known state.');
         }
         if (currentArtifact !== priorArtifact && currentArtifact !== nextArtifact) {
-            throw new GovernanceError('RecoveryConflict', 'Current artifact bytes match neither journal endpoint');
+            throw new GovernanceError('RecoveryConflict', 'Current artifact bytes match neither journal endpoint. Inspect the artifact and restore a known state.');
         }
         await this.assertJournalValidation(featureRoot, journalPhase, nextSpec, nextArtifact);
         await this.replaceCas(artifactPath, currentArtifact, convergeNext ? nextArtifact : priorArtifact, assertHeld);
@@ -688,13 +736,13 @@ let WorkflowEngineService = class WorkflowEngineService {
                 await assertHeld();
                 return;
             }
-            throw new GovernanceError('RecoveryConflict', `Concurrent byte change at ${path.basename(filePath)}`);
+            throw new GovernanceError('RecoveryConflict', `Concurrent byte change at ${path.basename(filePath)}. Retry after the other writer finishes.`);
         }
         if (desired === null) {
             if (current !== null)
                 await unlink(filePath);
             if (await this.readOptional(filePath) !== null) {
-                throw new GovernanceError('RecoveryConflict', `Delete verification failed for ${path.basename(filePath)}`);
+                throw new GovernanceError('RecoveryConflict', `Delete verification failed for ${path.basename(filePath)}. Inspect the file and retry.`);
             }
         }
         else {
@@ -716,7 +764,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             if (heading) {
                 const id = heading[1];
                 if (headings.has(id)) {
-                    throw new GovernanceError('LegacyTaskConflict', `Duplicate legacy task ${id}`);
+                    throw new GovernanceError('LegacyTaskConflict', `Duplicate legacy task ${id}. Rename one task so each identifier is unique.`);
                 }
                 const body = [];
                 for (let cursor = index + 1; cursor < lines.length && !headingPattern.test(lines[cursor]); cursor += 1) {
@@ -745,12 +793,12 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         const ids = new Set([...headings.keys(), ...checklist.keys()]);
         if (ids.size > 5_000) {
-            throw new GovernanceError('LegacyTaskConflict', 'Legacy tasks contain too many task identifiers');
+            throw new GovernanceError('LegacyTaskConflict', 'Legacy tasks contain too many task identifiers. Split the work into a smaller tasks artifact.');
         }
         for (const id of ids) {
             const title = headings.get(id)?.title ?? checklist.get(id)?.title ?? id;
             if (id.length > 50 || title.trim().length === 0 || title.length > 500) {
-                throw new GovernanceError('LegacyTaskConflict', `Legacy task ${id.slice(0, 50)} exceeds schema-v5 field limits`);
+                throw new GovernanceError('LegacyTaskConflict', `Legacy task ${id.slice(0, 50)} exceeds schema-v5 field limits. Shorten its fields in the tasks artifact.`);
             }
         }
         const parents = new Set();
@@ -763,7 +811,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         }
         const leaves = [...ids].filter((id) => !parents.has(id));
         if (leaves.length > 1_000) {
-            throw new GovernanceError('LegacyTaskConflict', 'Legacy tasks contain more than 1000 executable leaves');
+            throw new GovernanceError('LegacyTaskConflict', 'Legacy tasks contain more than 1000 executable leaves. Merge tasks to stay within 1000 leaves.');
         }
         return leaves.map((id) => {
             const heading = headings.get(id);
@@ -813,7 +861,7 @@ let WorkflowEngineService = class WorkflowEngineService {
     assertPriorApproved(phase, approvals) {
         for (const prior of PHASES.slice(0, PHASES.indexOf(phase)))
             if (!approvals[prior].approved)
-                throw new GovernanceError('PhaseNotApproved', `${prior} is not approved`);
+                throw new GovernanceError('PhaseNotApproved', `${prior} is not approved. Approve the ${prior} phase first.`);
     }
     assertLegacyOrdering(approvals) {
         for (const [index, phase] of PHASES.entries()) {
@@ -821,7 +869,7 @@ let WorkflowEngineService = class WorkflowEngineService {
                 continue;
             for (const prior of PHASES.slice(0, index)) {
                 if (!approvals[prior].approved) {
-                    throw new GovernanceError('LegacyStateConflict', `${phase} exists before ${prior} approval`);
+                    throw new GovernanceError('LegacyStateConflict', `${phase} exists before ${prior} approval. Approve ${prior} first, or move the ${phase} artifact out of the feature folder.`);
                 }
             }
         }
@@ -842,15 +890,15 @@ let WorkflowEngineService = class WorkflowEngineService {
                                 ? 'requirements-generated'
                                 : 'init';
         if (!implementationRank && legacyPhase !== expected) {
-            throw new GovernanceError('LegacyStateConflict', `Legacy phase ${legacyPhase} disagrees with approval records (${expected})`);
+            throw new GovernanceError('LegacyStateConflict', `Legacy phase ${legacyPhase} disagrees with approval records (${expected}). Correct the phase in the workflow state file.`);
         }
         if (typeof raw.ready_for_implementation === 'boolean' && raw.ready_for_implementation !== implementationRank) {
-            throw new GovernanceError('LegacyStateConflict', 'ready_for_implementation disagrees with legacy phase rank');
+            throw new GovernanceError('LegacyStateConflict', 'ready_for_implementation disagrees with legacy phase rank. Correct the flag in the workflow state file.');
         }
         if (typeof raw.implementation_completed === 'boolean') {
             const completedRank = legacyPhase === 'completed' || legacyPhase === 'implementation-completed';
             if (raw.implementation_completed !== completedRank) {
-                throw new GovernanceError('LegacyStateConflict', 'implementation_completed disagrees with legacy phase rank');
+                throw new GovernanceError('LegacyStateConflict', 'implementation_completed disagrees with legacy phase rank. Correct the flag in the workflow state file.');
             }
         }
     }
@@ -861,7 +909,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         return WorkflowPhase.REQUIREMENTS; return WorkflowPhase.INIT; }
     implementationCounts(value) { const tasks = Object.values(value.tasks); return { completed: tasks.filter((t) => t.status === 'completed').length, total: tasks.length, active: tasks.filter((t) => ['in-progress', 'red-observed', 'green-observed'].includes(t.status)).length, blocked: tasks.filter((t) => t.status === 'blocked').length }; }
     allComplete(value) { const tasks = Object.values(value.tasks); return tasks.length > 0 && tasks.every((task) => task.status === 'completed'); }
-    invalidTransition(action, status) { throw new GovernanceError('TaskTransitionInvalid', `Cannot ${action} from ${status}`); }
+    invalidTransition(action, status) { throw new GovernanceError('TaskTransitionInvalid', `Cannot ${action} from ${status}. Select a task action valid for its current status.`); }
     evidence(value) {
         if (typeof value.command !== 'string'
             || value.command.trim().length === 0
@@ -1382,7 +1430,7 @@ let WorkflowEngineService = class WorkflowEngineService {
         const priorRaw = this.parseSpecBytes(priorBytes);
         const nextRaw = this.parseSpecBytes(nextBytes);
         if (priorRaw.schema_version !== 5 || nextRaw.schema_version !== 5) {
-            throw new GovernanceError('RecoveryConflict', 'Submission journal endpoints must use schema-v5');
+            throw new GovernanceError('RecoveryConflict', 'Submission journal endpoints must use schema-v5. Inspect the journal and spec files, then restore a known state.');
         }
         let prior;
         let next;
@@ -1391,14 +1439,14 @@ let WorkflowEngineService = class WorkflowEngineService {
             next = this.normalizeV5(nextRaw);
         }
         catch (error) {
-            throw new GovernanceError('RecoveryConflict', 'Submission journal contains invalid workflow state', { cause: errorSummary(error) });
+            throw new GovernanceError('RecoveryConflict', 'Submission journal contains invalid workflow state. Inspect the journal and spec files, then restore a known state.', { cause: errorSummary(error) });
         }
         const changed = PHASES.filter((phase) => next.approvals[phase].revision === prior.approvals[phase].revision + 1);
         if (changed.length !== 1
             || prior.feature_name !== next.feature_name
             || PHASES.some((phase) => phase !== changed[0]
                 && next.approvals[phase].revision !== prior.approvals[phase].revision)) {
-            throw new GovernanceError('RecoveryConflict', 'Submission journal does not describe one phase revision');
+            throw new GovernanceError('RecoveryConflict', 'Submission journal does not describe one phase revision. Inspect the journal and spec files, then restore a known state.');
         }
         const changedPhase = changed[0];
         const priorRecord = prior.approvals[changedPhase];
@@ -1433,7 +1481,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             || !priorArtifactValid
             || !submissionRecordValid
             || !workflowMetadataValid) {
-            throw new GovernanceError('RecoveryConflict', 'Submission journal does not describe a valid phase submission');
+            throw new GovernanceError('RecoveryConflict', 'Submission journal does not describe a valid phase submission. Inspect the journal and spec files, then restore a known state.');
         }
         return changedPhase;
     }
@@ -1449,7 +1497,7 @@ let WorkflowEngineService = class WorkflowEngineService {
             }
         }
         catch (error) {
-            throw new GovernanceError('RecoveryConflict', 'Submission journal validation cannot be reproduced', { cause: errorSummary(error) });
+            throw new GovernanceError('RecoveryConflict', 'Submission journal validation cannot be reproduced. Inspect the artifact, then submit the phase again.', { cause: errorSummary(error) });
         }
     }
     journalAncillaryState(spec) {
@@ -1511,8 +1559,8 @@ export { WorkflowEngineService };
 function sha256(content) { return createHash('sha256').update(content).digest('hex'); }
 function encode(content) { return { base64: Buffer.from(content).toString('base64'), sha256: sha256(content) }; }
 function decode(value) { if (!value || typeof value.base64 !== 'string' || typeof value.sha256 !== 'string')
-    throw new GovernanceError('RecoveryConflict', 'Journal byte record is malformed'); const bytes = Buffer.from(value.base64, 'base64'); if (bytes.length > JOURNAL_LIMIT)
-    throw new GovernanceError('RecoveryConflict', 'Journal byte record exceeds size limit'); const content = bytes.toString('utf8'); if (sha256(content) !== value.sha256 || Buffer.from(content).toString('base64') !== value.base64)
-    throw new GovernanceError('RecoveryConflict', 'Journal byte hash or encoding is invalid'); return content; }
+    throw new GovernanceError('RecoveryConflict', 'Journal byte record is malformed. Inspect the journal and spec files, then restore a known state.'); const bytes = Buffer.from(value.base64, 'base64'); if (bytes.length > JOURNAL_LIMIT)
+    throw new GovernanceError('RecoveryConflict', 'Journal byte record exceeds size limit. Inspect the journal and spec files, then restore a known state.'); const content = bytes.toString('utf8'); if (sha256(content) !== value.sha256 || Buffer.from(content).toString('base64') !== value.base64)
+    throw new GovernanceError('RecoveryConflict', 'Journal byte hash or encoding is invalid. Inspect the journal and spec files, then restore a known state.'); return content; }
 function errorSummary(error) { return String(error).slice(0, 2_000); }
 //# sourceMappingURL=WorkflowEngineService.js.map