vibe-coding-master 0.9.2 → 0.9.4

package/dist/backend/services/translation-worker-service.js

@@ -22,6 +22,7 @@ const MEMORY_TOTAL_LIMIT_BYTES = 80 * 1024;
 const MEMORY_INITIALIZED_MIN_FILES = 2;
 const MEMORY_FILE_NAMES = ["glossary.md", "style-guide.md", "project-context.md", "decisions.md"];
 const TRANSLATOR_ROLE = "translator";
+const QUEUE_HOOK_EVENTS = new Set(["UserPromptSubmit", "Stop", "StopFailure"]);
 const FILE_BROWSER_DEFAULT_LIMIT = 200;
 const FILE_BROWSER_MAX_LIMIT = 500;
 const FILE_BROWSER_SEARCH_MAX_DEPTH = 6;
@@ -99,6 +100,26 @@ const BINARY_LIKE_EXTENSIONS = new Set([
 export function createTranslationWorkerService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
     const createId = deps.id ?? (() => randomUUID());
+    const queueLocks = new Map();
+    // Every queue and index access happens in this process. Serializing them per
+    // repository keeps concurrent load-modify-save cycles from dropping each
+    // other's updates and keeps readers out of an in-flight rename.
+    function withQueueLock(repoRoot, operation) {
+        const key = path.resolve(repoRoot);
+        const previous = queueLocks.get(key) ?? Promise.resolve();
+        const result = previous.then(operation);
+        const settled = result.then(() => undefined, () => undefined);
+        queueLocks.set(key, settled);
+        void settled.then(() => {
+            if (queueLocks.get(key) === settled) {
+                queueLocks.delete(key);
+            }
+        });
+        return result;
+    }
+    function scheduleDispatch(repoRoot) {
+        void withQueueLock(repoRoot, () => dispatchNext(repoRoot)).catch(() => undefined);
+    }
     async function ensureLayout(repoRoot) {
         await Promise.all([
             deps.fs.ensureDir(resolveRepoPath(repoRoot, MEMORY_DIR)),
@@ -917,7 +938,7 @@ export function createTranslationWorkerService(deps) {
         queue.updatedAt = now();
         await saveQueue(repoRoot, queue);
     }
-    return {
+    const service = {
         async cleanupStartupRuntime(repoRoot) {
             await removeRepoPath(repoRoot, TRANSLATIONS_RUNTIME_DIR, true);
             await cleanupStartupFileIndex(repoRoot);
@@ -1006,7 +1027,7 @@ export function createTranslationWorkerService(deps) {
             const activeExisting = (await loadRuntimeFileJobs(repoRoot)).find((job) => fileTranslationReplacementKey(job) === replacementKey &&
                 isActiveFileTranslationJobStatus(job.status));
             if (activeExisting) {
-                void dispatchNext(repoRoot);
+                scheduleDispatch(repoRoot);
                 return activeExisting;
             }
             const timestamp = now();
@@ -1106,7 +1127,7 @@ export function createTranslationWorkerService(deps) {
                 lastUpdatedAt: timestamp
             });
             await deps.fs.writeText(resolveRepoPath(repoRoot, job.reportPath), `# Translation Report\n\nStatus: queued\nJob: ${jobId}\n`);
-            void dispatchNext(repoRoot);
+            scheduleDispatch(repoRoot);
             return job;
         },
         async createBootstrapRun(repoRoot, input) {
@@ -1165,7 +1186,7 @@ export function createTranslationWorkerService(deps) {
             index.runs = [run, ...index.runs];
             index.updatedAt = timestamp;
             await saveBootstrapIndex(repoRoot, index);
-            void dispatchNext(repoRoot);
+            scheduleDispatch(repoRoot);
             return run;
         },
         async createMemoryUpdate(repoRoot, input) {
@@ -1223,7 +1244,7 @@ export function createTranslationWorkerService(deps) {
                     "Delete or merge stale, duplicate, temporary, and task-local content."
                 ]
             });
-            void dispatchNext(repoRoot);
+            scheduleDispatch(repoRoot);
             return queueItem;
         },
         async readFileJobOutput(repoRoot, jobId) {
@@ -1297,7 +1318,7 @@ export function createTranslationWorkerService(deps) {
             });
             job.queueItemId = queueItem.id;
             if (!input.deferDispatch) {
-                void dispatchNext(repoRoot);
+                scheduleDispatch(repoRoot);
             }
             return job;
         },
@@ -1410,6 +1431,23 @@ export function createTranslationWorkerService(deps) {
             });
         }
     };
+    return {
+        ...service,
+        cleanupStartupRuntime: (repoRoot) => withQueueLock(repoRoot, () => service.cleanupStartupRuntime(repoRoot)),
+        getState: (repoRoot, options) => withQueueLock(repoRoot, () => service.getState(repoRoot, options)),
+        createFileJob: (repoRoot, input) => withQueueLock(repoRoot, () => service.createFileJob(repoRoot, input)),
+        readFileJobOutput: (repoRoot, jobId) => withQueueLock(repoRoot, () => service.readFileJobOutput(repoRoot, jobId)),
+        createBootstrapRun: (repoRoot, input) => withQueueLock(repoRoot, () => service.createBootstrapRun(repoRoot, input)),
+        createMemoryUpdate: (repoRoot, input) => withQueueLock(repoRoot, () => service.createMemoryUpdate(repoRoot, input)),
+        createConversationJob: (repoRoot, input) => withQueueLock(repoRoot, () => service.createConversationJob(repoRoot, input)),
+        validateConversationResult: (repoRoot, input) => withQueueLock(repoRoot, () => service.validateConversationResult(repoRoot, input)),
+        promoteFileJob: (repoRoot, jobId, targetPath) => withQueueLock(repoRoot, () => service.promoteFileJob(repoRoot, jobId, targetPath)),
+        // Only the events that touch the queue wait for the lock, so a SessionStart
+        // hook fired while a dispatch is starting the Translator never waits on it.
+        handleTranslatorHook: (repoRoot, eventName, taskSlug) => QUEUE_HOOK_EVENTS.has(eventName)
+            ? withQueueLock(repoRoot, () => service.handleTranslatorHook(repoRoot, eventName, taskSlug))
+            : service.handleTranslatorHook(repoRoot, eventName, taskSlug)
+    };
 }
 function requireTranslationTaskSlug(value) {
     const taskSlug = value?.trim();

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

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { VcmError } from "../errors.js";
+import { CODE_DIFF_DOCS_COVERAGE_ERROR_PREFIX } from "../../shared/types/gate-review.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";
@@ -147,7 +148,7 @@ export function createWorkflowControlService(deps) {
                     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.");
+                    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 a successful validation-adequacy Gate (and, in a Debug or Diagnosis Branch, its code-diff Gate).", "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;
@@ -401,7 +402,6 @@ export function createWorkflowControlService(deps) {
         resolveUserInput,
         runWhileNotAwaitingUser,
         submitProgress,
-        assertDocsArtifactAllowed: (input, kind, role) => withLock(statePath(input), () => assertDocsArtifactAllowed(input, kind, role)),
         assertRouteAuthorized: (input) => withLock(statePath(input), () => assertRouteAuthorized(input)),
         claimDispatch,
         releaseDispatch,
@@ -410,37 +410,6 @@ export function createWorkflowControlService(deps) {
         confirmDispatch,
         recoverTask
     };
-    async function assertDocsArtifactAllowed(input, kind, role) {
-        const state = await getState(input);
-        failOnStateWarnings(state);
-        const progress = await readProgress(deps.fs, input);
-        const active = state.activeDispatch;
-        if (progress.status !== "active" || !active || active.targetRole !== role)
-            return;
-        let expected;
-        if (progress.flow === "docs-only") {
-            expected = "docs-update-report";
-        }
-        else if (role === "architect" && (progress.flow === "code-change"
-            || progress.flow === "architect-debug" || progress.flow === "architecture-diagnosis")) {
-            const flow = progress.flow;
-            const run = resolveFlowRun(state.flowRun, progress);
-            const hadTester = progress.history.some((entry) => entry.sequence >= run.startedAtSequence
-                && entry.sequence < active.sequence && entry.targetRole === "tester");
-            if (!run.activeBranch && hadTester) {
-                const source = run.resumedFromBranch ?? (flow === "code-change" ? "coder" : flow);
-                const docsTarget = `${flow}/architect`;
-                const allowed = await allowedAfterTester(deps.fs, input, state, flow, source, {
-                    successTarget: docsTarget
-                });
-                if (allowed.includes(docsTarget))
-                    expected = "docs-sync-report";
-            }
-        }
-        if (expected && expected !== kind) {
-            throw workflowError("WORKFLOW_DOCS_ARTIFACT_MISMATCH", `${kind} was not written: the active ${progress.flow} dispatch #${active.sequence} requires ${path.posix.join(input.handoffDir, `${expected}.md`)}.`, `Submit --kind ${expected} through .ai/tools/vcm-artifact. The two documentation reports are not interchangeable.`);
-        }
-    }
     async function requestUserInput(input, question) {
         return withLock(statePath(input), async () => {
             const state = await getState(input);
@@ -730,15 +699,14 @@ async function canRouteUserApprovedFollowUp(fs, input, state, current, effective
         return false;
     }
     const validation = await gateState(fs, input, "validation-adequacy");
+    if (!gatePassedForDispatch(state, effectiveFlow, "tester", "validation-adequacy", validation))
+        return false;
     const codeDiff = await gateState(fs, input, "code-diff");
-    if (!gatePassedForDispatch(state, effectiveFlow, "tester", "validation-adequacy", validation)
-        || !gatePassedForDispatch(state, effectiveFlow, "tester", "code-diff", codeDiff))
+    if (!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;
+    // Both Gates passed and no Final Acceptance follow-up is pending: the flow
+    // is waiting for Final Acceptance, the checkpoint the follow-up returns to.
+    return allowedTransitions.length === 0;
 }
 async function getAllowedTransitions(fs, input, state, current) {
     if (current.status === "completed")
@@ -775,9 +743,6 @@ 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);
@@ -799,20 +764,10 @@ 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) {
-        if (testerIndex < 0) {
-            return allowedPostImplementationArchitect(fs, input, state, "code-change");
-        }
-        return allowedAfterTester(fs, input, state, "code-change", resumedFromBranch, {
-            testerFailureFlow: "architect-debug",
-            implementationFailureFlow: "architect-debug",
-            successTarget: "code-change/architect"
-        });
-    }
-    if (coderIndex < 0) {
+    if (coderIndex < 0 && !resumedFromBranch) {
         return (await allowedFreshArchitecturePlan(fs, input, state)) ?? ["code-change/architect"];
     }
-    if (testerIndex < coderIndex) {
+    if (coderIndex >= 0 && 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"];
@@ -821,14 +776,13 @@ async function allowedCodeChange(fs, input, state, segment, resumedFromBranch) {
             return ["architect-debug/architect"];
         return coder.value === "ready_for_review" ? ["code-change/tester"] : ["code-change/coder"];
     }
+    // An Architect dispatch after validation (a code-diff docs correction or a
+    // Final Acceptance follow-up, including the first dispatch after a branch
+    // returns) is reviewed by an incremental code-diff Gate.
     if (segment.some((entry, index) => index > testerIndex && entry.targetRole === "architect")) {
-        return allowedPostImplementationArchitect(fs, input, state, "code-change");
+        return allowedPostImplementationArchitect(fs, input, state, "code-change", "code-change");
     }
-    return allowedAfterTester(fs, input, state, "code-change", "coder", {
-        testerFailureFlow: "architect-debug",
-        implementationFailureFlow: "architect-debug",
-        successTarget: "code-change/architect"
-    });
+    return allowedAfterTester(fs, input, state, "code-change", resumedFromBranch && coderIndex < 0 ? resumedFromBranch : "coder", { testerFailureFlow: "architect-debug", acceptanceFlow: "code-change" });
 }
 async function allowedFreshArchitecturePlan(fs, input, state, gateMustPostdate) {
     const baseline = matchingEvidenceBaseline(state, "code-change", "architect");
@@ -850,19 +804,19 @@ async function allowedFreshArchitecturePlan(fs, input, state, gateMustPostdate)
 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);
-    }
+    // A branch that passes its own code-diff Gate has returned to its parent, so
+    // Final Acceptance and its follow-ups belong to the parent flow.
+    const acceptanceFlow = parentFlow ?? source;
     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)) {
+    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");
+    const artifactFresh = evidenceIsFresh(state, source, "architect", artifactName, artifact.hash);
+    if (testerIndex < 0 && !resumedFromBranch) {
+        if (!artifactFresh)
             return [`${source}/architect`];
-        }
         if (source === "architect-debug" && artifact.disposition === ARCHITECT_DEBUG_NORMAL_PLAN_DISPOSITION) {
             return ["code-change/architect"];
         }
@@ -875,73 +829,57 @@ async function allowedArchitectFix(fs, input, state, segment, source, resumedFro
         return artifact.complete ? [`${source}/tester`] : [`${source}/architect`];
     }
     if (architectIndex > testerIndex) {
-        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.disposition === "user clarification required") {
+        if (artifactFresh && artifact.disposition === "user clarification required") {
             return [`${source}/architect`];
         }
-        if (evidenceIsFresh(state, source, "architect", artifactName, artifact.hash) && artifact.complete) {
+        // A new fix needs validation; any other post-validation Architect change
+        // is reviewed by an incremental code-diff Gate.
+        if (artifactFresh && artifact.complete)
             return [`${source}/tester`];
-        }
-        const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
-        return evidenceIsFresh(state, source, "architect", "docs-sync-report.md", docs.hash)
-            && (docs.value === "synced" || docs.value === "unchanged")
-            ? []
-            : [`${source}/architect`];
+        return allowedPostImplementationArchitect(fs, input, state, source, acceptanceFlow);
     }
     return allowedAfterTester(fs, input, state, source, source, {
         testerFailureFlow: source === "architect-debug" ? "architecture-diagnosis" : undefined,
-        implementationFailureFlow: source,
-        successTarget: parentFlow ? `${parentFlow}/architect` : `${source}/architect`
+        acceptanceFlow
     });
 }
-async function allowedPostImplementationArchitect(fs, input, state, flow) {
-    const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
-    const acceptance = await artifactState(fs, input, "final-acceptance.md", "final-acceptance");
+async function allowedPostImplementationArchitect(fs, input, state, flow, acceptanceFlow) {
     if (flow === "code-change") {
         const planningTransition = await allowedFreshArchitecturePlan(fs, input, state, matchingEvidenceBaseline(state, "code-change", "architect")?.confirmedAt);
         if (planningTransition !== undefined)
             return planningTransition;
     }
-    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}`];
-        }
+    const codeDiff = await gateState(fs, input, "code-diff");
+    if (freshGateDecision(state, flow, "architect", "code-diff", codeDiff) === "request_changes") {
+        return codeDiffCorrectionTargets(codeDiff, flow);
+    }
+    if (gatePassedForDispatch(state, flow, "architect", "code-diff", codeDiff)) {
+        return finalAcceptanceFollowUpTargets(fs, input, state, flow, "architect", acceptanceFlow);
     }
     return [`${flow}/architect`];
 }
-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"];
+// Routes a code-diff Gate rejection: any implementation finding goes to the
+// flow's Architect fix path, docs-only findings (alone or with test-only ones)
+// to Architect first, and test-only findings to Tester.
+function codeDiffCorrectionTargets(codeDiff, flow) {
+    const scopes = (codeDiff?.findings ?? []).map((finding) => finding.scope);
+    if (scopes.length === 0 || scopes.some((scope) => scope !== "docs-only" && scope !== "test-only")) {
+        return [flow === "code-change" ? "architect-debug/architect" : `${flow}/architect`];
+    }
+    return scopes.includes("docs-only") ? [`${flow}/architect`] : [`${flow}/tester`];
+}
+// After a passed code-diff Gate, PM runs Final Acceptance. Only a Final
+// Acceptance produced after the latest dispatch can route a follow-up.
+async function finalAcceptanceFollowUpTargets(fs, input, state, flow, targetRole, acceptanceFlow) {
+    const acceptance = await artifactState(fs, input, "final-acceptance.md", "final-acceptance");
+    if (!acceptance.complete
+        || !evidenceProducedAfterActiveDispatch(state, flow, targetRole, "final-acceptance.md", acceptance.hash)) {
+        return [];
+    }
+    if (acceptance.value === "needs-coder-follow-up" && acceptanceFlow === "code-change")
+        return ["code-change/coder"];
+    if (acceptance.value === "needs-architect-follow-up")
+        return [`${acceptanceFlow}/architect`];
     return [];
 }
 async function allowedAfterTester(fs, input, state, currentFlow, codeSource, options) {
@@ -962,10 +900,14 @@ async function allowedAfterTester(fs, input, state, currentFlow, codeSource, opt
         return [];
     const codeDiff = await gateState(fs, input, "code-diff");
     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`] : [];
+        return codeDiffCorrectionTargets(codeDiff, currentFlow);
+    }
+    // The docs coverage check refused to start code-diff: Architect updates the
+    // owning docs, then PM requests code-diff again.
+    if (codeDiff?.status === "failed"
+        && codeDiff.error?.startsWith(CODE_DIFF_DOCS_COVERAGE_ERROR_PREFIX)
+        && gateRecordIsFresh(state, currentFlow, "tester", "code-diff", codeDiff)) {
+        return [`${currentFlow}/architect`];
     }
     if (!gatePassedForDispatch(state, currentFlow, "tester", "code-diff", codeDiff))
         return [];
@@ -973,7 +915,7 @@ async function allowedAfterTester(fs, input, state, currentFlow, codeSource, opt
     const reviewedSources = codeDiff?.codeDiffSources ?? (codeDiff?.codeDiffSource ? [codeDiff.codeDiffSource] : []);
     if (codeDiff?.status === "completed" && !reviewedSources.includes(gateCodeSource))
         return [];
-    return [options.successTarget];
+    return finalAcceptanceFollowUpTargets(fs, input, state, currentFlow, "tester", options.acceptanceFlow);
 }
 async function artifactState(fs, input, fileName, kind) {
     const relative = path.posix.join(input.handoffDir, fileName);
@@ -994,7 +936,7 @@ async function artifactState(fs, input, fileName, kind) {
         value = readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase();
     if (kind === "test-report")
         value = inline("Test Result");
-    if (kind === "docs-update-report" || kind === "docs-sync-report" || kind === "final-acceptance") {
+    if (kind === "docs-update-report" || kind === "final-acceptance") {
         value = readArtifactSectionContent(content, "Decision")?.trim().toLowerCase();
     }
     const infrastructure = kind === "test-report"
@@ -1007,19 +949,13 @@ 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: await artifactFingerprint(fs, absolute, content),
         value,
         infrastructure,
         hasUserApprovedCoverageGap,
-        disposition,
-        correctionOwner: correctionOwner === "none" || asTargetRole(correctionOwner)
-            ? correctionOwner
-            : undefined
+        disposition
     };
 }
 function hasSubstantiveArtifactSection(value) {
@@ -1213,7 +1149,7 @@ async function describeBlockedCheckpoint(fs, input, state, current) {
         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.";
+        return "The latest Tester result is waiting for its current validation-adequacy or code-diff Gate result, or, after both Gates pass, for Final Acceptance.";
     }
     if (baseline.targetRole === "architect") {
         return "The latest Architect dispatch has not produced the fresh workflow artifact required for its next step.";
@@ -1228,19 +1164,18 @@ async function validateCompletion(fs, input, state, candidate) {
         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") {
-        await validateCompleteDeliveryEvidence(fs, input, state, candidate.flow);
-        return;
-    }
-    if (candidate.flow === "architecture-diagnosis") {
+    // A Debug or Diagnosis Branch returns to its parent once it passes its own
+    // code-diff Gate, so the parent's Final Acceptance completes the run there.
+    const inBranch = flowRun.activeBranch === candidate.flow;
+    if (candidate.flow === "architecture-diagnosis" && !inBranch) {
         const diagnosis = await artifactState(fs, input, "architecture-diagnosis.md", "architecture-diagnosis");
         if (diagnosis.disposition === "analysis completed"
             && evidenceProducedAfterActiveDispatch(state, candidate.flow, "architect", "architecture-diagnosis.md", diagnosis.hash))
             return;
-        await validateCompleteDeliveryEvidence(fs, input, state, candidate.flow);
+    }
+    if (candidate.flow === "code-change" || candidate.flow === "architect-debug"
+        || candidate.flow === "architecture-diagnosis") {
+        await validateCompleteDeliveryEvidence(fs, input, state, { ...candidate, status: "active" }, candidate.flow, flowRun);
         return;
     }
     if (candidate.flow === "docs-only") {
@@ -1265,29 +1200,28 @@ async function validateCompletion(fs, input, state, candidate) {
         }
     }
 }
-async function validateCompleteDeliveryEvidence(fs, input, state, flow) {
+async function validateCompleteDeliveryEvidence(fs, input, state, current, flow, flowRun) {
     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 || baseline.artifactHashes["docs-sync-report.md"] === docs.hash) {
-        const update = await artifactState(fs, input, "docs-update-report.md", "docs-update-report");
-        const wrongReport = update.hash !== MISSING_EVIDENCE_HASH
-            && baseline.artifactHashes["docs-update-report.md"] !== update.hash;
-        const reason = !docs.complete
-            ? "Docs Sync Report is missing or malformed for this complete delivery flow."
-            : "Docs Sync Report was not produced after the final Architect dispatch.";
-        throw workflowError("WORKFLOW_COMPLETION_INVALID", `${reason} Required file: ${path.posix.join(input.handoffDir, "docs-sync-report.md")}, produced after dispatch #${baseline.sequence} (${baseline.confirmedAt}).`
-            + (wrongReport
-                ? ` ${path.posix.join(input.handoffDir, "docs-update-report.md")} was updated after this dispatch, but cannot replace docs-sync-report.md.`
-                : ""), "Ask Architect to submit --kind docs-sync-report through .ai/tools/vcm-artifact with Decision: synced or unchanged and Correction Owner: none. Report blocked with its correction owner when synchronization is incomplete.");
-    }
-    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 validated = current.history.some((entry) => entry.sequence >= flowRun.startedAtSequence
+        && entry.sequence < baseline.sequence && entry.targetRole === "tester");
+    if (baseline.targetRole !== "tester" && !(baseline.targetRole === "architect" && validated)) {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", `The latest ${flow} dispatch is to ${baseline.targetRole}. Complete Tester validation and the validation-adequacy and code-diff Gates before completing the flow.`);
+    }
+    if (baseline.targetRole === "tester") {
+        const test = await artifactState(fs, input, "test-report.md", "test-report");
+        const validation = await gateState(fs, input, "validation-adequacy");
+        if (!evidenceProducedAfterActiveDispatch(state, flow, "tester", "test-report.md", test.hash)
+            || !(test.value === "pass" || (test.value === "fail" && test.hasUserApprovedCoverageGap))
+            || !gatePassedForDispatch(state, flow, "tester", "validation-adequacy", validation)) {
+            throw workflowError("WORKFLOW_COMPLETION_INVALID", `The latest Tester dispatch #${baseline.sequence} has no passing Test Report with a passed validation-adequacy Gate.`);
+        }
+    }
+    const codeDiff = await gateState(fs, input, "code-diff");
+    if (!gatePassedForDispatch(state, flow, baseline.targetRole, "code-diff", codeDiff)) {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", `The code-diff Gate has not approved the work since the latest ${baseline.targetRole} dispatch #${baseline.sequence}.`, "Run .ai/tools/request-gate-review --gate code-diff for the current changes, then complete Final Acceptance.");
     }
     const acceptance = await artifactState(fs, input, "final-acceptance.md", "final-acceptance");
     if (!acceptance.complete) {
@@ -1297,7 +1231,11 @@ async function validateCompleteDeliveryEvidence(fs, input, state, flow) {
         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.");
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", `Final Acceptance was not produced after the latest dispatch #${baseline.sequence}.`);
+    }
+    const pending = await getAllowedTransitions(fs, input, state, current);
+    if (pending.length > 0) {
+        throw workflowError("WORKFLOW_COMPLETION_INVALID", `The ${flow} flow still requires a dispatch before completion: ${pending.join(", ")}.`);
     }
 }
 function evidenceProducedAfterActiveDispatch(state, flow, targetRole, artifact, currentHash) {

package/dist/backend/templates/handoff.js

@@ -1,4 +1,4 @@
-import { ARCHITECT_DEBUG_DISPOSITIONS, ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, DOCS_UPDATE_COMMIT_RULE, DOCS_SYNC_CORRECTION_OWNERS, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
+import { ARCHITECT_DEBUG_DISPOSITIONS, ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, DOCS_UPDATE_COMMIT_RULE, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
 const CURRENT_HANDOFF_NOTICE = "<!-- VCM current handoff: replace this file with one complete, self-contained snapshot of the current result. Restate all still-relevant evidence; do not refer to a prior revision, route message, Session, or transcript as evidence. -->";
 export function renderArchitectureBriefTemplate(taskSlug) {
     return `# Architecture Brief: ${taskSlug}
@@ -483,52 +483,6 @@ TBD
 ${renderArtifactOptions(ARCHITECTURE_DIAGNOSIS_DISPOSITIONS)}
 `;
 }
-export function renderDocsSyncReportTemplate(taskSlug) {
-    return `# Docs Sync Report: ${taskSlug}
-
-${CURRENT_HANDOFF_NOTICE}
-
-## Summary
-
-TBD
-
-## Architecture Drift Check
-
-TBD
-
-## Docs Updated
-
-TBD
-
-## Docs Reviewed And Left Unchanged
-
-TBD
-
-## Public Contract / Module Boundary Notes
-
-TBD
-
-## Remaining Documentation Risks
-
-TBD
-
-## Known Issues Disposition
-
-TBD
-
-## Correction Owner
-
-${renderArtifactOptions(DOCS_SYNC_CORRECTION_OWNERS)}
-
-## Correction Evidence
-
-${STRICT_NONE_VALUE}
-
-## Decision
-
-${renderArtifactOptions(DOCS_REPORT_DECISIONS)}
-`;
-}
 export function renderDocsUpdateReportTemplate(taskSlug, assignmentId = "docs-only") {
     return `# Docs Update Report: ${taskSlug}
 
@@ -639,7 +593,7 @@ TBD
 
 TBD
 
-## Review And Docs Sync
+## Review And Documentation
 
 TBD