vibe-coding-master 0.7.4 → 0.7.5

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

@@ -3,7 +3,7 @@ import { DISPATCHABLE_ROLES } from "../../shared/constants.js";
 import { checkMarkdownArtifact } from "../../shared/validation/artifact-check.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
-import { renderArchitecturePlanTemplate, renderCoderCompletionTemplate, renderDocsSyncReportTemplate, renderFinalAcceptanceTemplate, renderKnownIssuesTemplate, renderMessageRouteTemplate, renderTestReportTemplate } from "../templates/handoff.js";
+import { renderArchitecturePlanTemplate, renderArchitectDebugTemplate, renderCoderCompletionTemplate, renderDocsSyncReportTemplate, renderFinalAcceptanceTemplate, renderKnownIssuesTemplate, renderMessageRouteTemplate, renderTestReportTemplate } from "../templates/handoff.js";
 import { renderRoleCommandTemplate } from "../templates/role-command.js";
 const ARTIFACT_PATH_KEYS = [
     ["architecture-plan", "architecturePlanPath"],
@@ -62,6 +62,7 @@ export function createArtifactService(fs) {
                 [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.testReportPath, renderTestReportTemplate(input.taskSlug)],
                 [paths.docsSyncReportPath, renderDocsSyncReportTemplate(input.taskSlug)],
                 [paths.finalAcceptancePath, renderFinalAcceptanceTemplate(input.taskSlug)],

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

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import path from "node:path";
 import { CODE_DIFF_SOURCES, GATE_REVIEW_GATES } from "../../shared/types/gate-review.js";
+import { checkMarkdownArtifact } from "../../shared/validation/artifact-check.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
@@ -13,13 +14,52 @@ const GATE_REVIEWER_ROLE = "gate-reviewer";
 const DEFAULT_REPORT_POLL_INTERVAL_MS = 1000;
 const DEFAULT_REPORT_TIMEOUT_MS = 30 * 60 * 1000;
 const activeRuns = new Set();
+const ARCHITECTURE_ANALYSIS_FIELDS = [
+    "Evidence Read",
+    "End-To-End Flow",
+    "Scope Fit",
+    "Code Reality",
+    "Ownership",
+    "Data Flow",
+    "Lifecycle",
+    "Invariants",
+    "Boundaries And Public Surface",
+    "Failure Model",
+    "Coder Readiness"
+];
+const VALIDATION_ANALYSIS_FIELDS = [
+    "Evidence Read",
+    "Changed Behavior And Risk",
+    "Coverage Mapping",
+    "Baseline Coverage",
+    "Integration And E2E Coverage",
+    "Boundary And Failure Coverage",
+    "Public Contract Coverage",
+    "Test Integrity",
+    "Skips And Gaps",
+    "Validation Readiness"
+];
+const CODE_DIFF_ANALYSIS_FIELDS = [
+    "Commit Range And Sources",
+    "Evidence Read",
+    "Changed Files And Symbols",
+    "Changed Behavior",
+    "Source Evidence Fit",
+    "Callers And Public Surface",
+    "State Lifecycle And Failure Paths",
+    "Coding Standards",
+    "Baseline Test Integrity",
+    "Generated Context And Durable Docs",
+    "Code Readiness"
+];
 const SOURCE_ARTIFACTS = {
     "architecture-plan": [
         ".ai/vcm/handoffs/architecture-plan.md"
     ],
     "validation-adequacy": [
         ".ai/vcm/handoffs/architecture-plan.md",
-        ".ai/vcm/handoffs/test-report.md"
+        ".ai/vcm/handoffs/test-report.md",
+        "docs/TESTING.md"
     ],
     "code-diff": []
 };
@@ -29,7 +69,8 @@ const CODE_DIFF_SOURCE_ARTIFACTS = {
         ".ai/vcm/handoffs/coder-completion.md"
     ],
     "architect-debug": [
-        ".ai/vcm/handoffs/role-commands/architect.md"
+        ".ai/vcm/handoffs/role-commands/architect.md",
+        ".ai/vcm/handoffs/architect-debug.md"
     ],
     "architect-diagnosis": [
         ".ai/vcm/handoffs/architecture-diagnosis.md"
@@ -103,6 +144,7 @@ export function createGateReviewService(deps) {
                 decision: undefined,
                 error: message,
                 codeDiffSource: undefined,
+                codeDiffSources: undefined,
                 requestId: undefined,
                 requestPath: undefined,
                 inputHash: undefined,
@@ -143,6 +185,7 @@ export function createGateReviewService(deps) {
                     changedFiles: undefined,
                     diffStat: undefined,
                     codeDiffSource,
+                    codeDiffSources: codeDiffSource ? [codeDiffSource] : undefined,
                     requestedAt: undefined,
                     startedAt: undefined,
                     completedAt: now(),
@@ -200,6 +243,7 @@ export function createGateReviewService(deps) {
                 changedFiles: undefined,
                 diffStat: undefined,
                 codeDiffSource,
+                codeDiffSources: codeDiffSource ? [codeDiffSource] : undefined,
                 requestedAt: undefined,
                 startedAt: undefined,
                 completedAt: undefined,
@@ -214,7 +258,10 @@ export function createGateReviewService(deps) {
                 message: "No new commits to review."
             };
         }
-        const inputHash = await computeInputHash(deps, context.taskRepoRoot, gate, codeDiffInput, codeDiffSource);
+        const codeDiffSources = gate === "code-diff" && codeDiffInput && codeDiffSource
+            ? resolveCodeDiffSources(record, codeDiffInput, codeDiffSource)
+            : undefined;
+        const inputHash = await computeInputHash(deps, context.taskRepoRoot, gate, codeDiffInput, codeDiffSources);
         if (!options.force
             && record.status === "completed"
             && record.decision === "approve"
@@ -246,6 +293,7 @@ export function createGateReviewService(deps) {
             changedFiles: codeDiffInput?.changedFiles,
             diffStat: codeDiffInput?.diffStat,
             codeDiffSource,
+            codeDiffSources,
             requestedAt: timestamp,
             startedAt: undefined,
             completedAt: undefined,
@@ -270,12 +318,13 @@ export function createGateReviewService(deps) {
             requestedAt: timestamp,
             inputHash,
             codeDiffSource,
+            codeDiffSources,
             codeDiff: codeDiffInput,
             reportPath: nextRecord.reportPath,
             promptPath: nextRecord.promptPath
         });
         await saveIndex(deps.fs, context.taskRepoRoot, index);
-        void runGateReview(context, gate, requestId, codeDiffInput, codeDiffSource).catch(() => {
+        void runGateReview(context, gate, requestId, codeDiffInput, codeDiffSources).catch(() => {
             // runGateReview records failures in the persisted gate state.
         });
         return {
@@ -285,7 +334,7 @@ export function createGateReviewService(deps) {
             message: "Gate review started."
         };
     }
-    async function runGateReview(context, gate, requestId, codeDiffInput, codeDiffSource) {
+    async function runGateReview(context, gate, requestId, codeDiffInput, codeDiffSources) {
         const runKey = `${context.taskRepoRoot}:${context.taskSlug}:${gate}`;
         if (activeRuns.has(runKey)) {
             return;
@@ -302,7 +351,7 @@ export function createGateReviewService(deps) {
             await updateRequestStatus(deps.fs, context, requestId, "running", { startedAt: timestamp });
             const reviewDir = resolveRepoPath(context.taskRepoRoot, GATE_REVIEW_DIR);
             const agentPath = resolveRepoPath(context.repoRoot, GATE_REVIEW_AGENT_PATH);
-            const prompt = buildGatePrompt(context, gate, requestId, codeDiffInput, codeDiffSource);
+            const prompt = buildGatePrompt(context, gate, requestId, codeDiffInput, codeDiffSources);
             await deps.fs.ensureDir(reviewDir);
             await deps.fs.ensureDir(resolveRepoPath(context.taskRepoRoot, REQUESTS_DIR));
             await deps.fs.writeText(resolveRepoPath(context.taskRepoRoot, promptPathForRequest(requestId)), prompt);
@@ -333,6 +382,12 @@ export function createGateReviewService(deps) {
             const completedAt = now();
             await recordGateReviewerTurnStop(context, gateTurnStarted);
             gateTurnStarted = false;
+            await updateRequestStatus(deps.fs, context, requestId, "completed", {
+                completedAt,
+                decision: parsed.decision,
+                reportPath: parsed.reportPath
+            });
+            activeRuns.delete(runKey);
             await updateGateRecord(context, gate, {
                 status: "completed",
                 decision: parsed.decision,
@@ -344,11 +399,6 @@ export function createGateReviewService(deps) {
                 callbackError: undefined,
                 updatedAt: completedAt
             }, { clearActiveGate: true });
-            await updateRequestStatus(deps.fs, context, requestId, "completed", {
-                completedAt,
-                decision: parsed.decision,
-                reportPath: parsed.reportPath
-            });
             await callbackProjectManager(context, gate, "completed", parsed.decision, parsed.reportPath);
         }
         catch (error) {
@@ -356,6 +406,11 @@ export function createGateReviewService(deps) {
             const message = errorMessage(error);
             await recordGateReviewerTurnStop(context, gateTurnStarted);
             gateTurnStarted = false;
+            await updateRequestStatus(deps.fs, context, requestId, "failed", {
+                completedAt: timestamp,
+                error: message
+            });
+            activeRuns.delete(runKey);
             await updateGateRecord(context, gate, {
                 status: "failed",
                 error: message,
@@ -364,10 +419,6 @@ export function createGateReviewService(deps) {
                 callbackError: undefined,
                 updatedAt: timestamp
             }, { clearActiveGate: true });
-            await updateRequestStatus(deps.fs, context, requestId, "failed", {
-                completedAt: timestamp,
-                error: message
-            });
             await callbackProjectManager(context, gate, "failed", undefined, reportPathForGate(gate), message);
         }
         finally {
@@ -598,6 +649,7 @@ function normalizeIndex(raw, config, timestamp) {
             changedFiles: Array.isArray(existing?.changedFiles) ? existing.changedFiles.filter(isString) : undefined,
             diffStat: typeof existing?.diffStat === "string" ? existing.diffStat : undefined,
             codeDiffSource: isCodeDiffSource(existing?.codeDiffSource) ? existing.codeDiffSource : undefined,
+            codeDiffSources: normalizeCodeDiffSources(existing?.codeDiffSources, existing?.codeDiffSource),
             summary: typeof existing?.summary === "string" ? existing.summary : undefined,
             findings: Array.isArray(existing?.findings) ? existing.findings.filter(isFinding) : undefined,
             error: typeof existing?.error === "string" ? existing.error : undefined,
@@ -766,23 +818,25 @@ async function isAncestor(runner, cwd, ancestor, descendant) {
     const result = await runner.run("git", ["merge-base", "--is-ancestor", ancestor, descendant], { cwd });
     return result.exitCode === 0;
 }
-async function computeInputHash(deps, taskRepoRoot, gate, codeDiffInput, codeDiffSource) {
+async function computeInputHash(deps, taskRepoRoot, gate, codeDiffInput, codeDiffSources) {
     const digest = createHash("sha256");
     const coreArtifact = CORE_INPUT_ARTIFACTS[gate];
     if (coreArtifact) {
         digest.update(coreArtifact);
         digest.update(await deps.fs.readText(resolveRepoPath(taskRepoRoot, coreArtifact)));
-        return digest.digest("hex");
     }
     const common = [
         "CLAUDE.md",
+        ".claude/agents/architect.md",
+        ".claude/agents/coder.md",
         ".claude/agents/gate-reviewer.md",
+        ".claude/agents/tester.md",
         ".claude/skills/vcm-gate-review/SKILL.md",
         ".ai/tools/request-gate-review",
         "docs/CODING_STANDARDS.md"
     ];
-    const sourceArtifacts = getSourceArtifacts(gate, codeDiffSource);
-    for (const relativePath of [...common, ...sourceArtifacts]) {
+    const sourceArtifacts = getSourceArtifacts(gate, codeDiffSources);
+    for (const relativePath of new Set([...common, ...sourceArtifacts].filter((item) => item !== coreArtifact))) {
         digest.update(relativePath);
         const absolutePath = resolveRepoPath(taskRepoRoot, relativePath);
         if (await deps.fs.pathExists(absolutePath)) {
@@ -793,8 +847,8 @@ async function computeInputHash(deps, taskRepoRoot, gate, codeDiffInput, codeDif
         }
     }
     if (gate === "code-diff" && codeDiffInput) {
-        digest.update("codeDiffSource");
-        digest.update(codeDiffSource ?? "<missing>");
+        digest.update("codeDiffSources");
+        digest.update(codeDiffSources?.join("\n") ?? "<missing>");
         digest.update("baseCommit");
         digest.update(codeDiffInput.baseCommit);
         digest.update("headCommit");
@@ -807,9 +861,44 @@ async function computeInputHash(deps, taskRepoRoot, gate, codeDiffInput, codeDif
         digest.update(codeDiffInput.diffHash);
     }
     if (gate === "architecture-plan") {
-        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["status", "--porcelain=v1"]));
-        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["diff", "--binary"]));
-        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["diff", "--cached", "--binary"]));
+        const evidencePathspec = ["--", ".", ":(exclude).ai/vcm/**"];
+        digest.update("head");
+        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["rev-parse", "HEAD"]));
+        digest.update("workingDiff");
+        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["diff", "--binary", ...evidencePathspec]));
+        digest.update("stagedDiff");
+        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["diff", "--cached", "--binary", ...evidencePathspec]));
+        const untracked = splitLines(await commandStdout(deps.runner, taskRepoRoot, [
+            "ls-files",
+            "--others",
+            "--exclude-standard",
+            ...evidencePathspec
+        ]));
+        for (const relativePath of untracked) {
+            digest.update("untracked");
+            digest.update(relativePath);
+            digest.update(await commandStdout(deps.runner, taskRepoRoot, ["hash-object", "--", relativePath]));
+        }
+    }
+    if (gate === "validation-adequacy") {
+        const evidencePathspec = ["--", ".", ":(exclude).ai/vcm/**", ":(exclude)docs/**"];
+        digest.update("trackedEvidence");
+        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["ls-files", "-s", ...evidencePathspec]));
+        digest.update("workingEvidence");
+        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["diff", "--binary", ...evidencePathspec]));
+        digest.update("stagedEvidence");
+        digest.update(await commandStdout(deps.runner, taskRepoRoot, ["diff", "--cached", "--binary", ...evidencePathspec]));
+        const untracked = splitLines(await commandStdout(deps.runner, taskRepoRoot, [
+            "ls-files",
+            "--others",
+            "--exclude-standard",
+            ...evidencePathspec
+        ]));
+        for (const relativePath of untracked) {
+            digest.update("untrackedEvidence");
+            digest.update(relativePath);
+            digest.update(await commandStdout(deps.runner, taskRepoRoot, ["hash-object", "--", relativePath]));
+        }
     }
     return digest.digest("hex");
 }
@@ -838,21 +927,30 @@ function splitLines(value) {
         .map((line) => line.trim())
         .filter(Boolean);
 }
-function buildGatePrompt(context, gate, requestId, codeDiffInput, codeDiffSource) {
+function buildGatePrompt(context, gate, requestId, codeDiffInput, codeDiffSources) {
     const reportPath = reportPathForGate(gate);
     const absoluteReportPath = resolveRepoPath(context.taskRepoRoot, reportPath);
-    const evidence = getSourceArtifacts(gate, codeDiffSource)
+    const evidence = getSourceArtifacts(gate, codeDiffSources)
         .map((relativePath) => `- ${relativePath}`)
         .join("\n");
     const gitLine = gate === "architecture-plan"
         ? "\nDiff: inspect git status/diff in Worktree."
         : "";
+    const architectureContract = gate === "architecture-plan"
+        ? "\n\nComplete every Architecture Analysis field required by the Gate Reviewer role with concrete current-worktree evidence before deciding."
+        : "";
+    const validationContract = gate === "validation-adequacy"
+        ? "\n\nComplete every Validation Analysis field required by the Gate Reviewer role with concrete current-worktree production and test evidence before deciding."
+        : "";
+    const codeDiffContract = gate === "code-diff"
+        ? "\n\nComplete every Code Diff Analysis field required by the Gate Reviewer role with concrete evidence from the named commit range before deciding."
+        : "";
     const codeDiffSection = gate === "code-diff" && codeDiffInput
         ? `
 
 Code Diff Input:
 This code-diff gate reviews the new commits from one PM route flow, not the whole task and not one terminal turn.
-Code source: ${codeDiffSource}
+Code sources: ${codeDiffSources?.join(" -> ") ?? "<missing>"}
 Base commit: ${codeDiffInput.baseCommit}
 Head commit: ${codeDiffInput.headCommit}
 Commits:
@@ -873,7 +971,7 @@ Request: ${requestId}
 Report: ${absoluteReportPath}
 
 Evidence:
-${evidence}${gitLine}${codeDiffSection}
+${evidence}${gitLine}${architectureContract}${validationContract}${codeDiffContract}${codeDiffSection}
 
 Write only Report. Start exactly:
 Gate: ${gate}
@@ -940,17 +1038,155 @@ async function parseGateReport(fs, taskRepoRoot, gate, requestId, timestamp) {
             statusCode: 500
         });
     }
+    const findings = extractFindings(content);
+    if (gate === "architecture-plan") {
+        validateArchitectureAnalysis(content);
+    }
+    if (gate === "validation-adequacy") {
+        validateValidationAnalysis(content);
+        if (decision === "approve") {
+            await validateValidationApprovalInput(fs, taskRepoRoot);
+        }
+    }
+    if (gate === "code-diff") {
+        validateCodeDiffAnalysis(content);
+    }
+    if (decision === "request_changes") {
+        validateRequestChangeFindings(findings);
+        if (gate === "code-diff") {
+            validateCodeDiffFindings(findings);
+        }
+    }
     return {
         gate,
         requestId: parsedRequest,
         decision,
         summary: extractSummary(content),
-        findings: extractFindings(content),
+        findings,
         reportPath,
         content,
         parsedAt: timestamp
     };
 }
+function validateArchitectureAnalysis(content) {
+    const section = extractMarkdownSection(content, "Architecture Analysis");
+    if (!section) {
+        throw new VcmError({
+            code: "GATE_REVIEW_ARCHITECTURE_ANALYSIS_MISSING",
+            message: "Architecture-plan review must contain a non-empty Architecture Analysis section.",
+            statusCode: 500
+        });
+    }
+    const missingFields = ARCHITECTURE_ANALYSIS_FIELDS.filter((field) => !matchField(section, field));
+    if (missingFields.length > 0) {
+        throw new VcmError({
+            code: "GATE_REVIEW_ARCHITECTURE_ANALYSIS_INCOMPLETE",
+            message: `Architecture Analysis is missing required evidence: ${missingFields.join(", ")}.`,
+            statusCode: 500
+        });
+    }
+}
+function validateValidationAnalysis(content) {
+    const section = extractMarkdownSection(content, "Validation Analysis");
+    if (!section) {
+        throw new VcmError({
+            code: "GATE_REVIEW_VALIDATION_ANALYSIS_MISSING",
+            message: "Validation-adequacy review must contain a non-empty Validation Analysis section.",
+            statusCode: 500
+        });
+    }
+    const missingFields = VALIDATION_ANALYSIS_FIELDS.filter((field) => !matchField(section, field));
+    if (missingFields.length > 0) {
+        throw new VcmError({
+            code: "GATE_REVIEW_VALIDATION_ANALYSIS_INCOMPLETE",
+            message: `Validation Analysis is missing required evidence: ${missingFields.join(", ")}.`,
+            statusCode: 500
+        });
+    }
+}
+function validateCodeDiffAnalysis(content) {
+    const section = extractMarkdownSection(content, "Code Diff Analysis");
+    if (!section) {
+        throw new VcmError({
+            code: "GATE_REVIEW_CODE_DIFF_ANALYSIS_MISSING",
+            message: "Code-diff review must contain a non-empty Code Diff Analysis section.",
+            statusCode: 500
+        });
+    }
+    const missingFields = CODE_DIFF_ANALYSIS_FIELDS.filter((field) => !matchField(section, field));
+    if (missingFields.length > 0) {
+        throw new VcmError({
+            code: "GATE_REVIEW_CODE_DIFF_ANALYSIS_INCOMPLETE",
+            message: `Code Diff Analysis is missing required evidence: ${missingFields.join(", ")}.`,
+            statusCode: 500
+        });
+    }
+}
+async function validateValidationApprovalInput(fs, taskRepoRoot) {
+    const relativePath = CORE_INPUT_ARTIFACTS["validation-adequacy"];
+    if (!relativePath) {
+        return;
+    }
+    const absolutePath = resolveRepoPath(taskRepoRoot, relativePath);
+    const content = await fs.pathExists(absolutePath) ? await fs.readText(absolutePath) : null;
+    const check = checkMarkdownArtifact("test-report", relativePath, content);
+    const testResult = content ? matchField(content, "Test Result")?.toLowerCase() : undefined;
+    if (check.status === "ok" && testResult === "pass") {
+        return;
+    }
+    const details = [
+        check.status !== "ok" ? `status=${check.status}` : "",
+        check.missingHeadings.length > 0 ? `missing headings: ${check.missingHeadings.join(", ")}` : "",
+        check.invalidFields.length > 0 ? check.invalidFields.join(" ") : "",
+        check.hasPlaceholder ? "contains placeholders" : "",
+        testResult !== "pass" ? "Test Result must be pass before approval." : ""
+    ].filter(Boolean).join("; ");
+    throw new VcmError({
+        code: "GATE_REVIEW_VALIDATION_INPUT_INCOMPLETE",
+        message: `Validation-adequacy cannot approve incomplete Tester evidence in ${relativePath}. ${details}`,
+        statusCode: 500
+    });
+}
+function validateRequestChangeFindings(findings) {
+    if (findings.length === 0) {
+        throw new VcmError({
+            code: "GATE_REVIEW_FINDINGS_MISSING",
+            message: "A request_changes decision must contain at least one structured finding.",
+            statusCode: 500
+        });
+    }
+    const incomplete = findings.find((finding) => (!finding.evidence.trim()
+        || !finding.expected.trim()
+        || !finding.gap.trim()
+        || !finding.risk.trim()));
+    if (incomplete) {
+        throw new VcmError({
+            code: "GATE_REVIEW_FINDING_INCOMPLETE",
+            message: `Finding ${incomplete.title} must contain Evidence, Expected, Gap, and Risk.`,
+            statusCode: 500
+        });
+    }
+}
+function validateCodeDiffFindings(findings) {
+    const incomplete = findings.find((finding) => !finding.file?.trim() || !finding.location?.trim());
+    if (incomplete) {
+        throw new VcmError({
+            code: "GATE_REVIEW_CODE_DIFF_FINDING_LOCATION_MISSING",
+            message: `Code-diff finding ${incomplete.title} must contain File and Line Or Symbol.`,
+            statusCode: 500
+        });
+    }
+}
+function extractMarkdownSection(content, heading) {
+    const match = new RegExp(`^##\\s+${escapeRegex(heading)}\\s*$`, "im").exec(content);
+    if (!match || match.index === undefined) {
+        return undefined;
+    }
+    const remainder = content.slice(match.index + match[0].length);
+    const nextHeading = remainder.search(/^##\s+/m);
+    const section = (nextHeading >= 0 ? remainder.slice(0, nextHeading) : remainder).trim();
+    return section || undefined;
+}
 async function updateRequestStatus(fs, context, requestId, status, patch) {
     const requestPath = resolveRepoPath(context.taskRepoRoot, path.posix.join(REQUESTS_DIR, `${requestId}.json`));
     const current = await readJsonOrNull(fs, requestPath) ?? {
@@ -1018,6 +1254,7 @@ function extractFindings(content) {
             title,
             file: matchField(block, "file"),
             line: parsePositiveInteger(matchField(block, "line")),
+            location: matchField(block, "line or symbol"),
             evidence: matchField(block, "evidence") ?? "",
             expected: matchField(block, "expected") ?? "",
             gap: matchField(block, "gap") ?? "",
@@ -1026,11 +1263,30 @@ function extractFindings(content) {
     }
     return findings;
 }
-function getSourceArtifacts(gate, codeDiffSource) {
+function getSourceArtifacts(gate, codeDiffSources) {
     if (gate !== "code-diff") {
         return SOURCE_ARTIFACTS[gate];
     }
-    return codeDiffSource ? CODE_DIFF_SOURCE_ARTIFACTS[codeDiffSource] : [];
+    return [...new Set((codeDiffSources ?? []).flatMap((source) => CODE_DIFF_SOURCE_ARTIFACTS[source]))];
+}
+function resolveCodeDiffSources(record, codeDiffInput, currentSource) {
+    const continuingRecordedRange = record.baseCommit === codeDiffInput.baseCommit
+        && ((record.status === "completed" && record.decision === "request_changes")
+            || record.status === "failed");
+    if (!continuingRecordedRange) {
+        return [currentSource];
+    }
+    return [...new Set([
+            ...(normalizeCodeDiffSources(record.codeDiffSources, record.codeDiffSource) ?? []),
+            currentSource
+        ])];
+}
+function normalizeCodeDiffSources(sources, source) {
+    const normalized = Array.isArray(sources) ? sources.filter(isCodeDiffSource) : [];
+    if (normalized.length === 0 && isCodeDiffSource(source)) {
+        normalized.push(source);
+    }
+    return normalized.length > 0 ? [...new Set(normalized)] : undefined;
 }
 export function isCodeDiffSource(value) {
     return typeof value === "string" && CODE_DIFF_SOURCES.includes(value);
@@ -1119,6 +1375,10 @@ function errorMessage(error) {
 function isPendingReportError(error) {
     return error instanceof VcmError && [
         "GATE_REVIEW_DECISION_MISSING",
+        "GATE_REVIEW_ARCHITECTURE_ANALYSIS_MISSING",
+        "GATE_REVIEW_ARCHITECTURE_ANALYSIS_INCOMPLETE",
+        "GATE_REVIEW_FINDINGS_MISSING",
+        "GATE_REVIEW_FINDING_INCOMPLETE",
         "GATE_REVIEW_REPORT_GATE_MISMATCH",
         "GATE_REVIEW_REPORT_MISSING",
         "GATE_REVIEW_REPORT_STALE"

package/dist/backend/templates/handoff.js

@@ -7,10 +7,56 @@ TBD
 
 ## Current Code Reality
 
+### Planning Boundary
+
+TBD
+
+### Code Reading Evidence
+
+| File / Symbol | Called By | Calls / Consumers | State / Side Effects | Verified Behavior |
+| --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD |
+
+### Existing Behavior Trace
+
+TBD
+
+### Code / Docs Conflicts
+
 TBD
 
 ## Architecture Decision
 
+### Changed Behavior Flow
+
+TBD
+
+### Ownership
+
+TBD
+
+### Data Flow
+
+TBD
+
+### Lifecycle
+
+TBD
+
+### Boundaries
+
+TBD
+
+### Invariants
+
+TBD
+
+### Failure Model
+
+TBD
+
+### Decision Rationale
+
 TBD
 
 ## Module/File Plan
@@ -27,7 +73,7 @@ Task-specific context and coder guidance go here, not in source-code comments.
 Source-code comments should only describe durable behavior, contracts, invariants,
 error boundaries, or non-obvious logic that should remain useful after this task.
 
-| ID | File / Action | Why In Scope | Coder Work | Allowed Freedom | Expected VCM:CODE | Durable Comment Needs | Behavior / Contract Proof Points |
+| ID | File / Action | Current Evidence / Why In Scope | Coder Work | Allowed Freedom | Expected VCM:CODE | Durable Comment Needs | Behavior / Contract Proof Points |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | SCF-001 | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
 
@@ -73,6 +119,10 @@ TBD
 
 TBD
 
+## Coverage Mapping
+
+TBD
+
 ## Commands Run Or Checked
 
 TBD
@@ -145,6 +195,44 @@ TBD
 
 ## Objective Failures
 
+TBD
+`;
+}
+export function renderArchitectDebugTemplate(taskSlug) {
+    return `# Architect Debug: ${taskSlug}
+
+Status: pending|completed
+
+## PM-Routed Failure
+
+TBD
+
+## Confirmed Root Cause
+
+TBD
+
+## Implementation
+
+TBD
+
+## Changed Files And Public Surface
+
+TBD
+
+## Baseline Tests
+
+TBD
+
+## Diagnostic And L0-L3 Validation
+
+TBD
+
+## Generated Context
+
+TBD
+
+## Remaining Failure Evidence
+
 TBD
 `;
 }