vibe-coding-master 0.7.50 → 0.8.0

package/dist/backend/services/workflow-control-service.js

@@ -4,11 +4,14 @@ import { resolveRepoPath } from "../adapters/filesystem.js";
 import { VcmError } from "../errors.js";
 import { WORKFLOW_EVIDENCE_ARTIFACTS, WORKFLOW_EVIDENCE_GATES, WORKFLOW_FLOWS } from "../../shared/types/workflow.js";
 import { checkMarkdownArtifact, readArtifactSectionContent } from "../../shared/validation/artifact-check.js";
+import { ARCHITECT_DEBUG_NORMAL_PLAN_DISPOSITION } from "../../shared/validation/artifact-contract.js";
 import { renderWorkflowProgressTemplate } from "../templates/handoff.js";
-const HISTORY_HEADER = "| Sequence | Flow | Target Role | Evidence | Override Authorization | Confirmed At |";
-const HISTORY_SEPARATOR = "| --- | --- | --- | --- | --- | --- |";
+const HISTORY_HEADER = "| Sequence | Flow | Target Role | Evidence | Override Authorization | Follow-Up Approval | Confirmed At |";
+const HISTORY_SEPARATOR = "| --- | --- | --- | --- | --- | --- | --- |";
+const LEGACY_HISTORY_HEADER = "| Sequence | Flow | Target Role | Evidence | Override Authorization | Confirmed At |";
+const LEGACY_HISTORY_SEPARATOR = "| --- | --- | --- | --- | --- | --- |";
 const TARGET_ROLES = new Set(["architect", "coder", "tester"]);
