vibe-coding-master 0.9.2 → 0.9.4

package/README.md

@@ -211,10 +211,11 @@ Typical flow:
 
 ```text
 Project Manager
-  -> Architect
+  -> Architect (plan, scaffold, and architecture docs)
   -> Coder
   -> Tester
-  -> Architect docs sync
+  -> validation-adequacy Gate Review
+  -> code-diff Gate Review (code and docs)
   -> Project Manager final acceptance
 ```
 

package/dist/backend/adapters/command-runner.js

@@ -7,6 +7,7 @@ export function createCommandRunner() {
                     cwd: options.cwd,
                     env: options.env,
                     timeout: options.timeoutMs,
+                    input: options.input,
                     reject: false
                 });
                 return {

package/dist/backend/adapters/filesystem.js

@@ -70,13 +70,16 @@ export function createNodeFileSystemAdapter() {
         async readJson(targetPath) {
             let attempt = 0;
             for (;;) {
-                const content = await runFileOperation(() => fs.readFile(targetPath, "utf8"));
                 try {
+                    const content = await runFileOperation(() => fs.readFile(targetPath, "utf8"));
                     return JSON.parse(content);
                 }
                 catch (error) {
+                    // A concurrent rename-over can leave the target briefly missing on
+                    // some shared mounts, so ENOENT gets the same short retry as a
+                    // partially written file. A file that stays missing still throws.
                     const delayMs = JSON_READ_RETRY_DELAYS_MS[attempt];
-                    if (!(error instanceof SyntaxError) || delayMs === undefined) {
+                    if (!(error instanceof SyntaxError || getErrorCode(error) === "ENOENT") || delayMs === undefined) {
                         throw error;
                     }
                     attempt += 1;

package/dist/backend/api/artifact-routes.js

@@ -147,9 +147,6 @@ function artifactNameToPath(paths, artifactName) {
     if (artifactName === "docs-update-report.md") {
         return paths.docsUpdateReportPath;
     }
-    if (artifactName === "docs-sync-report.md") {
-        return paths.docsSyncReportPath;
-    }
     if (artifactName === "workflow-progress.md") {
         return paths.workflowProgressPath;
     }

package/dist/backend/api/task-routes.js

@@ -226,7 +226,6 @@ function degradedArtifactSummary(handoffDir) {
             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/cli/install-vcm-harness.js

@@ -320,6 +320,12 @@ const WHOLE_FILES = [
         mode: 0o755,
         templatePath: "scripts/harness-tools/check-durable-docs"
     },
+    {
+        path: ".ai/tools/check-docs-sync",
+        category: "durable-docs-tool",
+        mode: 0o755,
+        templatePath: "scripts/harness-tools/check-docs-sync"
+    },
     {
         path: ".claude/skills/vcm-architecture-interview/SKILL.md",
         category: "skill",

package/dist/backend/server.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import Fastify from "fastify";
 import fastifyStatic from "@fastify/static";
+import { createDocsCoverageCheck } from "./services/docs-sync-check.js";
 import { createArtifactService } from "./services/artifact-service.js";
 import { createClaudeAdapter } from "./adapters/claude-adapter.js";
 import { createCodexBridgeAdapter } from "./adapters/codex-bridge-adapter.js";
@@ -354,6 +355,7 @@ export function createDefaultServerDeps(options = {}) {
         sessionService,
         roundService,
         workflowControlService,
+        checkDocsCoverage: createDocsCoverageCheck(runner),
         onArchitecturePlanDisposition: ({ repoRoot, taskSlug, accepted }) => architectRestartService.recordArchitectureGateDisposition(repoRoot, taskSlug, accepted)
     });
     const translationWorkerService = createTranslationWorkerService({

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

@@ -4,7 +4,7 @@ import { checkMarkdownArtifact, readArtifactSectionValue } from "../../shared/va
 import { getManagedArtifactDefinition, isArtifactKind, isManagedArtifactKind } from "../../shared/validation/artifact-registry.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
-import { renderArchitectureBriefTemplate, renderArchitectureDiagnosisTemplate, renderArchitectureEvidenceTemplate, renderArchitecturePlanTemplate, renderArchitectDebugTemplate, renderCoderCompletionTemplate, renderDocsUpdateReportTemplate, renderDocsSyncReportTemplate, renderFinalAcceptanceTemplate, renderKnownIssuesTemplate, renderPlanningProgressTemplate, renderMessageRouteTemplate, renderTestReportTemplate, renderWorkflowProgressTemplate } from "../templates/handoff.js";
+import { renderArchitectureBriefTemplate, renderArchitectureDiagnosisTemplate, renderArchitectureEvidenceTemplate, renderArchitecturePlanTemplate, renderArchitectDebugTemplate, renderCoderCompletionTemplate, renderDocsUpdateReportTemplate, renderFinalAcceptanceTemplate, renderKnownIssuesTemplate, renderPlanningProgressTemplate, renderMessageRouteTemplate, renderTestReportTemplate, renderWorkflowProgressTemplate } from "../templates/handoff.js";
 import { renderRoleCommandTemplate } from "../templates/role-command.js";
 import { isMemoryProposalSubmissionPath } from "./memory-review-paths.js";
 import { validateManagedArtifactContent } from "./managed-artifact-validation.js";
@@ -19,7 +19,6 @@ const ARTIFACT_PATH_KEYS = [
     ["architecture-diagnosis", "architectureDiagnosisPath"],
     ["test-report", "testReportPath"],
     ["docs-update-report", "docsUpdateReportPath"],
-    ["docs-sync-report", "docsSyncReportPath"],
     ["workflow-progress", "workflowProgressPath"],
     ["final-acceptance", "finalAcceptancePath"]
 ];
@@ -57,7 +56,6 @@ export function createArtifactService(fs, deps = {}) {
                 architectureDiagnosisPath: path.posix.join(handoffDir, "architecture-diagnosis.md"),
                 testReportPath: path.posix.join(handoffDir, "test-report.md"),
                 docsUpdateReportPath: path.posix.join(handoffDir, "docs-update-report.md"),
-                docsSyncReportPath: path.posix.join(handoffDir, "docs-sync-report.md"),
                 workflowProgressPath: path.posix.join(handoffDir, "workflow-progress.md"),
                 finalAcceptancePath: path.posix.join(handoffDir, "final-acceptance.md")
             };
@@ -88,7 +86,6 @@ export function createArtifactService(fs, deps = {}) {
                 [paths.architectureDiagnosisPath, renderArchitectureDiagnosisTemplate(input.taskSlug)],
                 [paths.testReportPath, renderTestReportTemplate(input.taskSlug)],
                 [paths.docsUpdateReportPath, renderDocsUpdateReportTemplate(input.taskSlug)],
-                [paths.docsSyncReportPath, renderDocsSyncReportTemplate(input.taskSlug)],
                 [paths.workflowProgressPath, renderWorkflowProgressTemplate(input.taskSlug)],
                 [paths.finalAcceptancePath, renderFinalAcceptanceTemplate(input.taskSlug)],
                 ...Object.values(paths.messageRoutePaths).map((messagePath) => [
@@ -230,18 +227,6 @@ 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.
-                    if (!assignment) {
-                        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/auto-memory-service.js

@@ -8,6 +8,7 @@ import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { readVcmMemoryHostFrame, readVcmMemoryBlock, replaceVcmMemoryBlock } from "../templates/harness/memory-block.js";
 import { ARCHITECT_PLANNING_MEMORY_CANDIDATE_PATH, architectPlanningCandidateSnapshotPath, durableDocAssignmentReportPath, memoryReviewRoleDraftPath, MEMORY_REVIEW_RUNS_ROOT, MEMORY_REVIEW_STATE_PATH } from "./memory-review-paths.js";
 import { parseMemoryProposal, validateMemoryProposal } from "./memory-proposal-validation.js";
+const MEMORY_REVIEW_STOP_BLOCK_LIMIT = 3;
 const MEMORY_FILE_DEFINITIONS = [
     { path: "CLAUDE.md", title: "Shared Memory" },
     { path: ".claude/agents/project-manager.md", title: "Project Manager Memory", role: "project-manager" },
@@ -436,43 +437,75 @@ export function createAutoMemoryService(deps) {
         if (!(await deps.appSettings.getPreferences()).autoMemoryEnabled && !preserveDisabledReview(state)) {
             if (state) {
                 await discardActiveReview(input.taskRepoRoot, state);
-                return true;
+                return { handled: true };
             }
-            return false;
+            return { handled: false };
         }
         if (state?.status === "reviewing" && !state.reviewPromptDispatchedAt) {
-            return false;
+            return { handled: false };
         }
         if (!state || state.status !== "reviewing") {
-            return false;
+            return { handled: false };
         }
         if (input.eventName === "UserPromptSubmit" || input.eventName === "PostCompact") {
-            return true;
+            return { handled: true };
         }
         if (input.eventName === "StopFailure") {
             await failReview(input.taskRepoRoot, state, "Task Harness Retrospective memory review turn failed.");
-            return true;
+            return { handled: true };
         }
         if (input.eventName === "Stop") {
             if (!state.retrospectiveReportPath
                 || !(await deps.fs.pathExists(state.retrospectiveReportPath))
                 || !(await deps.fs.readText(state.retrospectiveReportPath)).trim()) {
-                await failReview(input.taskRepoRoot, state, "Task Harness Retrospective did not write the required retrospective report.");
-                return true;
+                return rejectHarnessEngineerStop(input, state, "Task Harness Retrospective did not write the required retrospective report.");
             }
             try {
                 await recordHarnessEngineerMemoryResult(input.taskRepoRoot, state);
-                if (state.assignments.length > 0) {
-                    await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, state);
-                }
             }
             catch (error) {
-                await failReview(input.taskRepoRoot, state, `Harness Engineer memory result could not be recorded: ${errorMessage(error)}`);
-                return true;
+                const message = `Harness Engineer memory result could not be recorded: ${errorMessage(error)}`;
+                if (!isFixableMemoryResultError(error)) {
+                    await failReview(input.taskRepoRoot, state, message);
+                    return { handled: true };
+                }
+                const hint = error instanceof VcmError && error.hint ? ` ${error.hint}` : "";
+                return rejectHarnessEngineerStop(input, state, `${message}${hint}`);
             }
-            return true;
+            if (state.assignments.length > 0) {
+                try {
+                    await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, state);
+                }
+                catch (error) {
+                    await failReview(input.taskRepoRoot, state, `Durable-document assignment could not be dispatched: ${errorMessage(error)}`);
+                }
+            }
+            return { handled: true };
         }
-        return true;
+        return { handled: true };
+    }
+    // A correctable retrospective result keeps the Harness Engineer turn alive
+    // with the validation error, a bounded number of times, so the role can fix
+    // review-result.json or the memory commit instead of the review failing
+    // silently after the turn has ended.
+    async function rejectHarnessEngineerStop(input, state, message) {
+        const blocks = state.stopBlockCount ?? 0;
+        if (!input.allowStopBlock || blocks >= MEMORY_REVIEW_STOP_BLOCK_LIMIT) {
+            await failReview(input.taskRepoRoot, state, message);
+            return { handled: true };
+        }
+        state.stopBlockCount = blocks + 1;
+        state.error = message;
+        state.updatedAt = now();
+        await persistActiveState(input.taskRepoRoot, state);
+        return {
+            handled: true,
+            stopBlockReason: [
+                message,
+                `Fix the retrospective report, ${resolveRepoPath(input.taskRepoRoot, reviewResultRelativePath(state.runId))}, or the memory commit, then end the turn again.`,
+                `Attempt ${state.stopBlockCount} of ${MEMORY_REVIEW_STOP_BLOCK_LIMIT}; after that the memory review fails.`
+            ].join(" ")
+        };
     }
     async function getFile(_baseRepoRoot, taskRepoRoot, filePath) {
         await assertMemoryBlocksInstalled(deps.fs, taskRepoRoot);
@@ -549,9 +582,47 @@ export function createAutoMemoryService(deps) {
                 statusCode: 409
             });
         }
+        if (await harnessEngineerResultWritten(taskRepoRoot, state)) {
+            // The Harness Engineer finished its turn, so re-validate the current
+            // result file and memory commit before discarding anything.
+            try {
+                await recordHarnessEngineerMemoryResult(taskRepoRoot, state);
+            }
+            catch (error) {
+                if (await memoryChangedSinceReview(taskRepoRoot, state)) {
+                    // Reviewed memory is already committed; restarting would lose the
+                    // durable-document moves recorded only in this run's result file.
+                    const message = `Harness Engineer memory result could not be recorded: ${errorMessage(error)}`;
+                    await failReview(taskRepoRoot, state, message);
+                    throw new VcmError({
+                        code: "MEMORY_REVIEW_RESULT_STILL_INVALID",
+                        message,
+                        statusCode: 409,
+                        hint: `Correct ${resolveRepoPath(taskRepoRoot, reviewResultRelativePath(state.runId))} or the memory commit, then retry.`
+                    });
+                }
+                await clearActiveState(taskRepoRoot);
+                return getState(baseRepoRoot, taskRepoRoot);
+            }
+            if (state.assignments.length > 0) {
+                await dispatchCurrentDurableDocAssignment(baseRepoRoot, taskRepoRoot, state);
+            }
+            return getState(baseRepoRoot, taskRepoRoot);
+        }
         await clearActiveState(taskRepoRoot);
         return getState(baseRepoRoot, taskRepoRoot);
     }
+    async function harnessEngineerResultWritten(taskRepoRoot, state) {
+        if (!state.reviewBaseCommit || !state.reviewPromptDispatchedAt) {
+            return false;
+        }
+        return deps.fs.pathExists(resolveRepoPath(taskRepoRoot, reviewResultRelativePath(state.runId)));
+    }
+    async function memoryChangedSinceReview(taskRepoRoot, state) {
+        const before = await readRunMemorySet(taskRepoRoot, state.runId, "before");
+        const after = await readMemorySet(taskRepoRoot);
+        return MEMORY_FILE_DEFINITIONS.some((definition) => before[definition.path] !== after[definition.path]);
+    }
     async function retryDurableDocAssignment(baseRepoRoot, taskRepoRoot, assignmentId) {
         const state = await loadActiveState(taskRepoRoot);
         const assignment = state && (state.status === "documenting" || state.status === "failed")
@@ -996,7 +1067,7 @@ export function createAutoMemoryService(deps) {
         await persistActiveState(taskRepoRoot, state);
     }
     async function readAndValidateHarnessMemoryReviewResult(taskRepoRoot, state, before, after, currentHead, changedMemoryPaths) {
-        const resultPath = resolveRepoPath(taskRepoRoot, `${MEMORY_REVIEW_RUNS_ROOT}/${state.runId}/review-result.json`);
+        const resultPath = resolveRepoPath(taskRepoRoot, reviewResultRelativePath(state.runId));
         if (!(await deps.fs.pathExists(resultPath))) {
             throw new VcmError({
                 code: "MEMORY_REVIEW_RESULT_MISSING",
@@ -1791,6 +1862,20 @@ function ensureTrailingNewline(content) {
 function sha256(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+function reviewResultRelativePath(runId) {
+    return `${MEMORY_REVIEW_RUNS_ROOT}/${runId}/review-result.json`;
+}
+// Errors the Harness Engineer can correct in its own output: the result file,
+// the memory edit, or the memory commit. A malformed result file surfaces as a
+// JSON SyntaxError.
+function isFixableMemoryResultError(error) {
+    if (error instanceof SyntaxError) {
+        return true;
+    }
+    return error instanceof VcmError
+        && error.code.startsWith("MEMORY_")
+        && error.code !== "MEMORY_REVIEW_BASE_MISSING";
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

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

@@ -114,29 +114,30 @@ export function createClaudeHookService(deps) {
             dispatchedCount: 0
         };
     }
-    async function processHarnessEngineerHook(input) {
+    async function processHarnessEngineerHook(input, options) {
         const eventName = parseBusinessHookEvent(input.event.hook_event_name);
         const context = await getProjectToolHookContext("Harness Engineer");
         const projectScoped = input.taskSlug === "__project_harness_engineer__";
-        const session = projectScoped
-            ? await deps.sessionService.recordProjectHarnessEngineerHookEvent(context.project.repoRoot, {
-                eventName,
+        const recordSessionEvent = (recordedEventName) => projectScoped
+            ? deps.sessionService.recordProjectHarnessEngineerHookEvent(context.project.repoRoot, {
+                eventName: recordedEventName,
                 sessionId: stringOrUndefined(input.event.session_id),
                 transcriptPath: stringOrUndefined(input.event.transcript_path),
                 cwd: stringOrUndefined(input.event.cwd) ?? stringOrUndefined(input.event.new_cwd),
                 runtimeSessionId: stringOrUndefined(input.event.vcm_runtime_session_id),
                 runtimeSessionToken: input.runtimeSessionToken
             })
-            : await deps.sessionService.recordRoleHookEvent(context.project.repoRoot, {
+            : deps.sessionService.recordRoleHookEvent(context.project.repoRoot, {
                 taskSlug: input.taskSlug,
                 role: input.role,
-                eventName,
+                eventName: recordedEventName,
                 sessionId: stringOrUndefined(input.event.session_id),
                 transcriptPath: stringOrUndefined(input.event.transcript_path),
                 cwd: stringOrUndefined(input.event.cwd) ?? stringOrUndefined(input.event.new_cwd),
                 runtimeSessionId: stringOrUndefined(input.event.vcm_runtime_session_id),
                 runtimeSessionToken: input.runtimeSessionToken
             });
+        const session = await recordSessionEvent(eventName);
         if (!session) {
             return completedHookResult(input, eventName);
         }
@@ -144,14 +145,32 @@ export function createClaudeHookService(deps) {
             ? (await deps.taskService.listTasks(context.project.repoRoot))
                 .find((task) => task.cleanupStatus !== "cleaned" && (projectScoped || task.taskSlug === input.taskSlug))
             : undefined;
-        const memoryHandled = activeTask
+        const memoryResult = activeTask
             ? await deps.autoMemoryService?.handleHarnessEngineerHook({
                 baseRepoRoot: context.project.repoRoot,
                 taskRepoRoot: getTaskRuntimeRepoRoot(activeTask),
                 taskSlug: activeTask.taskSlug,
-                eventName
+                eventName,
+                allowStopBlock: options.allowBlock && eventName === "Stop"
             })
-            : false;
+            : undefined;
+        if (memoryResult?.stopBlockReason) {
+            // The memory review result is still correctable: keep the Harness
+            // Engineer turn alive and skip retrospective completion until it passes.
+            // The turn continues, so the session must not stay recorded as idle and
+            // receive queued input meanwhile.
+            await recordSessionEvent("UserPromptSubmit");
+            return {
+                ok: true,
+                eventName,
+                taskSlug: activeTask?.taskSlug ?? input.taskSlug,
+                role: input.role,
+                sessionUpdated: Boolean(session),
+                dispatchedCount: 0,
+                stopDecision: { behavior: "block", reason: memoryResult.stopBlockReason }
+            };
+        }
+        const memoryHandled = memoryResult?.handled ?? false;
         const memoryState = activeTask && deps.autoMemoryService
             ? await deps.autoMemoryService.getState(context.project.repoRoot, getTaskRuntimeRepoRoot(activeTask))
             : undefined;
@@ -631,7 +650,7 @@ export function createClaudeHookService(deps) {
         });
         if (eventName === "Stop") {
             const memoryState = await deps.autoMemoryService.getState(context.project.repoRoot, context.taskRepoRoot);
-            await deps.harnessFeedbackService?.completeWaitingTaskRetrospective(context.project.repoRoot, context.taskSlug, memoryState.status);
+            await deps.harnessFeedbackService?.completeWaitingTaskRetrospective(context.project.repoRoot, context.taskSlug, memoryState);
         }
         return {
             ok: true,
@@ -908,7 +927,7 @@ export function createClaudeHookService(deps) {
                     return processTranslatorHook(input);
                 }
                 if (isHarnessEngineerToolRoleName(input.role)) {
-                    return processHarnessEngineerHook(input);
+                    return processHarnessEngineerHook(input, { allowBlock: false });
                 }
                 if (eventName === "UserPromptSubmit") {
                     return handleUserPromptSubmitHook(input);
@@ -930,7 +949,7 @@ export function createClaudeHookService(deps) {
                     return processTranslatorHook(input);
                 }
                 if (isHarnessEngineerToolRoleName(input.role)) {
-                    return processHarnessEngineerHook(input);
+                    return processHarnessEngineerHook(input, { allowBlock: true });
                 }
                 return processStopHook(input, { allowBlock: true });
             });

package/dist/backend/services/docs-sync-check.js

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import path from "node:path";
+const DOCS_SYNC_TOOL = ".ai/tools/check-docs-sync";
+const DOCS_SYNC_TIMEOUT_MS = 60_000;
+// Runs the task worktree's check-docs-sync, which compares the task's commits
+// with the architecture plan's Docs Impact, and returns one error per finding.
+// A worktree whose harness predates the tool is not checked.
+export function createDocsCoverageCheck(runner) {
+    return async (taskRepoRoot) => {
+        const tool = path.join(taskRepoRoot, DOCS_SYNC_TOOL);
+        if (!fs.existsSync(tool)) {
+            return [];
+        }
+        const result = await runner.run(process.execPath, [tool, "--json"], {
+            cwd: taskRepoRoot,
+            timeoutMs: DOCS_SYNC_TIMEOUT_MS
+        });
+        if (result.exitCode === 0) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(result.stdout);
+            if (result.exitCode === 1 && Array.isArray(parsed.findings) && parsed.findings.length > 0) {
+                return parsed.findings.map((finding) => `${finding.code} ${finding.subject}: ${finding.message}`);
+            }
+        }
+        catch {
+            // Fall through to the raw tool error below.
+        }
+        return [`${DOCS_SYNC_TOOL} could not check the task: ${(result.stderr || result.stdout).trim() || `exit ${result.exitCode}`}`];
+    };
+}

package/dist/backend/services/gate-review-service.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
-import { CODE_DIFF_FINDING_SCOPES, CODE_DIFF_SOURCES, GATE_REVIEW_GATES } from "../../shared/types/gate-review.js";
+import { CODE_DIFF_DOCS_COVERAGE_ERROR_PREFIX, CODE_DIFF_FINDING_SCOPES, CODE_DIFF_SOURCES, GATE_REVIEW_GATES } from "../../shared/types/gate-review.js";
 import { checkMarkdownArtifact, readArtifactSectionValue } from "../../shared/validation/artifact-check.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
@@ -379,6 +379,14 @@ export function createGateReviewService(deps) {
                     message: prerequisiteError
                 };
             }
+            const coverageFindings = deps.checkDocsCoverage
+                ? await deps.checkDocsCoverage(context.taskRepoRoot)
+                : [];
+            if (coverageFindings.length > 0) {
+                const message = `${CODE_DIFF_DOCS_COVERAGE_ERROR_PREFIX} ${coverageFindings.join(" ")}`;
+                index = await recordCodeDiffStartFailure(index, context, gate, codeDiffSource, message, codeDiffInput);
+                return { status: "failed_to_start", gate, record: index.gates[gate], message };
+            }
         }
         async function recordCodeDiffStartFailure(currentIndex, currentContext, currentGate, currentSource, message, currentCodeDiffInput) {
             const failedIndex = applyGateState(currentIndex, currentGate, {
@@ -1293,7 +1301,7 @@ async function computeInputHash(deps, taskRepoRoot, gate, codeDiffInput, codeDif
         }
     }
     if (gate === "validation-adequacy") {
-        const evidencePathspec = ["--", ".", ":(exclude).ai/vcm/**", ":(exclude)docs/**"];
+        const evidencePathspec = ["--", ".", ":(exclude).ai/vcm/**", ":(exclude)docs/**", ":(exclude,glob)**/ARCHITECTURE.md", ":(exclude).ai/generated/**"];
         digest.update("trackedEvidence");
         digest.update(await commandStdout(deps.runner, taskRepoRoot, ["ls-files", "-s", ...evidencePathspec]));
         digest.update("workingEvidence");

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

@@ -175,6 +175,7 @@ export function createHarnessFeedbackService(deps) {
                 ...processedMarker,
                 status: "failed",
                 durableDocFailure: input.memoryReviewHasAssignments,
+                memoryReviewFailure: true,
                 failedAt: timestamp,
                 updatedAt: timestamp,
                 error: input.memoryReviewError
@@ -194,15 +195,28 @@ export function createHarnessFeedbackService(deps) {
         await completeTaskRetrospective(repoRoot, processedMarker);
         return true;
     }
-    async function completeWaitingTaskRetrospective(repoRoot, taskSlug, memoryStatus) {
+    async function completeWaitingTaskRetrospective(repoRoot, taskSlug, memory) {
         const marker = await loadTaskRetrospectiveMarker(repoRoot, taskSlug);
-        if (!marker || (marker.status !== "waiting-docs" && !(marker.status === "failed" && marker.durableDocFailure))) {
+        // A memory review that failed validation recovers only when a retry
+        // re-validated and applied that same run; a discarded run never does.
+        const memoryReviewRecovered = Boolean(marker?.memoryReviewFailure
+            && marker.memoryRunId
+            && memory.runs.some((run) => run.runId === marker.memoryRunId && run.status === "applied"));
+        if (!marker
+            || (marker.status !== "waiting-docs"
+                && !(marker.status === "failed" && (marker.durableDocFailure || memoryReviewRecovered)))) {
             return false;
         }
+        const memoryStatus = memory.status;
         if (memoryStatus === "documenting") {
             if (marker.status === "failed") {
                 await persistTaskRetrospectiveMarker(repoRoot, {
-                    ...marker, status: "waiting-docs", updatedAt: now(), error: undefined, failedAt: undefined
+                    ...marker,
+                    status: "waiting-docs",
+                    memoryReviewFailure: undefined,
+                    updatedAt: now(),
+                    error: undefined,
+                    failedAt: undefined
                 });
             }
             return true;
@@ -235,6 +249,7 @@ export function createHarnessFeedbackService(deps) {
             ...processedMarker,
             status: "completed",
             durableDocFailure: undefined,
+            memoryReviewFailure: undefined,
             error: undefined,
             failedAt: undefined,
             completedAt: timestamp,
@@ -408,8 +423,11 @@ export function createHarnessFeedbackService(deps) {
                     `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.",
+                    "Every decision field is a non-empty string except evidence. Use \"none\" for finalContent when the decision keeps no memory text (remove, reject, move-to-durable-doc), and for durableDocPath unless the decision is move-to-durable-doc, where it must equal the assignment targetPath.",
+                    "For retain, update, keep-in-memory, and keep-memory-reference, finalContent must be the exact memory text now present in the <VCM-memory> block; an update's finalContent must be one complete semantic entry as it now appears.",
                     "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.",
+                    "VCM validates review-result.json and the memory commit when you end the turn. If validation fails, the Stop is rejected with the error; correct the result file or the memory commit and end the turn again.",
                     "In the retrospective report, include only this memory summary:",
                     "",
                     "## Memory Review",

package/dist/backend/services/lsp-plugin.js

@@ -41,7 +41,9 @@ export function lspUnavailableWarning(language) {
         : `Install or repair ${language.serverCommand} in the environment running the VCM backend${installCommands[language.serverCommand] ? ` (${installCommands[language.serverCommand]})` : ""} and ensure it is executable on PATH.`;
     return `LSP for ${language.label} is unavailable: ${language.error ?? `${language.serverCommand} is not runnable.`} ${recovery} Restart the LSP roles (Architect, Reviewer) after fixing the environment so VCM can detect and register the server again.`;
 }
-export function renderLspNotice(status) {
+// Architect stops semantic work in an unavailable language; Reviewer completes
+// the review and records those relationships as not LSP-verified.
+export function renderLspNotice(status, role = "architect") {
     if (status.languages.length === 0)
         return undefined;
     const available = status.languages.filter((language) => language.state === "server_runnable");
@@ -54,7 +56,9 @@ export function renderLspNotice(status) {
         ] : []),
         ...unavailable.map(lspUnavailableWarning),
         ...(unavailable.length > 0 ? [
-            "If your assignment requires a semantic query in an unavailable language, stop that work and report the environment prerequisite through the current communication channel. Do not substitute source text search or claim the relationship is verified. Continue only after the server is available."
+            role === "reviewer"
+                ? "For relationships in an unavailable language, complete the review by reading the complete candidate code, record each such relationship as not LSP-verified in the report, and name the missing server. Do not stop the review or treat text matches as verified relationships."
+                : "If your assignment requires a semantic query in an unavailable language, stop that work and report the environment prerequisite through the current communication channel. Do not substitute source text search or claim the relationship is verified. Continue only after the server is available."
         ] : [])
     ].join("\n");
 }

package/dist/backend/services/managed-artifact-validation.js

@@ -26,6 +26,7 @@ export const GATE_ANALYSIS_FIELDS = {
         "Invalidated Assumptions",
         "Existing-Class Completeness",
         "Relationship Evidence",
+        "Architecture Docs",
         "Ownership",
         "Data Flow",
         "Lifecycle",
@@ -60,7 +61,7 @@ export const GATE_ANALYSIS_FIELDS = {
         "State Lifecycle And Failure Paths",
         "Coding Standards",
         "Baseline Test Integrity",
-        "Generated Context And Durable Docs",
+        "Documentation Fit",
         "Code Readiness"
     ]
 };

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

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

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

@@ -85,7 +85,7 @@ export function createSessionService(deps) {
         const lspPluginDirs = roleUsesLsp(role)
             ? lspStatus ? await prepareTaskLspPlugin(deps.fs, taskRepoRoot, lspStatus) : [VCM_LSP_PLUGIN_DIR]
             : [];
-        const appendSystemPrompt = [input.appendSystemPrompt, lspStatus && renderLspNotice(lspStatus)]
+        const appendSystemPrompt = [input.appendSystemPrompt, lspStatus && renderLspNotice(lspStatus, role)]
             .filter(Boolean).join("\n\n") || undefined;
         const startCommand = {
             ...deps.claude.buildRoleStartCommand(role, config.claudeCommand, permissionMode, resumeClaudeSessionId, launchMode === "resume", model, effort, modelSettingsOverride, appendSystemPrompt, lspPluginDirs),

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

@@ -60,7 +60,6 @@ function degradedArtifactSummary(handoffDir) {
             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`
         },