vibe-coding-master 0.7.39 → 0.7.40

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

@@ -1,16 +1,24 @@
 import path from "node:path";
-import { DISPATCHABLE_ROLES } from "../../shared/constants.js";
+import { DISPATCHABLE_ROLES, VCM_ROLE_NAMES } from "../../shared/constants.js";
 import { checkMarkdownArtifact } from "../../shared/validation/artifact-check.js";
+import { getArtifactDefinition, isArtifactKind } from "../../shared/validation/artifact-registry.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
-import { renderArchitectureBriefTemplate, renderArchitecturePlanTemplate, renderArchitectDebugTemplate, renderCoderCompletionTemplate, renderDocsSyncReportTemplate, renderFinalAcceptanceTemplate, renderKnownIssuesTemplate, renderMessageRouteTemplate, renderTestReportTemplate } from "../templates/handoff.js";
+import { renderArchitectureBriefTemplate, renderArchitectureDiagnosisTemplate, renderArchitectureEvidenceTemplate, renderArchitecturePlanTemplate, renderArchitectDebugTemplate, renderCoderCompletionTemplate, renderDocsSyncReportTemplate, renderFinalAcceptanceTemplate, renderKnownIssuesTemplate, renderPlanningProgressTemplate, renderMessageRouteTemplate, renderTestReportTemplate, renderWorkflowProgressTemplate } from "../templates/handoff.js";
 import { renderRoleCommandTemplate } from "../templates/role-command.js";
+import { validateMemoryProposal } from "./memory-proposal-validation.js";
 const ARTIFACT_PATH_KEYS = [
     ["architecture-brief", "architectureBriefPath"],
+    ["architecture-evidence", "architectureEvidencePath"],
+    ["planning-progress", "planningProgressPath"],
     ["architecture-plan", "architecturePlanPath"],
     ["known-issues", "knownIssuesPath"],
+    ["coder-completion", "coderCompletionPath"],
+    ["architect-debug", "architectDebugPath"],
+    ["architecture-diagnosis", "architectureDiagnosisPath"],
     ["test-report", "testReportPath"],
     ["docs-sync-report", "docsSyncReportPath"],
+    ["workflow-progress", "workflowProgressPath"],
     ["final-acceptance", "finalAcceptancePath"]
 ];
 const ROLE_COMMAND_PLACEHOLDER_PATTERN = /(^|\n)\s*(TBD|status:\s*draft)\s*(\n|$)/i;
@@ -22,7 +30,7 @@ const DEFAULT_MESSAGE_ROUTES = [
     ["coder", "project-manager"],
     ["tester", "project-manager"]
 ];
