vibe-coding-master 0.7.43 → 0.7.44

package/dist/backend/services/harness-feedback-service.js

@@ -4,7 +4,6 @@ import { checkMarkdownArtifact, readArtifactSectionValue } from "../../shared/va
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { VcmError } from "../errors.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
-import { getRetrospectiveReportErrors } from "./artifact-service.js";
 const FEEDBACK_ROOT = ".ai/vcm/harness-feedback";
 const PENDING_DIR = `${FEEDBACK_ROOT}/pending`;
 const TASK_RETROSPECTIVE_DIR = `${FEEDBACK_ROOT}/task-retrospectives`;
@@ -143,7 +142,7 @@ export function createHarnessFeedbackService(deps) {
             ]
             : ["Report is empty."];
         const reportReady = reportErrors.length === 0;
-        if (!reportReady || (marker.memoryRunId && !input.memoryReviewSucceeded)) {
+        if (!reportReady || (marker.memoryRunId && input.memoryReviewStatus === "failed")) {
             await persistTaskRetrospectiveMarker(repoRoot, {
                 ...marker,
                 status: "failed",
@@ -155,6 +154,41 @@ export function createHarnessFeedbackService(deps) {
             });
             return true;
         }
+        if (marker.memoryRunId && input.memoryReviewStatus === "documenting") {
+            await persistTaskRetrospectiveMarker(repoRoot, {
+                ...marker,
+                status: "waiting-docs",
+                updatedAt: timestamp
+            });
+            return true;
+        }
+        await completeTaskRetrospective(repoRoot, marker);
+        return true;
+    }
+    async function completeWaitingTaskRetrospective(repoRoot, taskSlug, memoryStatus) {
+        const marker = await loadTaskRetrospectiveMarker(repoRoot, taskSlug);
+        if (!marker || marker.status !== "waiting-docs") {
+            return false;
+        }
+        if (memoryStatus === "documenting") {
+            return true;
+        }
+        if (memoryStatus === "failed") {
+            const timestamp = now();
+            await persistTaskRetrospectiveMarker(repoRoot, {
+                ...marker,
+                status: "failed",
+                failedAt: timestamp,
+                updatedAt: timestamp,
+                error: "Task Harness Retrospective durable-document assignment failed."
+            });
+            return true;
+        }
+        await completeTaskRetrospective(repoRoot, marker);
+        return true;
+    }
+    async function completeTaskRetrospective(repoRoot, marker) {
+        const timestamp = now();
         try {
             await removeProcessedFeedback(repoRoot, marker.pendingFeedbackPaths ?? []);
         }
@@ -166,7 +200,7 @@ export function createHarnessFeedbackService(deps) {
                 updatedAt: timestamp,
                 error: `VCM could not remove processed Harness Feedback: ${errorMessage(error)}`
             });
-            return true;
+            return;
         }
         await persistTaskRetrospectiveMarker(repoRoot, {
             ...marker,
@@ -174,7 +208,6 @@ export function createHarnessFeedbackService(deps) {
             completedAt: timestamp,
             updatedAt: timestamp
         });
-        return true;
     }
     async function assertHarnessEngineerAvailable(_repoRoot) {
         return undefined;
@@ -285,6 +318,16 @@ export function createHarnessFeedbackService(deps) {
                     `Current memory snapshot: ${memoryReview.currentMemoryPath}`,
                     "Active memory files:",
                     ...memoryReview.activeMemoryPaths.map((memoryPath) => `- ${memoryPath}`),
+                    "Proposal candidates:",
+                    ...(memoryReview.proposalCandidates.length > 0
+                        ? memoryReview.proposalCandidates.map((candidate) => [
+                            candidate.id,
+                            `source=${candidate.source}`,
+                            `operation=${candidate.operation}`,
+                            `target=${candidate.target}`,
+                            `entry=${candidate.content ?? candidate.existing ?? "none"}`
+                        ].join(" | "))
+                        : ["none"]),
                     ...(memoryReview.planningCandidatePath
                         ? [`Architect planning-session candidate: ${memoryReview.planningCandidatePath}`]
                         : []),
@@ -292,88 +335,30 @@ export function createHarnessFeedbackService(deps) {
                     "Review every memory candidate against final task evidence while performing this retrospective.",
                     "The snapshot files contain only the matching pre-review <VCM-memory> block content.",
                     "Before evaluating proposals, review every substantive entry in every current memory snapshot against current code, documentation, and final task evidence.",
-                    "For each existing entry, decide retain, update, remove, or move-to-durable-doc. Record the decision reason, the impact of removing it, and whether memory or a durable document is the correct source.",
-                    "Complete this full existing-memory review even when every proposal says no-change.",
-                    "Then evaluate every proposal item independently. Do not accept or reject a whole role draft as one decision.",
-                    "For every Add or Update candidate, independently explain why the memory is necessary, what fails if it is absent, and why memory or a durable document is the correct destination.",
-                    "Do not copy the proposer rationale as the review. Verify it against current code, durable documentation, and final task evidence.",
-                    "Keep only verified, durable, reusable project knowledge. Merge duplicates and keep role-specific knowledge in the matching role file.",
-                    "Do not record task narrative, temporary state, unverified conclusions, or Harness rules in memory.",
-                    "Final content must be one exact line written to the selected active <VCM-memory> block. Use none when the decision does not keep memory.",
-                    "For keep-in-memory use Durable doc disposition: memory. For keep-memory-reference use memory-reference. For move-to-durable-doc use durable-doc.",
-                    "Existing-memory Target must be shared or the exact role name. Decision must be retain, update, remove, or move-to-durable-doc.",
-                    "Durable doc disposition must be memory, durable-doc, or memory-reference. Use Durable doc path: none with memory and an actual path with the other dispositions.",
-                    "Do not keep full content in memory when durable-doc is correct. Use memory-reference only when an ongoing role needs the document pointer.",
-                    "Use none as the complete Existing Memory Decisions body only when no substantive existing memory entry exists.",
-                    "Apply the reviewed result directly to the <VCM-memory> blocks in the listed active memory files. Do not change any content outside those blocks.",
-                    "If memory changes, commit only the changed active memory files before ending the turn. Use commit message: chore: update VCM memory. If memory is unchanged, do not create a commit.",
-                    "Use this exact block in the retrospective report and replace each option or placeholder with one allowed value or a concise summary:",
+                    "Evaluate each proposal independently. Keep only verified, durable, reusable project knowledge; do not keep task narrative, temporary state, unverified conclusions, or Harness rules in memory.",
+                    "For every existing entry and proposal, record why the decision is necessary, the impact if the knowledge is absent, the evidence checked, and whether a durable document is the correct source.",
+                    "When the decision is move-to-durable-doc, remove the entry from memory now and add one durableDocAssignment. Do not wait for the durable document update before removing memory.",
+                    "Apply the reviewed result directly to the listed <VCM-memory> blocks. Do not change content outside those blocks.",
+                    "If memory changes, commit only the changed active memory files with message [VCM Harness] Update VCM memory. If memory is unchanged, do not create a commit.",
+                    `Write the complete machine-readable review to: ${memoryReview.reviewResultPath}`,
+                    "The JSON root must be: {\"version\":1,\"runId\":\"<assigned run id>\",\"memoryCommit\":\"<full commit or none>\",\"decisions\":[],\"durableDocAssignments\":[]}.",
+                    "Each decision must contain itemId, source (existing|proposal), target, entry, decision, reason, impactIfAbsent, evidence (non-empty array), finalContent, and durableDocPath.",
+                    "Existing decisions use retain|update|remove|move-to-durable-doc. Add or Update proposal decisions use keep-in-memory|keep-memory-reference|move-to-durable-doc|reject; Remove proposal decisions use remove|retain. Proposal itemId must equal the assigned candidate ID.",
+                    "Each durableDocAssignment must contain sourceMemoryPath, sourceEntry, targetPath, content, reason, and evidence (non-empty array). Use a project-relative Markdown target outside .ai/vcm.",
+                    "In the retrospective report, include only this memory summary:",
                     "",
                     "## Memory Review",
-                    "Existing memory reviewed: complete",
-                    "",
-                    "### Proposal Decisions",
-                    ...(memoryReview.proposalCandidates.length > 0
-                        ? memoryReview.proposalCandidates.flatMap(renderMemoryProposalDecisionTemplate)
-                        : ["none"]),
-                    "",
-                    "### Existing Memory Decisions",
-                    "#### Item 1",
-                    "Target: shared",
-                    "Existing: <exact existing memory entry>",
-                    "Decision: retain",
-                    "Reason: <why this decision is correct>",
-                    "Impact if removed: <specific future role or task failure>",
-                    "Durable doc disposition: memory",
-                    "Durable doc path: none",
-                    "Evidence: <current code, durable documentation, or final task evidence>",
-                    "",
-                    "### Existing Memory Changes",
-                    "- retained: <summary or none>",
-                    "- updated: <summary or none>",
-                    "- removed: <summary or none>",
-                    "",
-                    "Reviewed memory set: complete"
+                    "Memory commit: <full commit or none>",
+                    `Review result: ${memoryReview.reviewResultPath}`,
+                    "Durable document assignments: <count>"
                 ]
                 : []),
             "",
             `Write the analysis to Result Path: ${resolveRepoPath(repoRoot, analysisPath)}`,
-            `Submit with: .ai/tools/vcm-artifact retrospective-report --file <candidate> --path ${analysisPath} --mode final`,
-            "End your turn after VCM accepts the result."
+            "Write the report directly to that path. Do not use vcm-artifact.",
+            "End your turn after the report is complete."
         ].join("\n");
     }
