vibe-coding-master 0.8.3 → 0.8.4

package/README.md

@@ -195,7 +195,10 @@ Whenever Project Manager asks the user a question, it first uses
 `vcm-ask-user`. VCM records the wait and cancels any pending role dispatch in
 one state update. Stop Hook then ends the PM turn without route scanning. Only
 a new direct user message clears the wait, and the next role dispatch requires
-a fresh Workflow Review.
+a fresh Workflow Review. PM treats text emitted while a Round continues as
+intermediate output, not as delivered user communication. When the Round pauses
+or completes, its Round Final Reply restates the complete user-facing result or
+question without relying on earlier PM output.
 
 Typical flow:
 

package/dist/backend/server.js

@@ -243,7 +243,10 @@ export function createDefaultServerDeps(options = {}) {
     const runtime = createNodePtyTerminalRuntime({ fs });
     const registry = createSessionRegistry();
     const workflowControlService = createWorkflowControlService({ fs });
-    const artifactService = createArtifactService(fs, { workflowControlService });
+    const artifactService = createArtifactService(fs, {
+        workflowControlService,
+        isRoleMemoryTurn: (taskRepoRoot, role) => autoMemoryService.isRoleMemoryTurn(taskRepoRoot, role)
+    });
     const projectService = createProjectService({ fs, git, appSettings });
     const taskService = createTaskService({ fs, git, artifactService, projectService });
     const taskWorkflowService = createTaskWorkflowService({ fs });

package/dist/backend/services/artifact-service.js

@@ -219,6 +219,20 @@ export function createArtifactService(fs, deps = {}) {
                 if (validation.errors.length > 0) {
                     throw artifactRejected(input.kind, validation.errors);
                 }
+                if ((input.kind === "docs-update-report" || input.kind === "docs-sync-report")
+                    && deps.workflowControlService) {
+                    // Memory-owned documentation work is independent of PM's active dispatch.
+                    const memoryUpdate = input.kind === "docs-update-report"
+                        && await deps.isRoleMemoryTurn?.(input.repoRoot, input.role);
+                    if (!memoryUpdate) {
+                        await deps.workflowControlService.assertDocsArtifactAllowed({
+                            taskRepoRoot: input.repoRoot,
+                            stateRoot: input.stateRoot ?? ".ai/vcm",
+                            handoffDir: input.handoffDir,
+                            taskSlug: input.taskSlug
+                        }, input.kind, input.role);
+                    }
+                }
                 if (input.kind === "workflow-progress") {
                     if (input.mode !== "final") {
                         throw artifactRejected(input.kind, ["Workflow Progress must be submitted in final mode."]);

package/dist/backend/services/claude-hook-service.js

@@ -1,6 +1,7 @@
 import { isHarnessEngineerToolRoleName, isReviewerRoleName, isTranslatorToolRoleName, isVcmRoleName } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { readTranscriptTurnEvidence } from "./claude-transcript-reply.js";
+import { findPmUserQuestion } from "./pm-user-question.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { matchesRoleHookSession } from "./session-service.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
@@ -338,7 +339,10 @@ export function createClaudeHookService(deps) {
             }
             else {
                 const lastAssistantMessage = stringOrUndefined(input.event.last_assistant_message);
-                if (options.allowBlock && lastAssistantMessage && asksUserQuestion(lastAssistantMessage)) {
+                const question = options.allowBlock && lastAssistantMessage
+                    ? findPmUserQuestion(lastAssistantMessage)
+                    : undefined;
+                if (question) {
                     return {
                         ok: true,
                         eventName,
@@ -348,7 +352,7 @@ export function createClaudeHookService(deps) {
                         dispatchedCount: 0,
                         stopDecision: {
                             behavior: "block",
-                            reason: "You asked the user a question without registering the wait. Use vcm-ask-user with the exact question, then ask that question and stop. Do not advance or route the workflow."
+                            reason: `Possible unregistered user question: ${JSON.stringify(question.slice(0, 600))}. If you are asking the user, use vcm-ask-user with the exact question, then ask it and end the turn without advancing or routing the workflow. If this only reports or quotes another question, clarify that context and end normally; do not invent a user question or register a false wait.`
                         }
                     };
                 }
@@ -1003,14 +1007,3 @@ function isDirectUserPrompt(prompt) {
     const normalized = prompt.trim();
     return normalized.length > 0 && !/^\[VCM(?:\s|\])/i.test(normalized);
 }
-function asksUserQuestion(message) {
-    const withoutCodeBlocks = message.replace(/```[\s\S]*?```/g, "");
-    const lines = withoutCodeBlocks
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter(Boolean);
-    return lines.some((line) => /[?？]/.test(line)
-        || /^(?:please\s+(?:answer|choose|confirm|decide|provide|select|tell)|(?:can|could|do|does|is|are|should|will|would)\s+you\b)/i.test(line)
-        || /\b(?:please\s+(?:reply|respond|choose|confirm|decide|provide|select|tell|give)|i\s+need\s+your\s+(?:decision|choice|confirmation|answer)|let\s+me\s+know|your\s+(?:decision|choice|confirmation|answer)\s+is\s+required|waiting\s+for\s+your)\b/i.test(line)
-        || /(?:请(?:回答|回复|选择|确认|决定|提供|告知|给出|说明)|你(?:是否|能否|要不要|可否)|是否需要你|需要你(?:选择|确认|决定|提供|告知)|需要您的(?:选择|确认|决定|回复)|等待您的(?:选择|确认|决定|回复)|告诉我|告知我)/.test(line));
-}

package/dist/backend/services/pm-user-question.js

@@ -0,0 +1,62 @@
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+const markdown = unified().use(remarkParse).use(remarkGfm).freeze();
+// Match direct requests, not punctuation or requests mentioned inside a report.
+const DIRECT_REQUESTS = [
+    /^(?:can|could|do|did|are|have|should|will|would)\s+you\b/i,
+    /^(?:should|shall|may|can|could)\s+(?:i|we)\b/i,
+    /^(?:which|what|how|where|when|who)\b[^.!?]*\b(?:you|your|(?:should|shall|can|may)\s+(?:i|we))\b/i,
+    /^(?:which|what)\s+(?:option|approach|behavior|behaviour|choice)\b[^.!?]*\bshould\s+be\b/i,
+    /^(?:please\s+)?(?:answer|reply|respond|choose|confirm|decide|provide|select|tell\s+me|let\s+me\s+know|give\s+(?:me|your))\b/i,
+    /^i\s+need\s+your\s+(?:decision|choice|confirmation|answer|approval)\b/i,
+    /^your\s+(?:decision|choice|confirmation|answer|approval)\s+is\s+required\b/i,
+    /^(?:(?:i\s+am|i'm|we\s+are|we're)\s+)?waiting\s+for\s+your\s+(?:decision|choice|confirmation|answer|reply|approval)\b/i,
+    /^(?:请(?:您|你)?(?:回答|回复|选择|确认|决定|提供|告知|给出|说明)|[你您](?:是否|能否|要不要|可否|希望|想要)|是否需要[你您]|需要[你您](?:选择|确认|决定|提供|告知)|(?:需要|等待)[你您]的(?:选择|确认|决定|回复)|告诉我|告知我)/
+];
+export function findPmUserQuestion(message) {
+    return findQuestion(markdown.parse(message));
+}
+function findQuestion(node) {
+    // Quoted evidence and code are not PM addressing the user. Headings and table
+    // cells remain eligible: a real request does not stop being one when formatted.
+    if (["blockquote", "code", "html", "definition", "footnoteDefinition", "delete"].includes(node.type)) {
+        return undefined;
+    }
+    if (node.type === "paragraph" || node.type === "heading" || node.type === "tableCell") {
+        const prose = removeQuotedText(proseText(node)).replace(/\s+/g, " ");
+        for (const sentence of prose.split(/(?<=[.!?。！？；])\s*/)) {
+            const request = sentence.trim().replace(/^(?:(?:question(?:\s+for\s+you)?|your\s+decision|问题|请问)\s*[:：]\s*|before\s+(?:i|we)\s+(?:continue|proceed),?\s+)/i, "");
+            if (DIRECT_REQUESTS.some((pattern) => pattern.test(request))) {
+                return sentence.trim();
+            }
+        }
+        return undefined;
+    }
+    if ("children" in node) {
+        for (const child of node.children) {
+            const question = findQuestion(child);
+            if (question)
+                return question;
+        }
+    }
+    return undefined;
+}
+function proseText(node) {
+    if (node.type === "text")
+        return node.value;
+    if (node.type === "break")
+        return "\n";
+    if (["inlineCode", "html", "image", "imageReference", "delete", "footnoteReference"].includes(node.type))
+        return " ";
+    if (node.type === "link") {
+        const label = node.children.map(proseText).join("");
+        return label === node.url || /^(?:https?:\/\/|www\.)/i.test(label) ? " " : label;
+    }
+    if ("children" in node)
+        return node.children.map(proseText).join("");
+    return " ";
+}
+function removeQuotedText(text) {
+    return text.replace(/"[^"]*"|“[^”]*”|‘[^’]*’|「[^」]*」|『[^』]*』|(?<!\w)'[^']+'(?!\w)/g, " ");
+}

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

@@ -122,11 +122,11 @@ export function createWorkflowControlService(deps) {
                 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.`
+                        ? `Allowed next dispatches: ${verdict.allowedTransitions.join(", ")}. Recheck the flow, reuse an existing direct user instruction that explicitly authorizes this exact transition, or ask the user only when no such authorization exists.`
                         : verdict.blockedHint);
                 }
                 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.");
+                    throw workflowError("WORKFLOW_USER_AUTHORIZATION_INVALID", `User authorization must include the exact authorization text and exact violated rule: ${verdict.reason}`, "Copy an existing direct user instruction that explicitly authorizes this exact transition into Authorization Text. Ask the user only when no such authorization exists. Copy the rejection reason verbatim into Violated Rule.");
                 }
                 userAuthorization = createUserAuthorization(id(), current, candidate, effectiveFlow, baseHistoryHash, verdict.reason, authorizationText, now());
                 overrideAuthorizationId = userAuthorization.id;
@@ -318,6 +318,7 @@ export function createWorkflowControlService(deps) {
         requestUserInput,
         resolveUserInput,
         submitProgress,
+        assertDocsArtifactAllowed,
         assertRouteAuthorized,
         claimDispatch,
         releaseDispatch,
@@ -325,6 +326,37 @@ 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);
@@ -667,7 +699,7 @@ async function allowedCodeChange(fs, input, state, segment, resumedFromBranch) {
     const testerIndex = findLastIndex(segment, (entry) => entry.targetRole === "tester");
     if (resumedFromBranch && coderIndex < 0) {
         if (testerIndex < 0) {
-            return allowedPostImplementationArchitect(fs, input, state, "code-change", segment);
+            return allowedPostImplementationArchitect(fs, input, state, "code-change");
         }
         return allowedAfterTester(fs, input, state, "code-change", resumedFromBranch, {
             testerFailureFlow: "architect-debug",
@@ -676,17 +708,7 @@ async function allowedCodeChange(fs, input, state, segment, resumedFromBranch) {
         });
     }
     if (coderIndex < 0) {
-        const plan = await artifactState(fs, input, "architecture-plan.md", "architecture-plan");
-        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 (freshGateDecision(state, "code-change", "architect", "architecture-plan", gate) === "request_changes") {
-            return ["code-change/architect"];
-        }
-        return gatePassedForDispatch(state, "code-change", "architect", "architecture-plan", gate)
-            ? ["code-change/coder"]
-            : [];
+        return (await allowedFreshArchitecturePlan(fs, input, state)) ?? ["code-change/architect"];
     }
     if (testerIndex < coderIndex) {
         const coder = await artifactState(fs, input, "coder-completion.md", "coder-completion");
@@ -697,9 +719,8 @@ async function allowedCodeChange(fs, input, state, segment, resumedFromBranch) {
             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) {
-        return allowedPostImplementationArchitect(fs, input, state, "code-change", architectsAfterTester);
+    if (segment.some((entry, index) => index > testerIndex && entry.targetRole === "architect")) {
+        return allowedPostImplementationArchitect(fs, input, state, "code-change");
     }
     return allowedAfterTester(fs, input, state, "code-change", "coder", {
         testerFailureFlow: "architect-debug",
@@ -707,13 +728,15 @@ async function allowedCodeChange(fs, input, state, segment, resumedFromBranch) {
         successTarget: "code-change/architect"
     });
 }
-async function allowedArchitectureFollowup(fs, input, state, followupDispatchedAt) {
+async function allowedFreshArchitecturePlan(fs, input, state, gateMustPostdate) {
+    const baseline = matchingEvidenceBaseline(state, "code-change", "architect");
     const plan = await artifactState(fs, input, "architecture-plan.md", "architecture-plan");
-    if (!evidenceIsFresh(state, "code-change", "architect", "architecture-plan.md", plan.hash)
-        || plan.value !== "complete")
+    if (!baseline || baseline.artifactHashes["architecture-plan.md"] === plan.hash)
+        return undefined;
+    if (plan.value !== "complete")
         return ["code-change/architect"];
     const gate = await gateState(fs, input, "architecture-plan");
-    if (!gate || !followupDispatchedAt || gate.updatedAt <= followupDispatchedAt)
+    if (!gate || (gateMustPostdate && gate.updatedAt <= gateMustPostdate))
         return [];
     if (freshGateDecision(state, "code-change", "architect", "architecture-plan", gate) === "request_changes") {
         return ["code-change/architect"];
@@ -726,7 +749,7 @@ async function allowedArchitectFix(fs, input, state, segment, source, resumedFro
     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);
+        return allowedPostImplementationArchitect(fs, input, state, source);
     }
     if (architectIndex < 0)
         return [`${source}/architect`];
@@ -773,11 +796,13 @@ async function allowedArchitectFix(fs, input, state, segment, source, resumedFro
         successTarget: parentFlow ? `${parentFlow}/architect` : `${source}/architect`
     });
 }
-async function allowedPostImplementationArchitect(fs, input, state, flow, architectEntries) {
+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");
-    if (flow === "code-change" && architectEntries.length > 1 && acceptance.value === "needs-architect-follow-up") {
-        return allowedArchitectureFollowup(fs, input, state, architectEntries[1]?.confirmedAt);
+    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") {
@@ -824,13 +849,13 @@ async function allowedAfterTester(fs, input, state, currentFlow, codeSource, opt
     }
     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 (freshGateDecision(state, currentFlow, "tester", "validation-adequacy", validation) === "request_changes") {
         return [`${currentFlow}/tester`];
     }
+    if (test.value === "fail" && !test.hasUserApprovedCoverageGap) {
+        return options.testerFailureFlow ? [`${options.testerFailureFlow}/architect`] : [];
+    }
     if (!gatePassedForDispatch(state, currentFlow, "tester", "validation-adequacy", validation))
         return [];
     const codeDiff = await gateState(fs, input, "code-diff");
@@ -873,6 +898,10 @@ async function artifactState(fs, input, fileName, kind) {
     const infrastructure = kind === "test-report"
         ? /^Status:\s*(.+?)\s*$/mi.exec(readArtifactSectionContent(content, "Test Infrastructure") ?? "")?.[1]?.trim().toLowerCase()
         : undefined;
+    const hasUserApprovedCoverageGap = kind === "test-report"
+        && check.status === "ok"
+        && hasSubstantiveArtifactSection(readArtifactSectionContent(content, "Coverage Gaps"))
+        && hasSubstantiveArtifactSection(readArtifactSectionContent(content, "User Approval Evidence"));
     const disposition = kind === "architect-debug" || kind === "architecture-diagnosis"
         ? readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase()
         : undefined;
@@ -884,12 +913,17 @@ async function artifactState(fs, input, fileName, kind) {
         hash: await artifactFingerprint(fs, absolute, content),
         value,
         infrastructure,
+        hasUserApprovedCoverageGap,
         disposition,
         correctionOwner: correctionOwner === "none" || asTargetRole(correctionOwner)
             ? correctionOwner
             : undefined
     };
 }
+function hasSubstantiveArtifactSection(value) {
+    const normalized = value?.trim();
+    return Boolean(normalized && !/^(none|tbd)\.?$/i.test(normalized));
+}
 async function gateState(fs, input, gate) {
     const target = resolveRepoPath(input.taskRepoRoot, path.posix.join(".ai/vcm/gate-reviews", "index.json"));
     if (!(await fs.pathExists(target)))
@@ -1138,11 +1172,17 @@ async function validateCompleteDeliveryEvidence(fs, input, state, flow) {
         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.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"}.`);

package/dist/backend/templates/harness/project-manager-agent.js

@@ -18,6 +18,10 @@ ${renderRoleMemoryRules("project-manager")}
 
 ### User Communication
 
+- Assistant text emitted before a tool call or role dispatch while the current Round continues is not user communication. Do not use intermediate text to deliver status, findings, decisions, questions, or required actions to the user.
+- The user is informed only by PM's Round Final Reply when the Round pauses for user input or reaches a terminal result.
+- The Round Final Reply must be self-contained. Restate every result, blocker, decision, risk, and required user action needed to understand the current state. Never rely on earlier PM text in the same Round.
+- When asking the user a question, register it through \`vcm-ask-user\`, make the complete question and its necessary context the final reply, and end the turn.
 - Explain task status, blockers, role results, and decisions in user-facing language.
 - Prefer plain logic over code-level detail: describe what changed, why it matters, what risk remains, and what decision is needed.
 - Exclude irrelevant implementation detail, but retain the technical facts needed to explain the cause, evidence, impact, and unresolved state. Plain language means translating technical detail, not deleting it.
@@ -77,7 +81,7 @@ PM owns task flow selection. Every user request that asks VCM to perform deliver
 
 - After PM selects a flow, only its defined main path and explicitly allowed branches may be used.
 - The active flow may change only through a transition explicitly defined by that flow or an explicit user instruction.
-- Only the user may authorize any other flow change. Apply that authorization only to the exact change the user confirmed.
+- Only the user may authorize any other flow change. A direct user instruction that explicitly authorizes the exact change is the authorization. Reuse that instruction verbatim and do not ask the user to confirm it again.
 - A role request, role result, tool suggestion, requested next action, workload, task size, context size, difficulty, predicted risk, or PM discretion must not create an unlisted branch or change the active flow.
 - If a role requests an unlisted branch or role handoff, keep the current flow active and return the incomplete work to the current responsible role.
 - An incomplete, unrecognized, or non-standard role result returns to the same role for a valid result.
@@ -90,6 +94,8 @@ The main flow is:
 
 \`Architect Interview and planning -> architecture-plan Gate -> Coder implementation -> Tester validation -> validation-adequacy Gate -> code-diff Gate -> Architect docs sync -> Final Acceptance -> completed\`
 
+Require \`.ai/vcm/handoffs/docs-sync-report.md\` from the current Architect docs-sync dispatch. \`docs-update-report.md\` cannot replace it.
+
 PM may leave this path only through the allowed branches below.
 
 #### Allowed Branches
@@ -171,7 +177,7 @@ The shared path is:
 
 #### Successful Exit
 
-- For Architect Debug Flow, code-diff approval continues to \`Architect docs sync -> Final Acceptance\`.
+- For Architect Debug Flow, code-diff approval continues to \`Architect docs sync -> Final Acceptance\`. Require \`.ai/vcm/handoffs/docs-sync-report.md\` from this docs-sync dispatch with \`Decision: synced\` or \`unchanged\` and \`Correction Owner: none\`; handle \`blocked\` through Docs Sync Correction.
 - For Architect Debug Branch, code-diff approval returns to the recorded parent-flow resume point after the parent flow's validation and code-diff milestones. The branch does not run its own docs sync or Final Acceptance.
 
 Architect Debug Flow or Branch never routes implementation to Coder. Architect executes Architect Debug Mode; PM owns whether the current context is a Flow or Branch and where it continues afterward.
@@ -207,7 +213,7 @@ Architecture Diagnosis Mode must run before another Debug Mode fix or Coder disp
 
 - An analysis-only Architecture Diagnosis Flow completes from the diagnosis result.
 - An analysis-only Architecture Diagnosis Branch returns to the recorded parent-flow resume point.
-- A code-producing Architecture Diagnosis Flow continues after code-diff approval to \`Architect docs sync -> Final Acceptance\`.
+- A code-producing Architecture Diagnosis Flow continues after code-diff approval to \`Architect docs sync -> Final Acceptance\`. Require \`.ai/vcm/handoffs/docs-sync-report.md\` from this docs-sync dispatch with \`Decision: synced\` or \`unchanged\` and \`Correction Owner: none\`; handle \`blocked\` through Docs Sync Correction.
 - A code-producing Architecture Diagnosis Branch returns after code-diff approval to the recorded parent-flow resume point after the parent flow's validation and code-diff milestones. It does not run its own docs sync or Final Acceptance.
 
 After Tester Failure, PM should summarize:

package/dist/backend/templates/harness/vcm-workflow-review-skill.js

@@ -48,7 +48,13 @@ If VCM rejects the transition, remain in the current PM turn and choose a legal
 
 ## User Authorization
 
-Only the user's explicit instruction may authorize a rejected transition. Use \`vcm-ask-user\` with the exact authorization question, ask it, and wait. After the user authorizes the exact exception, resubmit the unchanged transition with:
+Only the user's explicit instruction may authorize a rejected transition.
+
+If the current user instruction already explicitly authorizes the exact rejected transition, reuse that instruction verbatim as \`Authorization Text\`. Do not ask the user to confirm it again.
+
+If no such instruction exists, use \`vcm-ask-user\` with the exact authorization question, ask it, and wait.
+
+Resubmit the unchanged transition with:
 
 \`\`\`text
 Authorization Text: <user's exact authorization>