-const FINAL_GATE_STATUSES = new Set(["disabled", "not_required", "skipped", "overridden"]);
+const FRESH_EXCEPTION_GATE_STATUSES = new Set(["not_required", "skipped", "overridden"]);
 const MISSING_EVIDENCE_HASH = "<missing>";
 const DOCS_ONLY_ROLE_TRANSITIONS = [
     "docs-only/architect",
@@ -25,18 +28,50 @@ export function createWorkflowControlService(deps) {
     const locks = new Map();
     async function getState(input) {
         try {
-            const progressWarning = await ensureProgressFile(deps.fs, input);
-            if (!(await deps.fs.pathExists(statePath(input)))) {
-                const state = emptyState(input.taskSlug, now());
-                return progressWarning ? { ...state, warnings: [progressWarning] } : state;
+            await recoverCommitJournal(input);
+            const hasProgress = await deps.fs.pathExists(progressPath(input));
+            const hasState = await deps.fs.pathExists(statePath(input));
+            if (!hasProgress && !hasState) {
+                await writeAtomic(deps.fs, progressPath(input), renderWorkflowProgressTemplate(input.taskSlug));
+                return emptyState(input.taskSlug, now());
+            }
+            if (!hasProgress) {
+                const state = hasState
+                    ? normalizeState(await deps.fs.readJson(statePath(input)), input.taskSlug, now())
+                    : emptyState(input.taskSlug, now());
+                return {
+                    ...state,
+                    warnings: [...state.warnings, "Workflow Progress is missing while workflow runtime state still exists. Restore workflow-progress.md before continuing."]
+                };
+            }
+            const progress = parseWorkflowProgress(await deps.fs.readText(progressPath(input)), input.taskSlug);
+            if (!hasState) {
+                if (progress.revision === 0 && progress.status === "not-started" && progress.history.length === 0 && !progress.proposal) {
+                    return emptyState(input.taskSlug, now());
+                }
+                if (!progress.proposal && progress.history.length > 0) {
+                    const recovered = await reconstructStateFromProgress(input, progress);
+                    await saveState(input, recovered);
+                    return recovered;
+                }
+                return {
+                    ...emptyState(input.taskSlug, now()),
+                    warnings: ["Workflow runtime state is missing for an active Workflow Progress record. Restore workflow-control.json before continuing."]
+                };
             }
             const state = normalizeState(await deps.fs.readJson(statePath(input)), input.taskSlug, now());
-            return progressWarning ? { ...state, warnings: [...state.warnings, progressWarning] } : state;
+            return {
+                ...state,
+                warnings: [...state.warnings, ...stateProgressConsistencyWarnings(state, progress)]
+            };
         }
         catch (error) {
+            const message = errorMessage(error);
             return {
                 ...emptyState(input.taskSlug, now()),
-                warnings: [`Workflow control state could not be read: ${errorMessage(error)}`]
+                warnings: [message.startsWith("Workflow Progress validation failed:")
+                        ? `Workflow Progress is invalid and was preserved unchanged: ${message}`
+                        : `Workflow control state could not be read: ${message}`]
             };
         }
     }
@@ -66,9 +101,23 @@ export function createWorkflowControlService(deps) {
             const baseHistoryHash = historyHash(current.history);
             const effectiveFlow = resolveEffectiveFlow(current.flow, candidate.proposal.requestedFlow);
             const verdict = await evaluateTransition(deps.fs, input, state, current, effectiveFlow, candidate.proposal.targetRole);
+            const followUpApprovalText = candidate.proposal.followUpApprovalText?.trim();
+            const followUpAllowed = Boolean(followUpApprovalText) && await canRouteUserApprovedFollowUp(deps.fs, input, state, current, effectiveFlow, candidate.proposal.targetRole, verdict.allowedTransitions);
             let overrideAuthorizationId;
             let userAuthorization;
-            if (!verdict.allowed) {
+            let followUpApprovalId;
+            let userApprovedFollowUp;
+            if (followUpApprovalText) {
+                if (verdict.allowed) {
+                    throw workflowError("WORKFLOW_FOLLOW_UP_APPROVAL_NOT_REQUIRED", "This workflow transition is already legal and must not consume a post-validation follow-up approval.", "Set User-Approved Follow-Up Approval Text to none.");
+                }
+                if (!followUpAllowed) {
+                    throw workflowError("WORKFLOW_FOLLOW_UP_APPROVAL_INVALID", "User-approved follow-up work is legal only for a Tester dispatch after a fresh passing Test Report and successful validation-adequacy and code-diff Gates.", "Use the normal allowed transition, or ask the user only when optional Tester-owned work is proposed after validation is fully green.");
+                }
+                userApprovedFollowUp = createUserApprovedFollowUp(id(), current, candidate, effectiveFlow, baseHistoryHash, followUpApprovalText, now());
+                followUpApprovalId = userApprovedFollowUp.id;
+            }
+            else if (!verdict.allowed) {
                 const authorizationText = candidate.proposal.authorizationText?.trim();
                 const violatedRule = candidate.proposal.violatedRule?.trim();
                 if (!authorizationText && !violatedRule) {
@@ -79,9 +128,6 @@ export function createWorkflowControlService(deps) {
                 if (!authorizationText || violatedRule !== verdict.reason) {
                     throw workflowError("WORKFLOW_USER_AUTHORIZATION_INVALID", `User authorization must include the exact authorization text and exact violated rule: ${verdict.reason}`, "Ask the user directly, then copy the user's authorization verbatim into Authorization Text and the rejection reason verbatim into Violated Rule.");
                 }
-                if (state.userAuthorizations.some((entry) => entry.authorizationText === authorizationText)) {
-                    throw workflowError("WORKFLOW_USER_AUTHORIZATION_REUSED", "This user authorization has already been recorded for another workflow transition.", "Ask the user for a new explicit authorization for this exact transition.");
-                }
                 userAuthorization = createUserAuthorization(id(), current, candidate, effectiveFlow, baseHistoryHash, verdict.reason, authorizationText, now());
                 overrideAuthorizationId = userAuthorization.id;
             }
@@ -98,6 +144,7 @@ export function createWorkflowControlService(deps) {
                 evidence: candidate.proposal.evidence,
                 expectedRoutePath: expectedRoutePath(input.handoffDir, candidate.proposal.targetRole),
                 overrideAuthorizationId,
+                followUpApprovalId,
                 status: "pending",
                 createdAt: timestamp,
                 updatedAt: timestamp
@@ -107,13 +154,15 @@ export function createWorkflowControlService(deps) {
                 proposal: candidate.proposal
             };
             const normalized = renderWorkflowProgress(accepted);
-            await writeAtomic(deps.fs, progressPath(input), normalized);
-            await saveState(input, {
+            await commitStateAndProgress(input, normalized, {
                 ...state,
                 pendingDispatch,
                 userAuthorizations: userAuthorization
                     ? [...state.userAuthorizations, userAuthorization]
                     : state.userAuthorizations,
+                userApprovedFollowUps: userApprovedFollowUp
+                    ? [...state.userApprovedFollowUps, userApprovedFollowUp]
+                    : state.userApprovedFollowUps,
                 updatedAt: timestamp
             });
             return { path: relativeProgressPath(input), content: normalized };
@@ -172,6 +221,25 @@ export function createWorkflowControlService(deps) {
             });
         });
     }
+    async function cancelPendingDispatch(input) {
+        await withLock(statePath(input), async () => {
+            const state = await getState(input);
+            const pending = state.pendingDispatch;
+            if (!pending)
+                return;
+            const progress = await readProgress(deps.fs, input);
+            await commitStateAndProgress(input, renderWorkflowProgress({
+                ...progress,
+                proposal: undefined
+            }), {
+                ...state,
+                pendingDispatch: null,
+                userAuthorizations: state.userAuthorizations.filter((entry) => entry.id !== pending.overrideAuthorizationId),
+                userApprovedFollowUps: state.userApprovedFollowUps.filter((entry) => entry.id !== pending.followUpApprovalId),
+                updatedAt: now()
+            });
+        });
+    }
     async function confirmDispatch(input, messageId) {
         await withLock(statePath(input), async () => {
             const state = await getState(input);
@@ -192,10 +260,11 @@ export function createWorkflowControlService(deps) {
                 targetRole: pending.targetRole,
                 evidence: pending.evidence,
                 overrideAuthorizationId: pending.overrideAuthorizationId,
+                followUpApprovalId: pending.followUpApprovalId,
                 confirmedAt: timestamp
             };
             const activeDispatch = await captureEvidenceBaseline(deps.fs, input, entry.sequence, entry.flow, entry.targetRole, timestamp);
-            const flowRun = await advanceFlowRun(deps.fs, input, state, current, pending.effectiveFlow, Boolean(pending.overrideAuthorizationId), entry.sequence);
+            const flowRun = await advanceFlowRun(deps.fs, input, state, current, pending.effectiveFlow, entry.sequence);
             const completed = {
                 ...current,
                 flow: pending.effectiveFlow,
@@ -206,36 +275,69 @@ export function createWorkflowControlService(deps) {
             const userAuthorizations = state.userAuthorizations.map((entry) => entry.id === pending.overrideAuthorizationId
                 ? { ...entry, status: "consumed", consumedAt: timestamp }
                 : entry);
-            await writeAtomic(deps.fs, progressPath(input), renderWorkflowProgress(completed));
-            await saveState(input, {
+            const userApprovedFollowUps = state.userApprovedFollowUps.map((entry) => entry.id === pending.followUpApprovalId
+                ? { ...entry, status: "consumed", consumedAt: timestamp }
+                : entry);
+            await commitStateAndProgress(input, renderWorkflowProgress(completed), {
                 ...state,
                 pendingDispatch: null,
                 activeDispatch,
                 flowRun,
                 userAuthorizations,
+                userApprovedFollowUps,
                 updatedAt: timestamp
             });
         });
     }
+    async function recoverTask(input) {
+        return withLock(statePath(input), async () => {
+            await recoverCommitJournal(input);
+            const state = await getState(input);
+            if (state.warnings.length > 0 || state.pendingDispatch?.status !== "dispatching")
+                return false;
+            await saveState(input, {
+                ...state,
+                pendingDispatch: {
+                    ...state.pendingDispatch,
+                    status: "pending",
+                    routeContentHash: undefined,
+                    messageId: undefined,
+                    updatedAt: now()
+                },
+                updatedAt: now()
+            });
+            return true;
+        });
+    }
     return {
         getState,
-        getProgress: (input) => readProgress(deps.fs, input),
+        getProgress: async (input) => {
+            await getState(input);
+            return readProgress(deps.fs, input);
+        },
         requestUserInput,
         resolveUserInput,
         submitProgress,
         assertRouteAuthorized,
         claimDispatch,
         releaseDispatch,
-        confirmDispatch
+        cancelPendingDispatch,
+        confirmDispatch,
+        recoverTask
     };
     async function requestUserInput(input, question) {
         return withLock(statePath(input), async () => {
             const state = await getState(input);
+            failOnStateWarnings(state);
+            if (state.pendingDispatch?.status === "dispatching") {
+                throw workflowError("WORKFLOW_DISPATCH_PENDING", "A role dispatch is already being submitted and cannot be canceled by a user question.", "Wait for the target UserPromptSubmit confirmation or recover the dispatch before asking the user.");
+            }
             const normalizedQuestion = question.trim();
             if (!normalizedQuestion) {
                 throw workflowError("WORKFLOW_USER_QUESTION_REQUIRED", "A non-empty user question is required.");
             }
             const timestamp = now();
+            const pending = state.pendingDispatch;
             const next = {
                 ...state,
                 awaitingUser: {
@@ -243,15 +345,27 @@ export function createWorkflowControlService(deps) {
                     requestedAt: timestamp
                 },
                 pendingDispatch: null,
+                userAuthorizations: state.userAuthorizations.filter((entry) => entry.id !== pending?.overrideAuthorizationId),
+                userApprovedFollowUps: state.userApprovedFollowUps.filter((entry) => entry.id !== pending?.followUpApprovalId),
                 updatedAt: timestamp
             };
-            await saveState(input, next);
+            if (pending) {
+                const progress = await readProgress(deps.fs, input);
+                await commitStateAndProgress(input, renderWorkflowProgress({
+                    ...progress,
+                    proposal: undefined
+                }), next);
+            }
+            else {
+                await saveState(input, next);
+            }
             return next;
         });
     }
     async function resolveUserInput(input) {
         return withLock(statePath(input), async () => {
             const state = await getState(input);
+            failOnStateWarnings(state);
             if (!state.awaitingUser)
                 return state;
             const next = {
@@ -266,6 +380,58 @@ export function createWorkflowControlService(deps) {
     async function saveState(input, state) {
         await deps.fs.writeJsonAtomic(statePath(input), state);
     }
+    async function commitStateAndProgress(input, progressContent, state) {
+        const journal = {
+            version: 1,
+            taskSlug: input.taskSlug,
+            status: "pending",
+            progressContent,
+            state,
+            createdAt: now()
+        };
+        await deps.fs.writeJsonAtomic(transactionPath(input), journal);
+        await writeAtomic(deps.fs, progressPath(input), progressContent);
+        await saveState(input, state);
+        await deps.fs.writeJsonAtomic(transactionPath(input), { ...journal, status: "committed" });
+        await removeTransactionJournal(transactionPath(input));
+    }
+    async function recoverCommitJournal(input) {
+        const target = transactionPath(input);
+        if (!(await deps.fs.pathExists(target)))
+            return;
+        const journal = await deps.fs.readJson(target);
+        if (journal.version !== 1 || journal.taskSlug !== input.taskSlug) {
+            throw new Error("Workflow commit journal does not match the active task.");
+        }
+        if (journal.status === "pending") {
+            parseWorkflowProgress(journal.progressContent, input.taskSlug);
+            const state = normalizeState(journal.state, input.taskSlug, now());
+            failOnStateWarnings(state);
+            await writeAtomic(deps.fs, progressPath(input), journal.progressContent);
+            await saveState(input, state);
+            await deps.fs.writeJsonAtomic(target, { ...journal, status: "committed" });
+        }
+        await removeTransactionJournal(target);
+    }
+    async function removeTransactionJournal(target) {
+        try {
+            await deps.fs.removePath?.(target, { force: true });
+        }
+        catch {
+            // A committed journal is safe to replay or remove on the next state read.
+        }
+    }
+    async function reconstructStateFromProgress(input, progress) {
+        const timestamp = now();
+        const last = progress.history.at(-1);
+        const activeDispatch = await captureEvidenceBaseline(deps.fs, input, last.sequence, last.flow, last.targetRole, last.confirmedAt ?? timestamp);
+        return {
+            ...emptyState(input.taskSlug, timestamp),
+            activeDispatch,
+            flowRun: resolveFlowRun(null, progress),
+            updatedAt: timestamp
+        };
+    }
     async function withLock(key, operation) {
         const previous = locks.get(key) ?? Promise.resolve();
         const next = previous.catch(() => undefined).then(operation);
@@ -337,6 +503,24 @@ export function parseWorkflowProgress(content, expectedTaskSlug) {
     else if (authorizationText !== "none" || violatedRule !== "none") {
         errors.push("User Authorization fields must be none when no role dispatch is proposed.");
     }
+    const followUpSection = readArtifactSectionContent(content, "User-Approved Follow-Up");
+    const followUpApprovalText = followUpSection === undefined
+        ? "none"
+        : rawField(followUpSection, "Approval Text");
+    if (!followUpApprovalText) {
+        errors.push("User-Approved Follow-Up requires an Approval Text field.");
+    }
+    else if (proposal) {
+        if (followUpApprovalText !== "none") {
+            if (proposal.authorizationText || proposal.violatedRule) {
+                errors.push("User-Approved Follow-Up and User Authorization cannot be used in the same proposal.");
+            }
+            proposal.followUpApprovalText = followUpApprovalText;
+        }
+    }
+    else if (followUpApprovalText !== "none") {
+        errors.push("User-Approved Follow-Up Approval Text must be none when no role dispatch is proposed.");
+    }
     if (errors.length > 0)
         throw progressValidationError(errors);
     return {
@@ -354,7 +538,7 @@ export function renderWorkflowProgress(progress) {
         : [
             HISTORY_HEADER,
             HISTORY_SEPARATOR,
-            ...progress.history.map((entry) => `| ${entry.sequence} | ${entry.flow} | ${entry.targetRole} | ${escapeCell(entry.evidence)} | ${entry.overrideAuthorizationId ?? "none"} | ${entry.confirmedAt ?? "none"} |`)
+            ...progress.history.map((entry) => `| ${entry.sequence} | ${entry.flow} | ${entry.targetRole} | ${escapeCell(entry.evidence)} | ${entry.overrideAuthorizationId ?? "none"} | ${entry.followUpApprovalId ?? "none"} | ${entry.confirmedAt ?? "none"} |`)
         ].join("\n");
     const proposal = progress.proposal;
     return `# Workflow Progress: ${progress.taskSlug}
@@ -377,6 +561,10 @@ Evidence: ${proposal?.evidence ?? "none"}
 
 Authorization Text: ${proposal?.authorizationText ?? "none"}
 Violated Rule: ${proposal?.violatedRule ?? "none"}
+
+## User-Approved Follow-Up
+
+Approval Text: ${proposal?.followUpApprovalText ?? "none"}
 `;
 }
 async function evaluateTransition(fs, input, state, current, effectiveFlow, targetRole) {
@@ -392,6 +580,32 @@ async function evaluateTransition(fs, input, state, current, effectiveFlow, targ
         blockedHint: await describeBlockedCheckpoint(fs, input, state, current)
     };
 }
+async function canRouteUserApprovedFollowUp(fs, input, state, current, effectiveFlow, targetRole, allowedTransitions) {
+    if (targetRole !== "tester"
+        || current.status !== "active"
+        || current.flow !== effectiveFlow
+        || (effectiveFlow !== "code-change"
+            && effectiveFlow !== "architect-debug"
+            && effectiveFlow !== "architecture-diagnosis"))
+        return false;
+    const active = state.activeDispatch;
+    if (!active || active.flow !== effectiveFlow || active.targetRole !== "tester")
+        return false;
+    const test = await artifactState(fs, input, "test-report.md", "test-report");
+    if (test.value !== "pass" || !evidenceIsFresh(state, effectiveFlow, "tester", "test-report.md", test.hash)) {
+        return false;
+    }
+    const validation = await gateState(fs, input, "validation-adequacy");
+    const codeDiff = await gateState(fs, input, "code-diff");
+    if (!gatePassedForDispatch(state, effectiveFlow, "tester", "validation-adequacy", validation)
+        || !gatePassedForDispatch(state, effectiveFlow, "tester", "code-diff", codeDiff))
+        return false;
+    const flowRun = resolveFlowRun(state.flowRun, current);
+    const expectedExit = flowRun.activeBranch === effectiveFlow
+        ? `${flowRun.rootFlow}/architect`
+        : `${effectiveFlow}/architect`;
+    return allowedTransitions.length === 1 && allowedTransitions[0] === expectedExit;
+}
 async function getAllowedTransitions(fs, input, state, current) {
     if (current.status === "completed")
         return initialTransitions();
@@ -427,9 +641,12 @@ async function getAllowedTransitions(fs, input, state, current) {
             return [];
         return [];
     }
+    const coderDocsCorrection = await allowedActiveCoderDocsCorrection(fs, input, state, flow);
+    if (coderDocsCorrection)
+        return coderDocsCorrection;
     const segment = activeFlowSegment(current.history, flow, flowRun.startedAtSequence);
     if (flow === "code-change") {
-        return allowedCodeChange(fs, input, state, segment, flowRun.resumedFromBranch !== undefined);
+        return allowedCodeChange(fs, input, state, segment, flowRun.resumedFromBranch);
     }
     if (flow === "architect-debug") {
         return allowedArchitectFix(fs, input, state, segment, "architect-debug", flowRun.resumedFromBranch !== undefined, flowRun.activeBranch ? flowRun.rootFlow : undefined);
@@ -448,8 +665,15 @@ function initialTransitions() {
 async function allowedCodeChange(fs, input, state, segment, resumedFromBranch) {
     const coderIndex = findLastIndex(segment, (entry) => entry.targetRole === "coder");
     const testerIndex = findLastIndex(segment, (entry) => entry.targetRole === "tester");
-    if (resumedFromBranch && coderIndex < 0 && testerIndex < 0) {
-        return allowedPostImplementationArchitect(fs, input, state, "code-change", segment);
+    if (resumedFromBranch && coderIndex < 0) {
+        if (testerIndex < 0) {
+            return allowedPostImplementationArchitect(fs, input, state, "code-change", segment);
+        }
+        return allowedAfterTester(fs, input, state, "code-change", resumedFromBranch, {
+            testerFailureFlow: "architect-debug",
+            implementationFailureFlow: "architect-debug",
+            successTarget: "code-change/architect"
+        });
     }
     if (coderIndex < 0) {
         const plan = await artifactState(fs, input, "architecture-plan.md", "architecture-plan");
@@ -477,7 +701,7 @@ async function allowedCodeChange(fs, input, state, segment, resumedFromBranch) {
     if (architectsAfterTester.length > 0) {
         return allowedPostImplementationArchitect(fs, input, state, "code-change", architectsAfterTester);
     }
-    return allowedAfterTester(fs, input, state, "coder", {
+    return allowedAfterTester(fs, input, state, "code-change", "coder", {
         testerFailureFlow: "architect-debug",
         implementationFailureFlow: "architect-debug",
         successTarget: "code-change/architect"
@@ -514,9 +738,15 @@ async function allowedArchitectFix(fs, input, state, segment, source, resumedFro
         if (!evidenceIsFresh(state, source, "architect", artifactName, artifact.hash)) {
             return [`${source}/architect`];
         }
-        if (source === "architect-debug" && artifact.disposition === "normal architecture plan required") {
+        if (source === "architect-debug" && artifact.disposition === ARCHITECT_DEBUG_NORMAL_PLAN_DISPOSITION) {
             return ["code-change/architect"];
         }
+        if (source === "architecture-diagnosis" && artifact.disposition === "analysis completed") {
+            return parentFlow ? [`${parentFlow}/architect`] : [];
+        }
+        if (artifact.disposition === "user clarification required") {
+            return [`${source}/architect`];
+        }
         return artifact.complete ? [`${source}/tester`] : [`${source}/architect`];
     }
     if (architectIndex > testerIndex) {
@@ -524,6 +754,10 @@ async function allowedArchitectFix(fs, input, state, segment, source, resumedFro
         const artifact = source === "architect-debug"
             ? await artifactState(fs, input, artifactName, "architect-debug")
             : await artifactState(fs, input, artifactName, "architecture-diagnosis");
+        if (evidenceIsFresh(state, source, "architect", artifactName, artifact.hash)
+            && artifact.disposition === "user clarification required") {
+            return [`${source}/architect`];
+        }
         if (evidenceIsFresh(state, source, "architect", artifactName, artifact.hash) && artifact.complete) {
             return [`${source}/tester`];
         }
@@ -533,7 +767,7 @@ async function allowedArchitectFix(fs, input, state, segment, source, resumedFro
             ? []
             : [`${source}/architect`];
     }
-    return allowedAfterTester(fs, input, state, source, {
+    return allowedAfterTester(fs, input, state, source, source, {
         testerFailureFlow: source === "architect-debug" ? "architecture-diagnosis" : undefined,
         implementationFailureFlow: source,
         successTarget: parentFlow ? `${parentFlow}/architect` : `${source}/architect`
@@ -545,21 +779,46 @@ async function allowedPostImplementationArchitect(fs, input, state, flow, archit
     if (flow === "code-change" && architectEntries.length > 1 && acceptance.value === "needs-architect-follow-up") {
         return allowedArchitectureFollowup(fs, input, state, architectEntries[1]?.confirmedAt);
     }
-    if (evidenceIsFresh(state, flow, "architect", "docs-sync-report.md", docs.hash)
-        && (docs.value === "synced" || docs.value === "unchanged")) {
-        if (acceptance.value === "needs-coder-follow-up" && flow === "code-change")
-            return ["code-change/coder"];
-        if (acceptance.value === "needs-docs-sync")
-            return [`${flow}/architect`];
-        if (acceptance.value === "needs-architect-follow-up")
-            return [`${flow}/architect`];
-        return [];
+    if (evidenceIsFresh(state, flow, "architect", "docs-sync-report.md", docs.hash) && docs.complete) {
+        if (docs.value === "synced" || docs.value === "unchanged") {
+            if (acceptance.value === "needs-coder-follow-up" && flow === "code-change")
+                return ["code-change/coder"];
+            if (acceptance.value === "needs-docs-sync")
+                return [`${flow}/architect`];
+            if (acceptance.value === "needs-architect-follow-up")
+                return [`${flow}/architect`];
+            return [];
+        }
+        if (docs.value === "blocked" && docs.correctionOwner && docs.correctionOwner !== "none") {
+            return [`${flow}/${docs.correctionOwner}`];
+        }
     }
     return [`${flow}/architect`];
 }
-async function allowedAfterTester(fs, input, state, codeSource, options) {
+async function allowedActiveCoderDocsCorrection(fs, input, state, flow) {
+    const active = state.activeDispatch;
+    if (!active || active.flow !== flow || active.targetRole !== "coder")
+        return undefined;
+    const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
+    if (!docs.complete
+        || docs.value !== "blocked"
+        || docs.correctionOwner !== "coder"
+        || active.artifactHashes["docs-sync-report.md"] !== docs.hash)
+        return undefined;
+    const coder = await artifactState(fs, input, "coder-completion.md", "coder-completion");
+    if (!evidenceIsFresh(state, flow, "coder", "coder-completion.md", coder.hash)
+        || coder.value === "incomplete")
+        return [`${flow}/coder`];
+    if (coder.value === "ready_for_review")
+        return [`${flow}/tester`];
+    if (flow === "code-change")
+        return ["architect-debug/architect"];
+    if (flow === "architect-debug")
+        return ["architecture-diagnosis/architect"];
+    return [];
+}
+async function allowedAfterTester(fs, input, state, currentFlow, codeSource, options) {
     const test = await artifactState(fs, input, "test-report.md", "test-report");
-    const currentFlow = codeSource === "coder" ? "code-change" : codeSource;
     if (!evidenceIsFresh(state, currentFlow, "tester", "test-report.md", test.hash)) {
         return [`${currentFlow}/tester`];
     }
@@ -617,12 +876,18 @@ async function artifactState(fs, input, fileName, kind) {
     const disposition = kind === "architect-debug" || kind === "architecture-diagnosis"
         ? readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase()
         : undefined;
+    const correctionOwner = kind === "docs-sync-report"
+        ? readArtifactSectionContent(content, "Correction Owner")?.trim().toLowerCase()
+        : undefined;
     return {
         complete: check.status === "ok",
-        hash: contentHash(content),
+        hash: await artifactFingerprint(fs, absolute, content),
         value,
         infrastructure,
-        disposition
+        disposition,
+        correctionOwner: correctionOwner === "none" || asTargetRole(correctionOwner)
+            ? correctionOwner
+            : undefined
     };
 }
 async function gateState(fs, input, gate) {
@@ -640,7 +905,9 @@ async function gateState(fs, input, gate) {
 async function captureEvidenceBaseline(fs, input, sequence, flow, targetRole, confirmedAt) {
     const artifactEntries = await Promise.all(WORKFLOW_EVIDENCE_ARTIFACTS.map(async (fileName) => {
         const target = resolveRepoPath(input.taskRepoRoot, path.posix.join(input.handoffDir, fileName));
-        const hash = await fs.pathExists(target) ? contentHash(await fs.readText(target)) : MISSING_EVIDENCE_HASH;
+        const hash = await fs.pathExists(target)
+            ? await artifactFingerprint(fs, target, await fs.readText(target))
+            : MISSING_EVIDENCE_HASH;
         return [fileName, hash];
     }));
     const gateEntries = await Promise.all(WORKFLOW_EVIDENCE_GATES.map(async (gate) => [
@@ -656,8 +923,8 @@ async function captureEvidenceBaseline(fs, input, sequence, flow, targetRole, co
         confirmedAt
     };
 }
-async function advanceFlowRun(fs, input, state, current, effectiveFlow, usedOverride, nextSequence) {
-    if (!current.flow || current.status === "completed" || (usedOverride && effectiveFlow !== current.flow)) {
+async function advanceFlowRun(fs, input, state, current, effectiveFlow, nextSequence) {
+    if (!current.flow || current.status === "completed") {
         return newFlowRun(effectiveFlow, nextSequence);
     }
     const run = resolveFlowRun(state.flowRun, current);
@@ -677,7 +944,7 @@ async function advanceFlowRun(fs, input, state, current, effectiveFlow, usedOver
     if (run.activeBranch === current.flow && effectiveFlow === run.rootFlow) {
         if (current.flow === "architect-debug" && effectiveFlow === "code-change") {
             const debug = await artifactState(fs, input, "architect-debug.md", "architect-debug");
-            if (debug.disposition === "normal architecture plan required") {
+            if (debug.disposition === ARCHITECT_DEBUG_NORMAL_PLAN_DISPOSITION) {
                 return newFlowRun("code-change", nextSequence);
             }
         }
@@ -766,11 +1033,18 @@ function freshGateDecision(state, flow, targetRole, gate, record) {
 function gatePassedForDispatch(state, flow, targetRole, gate, record) {
     if (!record)
         return false;
-    if (FINAL_GATE_STATUSES.has(record.status))
+    if (record.status === "disabled")
         return true;
+    if (FRESH_EXCEPTION_GATE_STATUSES.has(record.status)) {
+        return gateRecordIsFresh(state, flow, targetRole, gate, record);
+    }
     return freshGateDecision(state, flow, targetRole, gate, record) === "approve"
         && record.status === "completed";
 }
+function gateRecordIsFresh(state, flow, targetRole, gate, record) {
+    const baseline = matchingEvidenceBaseline(state, flow, targetRole);
+    return !baseline || baseline.gateFingerprints[gate] !== gateFingerprint(record);
+}
 function matchingEvidenceBaseline(state, flow, targetRole) {
     const baseline = state.activeDispatch;
     return baseline?.flow === flow && baseline.targetRole === targetRole ? baseline : undefined;
@@ -786,7 +1060,8 @@ function gateFingerprint(record) {
         codeDiffSource: record.codeDiffSource,
         codeDiffSources: record.codeDiffSources,
         findings: record.findings,
-        completedAt: record.completedAt
+        completedAt: record.completedAt,
+        updatedAt: record.updatedAt
     }));
 }
 async function describeBlockedCheckpoint(fs, input, state, current) {
@@ -821,11 +1096,7 @@ async function validateCompletion(fs, input, state, candidate) {
         throw workflowError("WORKFLOW_COMPLETION_INVALID", `${candidate.flow} is an active branch and must return to ${flowRun.rootFlow} before completion.`);
     }
     if (candidate.flow === "code-change" || candidate.flow === "architect-debug") {
-        const acceptance = await artifactState(fs, input, "final-acceptance.md", "final-acceptance");
-        if (!evidenceProducedAfterActiveDispatch(state, candidate.flow, "architect", "final-acceptance.md", acceptance.hash)
-            || (acceptance.value !== "accepted" && acceptance.value !== "accepted-with-known-risks")) {
-            throw workflowError("WORKFLOW_COMPLETION_INVALID", "Final Acceptance is not accepted for this complete delivery flow.");
-        }
+        await validateCompleteDeliveryEvidence(fs, input, state, candidate.flow);
         return;
     }
     if (candidate.flow === "architecture-diagnosis") {
@@ -833,11 +1104,7 @@ async function validateCompletion(fs, input, state, candidate) {
         if (diagnosis.disposition === "analysis completed"
             && evidenceProducedAfterActiveDispatch(state, candidate.flow, "architect", "architecture-diagnosis.md", diagnosis.hash))
             return;
-        const acceptance = await artifactState(fs, input, "final-acceptance.md", "final-acceptance");
-        if (!evidenceProducedAfterActiveDispatch(state, candidate.flow, "architect", "final-acceptance.md", acceptance.hash)
-            || (acceptance.value !== "accepted" && acceptance.value !== "accepted-with-known-risks")) {
-            throw workflowError("WORKFLOW_COMPLETION_INVALID", "Implemented Architecture Diagnosis requires accepted Final Acceptance evidence.");
-        }
+        await validateCompleteDeliveryEvidence(fs, input, state, candidate.flow);
         return;
     }
     if (candidate.flow === "docs-only") {
@@ -862,6 +1129,35 @@ async function validateCompletion(fs, input, state, candidate) {
         }
     }
 }
+async function validateCompleteDeliveryEvidence(fs, input, state, flow) {
+    const baseline = state.activeDispatch;
+    if (!baseline || baseline.flow !== flow) {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", `The latest confirmed dispatch does not belong to the active ${flow} flow.`);
+    }
+    if (baseline.targetRole !== "architect") {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", `The latest ${flow} dispatch is to ${baseline.targetRole}. Complete every required downstream validation and Gate step, then route Architect for docs sync before completing the flow.`);
+    }
+    const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
+    if (!docs.complete) {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", "Docs Sync Report is missing or malformed for this complete delivery flow.");
+    }
+    if (baseline.artifactHashes["docs-sync-report.md"] === docs.hash) {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", "Docs Sync Report was not produced after the final Architect dispatch.");
+    }
+    if (docs.value !== "synced" && docs.value !== "unchanged") {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", `Docs Sync Report Decision must be synced or unchanged before completion; found ${docs.value ?? "missing"}.`);
+    }
+    const acceptance = await artifactState(fs, input, "final-acceptance.md", "final-acceptance");
+    if (!acceptance.complete) {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", "Final Acceptance is missing or malformed for this complete delivery flow.");
+    }
+    if (acceptance.value !== "accepted" && acceptance.value !== "accepted-with-known-risks") {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", `Final Acceptance Decision must be accepted or accepted-with-known-risks; found ${acceptance.value ?? "missing"}.`);
+    }
+    if (baseline.artifactHashes["final-acceptance.md"] === acceptance.hash) {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", "Final Acceptance was not produced after the final Architect dispatch.");
+    }
+}
 function evidenceProducedAfterActiveDispatch(state, flow, targetRole, artifact, currentHash) {
     const baseline = matchingEvidenceBaseline(state, flow, targetRole);
     return Boolean(baseline && baseline.artifactHashes[artifact] !== currentHash);
@@ -879,6 +1175,31 @@ function validateCandidateAgainstCurrent(current, candidate) {
     if (errors.length > 0)
         throw progressValidationError(errors);
 }
+function stateProgressConsistencyWarnings(state, progress) {
+    const warnings = [];
+    const pending = state.pendingDispatch;
+    if (!pending && progress.proposal) {
+        warnings.push("Workflow Progress contains a dispatch proposal without a runtime approval.");
+    }
+    if (pending && (pending.revision !== progress.revision
+        || pending.baseHistoryHash !== historyHash(progress.history)
+        || progress.proposal?.requestedFlow !== pending.requestedFlow
+        || progress.proposal?.targetRole !== pending.targetRole
+        || progress.proposal?.evidence !== pending.evidence)) {
+        warnings.push("Workflow runtime approval does not match workflow-progress.md.");
+    }
+    const last = progress.history.at(-1);
+    if (last && (!state.activeDispatch
+        || state.activeDispatch.sequence !== last.sequence
+        || state.activeDispatch.flow !== last.flow
+        || state.activeDispatch.targetRole !== last.targetRole)) {
+        warnings.push("Workflow active dispatch does not match the latest Workflow Progress history entry.");
+    }
+    if (!last && state.activeDispatch) {
+        warnings.push("Workflow active dispatch exists without a Workflow Progress history entry.");
+    }
+    return warnings;
+}
 function createUserAuthorization(authorizationId, current, candidate, effectiveFlow, baseHistoryHash, violation, authorizationText, timestamp) {
     return {
         id: authorizationId,
@@ -896,31 +1217,33 @@ function createUserAuthorization(authorizationId, current, candidate, effectiveF
         createdAt: timestamp
     };
 }
+function createUserApprovedFollowUp(approvalId, current, candidate, effectiveFlow, baseHistoryHash, approvalText, timestamp) {
+    return {
+        id: approvalId,
+        status: "accepted",
+        role: "project-manager",
+        operation: "post-validation-follow-up",
+        baseRevision: current.revision,
+        baseHistoryHash,
+        effectiveFlow: effectiveFlow,
+        targetRole: "tester",
+        evidence: candidate.proposal.evidence,
+        approvalText,
+        createdAt: timestamp
+    };
+}
 async function readProgress(fs, input) {
     const target = progressPath(input);
     if (!(await fs.pathExists(target)))
         return parseWorkflowProgress(renderWorkflowProgressTemplate(input.taskSlug), input.taskSlug);
     return parseWorkflowProgress(await fs.readText(target), input.taskSlug);
 }
-async function ensureProgressFile(fs, input) {
-    const target = progressPath(input);
-    if (!(await fs.pathExists(target))) {
-        await writeAtomic(fs, target, renderWorkflowProgressTemplate(input.taskSlug));
-        return undefined;
-    }
-    try {
-        parseWorkflowProgress(await fs.readText(target), input.taskSlug);
-        return undefined;
-    }
-    catch (error) {
-        return `Workflow Progress is invalid and was preserved unchanged: ${errorMessage(error)}`;
-    }
-}
 function parseHistory(value, errors) {
     if (!value || value.trim() === "none")
         return [];
     const lines = value.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-    if (lines[0] !== HISTORY_HEADER || lines[1] !== HISTORY_SEPARATOR) {
+    const legacy = lines[0] === LEGACY_HISTORY_HEADER && lines[1] === LEGACY_HISTORY_SEPARATOR;
+    if (!legacy && (lines[0] !== HISTORY_HEADER || lines[1] !== HISTORY_SEPARATOR)) {
         errors.push("Dispatch History must use the exact VCM table header.");
         return [];
     }
@@ -929,8 +1252,9 @@ function parseHistory(value, errors) {
         const cells = line.startsWith("|") && line.endsWith("|")
             ? line.slice(1, -1).split("|").map((cell) => cell.trim())
             : [];
-        if (cells.length !== 6) {
-            errors.push("Every Dispatch History row must contain exactly six columns.");
+        const expectedColumns = legacy ? 6 : 7;
+        if (cells.length !== expectedColumns) {
+            errors.push(`Every Dispatch History row must contain exactly ${expectedColumns} columns.`);
             continue;
         }
         const sequence = Number(cells[0]);
@@ -946,7 +1270,8 @@ function parseHistory(value, errors) {
             targetRole,
             evidence: cells[3],
             overrideAuthorizationId: cells[4] === "none" ? undefined : cells[4],
-            confirmedAt: cells[5] === "none" ? undefined : cells[5]
+            followUpApprovalId: legacy || cells[5] === "none" ? undefined : cells[5],
+            confirmedAt: cells[legacy ? 5 : 6] === "none" ? undefined : cells[legacy ? 5 : 6]
         });
     }
     return entries;
@@ -964,6 +1289,11 @@ function normalizeState(value, taskSlug, timestamp) {
         : value.userAuthorizations === undefined && Array.isArray(value.overrideRequests)
             ? []
             : undefined;
+    const userApprovedFollowUps = value.userApprovedFollowUps === undefined
+        ? []
+        : Array.isArray(value.userApprovedFollowUps) && value.userApprovedFollowUps.every(isUserApprovedFollowUp)
+            ? value.userApprovedFollowUps
+            : undefined;
     const activeDispatch = value.activeDispatch === undefined || value.activeDispatch === null
         ? null
         : normalizeDispatchEvidenceBaseline(value.activeDispatch);
@@ -977,6 +1307,7 @@ function normalizeState(value, taskSlug, timestamp) {
         || activeDispatch === undefined
         || flowRun === undefined
         || userAuthorizations === undefined
+        || userApprovedFollowUps === undefined
         || awaitingUser === undefined) {
         return { ...emptyState(taskSlug, timestamp), warnings: ["Workflow control state has an unsupported shape."] };
     }
@@ -988,6 +1319,7 @@ function normalizeState(value, taskSlug, timestamp) {
         activeDispatch,
         flowRun,
         userAuthorizations,
+        userApprovedFollowUps,
         warnings: [],
         updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : timestamp
     };
@@ -1001,6 +1333,7 @@ function emptyState(taskSlug, timestamp) {
         activeDispatch: null,
         flowRun: null,
         userAuthorizations: [],
+        userApprovedFollowUps: [],
         warnings: [],
         updatedAt: timestamp
     };
@@ -1018,6 +1351,9 @@ function expectedRoutePath(handoffDir, role) {
 function statePath(input) {
     return path.join(input.taskRepoRoot, input.stateRoot, "workflow-control.json");
 }
+function transactionPath(input) {
+    return path.join(input.taskRepoRoot, input.stateRoot, "workflow-control-transaction.json");
+}
 function relativeProgressPath(input) {
     return path.posix.join(input.handoffDir, "workflow-progress.md");
 }
@@ -1030,6 +1366,12 @@ function historyHash(history) {
 function contentHash(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+async function artifactFingerprint(fs, target, content) {
+    const contentDigest = contentHash(content);
+    if (!fs.fileVersion)
+        return contentDigest;
+    return contentHash(`${contentDigest}:${await fs.fileVersion(target)}`);
+}
 function field(content, name) {
     return rawField(content, name)?.toLowerCase();
 }
@@ -1098,6 +1440,7 @@ function isPendingDispatch(value) {
         && typeof value.evidence === "string"
         && typeof value.expectedRoutePath === "string"
         && (value.overrideAuthorizationId === undefined || typeof value.overrideAuthorizationId === "string")
+        && (value.followUpApprovalId === undefined || typeof value.followUpApprovalId === "string")
         && (value.status === "pending" || value.status === "dispatching")
         && (value.routeContentHash === undefined || typeof value.routeContentHash === "string")
         && (value.messageId === undefined || typeof value.messageId === "string")
@@ -1122,6 +1465,24 @@ function isUserAuthorization(value) {
         && typeof value.createdAt === "string"
         && (value.consumedAt === undefined || typeof value.consumedAt === "string");
 }
+function isUserApprovedFollowUp(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value.id === "string"
+        && (value.status === "accepted" || value.status === "consumed")
+        && value.role === "project-manager"
+        && value.operation === "post-validation-follow-up"
+        && Number.isInteger(value.baseRevision)
+        && typeof value.baseHistoryHash === "string"
+        && (value.effectiveFlow === "code-change"
+            || value.effectiveFlow === "architect-debug"
+            || value.effectiveFlow === "architecture-diagnosis")
+        && value.targetRole === "tester"
+        && typeof value.evidence === "string"
+        && typeof value.approvalText === "string"
+        && typeof value.createdAt === "string"
+        && (value.consumedAt === undefined || typeof value.consumedAt === "string");
+}
 function normalizeDispatchEvidenceBaseline(value) {
     if (!isRecord(value) || !isRecord(value.artifactHashes) || !isRecord(value.gateFingerprints))
         return undefined;