-    function renderMemoryProposalDecisionTemplate(candidate) {
-        if (candidate.operation === "remove") {
-            return [
-                `#### Candidate ${candidate.id}`,
-                `Source: ${candidate.source}`,
-                "Operation: remove",
-                `Target: ${candidate.target}`,
-                `Existing: ${candidate.existing}`,
-                "Decision: remove|retain",
-                "Reason: <why the proposed removal should be applied or rejected>",
-                "Evidence checked: <current code, durable documentation, or final task evidence>",
-                ""
-            ];
-        }
-        return [
-            `#### Candidate ${candidate.id}`,
-            `Source: ${candidate.source}`,
-            `Operation: ${candidate.operation}`,
-            `Target: ${candidate.target}`,
-            `Candidate: ${candidate.content}`,
-            "Decision: keep-in-memory|keep-memory-reference|move-to-durable-doc|reject",
-            "Final target: shared|project-manager|architect|coder|tester|reviewer|harness-engineer|none",
-            "Why memory is necessary: <independent reason, or why it is not necessary>",
-            "Impact if absent: <specific impact, or why no durable impact exists>",
-            "Durable doc disposition: memory|durable-doc|memory-reference",
-            "Durable doc analysis: <why this destination is correct>",
-            "Durable doc path: <none or a project-relative durable doc path>",
-            "Evidence checked: <current code, durable documentation, or final task evidence>",
-            "Final content: <exact one-line reviewed-memory content or none>",
-            ""
-        ];
-    }
     function buildPendingFeedbackPrompt(repoRoot, feedbackPath) {
         return [
             "[VCM Harness Feedback]",
@@ -431,6 +416,7 @@ export function createHarnessFeedbackService(deps) {
         sendPendingFeedback,
         startTaskRetrospective,
         handleTaskRetrospectiveHook,
+        completeWaitingTaskRetrospective,
         assertHarnessEngineerAvailable
     };
 }
@@ -495,6 +481,18 @@ function assertPendingFeedbackPath(feedbackPath) {
         throw new Error(`Invalid assigned Harness Feedback path: ${feedbackPath}.`);
     }
 }
