vibe-coding-master 0.7.42 → 0.7.43

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

@@ -2,16 +2,17 @@ import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { VcmError } from "../errors.js";
-import { WORKFLOW_FLOWS } from "../../shared/types/workflow.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 { renderWorkflowProgressTemplate } from "../templates/handoff.js";
 const HISTORY_HEADER = "| Sequence | Flow | Target Role | Evidence | Override Authorization | Confirmed At |";
 const HISTORY_SEPARATOR = "| --- | --- | --- | --- | --- | --- |";
 const TARGET_ROLES = new Set(["architect", "coder", "tester"]);
 const FINAL_GATE_STATUSES = new Set(["disabled", "not_required", "skipped", "overridden"]);
+const MISSING_EVIDENCE_HASH = "<missing>";
 export function createWorkflowControlService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
-    const id = deps.id ?? (() => `wfovr_${randomUUID()}`);
+    const id = deps.id ?? (() => `wfauth_${randomUUID()}`);
     const locks = new Map();
     async function getState(input) {
         try {
@@ -44,49 +45,38 @@ export function createWorkflowControlService(deps) {
                 if (candidate.status !== "completed") {
                     throw workflowError("WORKFLOW_PROPOSAL_REQUIRED", "Workflow Progress must propose one role dispatch or mark the active flow completed.", "Set Proposed Dispatch to a target role, or submit Status: completed after the flow's completion evidence exists.");
                 }
-                await validateCompletion(deps.fs, input, candidate);
+                await validateCompletion(deps.fs, input, state, candidate);
                 const normalized = renderWorkflowProgress(candidate);
                 await writeAtomic(deps.fs, progressPath(input), normalized);
                 return { path: relativeProgressPath(input), content: normalized };
             }
+            if (current.status === "completed" && !candidate.proposal.requestedFlow) {
+                throw workflowError("WORKFLOW_FLOW_REQUIRED", "Requested Flow is required when starting another flow after completion.", "Select the next flow explicitly before dispatching its first role.");
+            }
             const baseHistoryHash = historyHash(current.history);
             const effectiveFlow = resolveEffectiveFlow(current.flow, candidate.proposal.requestedFlow);
-            const verdict = await evaluateTransition(deps.fs, input, current, effectiveFlow, candidate.proposal.targetRole);
+            const verdict = await evaluateTransition(deps.fs, input, state, current, effectiveFlow, candidate.proposal.targetRole);
             let overrideAuthorizationId;
+            let userAuthorization;
             if (!verdict.allowed) {
-                const authorizationId = candidate.proposal.authorizationId;
-                if (authorizationId === "request") {
-                    const existingPending = state.overrideRequests.find((entry) => entry.status === "pending");
-                    if (existingPending) {
-                        throw workflowError("WORKFLOW_OVERRIDE_PENDING", `Workflow override ${existingPending.id} is already waiting for the user's decision.`, "Wait for the current user decision before requesting another workflow override.");
-                    }
-                    const quote = candidate.proposal.authorizationQuote?.trim();
-                    const violatedRule = candidate.proposal.violatedRule?.trim();
-                    if (!quote || !violatedRule || violatedRule !== verdict.reason) {
-                        throw workflowError("WORKFLOW_OVERRIDE_REQUEST_INVALID", `Override request must include the proposed user authorization and the exact violated rule: ${verdict.reason}`, "Copy the rejection reason exactly into Violated Rule and record the user's proposed authorization text.");
-                    }
-                    const pending = createOverrideRequest(id(), current, candidate, effectiveFlow, baseHistoryHash, verdict.reason, quote, now());
-                    const next = {
-                        ...state,
-                        overrideRequests: [...state.overrideRequests, pending],
-                        updatedAt: now()
-                    };
-                    await saveState(input, next);
-                    throw workflowError("WORKFLOW_OVERRIDE_PENDING", `Workflow override ${pending.id} requires direct user confirmation in VCM.`, "Wait for the user's decision. If approved, resubmit with the returned Authorization ID and exact authorization text.");
+                const authorizationText = candidate.proposal.authorizationText?.trim();
+                const violatedRule = candidate.proposal.violatedRule?.trim();
+                if (!authorizationText && !violatedRule) {
+                    throw workflowError("WORKFLOW_TRANSITION_DENIED", verdict.reason, verdict.allowedTransitions.length > 0
+                        ? `Allowed next dispatches: ${verdict.allowedTransitions.join(", ")}. Recheck the flow, or ask the user directly for an exact one-time authorization.`
+                        : verdict.blockedHint);
                 }
-                if (authorizationId && authorizationId !== "none") {
-                    const override = state.overrideRequests.find((entry) => entry.id === authorizationId);
-                    validateApprovedOverride(override, current, candidate, effectiveFlow, baseHistoryHash, verdict.reason);
-                    overrideAuthorizationId = override.id;
+                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.");
                 }
-                else {
-                    throw workflowError("WORKFLOW_TRANSITION_DENIED", verdict.reason, verdict.allowedTransitions.length > 0
-                        ? `Allowed next dispatches: ${verdict.allowedTransitions.join(", ")}. Recheck the flow, or request an exact one-time user override.`
-                        : "No role dispatch is legal at this checkpoint. Complete the required Gate, user decision, or PM-only step first.");
+                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;
             }
-            else if (candidate.proposal.authorizationId && candidate.proposal.authorizationId !== "none") {
-                throw workflowError("WORKFLOW_OVERRIDE_NOT_REQUIRED", "This workflow transition is legal and must not consume a user override.", "Set every User Override field to none.");
+            else if (candidate.proposal.authorizationText || candidate.proposal.violatedRule) {
+                throw workflowError("WORKFLOW_USER_AUTHORIZATION_NOT_REQUIRED", "This workflow transition is legal and must not consume user authorization.", "Set every User Authorization field to none.");
             }
             const timestamp = now();
             const pendingDispatch = {
@@ -104,20 +94,16 @@ export function createWorkflowControlService(deps) {
             };
             const accepted = {
                 ...candidate,
-                proposal: {
-                    ...candidate.proposal,
-                    authorizationId: overrideAuthorizationId,
-                    authorizationQuote: overrideAuthorizationId
-                        ? state.overrideRequests.find((entry) => entry.id === overrideAuthorizationId)?.authorizationText
-                        : undefined,
-                    violatedRule: overrideAuthorizationId ? verdict.reason : undefined
-                }
+                proposal: candidate.proposal
             };
             const normalized = renderWorkflowProgress(accepted);
             await writeAtomic(deps.fs, progressPath(input), normalized);
             await saveState(input, {
                 ...state,
                 pendingDispatch,
+                userAuthorizations: userAuthorization
+                    ? [...state.userAuthorizations, userAuthorization]
+                    : state.userAuthorizations,
                 updatedAt: timestamp
             });
             return { path: relativeProgressPath(input), content: normalized };
@@ -196,6 +182,8 @@ export function createWorkflowControlService(deps) {
                 overrideAuthorizationId: pending.overrideAuthorizationId,
                 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 completed = {
                 ...current,
                 flow: pending.effectiveFlow,
@@ -203,62 +191,27 @@ export function createWorkflowControlService(deps) {
                 history: [...current.history, entry],
                 proposal: undefined
             };
-            const overrideRequests = state.overrideRequests.map((entry) => entry.id === pending.overrideAuthorizationId
+            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, {
                 ...state,
                 pendingDispatch: null,
-                overrideRequests,
+                activeDispatch,
+                flowRun,
+                userAuthorizations,
                 updatedAt: timestamp
             });
         });
     }
-    async function approveOverride(input, overrideId, authorizationText) {
-        return decideOverride(input, overrideId, "approved", authorizationText);
-    }
-    async function rejectOverride(input, overrideId) {
-        return decideOverride(input, overrideId, "rejected");
-    }
-    async function decideOverride(input, overrideId, decision, authorizationText) {
-        return withLock(statePath(input), async () => {
-            const state = await getState(input);
-            failOnStateWarnings(state);
-            const existing = state.overrideRequests.find((entry) => entry.id === overrideId);
-            if (!existing || existing.status !== "pending") {
-                throw workflowError("WORKFLOW_OVERRIDE_NOT_PENDING", `Workflow override ${overrideId} is not pending.`, "Refresh the task state and act only on the current pending override.");
-            }
-            const normalizedAuthorization = authorizationText?.trim();
-            if (decision === "approved" && !normalizedAuthorization) {
-                throw workflowError("WORKFLOW_OVERRIDE_AUTHORIZATION_REQUIRED", "Direct user authorization text is required.", "Describe the exact one-time workflow exception being authorized.");
-            }
-            const timestamp = now();
-            const next = {
-                ...state,
-                overrideRequests: state.overrideRequests.map((entry) => entry.id === overrideId
-                    ? {
-                        ...entry,
-                        status: decision,
-                        authorizationText: decision === "approved" ? normalizedAuthorization : undefined,
-                        decidedAt: timestamp
-                    }
-                    : entry),
-                updatedAt: timestamp
-            };
-            await saveState(input, next);
-            return next;
-        });
-    }
     return {
         getState,
         submitProgress,
         assertRouteAuthorized,
         claimDispatch,
         releaseDispatch,
-        confirmDispatch,
-        approveOverride,
-        rejectOverride
+        confirmDispatch
     };
     async function saveState(input, state) {
         await deps.fs.writeJsonAtomic(statePath(input), state);
@@ -315,26 +268,24 @@ export function parseWorkflowProgress(content, expectedTaskSlug) {
     else if (requestedFlowValue !== "none" || evidence !== "none") {
         errors.push("A completed/no-dispatch proposal must use Requested Flow, Target Role, and Evidence value none.");
     }
-    const overrideSection = readArtifactSectionContent(content, "User Override") ?? "";
-    const authorizationId = rawField(overrideSection, "Authorization ID");
-    const authorizationQuote = rawField(overrideSection, "Authorization Quote");
-    const violatedRule = rawField(overrideSection, "Violated Rule");
-    if (!authorizationId || !authorizationQuote || !violatedRule) {
-        errors.push("User Override requires Authorization ID, Authorization Quote, and Violated Rule fields.");
+    const authorizationSection = readArtifactSectionContent(content, "User Authorization") ?? "";
+    const authorizationText = rawField(authorizationSection, "Authorization Text");
+    const violatedRule = rawField(authorizationSection, "Violated Rule");
+    if (!authorizationText || !violatedRule) {
+        errors.push("User Authorization requires Authorization Text and Violated Rule fields.");
     }
     else if (proposal) {
-        const allNone = authorizationId === "none" && authorizationQuote === "none" && violatedRule === "none";
-        const allSet = authorizationId !== "none" && authorizationQuote !== "none" && violatedRule !== "none";
+        const allNone = authorizationText === "none" && violatedRule === "none";
+        const allSet = authorizationText !== "none" && violatedRule !== "none";
         if (!allNone && !allSet)
-            errors.push("User Override fields must all be none or all contain the exact override data.");
+            errors.push("User Authorization fields must both be none or both contain exact authorization evidence.");
         if (allSet) {
-            proposal.authorizationId = authorizationId;
-            proposal.authorizationQuote = authorizationQuote;
+            proposal.authorizationText = authorizationText;
             proposal.violatedRule = violatedRule;
         }
     }
-    else if (authorizationId !== "none" || authorizationQuote !== "none" || violatedRule !== "none") {
-        errors.push("User Override fields must be none when no role dispatch is proposed.");
+    else if (authorizationText !== "none" || violatedRule !== "none") {
+        errors.push("User Authorization fields must be none when no role dispatch is proposed.");
     }
     if (errors.length > 0)
         throw progressValidationError(errors);
@@ -372,165 +323,211 @@ Requested Flow: ${proposal?.requestedFlow ?? "none"}
 Target Role: ${proposal?.targetRole ?? "none"}
 Evidence: ${proposal?.evidence ?? "none"}
 
-## User Override
+## User Authorization
 
-Authorization ID: ${proposal?.authorizationId ?? "none"}
-Authorization Quote: ${proposal?.authorizationQuote ?? "none"}
+Authorization Text: ${proposal?.authorizationText ?? "none"}
 Violated Rule: ${proposal?.violatedRule ?? "none"}
 `;
 }
-async function evaluateTransition(fs, input, current, effectiveFlow, targetRole) {
-    const allowedTransitions = await getAllowedTransitions(fs, input, current);
+async function evaluateTransition(fs, input, state, current, effectiveFlow, targetRole) {
+    const allowedTransitions = await getAllowedTransitions(fs, input, state, current);
     const signature = `${effectiveFlow}/${targetRole}`;
-    if (allowedTransitions.includes(signature))
-        return { allowed: true, reason: "allowed", allowedTransitions };
+    if (allowedTransitions.includes(signature)) {
+        return { allowed: true, reason: "allowed", allowedTransitions, blockedHint: "" };
+    }
     return {
         allowed: false,
         reason: `Transition ${signature} is not legal after the confirmed Workflow Progress history.`,
-        allowedTransitions
+        allowedTransitions,
+        blockedHint: await describeBlockedCheckpoint(fs, input, state, current)
     };
 }
-async function getAllowedTransitions(fs, input, current) {
+async function getAllowedTransitions(fs, input, state, current) {
     if (current.status === "completed")
-        return [];
+        return initialTransitions();
     if (!current.flow || current.history.length === 0) {
-        return [
-            "code-change/architect",
-            "architect-debug/architect",
-            "architecture-diagnosis/architect",
-            "docs-only/architect",
-            "validation-only/tester"
-        ];
+        return initialTransitions();
     }
     const flow = current.flow;
+    const flowRun = resolveFlowRun(state.flowRun, current);
     if (flow === "docs-only") {
         const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
-        return docs.value === "synced" || docs.value === "unchanged"
+        return evidenceIsFresh(state, flow, "architect", "docs-sync-report.md", docs.hash)
+            && docs.complete && (docs.value === "synced" || docs.value === "unchanged")
             ? []
             : ["docs-only/architect", "code-change/architect", "validation-only/tester"];
     }
     if (flow === "validation-only") {
         const test = await artifactState(fs, input, "test-report.md", "test-report");
+        if (!evidenceIsFresh(state, flow, "tester", "test-report.md", test.hash))
+            return ["validation-only/tester"];
         if (test.infrastructure === "production-change-required")
             return ["code-change/architect"];
         if (test.value === "incomplete" || test.infrastructure === "repair-required")
             return ["validation-only/tester"];
         const validationGate = await gateState(fs, input, "validation-adequacy");
-        if (validationGate?.decision === "request_changes")
+        if (freshGateDecision(state, flow, "tester", "validation-adequacy", validationGate) === "request_changes") {
             return ["validation-only/tester"];
-        if (!gatePassed(validationGate))
+        }
+        if (!gatePassedForDispatch(state, flow, "tester", "validation-adequacy", validationGate))
             return [];
         return [];
     }
-    const segment = current.history.slice(findLastIndex(current.history, (entry) => entry.flow !== flow) + 1);
-    if (flow === "code-change")
-        return allowedCodeChange(fs, input, current.history);
-    if (flow === "architect-debug")
-        return allowedArchitectFix(fs, input, current, segment, "architect-debug");
-    return allowedArchitectFix(fs, input, current, segment, "architecture-diagnosis");
+    const segment = activeFlowSegment(current.history, flow, flowRun.startedAtSequence);
+    if (flow === "code-change") {
+        return allowedCodeChange(fs, input, state, segment, flowRun.resumedFromBranch !== undefined);
+    }
+    if (flow === "architect-debug") {
+        return allowedArchitectFix(fs, input, state, segment, "architect-debug", flowRun.resumedFromBranch !== undefined, flowRun.activeBranch ? flowRun.rootFlow : undefined);
+    }
+    return allowedArchitectFix(fs, input, state, segment, "architecture-diagnosis", false, flowRun.activeBranch ? flowRun.rootFlow : undefined);
 }
-async function allowedCodeChange(fs, input, segment) {
+function initialTransitions() {
+    return [
+        "code-change/architect",
+        "architect-debug/architect",
+        "architecture-diagnosis/architect",
+        "docs-only/architect",
+        "validation-only/tester"
+    ];
+}
+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 (coderIndex < 0) {
         const plan = await artifactState(fs, input, "architecture-plan.md", "architecture-plan");
-        const gate = await gateState(fs, input, "architecture-plan");
-        if (plan.value !== "complete")
+        if (!evidenceIsFresh(state, "code-change", "architect", "architecture-plan.md", plan.hash)
+            || plan.value !== "complete")
             return ["code-change/architect"];
-        if (gate?.decision === "request_changes")
+        const gate = await gateState(fs, input, "architecture-plan");
+        if (freshGateDecision(state, "code-change", "architect", "architecture-plan", gate) === "request_changes") {
             return ["code-change/architect"];
-        return gatePassed(gate) ? ["code-change/coder"] : [];
+        }
+        return gatePassedForDispatch(state, "code-change", "architect", "architecture-plan", gate)
+            ? ["code-change/coder"]
+            : [];
     }
     if (testerIndex < coderIndex) {
         const coder = await artifactState(fs, input, "coder-completion.md", "coder-completion");
+        if (!evidenceIsFresh(state, "code-change", "coder", "coder-completion.md", coder.hash)) {
+            return ["code-change/coder"];
+        }
         if (coder.value === "failed")
             return ["architect-debug/architect"];
         return coder.value === "ready_for_review" ? ["code-change/tester"] : ["code-change/coder"];
     }
     const architectsAfterTester = segment.filter((entry, index) => index > testerIndex && entry.targetRole === "architect");
     if (architectsAfterTester.length > 0) {
-        const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
-        if (docs.value === "synced" || docs.value === "unchanged") {
-            const acceptance = await artifactState(fs, input, "final-acceptance.md", "final-acceptance");
-            if (acceptance.value === "needs-coder-follow-up")
-                return ["code-change/coder"];
-            if (acceptance.value === "needs-docs-sync")
-                return ["code-change/architect"];
-            if (acceptance.value === "needs-architect-follow-up") {
-                if (architectsAfterTester.length === 1)
-                    return ["code-change/architect"];
-                return allowedArchitectureFollowup(fs, input, architectsAfterTester[1]?.confirmedAt);
-            }
-            return [];
-        }
-        return ["code-change/architect"];
+        return allowedPostImplementationArchitect(fs, input, state, "code-change", architectsAfterTester);
     }
-    return allowedAfterTester(fs, input, "coder", {
+    return allowedAfterTester(fs, input, state, "coder", {
         testerFailureFlow: "architect-debug",
         implementationFailureFlow: "architect-debug",
         successTarget: "code-change/architect"
     });
 }
-async function allowedArchitectureFollowup(fs, input, followupDispatchedAt) {
+async function allowedArchitectureFollowup(fs, input, state, followupDispatchedAt) {
     const plan = await artifactState(fs, input, "architecture-plan.md", "architecture-plan");
-    if (plan.value !== "complete")
+    if (!evidenceIsFresh(state, "code-change", "architect", "architecture-plan.md", plan.hash)
+        || plan.value !== "complete")
         return ["code-change/architect"];
     const gate = await gateState(fs, input, "architecture-plan");
     if (!gate || !followupDispatchedAt || gate.updatedAt <= followupDispatchedAt)
         return [];
-    if (gate.decision === "request_changes")
+    if (freshGateDecision(state, "code-change", "architect", "architecture-plan", gate) === "request_changes") {
         return ["code-change/architect"];
-    return gatePassed(gate) ? ["code-change/coder"] : [];
+    }
+    return gatePassedForDispatch(state, "code-change", "architect", "architecture-plan", gate)
+        ? ["code-change/coder"]
+        : [];
 }
-async function allowedArchitectFix(fs, input, current, segment, source) {
+async function allowedArchitectFix(fs, input, state, segment, source, resumedFromBranch, parentFlow) {
     const architectIndex = findLastIndex(segment, (entry) => entry.targetRole === "architect");
     const testerIndex = findLastIndex(segment, (entry) => entry.targetRole === "tester");
+    if (resumedFromBranch && architectIndex >= 0 && testerIndex < 0) {
+        return allowedPostImplementationArchitect(fs, input, state, source, segment);
+    }
     if (architectIndex < 0)
         return [`${source}/architect`];
     if (testerIndex < 0) {
         const artifact = source === "architect-debug"
             ? await artifactState(fs, input, "architect-debug.md", "architect-debug")
             : await artifactState(fs, input, "architecture-diagnosis.md", "architecture-diagnosis");
+        const artifactName = source === "architect-debug" ? "architect-debug.md" : "architecture-diagnosis.md";
+        if (!evidenceIsFresh(state, source, "architect", artifactName, artifact.hash)) {
+            return [`${source}/architect`];
+        }
         if (source === "architect-debug" && artifact.disposition === "normal architecture plan required") {
             return ["code-change/architect"];
         }
         return artifact.complete ? [`${source}/tester`] : [`${source}/architect`];
     }
     if (architectIndex > testerIndex) {
-        const codeDiff = await gateState(fs, input, "code-diff");
-        if (codeDiff?.decision === "request_changes")
+        const artifactName = source === "architect-debug" ? "architect-debug.md" : "architecture-diagnosis.md";
+        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.complete) {
             return [`${source}/tester`];
+        }
         const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
-        return docs.value === "synced" || docs.value === "unchanged" ? [] : [`${source}/architect`];
+        return evidenceIsFresh(state, source, "architect", "docs-sync-report.md", docs.hash)
+            && (docs.value === "synced" || docs.value === "unchanged")
+            ? []
+            : [`${source}/architect`];
     }
-    const parentCodeChange = current.history.slice(0, -segment.length).some((entry) => entry.flow === "code-change");
-    return allowedAfterTester(fs, input, source, {
+    return allowedAfterTester(fs, input, state, source, {
         testerFailureFlow: source === "architect-debug" ? "architecture-diagnosis" : undefined,
         implementationFailureFlow: source,
-        successTarget: parentCodeChange ? "code-change/architect" : `${source}/architect`
+        successTarget: parentFlow ? `${parentFlow}/architect` : `${source}/architect`
     });
 }
-async function allowedAfterTester(fs, input, codeSource, options) {
+async function allowedPostImplementationArchitect(fs, input, state, flow, architectEntries) {
+    const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
+    const acceptance = await artifactState(fs, input, "final-acceptance.md", "final-acceptance");
+    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 [];
+    }
+    return [`${flow}/architect`];
+}
+async function allowedAfterTester(fs, input, state, 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`];
+    }
     if (test.value === "incomplete" || test.infrastructure === "repair-required")
         return [`${currentFlow}/tester`];
     if (test.value === "fail" && test.infrastructure !== "repair-required") {
         return options.testerFailureFlow ? [`${options.testerFailureFlow}/architect`] : [];
     }
     const validation = await gateState(fs, input, "validation-adequacy");
-    if (validation?.decision === "request_changes")
+    if (freshGateDecision(state, currentFlow, "tester", "validation-adequacy", validation) === "request_changes") {
         return [`${currentFlow}/tester`];
-    if (!gatePassed(validation))
+    }
+    if (!gatePassedForDispatch(state, currentFlow, "tester", "validation-adequacy", validation))
         return [];
     const codeDiff = await gateState(fs, input, "code-diff");
-    if (codeDiff?.decision === "request_changes") {
-        const scopes = new Set(codeDiff.findings?.map((finding) => finding.scope).filter(Boolean));
+    if (freshGateDecision(state, currentFlow, "tester", "code-diff", codeDiff) === "request_changes") {
+        const scopes = new Set(codeDiff?.findings?.map((finding) => finding.scope).filter(Boolean));
         return scopes.size === 1 && scopes.has("test-only")
             ? [`${currentFlow}/tester`]
             : options.implementationFailureFlow ? [`${options.implementationFailureFlow}/architect`] : [];
     }
-    if (!gatePassed(codeDiff))
+    if (!gatePassedForDispatch(state, currentFlow, "tester", "code-diff", codeDiff))
         return [];
     const gateCodeSource = codeSource === "architecture-diagnosis" ? "architect-diagnosis" : codeSource;
     const reviewedSources = codeDiff?.codeDiffSources ?? (codeDiff?.codeDiffSource ? [codeDiff.codeDiffSource] : []);
@@ -542,7 +539,7 @@ async function artifactState(fs, input, fileName, kind) {
     const relative = path.posix.join(input.handoffDir, fileName);
     const absolute = resolveRepoPath(input.taskRepoRoot, relative);
     if (!(await fs.pathExists(absolute)))
-        return { complete: false };
+        return { complete: false, hash: MISSING_EVIDENCE_HASH };
     const content = await fs.readText(absolute);
     const check = checkMarkdownArtifact(kind, relative, content, { mode: "final" });
     const inline = (name) => new RegExp(`^${name}:\\s*(.+?)\\s*$`, "mi").exec(content)?.[1]?.trim().toLowerCase();
@@ -565,7 +562,13 @@ async function artifactState(fs, input, fileName, kind) {
     const disposition = kind === "architect-debug" || kind === "architecture-diagnosis"
         ? readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase()
         : undefined;
-    return { complete: check.status === "ok", value, infrastructure, disposition };
+    return {
+        complete: check.status === "ok",
+        hash: contentHash(content),
+        value,
+        infrastructure,
+        disposition
+    };
 }
 async function gateState(fs, input, gate) {
     const target = resolveRepoPath(input.taskRepoRoot, path.posix.join(".ai/vcm/gate-reviews", "index.json"));
@@ -579,46 +582,231 @@ async function gateState(fs, input, gate) {
         return undefined;
     }
 }
-function gatePassed(record) {
-    return Boolean(record && (FINAL_GATE_STATUSES.has(record.status)
-        || (record.status === "completed" && record.decision === "approve")));
+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;
+        return [fileName, hash];
+    }));
+    const gateEntries = await Promise.all(WORKFLOW_EVIDENCE_GATES.map(async (gate) => [
+        gate,
+        gateFingerprint(await gateState(fs, input, gate))
+    ]));
+    return {
+        sequence,
+        flow,
+        targetRole,
+        artifactHashes: Object.fromEntries(artifactEntries),
+        gateFingerprints: Object.fromEntries(gateEntries),
+        confirmedAt
+    };
 }
-async function validateCompletion(fs, input, candidate) {
+async function advanceFlowRun(fs, input, state, current, effectiveFlow, usedOverride, nextSequence) {
+    if (!current.flow || current.status === "completed" || (usedOverride && effectiveFlow !== current.flow)) {
+        return newFlowRun(effectiveFlow, nextSequence);
+    }
+    const run = resolveFlowRun(state.flowRun, current);
+    if (effectiveFlow === current.flow)
+        return run;
+    if (current.flow === "code-change" && effectiveFlow === "architect-debug" && run.rootFlow === "code-change") {
+        return { ...run, activeBranch: "architect-debug", resumedFromBranch: undefined };
+    }
+    if (current.flow === "architect-debug" && effectiveFlow === "architecture-diagnosis") {
+        if (run.rootFlow === "code-change" && run.activeBranch === "architect-debug") {
+            return { ...run, activeBranch: "architecture-diagnosis", resumedFromBranch: undefined };
+        }
+        if (run.rootFlow === "architect-debug" && !run.activeBranch) {
+            return { ...run, activeBranch: "architecture-diagnosis", resumedFromBranch: undefined };
+        }
+    }
+    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") {
+                return newFlowRun("code-change", nextSequence);
+            }
+        }
+        return {
+            ...run,
+            activeBranch: undefined,
+            resumedFromBranch: current.flow
+        };
+    }
+    return newFlowRun(effectiveFlow, nextSequence);
+}
+function newFlowRun(flow, startedAtSequence) {
+    return { rootFlow: flow, startedAtSequence };
+}
+function resolveFlowRun(recorded, current) {
+    if (recorded && current.flow
+        && (recorded.rootFlow === current.flow || recorded.activeBranch === current.flow)) {
+        return recorded;
+    }
+    if (!current.flow || current.history.length === 0) {
+        return newFlowRun(current.flow ?? "code-change", 1);
+    }
+    const segments = flowHistorySegments(current.history);
+    const last = segments.at(-1);
+    const previous = segments.at(-2);
+    const grandparent = segments.at(-3);
+    if (last.flow === "architect-debug" && previous?.flow === "code-change") {
+        return {
+            rootFlow: "code-change",
+            activeBranch: "architect-debug",
+            startedAtSequence: previous.startedAtSequence
+        };
+    }
+    if (last.flow === "architecture-diagnosis" && previous?.flow === "architect-debug") {
+        return {
+            rootFlow: grandparent?.flow === "code-change" ? "code-change" : "architect-debug",
+            activeBranch: "architecture-diagnosis",
+            startedAtSequence: grandparent?.flow === "code-change"
+                ? grandparent.startedAtSequence
+                : previous.startedAtSequence
+        };
+    }
+    if (last.flow === "architecture-diagnosis" && previous?.flow === "code-change") {
+        return {
+            rootFlow: "code-change",
+            activeBranch: "architecture-diagnosis",
+            startedAtSequence: previous.startedAtSequence
+        };
+    }
+    if (last.flow === "code-change" && previous
+        && (previous.flow === "architect-debug" || previous.flow === "architecture-diagnosis")
+        && grandparent?.flow === "code-change") {
+        return {
+            rootFlow: "code-change",
+            resumedFromBranch: previous.flow,
+            startedAtSequence: grandparent.startedAtSequence
+        };
+    }
+    return newFlowRun(last.flow, last.startedAtSequence);
+}
+function flowHistorySegments(history) {
+    const segments = [];
+    for (const entry of history) {
+        if (segments.at(-1)?.flow !== entry.flow) {
+            segments.push({ flow: entry.flow, startedAtSequence: entry.sequence });
+        }
+    }
+    return segments;
+}
+function activeFlowSegment(history, flow, startedAtSequence) {
+    const runStart = history.findIndex((entry) => entry.sequence >= startedAtSequence);
+    const lastDifferent = findLastIndex(history, (entry) => entry.flow !== flow);
+    const start = Math.max(runStart < 0 ? 0 : runStart, lastDifferent + 1);
+    return history.slice(start);
+}
+function evidenceIsFresh(state, flow, targetRole, artifact, currentHash) {
+    const baseline = matchingEvidenceBaseline(state, flow, targetRole);
+    return !baseline || baseline.artifactHashes[artifact] !== currentHash;
+}
+function freshGateDecision(state, flow, targetRole, gate, record) {
+    const baseline = matchingEvidenceBaseline(state, flow, targetRole);
+    if (baseline && baseline.gateFingerprints[gate] === gateFingerprint(record))
+        return undefined;
+    return record?.decision;
+}
+function gatePassedForDispatch(state, flow, targetRole, gate, record) {
+    if (!record)
+        return false;
+    if (FINAL_GATE_STATUSES.has(record.status))
+        return true;
+    return freshGateDecision(state, flow, targetRole, gate, record) === "approve"
+        && record.status === "completed";
+}
+function matchingEvidenceBaseline(state, flow, targetRole) {
+    const baseline = state.activeDispatch;
+    return baseline?.flow === flow && baseline.targetRole === targetRole ? baseline : undefined;
+}
+function gateFingerprint(record) {
+    if (!record)
+        return MISSING_EVIDENCE_HASH;
+    return contentHash(JSON.stringify({
+        requestId: record.requestId,
+        inputHash: record.inputHash,
+        status: record.status,
+        decision: record.decision,
+        codeDiffSource: record.codeDiffSource,
+        codeDiffSources: record.codeDiffSources,
+        findings: record.findings,
+        completedAt: record.completedAt
+    }));
+}
+async function describeBlockedCheckpoint(fs, input, state, current) {
+    const baseline = state.activeDispatch;
+    if (!baseline || !current.flow) {
+        return "No role dispatch is legal at this checkpoint. Complete the required current Gate or PM-only step first.";
+    }
+    if (baseline.targetRole === "tester") {
+        const test = await artifactState(fs, input, "test-report.md", "test-report");
+        if (!evidenceIsFresh(state, baseline.flow, "tester", "test-report.md", test.hash)) {
+            return "The latest Tester dispatch has not produced a fresh test-report.md. Wait for Tester to finish or route Tester again if its result is incomplete.";
+        }
+        if (baseline.flow === "architecture-diagnosis" && test.value === "fail") {
+            return "Architecture Diagnosis stopped after the current Tester failure. Record the user's decision and use one exact Workflow Override if the user authorizes another Architect repair.";
+        }
+        return "The latest Tester result is waiting for its current validation-adequacy or code-diff Gate result.";
+    }
+    if (baseline.targetRole === "architect") {
+        return "The latest Architect dispatch has not produced the fresh workflow artifact required for its next step.";
+    }
+    if (baseline.targetRole === "coder") {
+        return "The latest Coder dispatch has not produced a fresh coder-completion.md.";
+    }
+    return "No role dispatch is legal at this checkpoint. Complete the required current Gate or PM-only step first.";
+}
+async function validateCompletion(fs, input, state, candidate) {
     if (!candidate.flow || candidate.history.length === 0) {
         throw workflowError("WORKFLOW_COMPLETION_INVALID", "An unstarted workflow cannot be completed.");
     }
+    const flowRun = resolveFlowRun(state.flowRun, candidate);
+    if (flowRun.activeBranch === candidate.flow) {
+        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 (acceptance.value !== "accepted" && acceptance.value !== "accepted-with-known-risks") {
+        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.");
         }
         return;
     }
     if (candidate.flow === "architecture-diagnosis") {
         const diagnosis = await artifactState(fs, input, "architecture-diagnosis.md", "architecture-diagnosis");
-        if (diagnosis.disposition === "analysis completed")
+        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 (acceptance.value !== "accepted" && acceptance.value !== "accepted-with-known-risks") {
+        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.");
         }
         return;
     }
     if (candidate.flow === "docs-only") {
         const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
-        if (docs.value !== "synced" && docs.value !== "unchanged") {
-            throw workflowError("WORKFLOW_COMPLETION_INVALID", "Docs-only completion requires a synced or unchanged Docs Sync Report.");
+        if (!evidenceProducedAfterActiveDispatch(state, candidate.flow, "architect", "docs-sync-report.md", docs.hash)
+            || !docs.complete || (docs.value !== "synced" && docs.value !== "unchanged")) {
+            throw workflowError("WORKFLOW_COMPLETION_INVALID", "Docs-only completion requires a complete Docs Sync Report with Decision: synced or Decision: unchanged.");
         }
         return;
     }
     if (candidate.flow === "validation-only") {
         const test = await artifactState(fs, input, "test-report.md", "test-report");
         const gate = await gateState(fs, input, "validation-adequacy");
-        if ((test.value !== "pass" && test.value !== "fail") || !gatePassed(gate)) {
+        if (!evidenceProducedAfterActiveDispatch(state, candidate.flow, "tester", "test-report.md", test.hash)
+            || (test.value !== "pass" && test.value !== "fail")
+            || !gatePassedForDispatch(state, candidate.flow, "tester", "validation-adequacy", gate)) {
             throw workflowError("WORKFLOW_COMPLETION_INVALID", "Validation-only completion requires a terminal Test Report and a passed Validation Adequacy Gate.");
         }
     }
 }
+function evidenceProducedAfterActiveDispatch(state, flow, targetRole, artifact, currentHash) {
+    const baseline = matchingEvidenceBaseline(state, flow, targetRole);
+    return Boolean(baseline && baseline.artifactHashes[artifact] !== currentHash);
+}
 function validateCandidateAgainstCurrent(current, candidate) {
     const errors = [];
     if (candidate.revision !== current.revision + 1)
@@ -632,26 +820,12 @@ function validateCandidateAgainstCurrent(current, candidate) {
     if (errors.length > 0)
         throw progressValidationError(errors);
 }
-function validateApprovedOverride(override, current, candidate, effectiveFlow, baseHistoryHash, violation) {
-    const proposal = candidate.proposal;
-    if (!override || override.status !== "approved")
-        throw workflowError("WORKFLOW_OVERRIDE_INVALID", "The supplied workflow override is not approved.");
-    if (override.baseRevision !== current.revision
-        || override.baseHistoryHash !== baseHistoryHash
-        || override.effectiveFlow !== effectiveFlow
-        || override.requestedFlow !== proposal.requestedFlow
-        || override.targetRole !== proposal.targetRole
-        || override.evidence !== proposal.evidence
-        || override.violatedRule !== violation
-        || override.authorizationText !== proposal.authorizationQuote
-        || proposal.violatedRule !== violation) {
-        throw workflowError("WORKFLOW_OVERRIDE_MISMATCH", "The approved override does not match this exact workflow transition.");
-    }
-}
-function createOverrideRequest(overrideId, current, candidate, effectiveFlow, baseHistoryHash, violation, quote, timestamp) {
+function createUserAuthorization(authorizationId, current, candidate, effectiveFlow, baseHistoryHash, violation, authorizationText, timestamp) {
     return {
-        id: overrideId,
-        status: "pending",
+        id: authorizationId,
+        status: "accepted",
+        role: "project-manager",
+        operation: "workflow-dispatch",
         baseRevision: current.revision,
         baseHistoryHash,
         requestedFlow: candidate.proposal.requestedFlow,
@@ -659,7 +833,7 @@ function createOverrideRequest(overrideId, current, candidate, effectiveFlow, ba
         targetRole: candidate.proposal.targetRole,
         evidence: candidate.proposal.evidence,
         violatedRule: violation,
-        proposedAuthorizationQuote: quote,
+        authorizationText,
         createdAt: timestamp
     };
 }
@@ -725,24 +899,43 @@ function normalizeState(value, taskSlug, timestamp) {
     const pendingDispatch = value.pendingDispatch === null
         ? null
         : isPendingDispatch(value.pendingDispatch) ? value.pendingDispatch : undefined;
-    const overrideRequests = Array.isArray(value.overrideRequests)
-        && value.overrideRequests.every(isOverrideRequest)
-        ? value.overrideRequests
-        : undefined;
-    if (pendingDispatch === undefined || overrideRequests === undefined) {
+    const userAuthorizations = Array.isArray(value.userAuthorizations)
+        && value.userAuthorizations.every(isUserAuthorization)
+        ? value.userAuthorizations
+        : value.userAuthorizations === undefined && Array.isArray(value.overrideRequests)
+            ? []
+            : undefined;
+    const activeDispatch = value.activeDispatch === undefined || value.activeDispatch === null
+        ? null
+        : normalizeDispatchEvidenceBaseline(value.activeDispatch);
+    const flowRun = value.flowRun === undefined || value.flowRun === null
+        ? null
+        : isFlowRun(value.flowRun) ? value.flowRun : undefined;
+    if (pendingDispatch === undefined || activeDispatch === undefined || flowRun === undefined || userAuthorizations === undefined) {
         return { ...emptyState(taskSlug, timestamp), warnings: ["Workflow control state has an unsupported shape."] };
     }
     return {
         version: 1,
         taskSlug,
         pendingDispatch,
-        overrideRequests,
+        activeDispatch,
+        flowRun,
+        userAuthorizations,
         warnings: [],
         updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : timestamp
     };
 }
 function emptyState(taskSlug, timestamp) {
-    return { version: 1, taskSlug, pendingDispatch: null, overrideRequests: [], warnings: [], updatedAt: timestamp };
+    return {
+        version: 1,
+        taskSlug,
+        pendingDispatch: null,
+        activeDispatch: null,
+        flowRun: null,
+        userAuthorizations: [],
+        warnings: [],
+        updatedAt: timestamp
+    };
 }
 function resolveEffectiveFlow(current, requested) {
     if (requested)
@@ -764,7 +957,10 @@ function progressPath(input) {
     return resolveRepoPath(input.taskRepoRoot, relativeProgressPath(input));
 }
 function historyHash(history) {
-    return createHash("sha256").update(JSON.stringify(history)).digest("hex");
+    return contentHash(JSON.stringify(history));
+}
+function contentHash(content) {
+    return createHash("sha256").update(content).digest("hex");
 }
 function field(content, name) {
     return rawField(content, name)?.toLowerCase();
@@ -824,11 +1020,13 @@ function isPendingDispatch(value) {
         && typeof value.createdAt === "string"
         && typeof value.updatedAt === "string";
 }
-function isOverrideRequest(value) {
+function isUserAuthorization(value) {
     if (!isRecord(value))
         return false;
     return typeof value.id === "string"
-        && ["pending", "approved", "rejected", "consumed"].includes(String(value.status))
+        && (value.status === "accepted" || value.status === "consumed")
+        && value.role === "project-manager"
+        && value.operation === "workflow-dispatch"
         && Number.isInteger(value.baseRevision)
         && typeof value.baseHistoryHash === "string"
         && (value.requestedFlow === undefined || Boolean(asFlow(typeof value.requestedFlow === "string" ? value.requestedFlow : undefined)))
@@ -836,12 +1034,50 @@ function isOverrideRequest(value) {
         && Boolean(asTargetRole(typeof value.targetRole === "string" ? value.targetRole : undefined))
         && typeof value.evidence === "string"
         && typeof value.violatedRule === "string"
-        && typeof value.proposedAuthorizationQuote === "string"
-        && (value.authorizationText === undefined || typeof value.authorizationText === "string")
+        && typeof value.authorizationText === "string"
         && typeof value.createdAt === "string"
-        && (value.decidedAt === undefined || typeof value.decidedAt === "string")
         && (value.consumedAt === undefined || typeof value.consumedAt === "string");
 }
+function normalizeDispatchEvidenceBaseline(value) {
+    if (!isRecord(value) || !isRecord(value.artifactHashes) || !isRecord(value.gateFingerprints))
+        return undefined;
+    const artifactHashes = value.artifactHashes;
+    const gateFingerprints = value.gateFingerprints;
+    if (!(Number.isInteger(value.sequence)
+        && Boolean(asFlow(typeof value.flow === "string" ? value.flow : undefined))
+        && Boolean(asTargetRole(typeof value.targetRole === "string" ? value.targetRole : undefined))
+        && WORKFLOW_EVIDENCE_GATES.every((gate) => typeof gateFingerprints[gate] === "string")
+        && typeof value.confirmedAt === "string"))
+        return undefined;
+    return {
+        sequence: Number(value.sequence),
+        flow: value.flow,
+        targetRole: value.targetRole,
+        artifactHashes: Object.fromEntries(WORKFLOW_EVIDENCE_ARTIFACTS.map((artifact) => [
+            artifact,
+            typeof artifactHashes[artifact] === "string" ? artifactHashes[artifact] : MISSING_EVIDENCE_HASH
+        ])),
+        gateFingerprints: Object.fromEntries(WORKFLOW_EVIDENCE_GATES.map((gate) => [
+            gate,
+            gateFingerprints[gate]
+        ])),
+        confirmedAt: value.confirmedAt
+    };
+}
+function isFlowRun(value) {
+    if (!isRecord(value))
+        return false;
+    const rootFlow = asFlow(typeof value.rootFlow === "string" ? value.rootFlow : undefined);
+    const activeBranch = value.activeBranch;
+    const resumedFromBranch = value.resumedFromBranch;
+    return Boolean(rootFlow)
+        && (activeBranch === undefined || activeBranch === "architect-debug" || activeBranch === "architecture-diagnosis")
+        && (resumedFromBranch === undefined
+            || resumedFromBranch === "architect-debug"
+            || resumedFromBranch === "architecture-diagnosis")
+        && Number.isInteger(value.startedAtSequence)
+        && Number(value.startedAtSequence) >= 1;
+}
 function findLastIndex(values, predicate) {
     for (let index = values.length - 1; index >= 0; index -= 1) {
         if (predicate(values[index]))