-export function createArtifactService(fs) {
+export function createArtifactService(fs, deps = {}) {
     return {
         getHandoffPaths(_repoRoot, handoffDir) {
             const roleCommandsDir = path.posix.join(handoffDir, "role-commands");
@@ -38,10 +46,16 @@ export function createArtifactService(fs) {
                 },
                 messageRoutePaths: getDefaultMessageRoutePaths(messagesDir),
                 architectureBriefPath: path.posix.join(handoffDir, "architecture-brief.md"),
+                architectureEvidencePath: path.posix.join(handoffDir, "architecture-evidence.md"),
+                planningProgressPath: path.posix.join(handoffDir, "planning-progress.md"),
                 architecturePlanPath: path.posix.join(handoffDir, "architecture-plan.md"),
                 knownIssuesPath: path.posix.join(handoffDir, "known-issues.md"),
+                coderCompletionPath: path.posix.join(handoffDir, "coder-completion.md"),
+                architectDebugPath: path.posix.join(handoffDir, "architect-debug.md"),
+                architectureDiagnosisPath: path.posix.join(handoffDir, "architecture-diagnosis.md"),
                 testReportPath: path.posix.join(handoffDir, "test-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")
             };
         },
@@ -62,12 +76,16 @@ export function createArtifactService(fs) {
                 [paths.roleCommandPaths.coder, renderRoleCommandTemplate(input.taskSlug, "coder", input.repoRoot, input.branch)],
                 [paths.roleCommandPaths.tester, renderRoleCommandTemplate(input.taskSlug, "tester", input.repoRoot, input.branch)],
                 [paths.architectureBriefPath, renderArchitectureBriefTemplate(input.taskSlug)],
+                [paths.architectureEvidencePath, renderArchitectureEvidenceTemplate(input.taskSlug)],
+                [paths.planningProgressPath, renderPlanningProgressTemplate(input.taskSlug)],
                 [paths.architecturePlanPath, renderArchitecturePlanTemplate(input.taskSlug)],
                 [paths.knownIssuesPath, renderKnownIssuesTemplate(input.taskSlug)],
-                [path.posix.join(paths.handoffDir, "coder-completion.md"), renderCoderCompletionTemplate(input.taskSlug)],
-                [path.posix.join(paths.handoffDir, "architect-debug.md"), renderArchitectDebugTemplate(input.taskSlug)],
+                [paths.coderCompletionPath, renderCoderCompletionTemplate(input.taskSlug)],
+                [paths.architectDebugPath, renderArchitectDebugTemplate(input.taskSlug)],
+                [paths.architectureDiagnosisPath, renderArchitectureDiagnosisTemplate(input.taskSlug)],
                 [paths.testReportPath, renderTestReportTemplate(input.taskSlug)],
                 [paths.docsSyncReportPath, renderDocsSyncReportTemplate(input.taskSlug)],
+                [paths.workflowProgressPath, renderWorkflowProgressTemplate(input.taskSlug)],
                 [paths.finalAcceptancePath, renderFinalAcceptanceTemplate(input.taskSlug)],
                 ...Object.values(paths.messageRoutePaths).map((messagePath) => [
                     messagePath,
@@ -163,9 +181,295 @@ export function createArtifactService(fs) {
         async saveRoleCommand(input) {
             const paths = this.getHandoffPaths(input.repoRoot, input.handoffDir);
             await fs.writeText(resolveRepoPath(input.repoRoot, paths.roleCommandPaths[input.role]), input.content);
+        },
+        async submitArtifact(input) {
+            const normalized = normalizeSubmissionContent(input.content);
+            if (!normalized.trim()) {
+                throw artifactRejected(input.kind, ["Artifact content is empty."]);
+            }
+            if (isArtifactKind(input.kind)) {
+                const definition = getArtifactDefinition(input.kind);
+                if (definition.owner !== input.role) {
+                    throw new VcmError({
+                        code: "ARTIFACT_OWNER_MISMATCH",
+                        message: `${input.kind} is owned by ${definition.owner}, not ${input.role}.`,
+                        statusCode: 403
+                    });
+                }
+                const artifactPath = path.posix.join(input.handoffDir, definition.fileName);
+                const check = checkMarkdownArtifact(input.kind, artifactPath, normalized, { mode: input.mode });
+                const errors = artifactCheckErrors(check, input.mode);
+                if (errors.length > 0) {
+                    throw artifactRejected(input.kind, errors);
+                }
+                if (input.kind === "workflow-progress") {
+                    if (input.mode !== "final") {
+                        throw artifactRejected(input.kind, ["Workflow Progress must be submitted in final mode."]);
+                    }
+                    if (!deps.workflowControlService) {
+                        throw new VcmError({
+                            code: "WORKFLOW_CONTROL_UNAVAILABLE",
+                            message: "Workflow Control is unavailable.",
+                            statusCode: 503
+                        });
+                    }
+                    const submitted = await deps.workflowControlService.submitProgress({
+                        taskRepoRoot: input.repoRoot,
+                        stateRoot: input.stateRoot ?? ".ai/vcm",
+                        handoffDir: input.handoffDir,
+                        taskSlug: input.taskSlug
+                    }, normalized);
+                    return {
+                        ok: true,
+                        kind: input.kind,
+                        mode: input.mode,
+                        path: submitted.path,
+                        status: "accepted"
+                    };
+                }
+                await writeAtomic(fs, resolveRepoPath(input.repoRoot, artifactPath), normalized);
+                return {
+                    ok: true,
+                    kind: input.kind,
+                    mode: input.mode,
+                    path: artifactPath,
+                    status: check.status
+                };
+            }
+            const dynamic = await validateDynamicArtifact(fs, input, normalized, deps.workflowControlService);
+            await writeAtomic(fs, resolveRepoPath(dynamic.root, dynamic.path), normalized);
+            return {
+                ok: true,
+                kind: dynamic.kind,
+                mode: input.mode,
+                path: dynamic.path,
+                status: "accepted"
+            };
         }
     };
 }
+function artifactCheckErrors(check, mode) {
+    const errors = [
+        ...check.missingHeadings.map((heading) => `Missing required heading: ${heading}.`),
+        ...check.invalidFields
+    ];
+    if (mode === "final" && check.hasPlaceholder) {
+        errors.push("Final artifacts must not contain TBD, draft, or not-run placeholders.");
+    }
+    return errors;
+}
+function artifactRejected(kind, errors) {
+    return new VcmError({
+        code: "ARTIFACT_VALIDATION_FAILED",
+        message: `${kind} was not written because validation failed:\n${errors.map((error) => `- ${error}`).join("\n")}`,
+        statusCode: 422,
+        hint: "Correct the candidate and submit it again with .ai/tools/vcm-artifact."
+    });
+}
+async function validateDynamicArtifact(fs, input, content, workflowControlService) {
+    if (input.mode !== "final") {
+        throw artifactRejected(input.kind, ["Dynamic artifacts must be submitted in final mode."]);
+    }
+    const artifactPath = normalizeRelativeArtifactPath(input.artifactPath);
+    if (input.kind === "route-message") {
+        const route = DEFAULT_MESSAGE_ROUTES.find(([fromRole, toRole]) => artifactPath === path.posix.join(input.handoffDir, "messages", `${fromRole}-${toRole}.md`));
+        if (!route || route[0] !== input.role) {
+            throw artifactRejected(input.kind, ["Route-message path must name the submitting role as the sender."]);
+        }
+        validateRouteMessage(content);
+        if (input.role === "project-manager") {
+            if (!workflowControlService) {
+                throw new VcmError({
+                    code: "WORKFLOW_CONTROL_UNAVAILABLE",
+                    message: "Workflow Control is unavailable.",
+                    statusCode: 503
+                });
+            }
+            await workflowControlService.assertRouteAuthorized({
+                taskRepoRoot: input.repoRoot,
+                stateRoot: input.stateRoot ?? ".ai/vcm",
+                handoffDir: input.handoffDir,
+                taskSlug: input.taskSlug,
+                routePath: artifactPath,
+                targetRole: route[1]
+            });
+        }
+        return { kind: input.kind, root: input.repoRoot, path: artifactPath };
+    }
+    if (input.kind === "coder-worker-report") {
+        if (input.role !== "coder" || !/^\.ai\/vcm\/coder-workers\/reports\/[A-Za-z0-9._-]+\.md$/.test(artifactPath)) {
+            throw artifactRejected(input.kind, ["Coder Worker reports must use the assigned .ai/vcm/coder-workers/reports/<worker-id>.md path."]);
+        }
+        validateCoderWorkerReport(content);
+        return { kind: input.kind, root: input.repoRoot, path: artifactPath };
+    }
+    if (input.kind === "gate-review-report") {
+        if (input.role !== "reviewer" || !/^\.ai\/vcm\/gate-reviews\/requests\/[A-Za-z0-9._-]+\.report\.md$/.test(artifactPath)) {
+            throw artifactRejected(input.kind, ["Reviewer must submit the assigned request report path."]);
+        }
+        await validateGateReviewReport(fs, input.repoRoot, artifactPath, content);
+        return { kind: input.kind, root: input.repoRoot, path: artifactPath };
+    }
+    if (input.kind === "memory-proposal") {
+        if (!VCM_ROLE_NAMES.includes(input.role)) {
+            throw artifactRejected(input.kind, ["Only a VCM workflow role may submit a Memory Proposal."]);
+        }
+        if (!/^\.ai\/vcm\/memory-review\/(?:runs\/[A-Za-z0-9._-]+\/drafts|candidates)\/[A-Za-z0-9._-]+\.md$/.test(artifactPath)) {
+            throw artifactRejected(input.kind, ["Memory proposal path is outside the VCM memory-review draft locations."]);
+        }
+        const memoryError = validateMemoryProposal(content);
+        if (memoryError) {
+            throw artifactRejected(input.kind, [`Memory proposal ${memoryError}.`]);
+        }
+        return { kind: input.kind, root: input.repoRoot, path: artifactPath };
+    }
+    if (input.kind === "harness-feedback") {
+        if (!VCM_ROLE_NAMES.includes(input.role)) {
+            throw artifactRejected(input.kind, ["Only a VCM workflow role may submit Harness Feedback."]);
+        }
+        if (!/^\.ai\/vcm\/harness-feedback\/pending\/[A-Za-z0-9._-]+\.md$/.test(artifactPath)) {
+            throw artifactRejected(input.kind, ["Harness Feedback path must be under .ai/vcm/harness-feedback/pending/. "]);
+        }
+        validateHarnessFeedback(content);
+        return { kind: input.kind, root: input.baseRepoRoot, path: artifactPath };
+    }
+    if (input.kind === "retrospective-report") {
+        if (input.role !== "harness-engineer") {
+            throw artifactRejected(input.kind, ["Only Harness Engineer may submit a retrospective report."]);
+        }
+        if (!/^\.ai\/vcm\/harness-feedback\/task-retrospectives\/[A-Za-z0-9._-]+\.md$/.test(artifactPath)) {
+            throw artifactRejected(input.kind, ["Retrospective report path must be under .ai/vcm/harness-feedback/task-retrospectives/."]);
+        }
+        validateRetrospectiveReport(content);
+        return { kind: input.kind, root: input.baseRepoRoot, path: artifactPath };
+    }
+    throw new VcmError({
+        code: "ARTIFACT_KIND_INVALID",
+        message: `Unknown managed artifact kind: ${input.kind}`,
+        statusCode: 400
+    });
+}
+function validateRetrospectiveReport(content) {
+    const errors = getRetrospectiveReportErrors(content);
+    if (errors.length > 0)
+        throw artifactRejected("retrospective-report", errors);
+}
+export 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(`^## ${escapeRegExp(heading)}\\s*$`, "m").test(content)) {
+            errors.push(`Missing required section: ${heading}.`);
+        }
+    }
+    return errors;
+}
+function validateCoderWorkerReport(content) {
+    const errors = [];
+    if (!/^# Coder Worker Report:\s*\S.+$/m.test(content)) {
+        errors.push("Coder Worker report requires '# Coder Worker Report: <worker-id>'.");
+    }
+    if (!/^Worker State:\s*completed\s*$/m.test(content)) {
+        errors.push("Worker State must be completed.");
+    }
+    if (!/^Implementation Result:\s*(success|has_failed_items)\s*$/m.test(content)) {
+        errors.push("Implementation Result must be success|has_failed_items.");
+    }
+    for (const heading of [
+        "Assigned Scope", "Item Dispositions", "Files Changed", "Tests Added Or Updated",
+        "L0/L1 Checks", "Commit", "Skipped Assigned Checks", "Objective Failures"
+    ]) {
+        if (!new RegExp(`^## ${escapeRegExp(heading)}\\s*$`, "m").test(content)) {
+            errors.push(`Missing required section: ${heading}.`);
+        }
+    }
+    if (errors.length > 0)
+        throw artifactRejected("coder-worker-report", errors);
+}
+function validateRouteMessage(content) {
+    const type = /^type:\s*(\S+)\s*$/m.exec(content)?.[1];
+    const allowed = new Set(["task", "question", "revise", "cancel", "result", "blocked", "finding"]);
+    if (!type || !allowed.has(type)) {
+        throw artifactRejected("route-message", ["Frontmatter type must be one of task|question|revise|cancel|result|blocked|finding."]);
+    }
+    if (!content.startsWith("---\n") || !/\n---\n/.test(content) || !content.split(/\n---\n/, 2)[1]?.trim()) {
+        throw artifactRejected("route-message", ["Route message requires frontmatter and a non-empty body."]);
+    }
+}
+async function validateGateReviewReport(fs, repoRoot, artifactPath, content) {
+    const requestId = path.posix.basename(artifactPath, ".report.md");
+    const requestPath = path.posix.join(".ai/vcm/gate-reviews/requests", `${requestId}.json`);
+    const absoluteRequestPath = resolveRepoPath(repoRoot, requestPath);
+    if (!(await fs.pathExists(absoluteRequestPath))) {
+        throw artifactRejected("gate-review-report", [`Gate request does not exist: ${requestPath}.`]);
+    }
+    const request = await fs.readJson(absoluteRequestPath);
+    const fields = Object.fromEntries(["Gate", "Request", "Decision", "Summary"].map((field) => [
+        field,
+        new RegExp(`^${field}:\\s*(.+?)\\s*$`, "mi").exec(content)?.[1]?.trim()
+    ]));
+    const errors = [];
+    if (fields.Gate !== request.gate)
+        errors.push(`Gate must be ${request.gate ?? "the requested gate"}.`);
+    if (fields.Request !== request.requestId)
+        errors.push(`Request must be ${request.requestId ?? requestId}.`);
+    if (fields.Decision !== "approve" && fields.Decision !== "request_changes")
+        errors.push("Decision must be approve|request_changes.");
+    if (!fields.Summary)
+        errors.push("Summary is required.");
+    const requiredSection = request.gate === "architecture-plan"
+        ? "Architecture Analysis"
+        : request.gate === "validation-adequacy"
+            ? "Validation Analysis"
+            : "Code Diff Analysis";
+    if (!new RegExp(`^## ${escapeRegExp(requiredSection)}\\s*$`, "m").test(content)) {
+        errors.push(`Missing required section: ${requiredSection}.`);
+    }
+    if (!/^## Findings\s*$/m.test(content))
+        errors.push("Missing required section: Findings.");
+    if (errors.length > 0)
+        throw artifactRejected("gate-review-report", errors);
+}
+function validateHarnessFeedback(content) {
+    const errors = [];
+    if (!/^#\s+\S.+$/m.test(content))
+        errors.push("Harness Feedback requires a title.");
+    for (const field of [
+        "Reporter role", "Task slug", "Summary", "Observed problem", "Expected behavior",
+        "Evidence", "Suspected harness area", "Impact", "Urgency"
+    ]) {
+        if (!new RegExp(`^- ${escapeRegExp(field)}:\\s*\\S`, "m").test(content)) {
+            errors.push(`Harness Feedback is missing ${field}.`);
+        }
+    }
+    if (!/^- Urgency:\s*(low|medium|high)\s*$/m.test(content)) {
+        errors.push("Urgency must be low|medium|high.");
+    }
+    if (errors.length > 0)
+        throw artifactRejected("harness-feedback", errors);
+}
+function normalizeRelativeArtifactPath(value) {
+    const normalized = value?.replaceAll("\\", "/").replace(/^\.\//, "").trim();
+    if (!normalized || path.posix.isAbsolute(normalized) || normalized.split("/").includes("..")) {
+        throw artifactRejected("dynamic artifact", ["A safe repository-relative --path is required."]);
+    }
+    return normalized;
+}
+function normalizeSubmissionContent(content) {
+    return `${content.replace(/\r\n/g, "\n").trimEnd()}\n`;
+}
+async function writeAtomic(fs, absolutePath, content) {
+    if (fs.writeTextAtomic) {
+        await fs.writeTextAtomic(absolutePath, content);
+        return;
+    }
+    await fs.writeText(absolutePath, content);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function getLegacyRoleCommandPath(roleCommandsDir, role) {
     return path.posix.join(roleCommandsDir, `${role}-command.md`);
 }

package/dist/backend/services/auto-memory-service.js

@@ -905,12 +905,12 @@ function buildRoleDraftPrompt(taskRepoRoot, state, draft, planningCandidatePath)
                 "Review that candidate against final task evidence. Carry forward only facts that remain verified after implementation and testing."
             ]
             : []),
-        `Write the draft to: ${resolveRepoPath(taskRepoRoot, draft.path)}`
+        `Assigned proposal path: ${resolveRepoPath(taskRepoRoot, draft.path)}`
     ];
     return [
         ...prompt,
         "",
-        "End the turn after writing the draft."
+        "End the turn after VCM accepts the proposal."
     ].join("\n");
 }
 function requireMemoryFileDefinition(filePath) {

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

@@ -1,7 +1,7 @@
 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 { checkMarkdownArtifact } from "../../shared/validation/artifact-check.js";
+import { checkMarkdownArtifact, readArtifactSectionValue } from "../../shared/validation/artifact-check.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
@@ -292,6 +292,32 @@ export function createGateReviewService(deps) {
                 message: `${coreInput.path} is ${coreInput.status}.`
             };
         }
+        if (gate === "architecture-plan") {
+            const architecturePlanError = await readArchitecturePlanError(deps.fs, context.taskRepoRoot);
+            if (architecturePlanError) {
+                index = applyGateState(index, gate, {
+                    status: "failed",
+                    decision: undefined,
+                    error: architecturePlanError,
+                    exceptionReason: undefined,
+                    requestId: undefined,
+                    requestPath: undefined,
+                    inputHash: undefined,
+                    requestedAt: undefined,
+                    startedAt: undefined,
+                    completedAt: now(),
+                    callbackStatus: "not_sent",
+                    callbackError: undefined
+                }, now(), true);
+                await saveIndex(deps.fs, context.taskRepoRoot, index);
+                return {
+                    status: "failed_to_start",
+                    gate,
+                    record: index.gates[gate],
+                    message: architecturePlanError
+                };
+            }
+        }
         if (gate === "validation-adequacy") {
             const validationReportError = await readValidationReportError(deps.fs, context.taskRepoRoot);
             if (validationReportError) {
@@ -319,7 +345,7 @@ export function createGateReviewService(deps) {
             }
         }
         if (gate === "code-diff") {
-            const prerequisiteError = await readCodeDiffPrerequisiteError(deps, context, index);
+            const prerequisiteError = await readCodeDiffPrerequisiteError(deps, context, index, codeDiffSource);
             if (prerequisiteError) {
                 index = applyGateState(index, gate, {
                     status: "failed",
@@ -1234,19 +1260,18 @@ async function readCoreInputArtifact(fs, taskRepoRoot, gate) {
 async function readArchitectureBriefError(fs, taskRepoRoot) {
     const relativePath = ".ai/vcm/handoffs/architecture-brief.md";
     const absolutePath = resolveRepoPath(taskRepoRoot, relativePath);
-    if (!await fs.pathExists(absolutePath)) {
+    const content = await fs.pathExists(absolutePath) ? await fs.readText(absolutePath) : null;
+    if (content === null)
         return `${relativePath} is missing. Complete Architect Interview before architecture planning.`;
-    }
-    const content = await fs.readText(absolutePath);
-    const check = checkMarkdownArtifact("architecture-brief", relativePath, content);
-    if (check.status !== "ok") {
-        return `${relativePath} is incomplete and cannot start architecture-plan review. ${formatArtifactCheckFailure(check)}`;
-    }
     const status = /^\s*Architecture Brief Status\s*:\s*(.+?)\s*$/im.exec(content)?.[1]?.trim();
     if (status?.toLowerCase() !== "confirmed") {
         return `${relativePath} is not confirmed and cannot start architecture-plan review. `
             + `Architecture Brief Status must be exactly "confirmed"; found ${renderFoundValue(status)}.`;
     }
+    const check = checkMarkdownArtifact("architecture-brief", relativePath, content);
+    if (check.status !== "ok") {
+        return `${relativePath} is incomplete and cannot start architecture-plan review. ${formatArtifactCheckFailure(check)}`;
+    }
     return undefined;
 }
 async function readValidationReportError(fs, taskRepoRoot) {
@@ -1270,41 +1295,63 @@ async function readValidationReportError(fs, taskRepoRoot) {
     }
     return undefined;
 }
-async function readCodeDiffPrerequisiteError(deps, context, index) {
+async function readCodeDiffPrerequisiteError(deps, context, index, source) {
     const reportError = await readValidationReportError(deps.fs, context.taskRepoRoot);
     if (reportError) {
         return "code-diff requires completed Tester validation. " + reportError;
     }
     const validationGate = index.gates["validation-adequacy"];
-    if (!validationGate.required) {
-        return undefined;
-    }
-    if (validationGate.status === "skipped" || validationGate.status === "overridden") {
-        return undefined;
-    }
-    if (validationGate.status !== "completed" || validationGate.decision !== "approve") {
-        return "code-diff requires the validation-adequacy Gate to complete successfully for the current Tester evidence.";
-    }
-    const currentValidationHash = await computeInputHash(deps, context.taskRepoRoot, "validation-adequacy");
-    if (!validationGate.inputHash || validationGate.inputHash !== currentValidationHash) {
-        return "code-diff requires a current validation-adequacy approval; code or test evidence changed after the recorded approval.";
+    if (validationGate.required && validationGate.status !== "skipped" && validationGate.status !== "overridden") {
+        if (validationGate.status !== "completed" || validationGate.decision !== "approve") {
+            return "code-diff requires the validation-adequacy Gate to complete successfully for the current Tester evidence.";
+        }
+        const currentValidationHash = await computeInputHash(deps, context.taskRepoRoot, "validation-adequacy");
+        if (!validationGate.inputHash || validationGate.inputHash !== currentValidationHash) {
+            return "code-diff requires a current validation-adequacy approval; code or test evidence changed after the recorded approval.";
+        }
     }
-    return undefined;
+    return readCodeDiffSourceArtifactError(deps.fs, context.taskRepoRoot, source);
 }
 async function readArchitectureEvidenceError(fs, taskRepoRoot) {
     const relativePath = ".ai/vcm/handoffs/architecture-evidence.md";
     const absolutePath = resolveRepoPath(taskRepoRoot, relativePath);
-    if (!await fs.pathExists(absolutePath)) {
-        return `${relativePath} is missing. Complete architecture evidence before requesting architecture-plan review.`;
+    const content = await fs.pathExists(absolutePath) ? await fs.readText(absolutePath) : null;
+    const check = checkMarkdownArtifact("architecture-evidence", relativePath, content);
+    if (check.status !== "ok") {
+        return `${relativePath} is incomplete and cannot start architecture-plan review. ${formatArtifactCheckFailure(check)}`;
     }
-    const content = await fs.readText(absolutePath);
-    if (content.trim().length === 0) {
-        return `${relativePath} is empty. Complete architecture evidence before requesting architecture-plan review.`;
+    return undefined;
+}
+async function readArchitecturePlanError(fs, taskRepoRoot) {
+    const relativePath = ".ai/vcm/handoffs/architecture-plan.md";
+    const absolutePath = resolveRepoPath(taskRepoRoot, relativePath);
+    const content = await fs.pathExists(absolutePath) ? await fs.readText(absolutePath) : null;
+    const check = checkMarkdownArtifact("architecture-plan", relativePath, content);
+    return check.status === "ok"
+        ? undefined
+        : `${relativePath} is incomplete and cannot start architecture-plan review. ${formatArtifactCheckFailure(check)}`;
+}
+async function readCodeDiffSourceArtifactError(fs, taskRepoRoot, source) {
+    if (!source) {
+        return "code-diff requires a production-code source.";
+    }
+    const sourceArtifacts = {
+        coder: ["coder-completion", ".ai/vcm/handoffs/coder-completion.md", "ready_for_review"],
+        "architect-debug": ["architect-debug", ".ai/vcm/handoffs/architect-debug.md", "completed"],
+        "architect-diagnosis": ["architecture-diagnosis", ".ai/vcm/handoffs/architecture-diagnosis.md", "diagnosis implementation completed"]
+    };
+    const [kind, relativePath, terminalValue] = sourceArtifacts[source];
+    const absolutePath = resolveRepoPath(taskRepoRoot, relativePath);
+    const content = await fs.pathExists(absolutePath) ? await fs.readText(absolutePath) : null;
+    const check = checkMarkdownArtifact(kind, relativePath, content);
+    if (check.status !== "ok") {
+        return `code-diff requires a complete ${relativePath}. ${formatArtifactCheckFailure(check)}`;
     }
-    const status = /^\s*Architecture Evidence Status\s*:\s*(.+?)\s*$/im.exec(content)?.[1]?.trim();
-    if (status?.toLowerCase() !== "complete") {
-        return `${relativePath} is incomplete and cannot start architecture-plan review. `
-            + `Architecture Evidence Status must be exactly "complete"; found ${renderFoundValue(status)}.`;
+    const value = kind === "architecture-diagnosis"
+        ? readArtifactSectionValue(content ?? "", "Final Disposition")?.toLowerCase()
+        : matchField(content ?? "", kind === "coder-completion" ? "Decision" : "Status");
+    if (value !== terminalValue) {
+        return `code-diff requires ${relativePath} to report ${terminalValue}; found ${renderFoundValue(value)}.`;
     }
     return undefined;
 }
@@ -1370,11 +1417,12 @@ Worktree: ${context.taskRepoRoot}
 Gate: ${gate}
 Request: ${requestId}
 Report: ${absoluteReportPath}
+Submit: .ai/tools/vcm-artifact gate-review-report --file <candidate> --path ${reportPath} --mode final
 
 Evidence:
 ${evidence}${capturedEvidence}${gitLine}${architectureContract}${validationContract}${codeDiffContract}${codeDiffSection}
 
-Write only Report. Start exactly:
+Write only the candidate Report and submit it with the command above. Start exactly:
 Gate: ${gate}
 Request: ${requestId}
 Decision: approve|request_changes

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

@@ -4,6 +4,7 @@ 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`;
@@ -131,8 +132,11 @@ export function createHarnessFeedbackService(deps) {
             return true;
         }
         const reportPath = resolveRepoPath(repoRoot, marker.analysisPath);
-        const reportReady = await deps.fs.pathExists(reportPath)
-            && Boolean((await deps.fs.readText(reportPath)).trim());
+        const reportContent = await deps.fs.pathExists(reportPath)
+            ? await deps.fs.readText(reportPath)
+            : "";
+        const reportErrors = reportContent.trim() ? getRetrospectiveReportErrors(reportContent) : ["Report is empty."];
+        const reportReady = reportErrors.length === 0;
         if (!reportReady || (marker.memoryRunId && !input.memoryReviewSucceeded)) {
             await persistTaskRetrospectiveMarker(repoRoot, {
                 ...marker,
@@ -140,7 +144,7 @@ export function createHarnessFeedbackService(deps) {
                 failedAt: timestamp,
                 updatedAt: timestamp,
                 error: !reportReady
-                    ? "Harness Engineer did not write the required Task Harness Retrospective report."
+                    ? `Harness Engineer did not write a valid Task Harness Retrospective report: ${reportErrors.join(" ")}`
                     : "Task Harness Retrospective memory review failed."
             });
             return true;
@@ -244,6 +248,8 @@ export function createHarnessFeedbackService(deps) {
                     "Process every listed feedback inside this retrospective. Record every disposition in the retrospective report, then delete the processed feedback files before ending the turn."
                 ]
                 : []),
+            "",
+            "The report must contain: # Task Harness Retrospective: <task>, ## Findings, ## Feedback Dispositions, ## Recommended Harness Changes, and ## VCM Issue Drafts.",
             ...(memoryReview
                 ? [
                     "",
@@ -305,7 +311,8 @@ export function createHarnessFeedbackService(deps) {
                 : []),
             "",
             `Write the analysis to Result Path: ${resolveRepoPath(repoRoot, analysisPath)}`,
-            "End your turn after writing the result."
+            `Submit with: .ai/tools/vcm-artifact retrospective-report --file <candidate> --path ${analysisPath} --mode final`,
+            "End your turn after VCM accepts the result."
         ].join("\n");
     }
     function renderMemoryProposalDecisionTemplate(candidate) {