+function getRetrospectiveReportErrors(content) {
+    const errors = [];
+    if (!/^# Task Harness Retrospective(?::\s*.+)?\s*$/m.test(content)) {
+        errors.push("Retrospective report requires '# Task Harness Retrospective: <task>'.");
+    }
+    for (const heading of ["Findings", "Feedback Dispositions", "Recommended Harness Changes", "VCM Issue Drafts"]) {
+        if (!new RegExp(`^## ${heading}\\s*$`, "m").test(content)) {
+            errors.push(`Missing required section: ${heading}.`);
+        }
+    }
+    return errors;
+}
 function parseSimpleMetadata(content) {
     const result = {};
     for (const line of content.split(/\r?\n/).slice(0, 80)) {

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

@@ -25,10 +25,12 @@ import { renderVcmLongRunningValidationSkillRules } from "../templates/harness/v
 import { renderVcmProposeMemorySkillRules } from "../templates/harness/vcm-propose-memory-skill.js";
 import { renderVcmReportHarnessIssueSkillRules } from "../templates/harness/vcm-report-harness-issue-skill.js";
 import { renderVcmRouteMessageSkillRules } from "../templates/harness/vcm-route-message-skill.js";
+import { renderAskUserTool, renderVcmAskUserSkillRules } from "../templates/harness/vcm-ask-user-skill.js";
 import { renderUpdateTaskStateTool, renderVcmTaskStateSkillRules } from "../templates/harness/vcm-task-state-skill.js";
 import { renderVcmWorkflowReviewSkillRules } from "../templates/harness/vcm-workflow-review-skill.js";
 import { renderCheckScaffoldLedgerTool } from "../templates/harness/check-scaffold-ledger.js";
 import { renderRequestArchitectRestartTool, renderRestartArchitectSkillRules } from "../templates/harness/restart-architect-skill.js";
+import { renderResolveDurableDocAssignmentTool } from "../templates/harness/resolve-durable-doc-assignment.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { VcmError } from "../errors.js";
 import { bumpHarnessRevision, readHarnessRevisionState } from "./harness-revision.js";
@@ -138,6 +140,14 @@ const HARNESS_FILES = [
         ownership: "whole-file",
         renderRules: renderVcmRouteMessageSkillRules
     },
+    {
+        kind: "skill-vcm-ask-user",
+        path: ".claude/skills/vcm-ask-user/SKILL.md",
+        title: "VCM Ask User Skill",
+        frontmatter: renderSkillFrontmatter("vcm-ask-user", "Use whenever project-manager asks the user a question and must pause the workflow."),
+        ownership: "whole-file",
+        renderRules: renderVcmAskUserSkillRules
+    },
     {
         kind: "skill-vcm-task-state",
         path: ".claude/skills/vcm-task-state/SKILL.md",
@@ -257,6 +267,13 @@ const HARNESS_FILES = [
         ownership: "raw-file",
         renderRules: renderRequestGateReviewTool
     },
+    {
+        kind: "tool-vcm-ask-user",
+        path: ".ai/tools/vcm-ask-user",
+        title: "VCM Ask User Tool",
+        ownership: "raw-file",
+        renderRules: renderAskUserTool
+    },
     {
         kind: "tool-update-task-state",
         path: ".ai/tools/update-task-state",
@@ -278,6 +295,13 @@ const HARNESS_FILES = [
         ownership: "raw-file",
         renderRules: renderRequestArchitectRestartTool
     },
+    {
+        kind: "tool-resolve-durable-doc-assignment",
+        path: ".ai/tools/resolve-durable-doc-assignment",
+        title: "Resolve Durable Documentation Assignment Tool",
+        ownership: "raw-file",
+        renderRules: renderResolveDurableDocAssignmentTool
+    },
     {
         kind: "agent-project-manager",
         path: ".claude/agents/project-manager.md",
@@ -360,7 +384,7 @@ export function createHarnessService(deps) {
             let harnessCommit;
             if (nextContent !== currentContent) {
                 await bumpHarnessRevision(deps.fs, repoRoot, now());
-                harnessCommit = (await commitHarnessVisibleChanges(deps.git, repoRoot, "chore(vcm-harness): update harness file")).harnessCommit;
+                harnessCommit = (await commitHarnessVisibleChanges(deps.git, repoRoot, "[VCM Harness] Update harness file")).harnessCommit;
             }
             const file = await readHarnessFileContent(deps.fs, repoRoot, definition.path);
             const [analyses, codeIntelligence] = await Promise.all([
@@ -384,7 +408,7 @@ export function createHarnessService(deps) {
                 if (result.changedFiles.length > 0) {
                     await bumpHarnessRevision(deps.fs, repoRoot, now());
                 }
-                const committed = await commitHarnessVisibleChanges(deps.git, repoRoot, "chore(vcm-harness): update fixed harness");
+                const committed = await commitHarnessVisibleChanges(deps.git, repoRoot, "[VCM Harness] Update fixed harness");
                 return {
                     ...result,
                     changedFiles: committed.changedFiles.length > 0 ? committed.changedFiles : result.changedFiles,
@@ -408,7 +432,7 @@ export function createHarnessService(deps) {
             if (changedFiles.length > 0) {
                 await bumpHarnessRevision(deps.fs, repoRoot, now());
             }
-            const committed = await commitHarnessVisibleChanges(deps.git, repoRoot, "chore(vcm-harness): update fixed harness");
+            const committed = await commitHarnessVisibleChanges(deps.git, repoRoot, "[VCM Harness] Update fixed harness");
             return {
                 version: VCM_HARNESS_VERSION,
                 changedFiles: committed.changedFiles.length > 0 ? committed.changedFiles : changedFiles,

package/dist/backend/services/runtime-coordinator-service.js

@@ -66,7 +66,8 @@ export function createRuntimeCoordinatorService(deps) {
             else {
                 await deps.translationService.stopTask(taskRepoRoot, activeTask.taskSlug).catch(() => undefined);
             }
-            await reconcileAutoMemory(repoRoot, activeTask, preferences.autoTaskHarnessReviewEnabled ? "auto" : undefined);
+            const memoryState = await reconcileAutoMemory(repoRoot, activeTask, preferences.autoTaskHarnessReviewEnabled ? "auto" : undefined);
+            await deps.harnessFeedbackService.completeWaitingTaskRetrospective(repoRoot, activeTask.taskSlug, memoryState.status);
             const memoryReadiness = await getTaskRetrospectiveMemoryReadiness(repoRoot, activeTask);
             if ((preferences.autoTaskHarnessReviewEnabled || memoryReadiness.trigger) && memoryReadiness.ready) {
                 await maybeStartTaskHarnessRetrospective(repoRoot, activeTask, memoryReadiness.trigger ?? "auto");

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

@@ -59,6 +59,7 @@ function degradedArtifactSummary(handoffDir) {
             architectDebugPath: `${handoffDir}/architect-debug.md`,
             architectureDiagnosisPath: `${handoffDir}/architecture-diagnosis.md`,
             testReportPath: `${handoffDir}/test-report.md`,
+            docsUpdateReportPath: `${handoffDir}/docs-update-report.md`,
             docsSyncReportPath: `${handoffDir}/docs-sync-report.md`,
             workflowProgressPath: `${handoffDir}/workflow-progress.md`,
             finalAcceptancePath: `${handoffDir}/final-acceptance.md`

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

@@ -214,14 +214,23 @@ export function createTranslationWorkerService(deps) {
             }
             const session = await ensureTranslatorSession(repoRoot, next.targetLanguage, next.taskSlug);
             await submitTerminalInput(deps.runtime, session.id, batch?.prompt ?? await buildQueuePrompt(repoRoot, next));
+            const latestQueue = await loadQueue(repoRoot);
+            if (latestQueue.activeItemId !== next.id) {
+                return;
+            }
+            const dispatchedItems = latestQueue.items.filter((item) => item.status === "dispatching" &&
+                (batch ? item.batchId === batch.items[0]?.batchId : item.id === next.id));
+            if (dispatchedItems.length === 0) {
+                return;
+            }
             const dispatchedAt = now();
-            for (const item of batch?.items ?? [next]) {
+            for (const item of dispatchedItems) {
                 item.status = "running";
                 item.updatedAt = dispatchedAt;
             }
-            queue.updatedAt = dispatchedAt;
-            await saveQueue(repoRoot, queue);
-            await Promise.all((batch?.items ?? [next]).map((item) => syncJobStatus(repoRoot, item)));
+            latestQueue.updatedAt = dispatchedAt;
+            await saveQueue(repoRoot, latestQueue);
+            await Promise.all(dispatchedItems.map((item) => syncJobStatus(repoRoot, item)));
         }
         catch (error) {
             const failedItems = queue.activeItemId === next.id
@@ -438,6 +447,12 @@ export function createTranslationWorkerService(deps) {
             await validateActiveQueueItem(repoRoot);
             return true;
         }
+        // `dispatching` covers the interval between writing the prompt and the
+        // Translator's UserPromptSubmit hook. The role session is legitimately idle
+        // during that interval, so only an actual result can reconcile the item.
+        if (active.status === "dispatching") {
+            return false;
+        }
         if (await translatorSessionSettled(repoRoot, active.taskSlug)) {
             await validateActiveQueueItem(repoRoot);
             return true;

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

@@ -10,6 +10,15 @@ 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>";
+const DOCS_ONLY_ROLE_TRANSITIONS = [
+    "docs-only/architect",
+    "docs-only/coder",
+    "docs-only/tester"
+];
+const DOCS_ONLY_EXIT_TRANSITIONS = [
+    "code-change/architect",
+    "validation-only/tester"
+];
 export function createWorkflowControlService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
     const id = deps.id ?? (() => `wfauth_${randomUUID()}`);
@@ -35,6 +44,7 @@ export function createWorkflowControlService(deps) {
         return withLock(statePath(input), async () => {
             const state = await getState(input);
             failOnStateWarnings(state);
+            failWhileAwaitingUser(state);
             if (state.pendingDispatch) {
                 throw workflowError("WORKFLOW_DISPATCH_PENDING", `A ${state.pendingDispatch.targetRole} dispatch is already ${state.pendingDispatch.status}.`, "Complete or recover the existing dispatch before proposing another workflow transition.");
             }
@@ -112,6 +122,7 @@ export function createWorkflowControlService(deps) {
     async function assertRouteAuthorized(input) {
         const state = await getState(input);
         failOnStateWarnings(state);
+        failWhileAwaitingUser(state);
         const pending = state.pendingDispatch;
         if (!pending || pending.status !== "pending") {
             throw workflowError("WORKFLOW_ROUTE_NOT_APPROVED", "Project Manager has no pending workflow approval for this route.", "Submit a valid workflow-progress.md transition before the PM route message.");
@@ -165,6 +176,7 @@ export function createWorkflowControlService(deps) {
         await withLock(statePath(input), async () => {
             const state = await getState(input);
             failOnStateWarnings(state);
+            failWhileAwaitingUser(state);
             const pending = state.pendingDispatch;
             if (!pending || pending.status !== "dispatching" || pending.messageId !== messageId) {
                 throw workflowError("WORKFLOW_DISPATCH_CONFIRMATION_MISMATCH", `Message ${messageId} does not own the pending workflow dispatch.`, "Do not advance Workflow Progress from an unrelated UserPromptSubmit event.");
@@ -207,12 +219,50 @@ export function createWorkflowControlService(deps) {
     }
     return {
         getState,
+        getProgress: (input) => readProgress(deps.fs, input),
+        requestUserInput,
+        resolveUserInput,
         submitProgress,
         assertRouteAuthorized,
         claimDispatch,
         releaseDispatch,
         confirmDispatch
     };
+    async function requestUserInput(input, question) {
+        return withLock(statePath(input), async () => {
+            const state = await getState(input);
+            const normalizedQuestion = question.trim();
+            if (!normalizedQuestion) {
+                throw workflowError("WORKFLOW_USER_QUESTION_REQUIRED", "A non-empty user question is required.");
+            }
+            const timestamp = now();
+            const next = {
+                ...state,
+                awaitingUser: {
+                    question: normalizedQuestion,
+                    requestedAt: timestamp
+                },
+                pendingDispatch: null,
+                updatedAt: timestamp
+            };
+            await saveState(input, next);
+            return next;
+        });
+    }
+    async function resolveUserInput(input) {
+        return withLock(statePath(input), async () => {
+            const state = await getState(input);
+            if (!state.awaitingUser)
+                return state;
+            const next = {
+                ...state,
+                awaitingUser: null,
+                updatedAt: now()
+            };
+            await saveState(input, next);
+            return next;
+        });
+    }
     async function saveState(input, state) {
         await deps.fs.writeJsonAtomic(statePath(input), state);
     }
@@ -351,11 +401,15 @@ async function getAllowedTransitions(fs, input, state, current) {
     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 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"];
+        const docs = await artifactState(fs, input, "docs-update-report.md", "docs-update-report");
+        const active = state.activeDispatch;
+        if (!active || active.flow !== "docs-only") {
+            return [...DOCS_ONLY_ROLE_TRANSITIONS, ...DOCS_ONLY_EXIT_TRANSITIONS];
+        }
+        const hasFreshResult = evidenceProducedAfterActiveDispatch(state, flow, active.targetRole, "docs-update-report.md", docs.hash);
+        return hasFreshResult && docs.complete
+            ? [...DOCS_ONLY_ROLE_TRANSITIONS, ...DOCS_ONLY_EXIT_TRANSITIONS]
+            : [`docs-only/${active.targetRole}`, ...DOCS_ONLY_EXIT_TRANSITIONS];
     }
     if (flow === "validation-only") {
         const test = await artifactState(fs, input, "test-report.md", "test-report");
@@ -387,7 +441,7 @@ function initialTransitions() {
         "code-change/architect",
         "architect-debug/architect",
         "architecture-diagnosis/architect",
-        "docs-only/architect",
+        ...DOCS_ONLY_ROLE_TRANSITIONS,
         "validation-only/tester"
     ];
 }
@@ -554,8 +608,9 @@ 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-sync-report" || kind === "final-acceptance")
+    if (kind === "docs-update-report" || kind === "docs-sync-report" || kind === "final-acceptance") {
         value = readArtifactSectionContent(content, "Decision")?.trim().toLowerCase();
+    }
     const infrastructure = kind === "test-report"
         ? /^Status:\s*(.+?)\s*$/mi.exec(readArtifactSectionContent(content, "Test Infrastructure") ?? "")?.[1]?.trim().toLowerCase()
         : undefined;
@@ -786,10 +841,14 @@ async function validateCompletion(fs, input, state, candidate) {
         return;
     }
     if (candidate.flow === "docs-only") {
-        const docs = await artifactState(fs, input, "docs-sync-report.md", "docs-sync-report");
-        if (!evidenceProducedAfterActiveDispatch(state, candidate.flow, "architect", "docs-sync-report.md", docs.hash)
+        const docs = await artifactState(fs, input, "docs-update-report.md", "docs-update-report");
+        const activeRole = state.activeDispatch?.flow === "docs-only"
+            ? state.activeDispatch.targetRole
+            : undefined;
+        if (!activeRole
+            || !evidenceProducedAfterActiveDispatch(state, candidate.flow, activeRole, "docs-update-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.");
+            throw workflowError("WORKFLOW_COMPLETION_INVALID", "Docs-only completion requires a fresh, complete Docs Update Report from the latest assigned role with Decision: synced or Decision: unchanged.");
         }
         return;
     }
@@ -911,12 +970,20 @@ function normalizeState(value, taskSlug, timestamp) {
     const flowRun = value.flowRun === undefined || value.flowRun === null
         ? null
         : isFlowRun(value.flowRun) ? value.flowRun : undefined;
-    if (pendingDispatch === undefined || activeDispatch === undefined || flowRun === undefined || userAuthorizations === undefined) {
+    const awaitingUser = value.awaitingUser === undefined || value.awaitingUser === null
+        ? null
+        : isAwaitingUser(value.awaitingUser) ? value.awaitingUser : undefined;
+    if (pendingDispatch === undefined
+        || activeDispatch === undefined
+        || flowRun === undefined
+        || userAuthorizations === undefined
+        || awaitingUser === undefined) {
         return { ...emptyState(taskSlug, timestamp), warnings: ["Workflow control state has an unsupported shape."] };
     }
     return {
         version: 1,
         taskSlug,
+        awaitingUser,
         pendingDispatch,
         activeDispatch,
         flowRun,
@@ -929,6 +996,7 @@ function emptyState(taskSlug, timestamp) {
     return {
         version: 1,
         taskSlug,
+        awaitingUser: null,
         pendingDispatch: null,
         activeDispatch: null,
         flowRun: null,
@@ -988,11 +1056,21 @@ function failOnStateWarnings(state) {
     if (state.warnings.length > 0)
         throw workflowError("WORKFLOW_STATE_INVALID", state.warnings.join(" "));
 }
+function failWhileAwaitingUser(state) {
+    if (!state.awaitingUser)
+        return;
+    throw workflowError("WORKFLOW_AWAITING_USER", "Project Manager is waiting for the user's answer and cannot advance the workflow.", "Wait for a new direct user message. The previous workflow approval was canceled; request a fresh approval after the answer arrives.");
+}
 function progressValidationError(errors) {
     return workflowError("WORKFLOW_PROGRESS_INVALID", `Workflow Progress validation failed:\n${errors.map((error) => `- ${error}`).join("\n")}`);
 }
 function workflowError(code, message, hint) {
-    return new VcmError({ code, message, hint, statusCode: code.includes("PENDING") ? 409 : 422 });
+    return new VcmError({
+        code,
+        message,
+        hint,
+        statusCode: code.includes("PENDING") || code.includes("AWAITING_USER") ? 409 : 422
+    });
 }
 async function writeAtomic(fs, target, content) {
     if (fs.writeTextAtomic)
@@ -1003,6 +1081,12 @@ async function writeAtomic(fs, target, content) {
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
+function isAwaitingUser(value) {
+    return isRecord(value)
+        && typeof value.question === "string"
+        && value.question.trim().length > 0
+        && typeof value.requestedAt === "string";
+}
 function isPendingDispatch(value) {
     if (!isRecord(value))
         return false;

package/dist/backend/templates/handoff.js

@@ -1,4 +1,4 @@
-import { ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_SYNC_DECISIONS, 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_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, 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}
@@ -518,7 +518,49 @@ TBD
 
 ## Decision
 
-${renderArtifactOptions(DOCS_SYNC_DECISIONS)}
+${renderArtifactOptions(DOCS_REPORT_DECISIONS)}
+`;
+}
+export function renderDocsUpdateReportTemplate(taskSlug, assignmentId = "docs-only") {
+    return `# Docs Update Report: ${taskSlug}
+
+${CURRENT_HANDOFF_NOTICE}
+
+## Summary
+
+TBD
+
+## Assignment ID
+
+${assignmentId}
+
+## Documents Updated
+
+TBD
+
+## Documents Reviewed And Left Unchanged
+
+TBD
+
+## Evidence Reviewed
+
+TBD
+
+## Checks Performed
+
+TBD
+
+## Commit
+
+TBD
+
+## Remaining Documentation Issues
+
+TBD
+
+## Decision
+
+${renderArtifactOptions(DOCS_REPORT_DECISIONS)}
 `;
 }
 export function renderWorkflowProgressTemplate(taskSlug) {