vibe-coding-master 0.9.9 → 0.9.11

package/dist/backend/gateway/gateway-service.js

@@ -1346,6 +1346,22 @@ export function createGatewayService(deps) {
     }
     function formatGatewayRoleStopFailure(input, round) {
         const roundLabel = round?.roundSequence ? `第 ${round.roundSequence} 轮` : "当前 round";
+        const claudeMessage = input.lastAssistantMessage && input.lastAssistantMessage !== input.errorDetails
+            ? `Claude Code: ${truncateGatewayFailureDetails(input.lastAssistantMessage)}`
+            : undefined;
+        if (input.usageLimitWait) {
+            return [
+                "Claude 额度已用完，VCM 已暂停该角色，等待额度恢复。",
+                `Task: ${input.taskSlug}`,
+                `Role: ${input.role}`,
+                `Round: ${roundLabel}`,
+                claudeMessage,
+                "",
+                input.usageLimitWait.resetAt
+                    ? "VCM 会在额度恢复约 2 分钟后自动继续，无需操作。"
+                    : "Claude Code 没有给出恢复时间，VCM 每小时自动检查一次，恢复后自动继续。"
+            ].filter((line) => line !== undefined).join("\n");
+        }
         const retryLine = input.maxAttempts !== undefined
             ? `Retry: ${input.attempt ?? 0}/${input.maxAttempts}`
             : undefined;
@@ -1357,6 +1373,7 @@ export function createGatewayService(deps) {
             input.error ? `Reason: ${input.error}` : undefined,
             retryLine,
             input.errorDetails ? `Details: ${truncateGatewayFailureDetails(input.errorDetails)}` : undefined,
+            claudeMessage,
             "",
             "请在 VCM 中检查状态，或修复问题后继续给出下一步指令。"
         ].filter((line) => line !== undefined).join("\n");

package/dist/backend/server.js

@@ -276,7 +276,8 @@ export function createDefaultServerDeps(options = {}) {
     const artifactService = createArtifactService(fs, {
         workflowControlService,
         getDurableDocAssignment: (taskRepoRoot, role) => autoMemoryService.getDurableDocAssignment(taskRepoRoot, role),
-        getCompletedDurableDocAssignment: (taskRepoRoot, role, artifactPath) => autoMemoryService.getCompletedDurableDocAssignment(taskRepoRoot, role, artifactPath)
+        getCompletedDurableDocAssignment: (taskRepoRoot, role, artifactPath) => autoMemoryService.getCompletedDurableDocAssignment(taskRepoRoot, role, artifactPath),
+        checkDurableDocReport: (taskRepoRoot, assignment, reportContent) => autoMemoryService.checkDurableDocAssignmentReport(taskRepoRoot, assignment, reportContent)
     });
     const projectService = createProjectService({
         fs,

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

@@ -240,6 +240,12 @@ export function createArtifactService(fs, deps = {}) {
                 if (validation.errors.length > 0) {
                     throw artifactRejected(input.kind, validation.errors);
                 }
+                if (assignment && input.mode === "final") {
+                    const problem = await deps.checkDurableDocReport?.(input.repoRoot, assignment, normalized);
+                    if (problem) {
+                        throw artifactRejected(input.kind, [problem]);
+                    }
+                }
                 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

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
 import { checkMarkdownArtifact, readArtifactSectionContent, readArtifactSectionValue } from "../../shared/validation/artifact-check.js";
-import { DOCS_UPDATE_COMMIT_RULE } from "../../shared/validation/artifact-contract.js";
+import { DOCS_UPDATE_COMMIT_RULE, durableDocCommitSubjectPrefix } from "../../shared/validation/artifact-contract.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { VcmError } from "../errors.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
@@ -383,6 +383,18 @@ export function createAutoMemoryService(deps) {
         const assignment = state?.status === "documenting" ? currentDurableDocAssignment(state) : undefined;
         return assignment?.status === "running" && assignment.owner === role ? assignment : undefined;
     }
+    async function checkDurableDocAssignmentReport(taskRepoRoot, assignment, reportContent) {
+        if (readArtifactSectionValue(reportContent, "Decision")?.trim().toLowerCase() !== "synced") {
+            return undefined;
+        }
+        try {
+            await validateDurableDocCommit(taskRepoRoot, assignment, reportContent, await deps.git.getHeadCommit(taskRepoRoot));
+            return undefined;
+        }
+        catch (error) {
+            return errorMessage(error);
+        }
+    }
     async function getCompletedDurableDocAssignment(taskRepoRoot, role, artifactPath) {
         const runId = artifactPath.startsWith(`${MEMORY_REVIEW_RUNS_ROOT}/`)
             ? artifactPath.slice(MEMORY_REVIEW_RUNS_ROOT.length + 1).split("/")[0]
@@ -893,8 +905,9 @@ export function createAutoMemoryService(deps) {
     async function validateDurableDocCommit(taskRepoRoot, assignment, reportContent, currentHead) {
         const reportedCommit = readArtifactSectionContent(reportContent, "Commit");
         let commit;
+        let subject;
         try {
-            commit = (await deps.git.getCommitInfo(taskRepoRoot, reportedCommit)).sha;
+            ({ sha: commit, subject } = await deps.git.getCommitInfo(taskRepoRoot, reportedCommit));
         }
         catch (error) {
             const detail = error instanceof VcmError && error.hint ? `${errorMessage(error)} ${error.hint}` : errorMessage(error);
@@ -919,6 +932,10 @@ export function createAutoMemoryService(deps) {
         if (!changedPaths.includes(assignment.targetPath)) {
             throw new Error(`Commit ${commit} modified ${assignment.targetPath}, but no net change remains in ${assignment.baseCommit}..${currentHead}. Verify the current document before reporting completion.`);
         }
+        const subjectPrefix = durableDocCommitSubjectPrefix(assignment.id);
+        if (!subject.startsWith(subjectPrefix)) {
+            throw new Error(`Commit ${commit} subject must start with "${subjectPrefix}"; found "${subject}". Reword the commit (git commit --amend when it is the latest commit) and report it again.`);
+        }
         return commit;
     }
     async function hashOptionalFile(taskRepoRoot, relativePath) {
@@ -1511,6 +1528,7 @@ export function createAutoMemoryService(deps) {
         isRoleMemoryTurn,
         getDurableDocAssignment,
         getCompletedDurableDocAssignment,
+        checkDurableDocAssignmentReport,
         handleRoleHook: (input) => withTaskLock(input.taskRepoRoot, () => handleRoleHook(input)),
         handleHarnessEngineerHook: (input) => withTaskLock(input.taskRepoRoot, () => handleHarnessEngineerHook(input)),
         assertHarnessEngineerAvailable
@@ -1619,6 +1637,7 @@ function buildDurableDocAssignmentPrompt(taskRepoRoot, assignment) {
         ...assignment.evidence.map((item) => `- ${item}`),
         "",
         "Verify the content, update the target and any directly related durable documentation, run applicable documentation checks, and commit the documentation changes.",
+        `Use the commit subject "${durableDocCommitSubjectPrefix(assignment.id)} <summary>" so Project Manager can tell this post-acceptance documentation commit apart; VCM rejects a synced report whose commit has another subject.`,
         `Assigned report path: ${assignment.reportPath}`,
         `Submit with .ai/tools/vcm-artifact docs-update-report --file <candidate> --path ${assignment.reportPath} --mode final`,
         "Set Assignment ID to the exact ID above.",

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

@@ -5,12 +5,21 @@ import { findPmUserQuestion } from "./pm-user-question.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { matchesRoleHookSession } from "./session-service.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
+import { detectUsageLimit } from "./usage-limit.js";
 const MAX_ROLE_RETRY_ATTEMPTS = 20;
 const ROLE_RETRY_BASE_DELAY_MS = 60_000;
+// A usage limit waits for its reset time, retried shortly after it; a limit
+// whose reset time is unknown is checked again every hour. Waiting stops after
+// eight days, longer than a weekly limit lasts.
+const USAGE_LIMIT_RESET_BUFFER_MS = 2 * 60_000;
+const USAGE_LIMIT_UNKNOWN_RESET_RETRY_MS = 60 * 60_000;
+const MAX_USAGE_LIMIT_WAIT_MS = 8 * 24 * 60 * 60_000;
 const NON_RETRYABLE_STOP_FAILURE_ERRORS = new Set([
     "authentication_failed",
     "oauth_org_not_allowed",
+    "account_on_hold",
     "billing_error",
+    "cloud_credential_error",
     "invalid_request",
     "model_not_found",
     "max_output_tokens",
@@ -464,7 +473,10 @@ export function createClaudeHookService(deps) {
                 }
             });
         }
-        const retryResult = await scheduleStopFailureRetry(input, context, failure);
+        const usageLimit = detectUsageLimit(failure, new Date(now()));
+        const retryResult = usageLimit
+            ? await scheduleUsageLimitRetry(input, context, failure, usageLimit)
+            : await scheduleStopFailureRetry(input, context, failure);
         if (retryResult === "scheduled") {
             return {
                 ok: true,
@@ -586,6 +598,7 @@ export function createClaudeHookService(deps) {
                 role: input.role,
                 error: options.gatewayStopFailure.error,
                 errorDetails: options.gatewayStopFailure.errorDetails,
+                lastAssistantMessage: options.gatewayStopFailure.lastAssistantMessage,
                 attempt: options.gatewayStopFailure.attempt,
                 maxAttempts: options.gatewayStopFailure.maxAttempts
             }).catch(() => undefined);
@@ -751,6 +764,76 @@ export function createClaudeHookService(deps) {
         scheduleStopFailureRetryTimer(input, context, attempt, nextRetryAt);
         return "scheduled";
     }
+    // Waits for the usage limit to reset instead of retrying on the short-term
+    // schedule, which would give up after about three and a half hours while a
+    // session or weekly limit can last longer. Waits do not count as retry
+    // attempts, and Gateway hears about the limit once, when the wait starts.
+    async function scheduleUsageLimitRetry(input, context, failure, usageLimit) {
+        const preferences = await deps.appSettings.getPreferences();
+        if (!preferences.roleRetryEnabled || !deps.runtime) {
+            return "not-scheduled";
+        }
+        const stateInput = createRoundStateInput(context);
+        const currentRoundState = await deps.roundService.getSessionRoundState(stateInput);
+        if (currentRoundState.stopReason === "manual-interrupt"
+            && currentRoundState.status === "stopped"
+            && currentRoundState.activeRole === input.role) {
+            return "manual-interrupt";
+        }
+        const previous = currentRoundState.roleRecovery?.role === input.role
+            && currentRoundState.roleRecovery.status !== "failed"
+            ? currentRoundState.roleRecovery
+            : undefined;
+        const alreadyWaiting = previous?.waitReason === "usage-limit";
+        const timestamp = now();
+        const nowMs = Date.parse(timestamp);
+        const limitSince = alreadyWaiting && previous?.limitSince ? previous.limitSince : timestamp;
+        const usageLimitFailure = { ...failure, usageLimit: { resetAt: usageLimit.resetAt, limitSince } };
+        if (nowMs - Date.parse(limitSince) >= MAX_USAGE_LIMIT_WAIT_MS) {
+            await markStopFailureRecoveryFailed(input, context, usageLimitFailure, previous?.attempt ?? 0, timestamp);
+            return "not-scheduled";
+        }
+        const resetMs = usageLimit.resetAt ? Date.parse(usageLimit.resetAt) : Number.NaN;
+        const nextRetryAt = new Date(resetMs > nowMs
+            ? resetMs + USAGE_LIMIT_RESET_BUFFER_MS
+            : nowMs + USAGE_LIMIT_UNKNOWN_RESET_RETRY_MS).toISOString();
+        const attempt = previous?.attempt ?? 0;
+        await deps.roundService.setRoleRecovery({
+            ...stateInput,
+            recovery: {
+                role: input.role,
+                status: "waiting",
+                attempt,
+                maxAttempts: MAX_ROLE_RETRY_ATTEMPTS,
+                lastFailureAt: timestamp,
+                error: failure.error,
+                errorDetails: failure.errorDetails,
+                lastAssistantMessage: failure.lastAssistantMessage,
+                retryable: true,
+                nextRetryAt,
+                waitReason: "usage-limit",
+                limitResetAt: usageLimit.resetAt,
+                limitSince
+            }
+        });
+        const session = await deps.sessionService.getRoleSession(context.project.repoRoot, context.taskSlug, input.role);
+        if (session) {
+            await deps.sessionService.markRoleActivityRunning(context.project.repoRoot, context.taskSlug, input.role, session.id);
+        }
+        scheduleStopFailureRetryTimer(input, context, attempt, nextRetryAt);
+        if (!alreadyWaiting && (await isHookSessionBoundToTask(context, input.role))) {
+            void deps.gatewayService?.handleRoleStopFailure({
+                repoRoot: context.project.repoRoot,
+                taskSlug: context.taskSlug,
+                role: input.role,
+                error: failure.error,
+                errorDetails: failure.errorDetails,
+                lastAssistantMessage: failure.lastAssistantMessage,
+                usageLimitWait: { resetAt: usageLimit.resetAt, nextRetryAt }
+            }).catch(() => undefined);
+        }
+        return "scheduled";
+    }
     async function isManualInterruptedStopFailure(context, role) {
         try {
             const state = await deps.roundService.getSessionRoundState(createRoundStateInput(context));
@@ -831,7 +914,10 @@ export function createClaudeHookService(deps) {
                 errorDetails: failure.errorDetails,
                 lastAssistantMessage: failure.lastAssistantMessage,
                 retryable: failure.retryable,
-                failedAt: timestamp
+                failedAt: timestamp,
+                ...(failure.usageLimit
+                    ? { waitReason: "usage-limit", limitResetAt: failure.usageLimit.resetAt, limitSince: failure.usageLimit.limitSince }
+                    : {})
             }
         });
     }

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

@@ -127,7 +127,7 @@ export function createTranslationService(deps) {
         taskFeeds.set(key, created);
         return created;
     }
-    async function prepareCache(input) {
+    async function prepareCache(input, options = {}) {
         const state = getState(input.sessionId);
         state.repoRoot = input.repoRoot;
         state.baseRepoRoot = input.baseRepoRoot ?? input.repoRoot;
@@ -145,7 +145,9 @@ export function createTranslationService(deps) {
             pruneTranslationEntries(input.sessionId);
         }
         syncTaskFeedFromSessionState(input.sessionId, state);
-        await deps.fs.ensureDir(path.dirname(cachePath));
+        if (options.createDir !== false) {
+            await deps.fs.ensureDir(path.dirname(cachePath));
+        }
         return state;
     }
     async function loadCachedEvents(state) {
@@ -1311,13 +1313,16 @@ export function createTranslationService(deps) {
         };
         const roleSession = await getGatewayRoleSession(input);
         if (roleSession) {
+            // A lookup only reads. A stopped session has no transcript tail to write
+            // events, and its task may be closing: creating the cache directory there
+            // would recreate the removed task worktree.
             const state = await prepareCache({
                 repoRoot: roleSession.cwd,
                 baseRepoRoot: input.repoRoot,
                 taskSlug: input.taskSlug,
                 role: input.role,
                 sessionId: roleSession.id
-            });
+            }, { createDir: roleSession.status === "running" });
             if (roleSession.status === "running") {
                 startTranscriptTail(roleSession);
             }

package/dist/backend/services/usage-limit.js

@@ -0,0 +1,133 @@
+// Claude Code reports a plan usage limit (the session or weekly limit) as an
+// ordinary `rate_limit` API error, the same type as short-term throttling.
+// Only the rendered message tells them apart, and it carries the reset time:
+//   "You've hit your session limit · resets 5:50pm (Asia/Singapore)"
+// Retrying before that time cannot succeed, so a usage limit waits for the
+// reset instead of following the short-term retry schedule.
+// A reset further away than this is treated as unparsed; weekly limits reset
+// within seven days.
+export const MAX_USAGE_LIMIT_RESET_MS = 8 * 24 * 60 * 60 * 1000;
+const USAGE_LIMIT_ERRORS = new Set(["rate_limit", "unknown"]);
+const USAGE_LIMIT_PATTERNS = [
+    /\bhit your\b[^\n]*?\blimit\b/i,
+    /\busage limit\b/i,
+    /\b(?:session|weekly|daily|monthly)\s+limit\b/i
+];
+const RESET_PATTERN = /\bresets?\s+(?:at\s+|on\s+)?([^()\n]+?)\s*\(([A-Za-z_]+(?:\/[A-Za-z0-9_+-]+)+|UTC|GMT)\)/i;
+const TIME_PATTERN = /(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*$/i;
+const DATE_PATTERN = /\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\.?\s+(\d{1,2})\b/i;
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function detectUsageLimit(failure, now) {
+    if (!USAGE_LIMIT_ERRORS.has(failure.error)) {
+        return undefined;
+    }
+    const message = [failure.lastAssistantMessage, failure.errorDetails]
+        .find((text) => Boolean(text) && USAGE_LIMIT_PATTERNS.some((pattern) => pattern.test(text)));
+    if (!message) {
+        return undefined;
+    }
+    return { message, resetAt: parseUsageLimitReset(message, now) };
+}
+// Parses "resets 5:50pm (Asia/Singapore)" or "resets Nov 12, 9am
+// (America/Los_Angeles)" into the next matching instant after `now`.
+export function parseUsageLimitReset(message, now) {
+    const match = RESET_PATTERN.exec(message);
+    if (!match) {
+        return undefined;
+    }
+    const when = match[1].trim();
+    const timeZone = match[2];
+    if (!isTimeZone(timeZone)) {
+        return undefined;
+    }
+    const time = TIME_PATTERN.exec(when);
+    if (!time) {
+        return undefined;
+    }
+    let hour = Number(time[1]);
+    const minute = Number(time[2] ?? 0);
+    const meridiem = time[3]?.toLowerCase();
+    if (minute > 59) {
+        return undefined;
+    }
+    if (meridiem) {
+        if (hour < 1 || hour > 12) {
+            return undefined;
+        }
+        hour = (hour % 12) + (meridiem === "pm" ? 12 : 0);
+    }
+    else if (hour > 23) {
+        return undefined;
+    }
+    const today = zonedDate(now, timeZone);
+    const date = DATE_PATTERN.exec(when);
+    let resetMs;
+    if (date) {
+        const month = MONTHS.indexOf(date[1].toLowerCase().slice(0, 3)) + 1;
+        const day = Number(date[2]);
+        const explicitYear = /\b(20\d{2})\b/.exec(when)?.[1];
+        const year = explicitYear ? Number(explicitYear) : today.year;
+        resetMs = zonedTimeToUtc(year, month, day, hour, minute, timeZone);
+        if (!explicitYear && resetMs < now.getTime() - DAY_MS) {
+            resetMs = zonedTimeToUtc(year + 1, month, day, hour, minute, timeZone);
+        }
+    }
+    else {
+        resetMs = zonedTimeToUtc(today.year, today.month, today.day, hour, minute, timeZone);
+        if (resetMs <= now.getTime()) {
+            resetMs = zonedTimeToUtc(today.year, today.month, today.day + 1, hour, minute, timeZone);
+        }
+    }
+    if (!Number.isFinite(resetMs) || resetMs - now.getTime() > MAX_USAGE_LIMIT_RESET_MS) {
+        return undefined;
+    }
+    return new Date(resetMs).toISOString();
+}
+function isTimeZone(timeZone) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function zonedParts(instantMs, timeZone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit"
+    }).formatToParts(new Date(instantMs));
+    const value = (type) => Number(parts.find((part) => part.type === type)?.value);
+    return {
+        year: value("year"),
+        month: value("month"),
+        day: value("day"),
+        hour: value("hour"),
+        minute: value("minute"),
+        second: value("second")
+    };
+}
+function zonedDate(now, timeZone) {
+    const parts = zonedParts(now.getTime(), timeZone);
+    return { year: parts.year, month: parts.month, day: parts.day };
+}
+// The time zone's offset from UTC at an instant, in milliseconds.
+function offsetMs(instantMs, timeZone) {
+    const parts = zonedParts(instantMs, timeZone);
+    const asUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+    return asUtc - Math.floor(instantMs / 1000) * 1000;
+}
+// The UTC instant of a wall-clock time in a time zone; the second pass
+// corrects for an offset change (daylight saving) between the two guesses.
+function zonedTimeToUtc(year, month, day, hour, minute, timeZone) {
+    const wallClockAsUtc = Date.UTC(year, month - 1, day, hour, minute);
+    const first = wallClockAsUtc - offsetMs(wallClockAsUtc, timeZone);
+    return wallClockAsUtc - offsetMs(first, timeZone);
+}

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

@@ -820,7 +820,9 @@ async function allowedArchitectFix(fs, input, state, segment, source, resumedFro
         if (source === "architect-debug" && artifact.disposition === ARCHITECT_DEBUG_NORMAL_PLAN_DISPOSITION) {
             return ["code-change/architect"];
         }
-        if (source === "architecture-diagnosis" && artifact.disposition === "analysis completed") {
+        // Only a completed analysis-only Diagnosis returns to its parent; a pending
+        // or blocked one sends the same Architect back.
+        if (source === "architecture-diagnosis" && artifact.complete && artifact.disposition === "analysis completed") {
             return parentFlow ? [`${parentFlow}/architect`] : [];
         }
         if (artifact.disposition === "user clarification required") {
@@ -954,7 +956,7 @@ async function artifactState(fs, input, fileName, kind) {
     if (kind === "architect-debug")
         value = inline("Status") ?? readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase();
     if (kind === "architecture-diagnosis")
-        value = readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase();
+        value = inline("Status") ?? readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase();
     if (kind === "test-report")
         value = inline("Test Result");
     if (kind === "docs-update-report" || kind === "final-acceptance") {
@@ -1190,7 +1192,10 @@ async function validateCompletion(fs, input, state, candidate) {
     const inBranch = flowRun.activeBranch === candidate.flow;
     if (candidate.flow === "architecture-diagnosis" && !inBranch) {
         const diagnosis = await artifactState(fs, input, "architecture-diagnosis.md", "architecture-diagnosis");
-        if (diagnosis.disposition === "analysis completed"
+        // The final contract rejects analysis completed with a commit or changed
+        // files, so a completed analysis-only Diagnosis changed no code.
+        if (diagnosis.complete
+            && diagnosis.disposition === "analysis completed"
             && evidenceProducedAfterActiveDispatch(state, candidate.flow, "architect", "architecture-diagnosis.md", diagnosis.hash))
             return;
     }

package/dist/backend/templates/handoff.js

@@ -1,4 +1,4 @@
-import { ARCHITECT_DEBUG_DISPOSITIONS, ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, DOCS_UPDATE_COMMIT_RULE, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
+import { ARCHITECT_DEBUG_DISPOSITIONS, ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_DIAGNOSIS_STATUSES, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, DOCS_UPDATE_COMMIT_RULE, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
 const CURRENT_HANDOFF_NOTICE = "<!-- VCM current handoff: replace this file with one complete, self-contained snapshot of the current result. Restate all still-relevant evidence; do not refer to a prior revision, route message, Session, or transcript as evidence. -->";
 export function renderArchitectureBriefTemplate(taskSlug) {
     return `# Architecture Brief: ${taskSlug}
@@ -417,6 +417,8 @@ export function renderArchitectureDiagnosisTemplate(taskSlug) {
 
 ${CURRENT_HANDOFF_NOTICE}
 
+Status: ${renderArtifactOptions(ARCHITECTURE_DIAGNOSIS_STATUSES)}
+
 ## Diagnosis Boundary
 
 TBD

package/dist/backend/templates/harness/architect-agent.js

@@ -286,9 +286,11 @@ Each rewritten \`architecture-diagnosis.md\` must be a complete, self-contained
 - Before reporting \`diagnosis implementation completed\`, run every existing L2/L3 check applicable to the diagnosed failure path.
 - Every applicable L2/L3 check must pass. If a level is not applicable, record the concrete reason.
 - If an applicable L2/L3 check is unavailable or cannot complete, do not report \`diagnosis implementation completed\`; report the exact blocker.
+- Keep \`Status: pending\` while the Diagnosis is in progress or blocked, and record the exact blocker under \`Implementation And Validation\`. Set \`Status: completed\` only with a final disposition.
 - Under \`Implementation And Validation\`, record each L2/L3 command or test case, the diagnosed failure path it covers, its result, and its evidence.
 - Architect-run Diagnosis validation is implementation evidence and does not replace Tester final validation.
 - Final disposition must be one of: \`analysis completed\`, \`diagnosis implementation completed\`, or \`user clarification required\`.
+- \`analysis completed\` means the Diagnosis changed no code: \`Changed Files And Public Surface\` and \`Commit\` are exactly \`None.\`. A Diagnosis that changed or committed code reports \`diagnosis implementation completed\`, or stays \`Status: pending\` while blocked.
 
 ### Replan And Drift
 

package/dist/backend/templates/harness/claude-root.js

@@ -66,6 +66,7 @@ If a reusable harness problem is suspected, it is enough to record a concise fee
 - Communication-Only Flow uses: \`project-manager response or relay -> completion\`.
 - Gate Review is PM-triggered at its defined trigger points; the tool decides whether review is enabled or required.
 - Ignore commits whose subject starts with \`[VCM Harness]\`. Do not review, attribute, or route those commits unless they cause a test failure. A test failure caused by a Harness commit follows the normal test-failure flow.
+- Commits whose subject starts with \`[VCM Docs]\` are durable-documentation updates that VCM assigned from a memory review after Final Acceptance. They belong to the task and its PR; do not review, re-gate, or route them.
 - Final acceptance closes only a complete code-delivery flow. After a Debug or Diagnosis Branch passes its code-diff Gate, final acceptance closes the parent flow it returned to, never the branch alone.
 - PR-Preparation Flow starts only after the active delivery flow completes; every complete code-delivery flow requires final acceptance to pass.
 - If Docs-Only Flow or Validation-Only Flow reveals that the accepted outcome requires production-code, runtime-behavior, public-contract, dependency, or system-architecture changes, project-manager routes through the full Code-Change Flow.

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

@@ -401,6 +401,7 @@ If required work or evidence is incomplete, return to the responsible flow or ro
 PR-Preparation Flow does not perform technical review, validation, documentation updates, Gate Review, or Final Acceptance.
 
 - Create a draft PR by default unless the user requests a ready PR.
+- Commits after the HEAD the latest code-diff Gate approved: \`[VCM Harness]\` and \`[VCM Docs]\` commits belong to the PR without another Gate. List each \`[VCM Docs]\` commit with its assignment ID (the subject's \`[VCM Docs] <assignment-id>:\`) in the PR description. Any other commit after that HEAD is unreviewed task work: return it to the responsible flow before preparing the PR.
 
 ### Background Jobs
 

package/dist/shared/validation/artifact-check.js

@@ -1,4 +1,4 @@
-import { ARCHITECT_DEBUG_DISPOSITIONS, ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, DOCS_UPDATE_COMMIT_PATTERN, DOCS_UPDATE_COMMIT_RULE, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS } from "./artifact-contract.js";
+import { ARCHITECT_DEBUG_DISPOSITIONS, ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_ANALYSIS_ONLY_DISPOSITION, ARCHITECTURE_DIAGNOSIS_ANALYSIS_ONLY_SECTIONS, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_DIAGNOSIS_STATUSES, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, DOCS_UPDATE_COMMIT_PATTERN, DOCS_UPDATE_COMMIT_RULE, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS } from "./artifact-contract.js";
 import { getArtifactDefinition } from "./artifact-registry.js";
 const PLACEHOLDER_PATTERN = /(^|\n)\s*(TBD|Not run yet\.?|status:\s*draft)\s*(\n|$)/i;
 export function checkMarkdownArtifact(kind, artifactPath, content, options = {}) {
@@ -104,10 +104,24 @@ function validateArtifactFields(kind, content, mode) {
         return invalidFields;
     }
     if (kind === "architecture-diagnosis") {
-        const disposition = readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase();
-        return isAllowedValue(disposition, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS)
-            ? []
-            : [renderExactSectionError("Final Disposition", ARCHITECTURE_DIAGNOSIS_DISPOSITIONS.join("|"), disposition)];
+        // Like architect-debug, an in-progress or blocked Diagnosis stays
+        // `Status: pending`; only a completed one carries a Final Disposition.
+        const invalidFields = validateLifecycleField(content, "Status", ARCHITECTURE_DIAGNOSIS_STATUSES, "completed", mode);
+        if (mode === "final") {
+            const disposition = readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase();
+            if (!isAllowedValue(disposition, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS)) {
+                invalidFields.push(renderExactSectionError("Final Disposition", ARCHITECTURE_DIAGNOSIS_DISPOSITIONS.join("|"), disposition));
+            }
+            else if (disposition === ARCHITECTURE_DIAGNOSIS_ANALYSIS_ONLY_DISPOSITION) {
+                for (const section of ARCHITECTURE_DIAGNOSIS_ANALYSIS_ONLY_SECTIONS) {
+                    const value = readArtifactSectionContent(content, section)?.trim();
+                    if (value !== STRICT_NONE_VALUE) {
+                        invalidFields.push(`${section} must be exactly "${STRICT_NONE_VALUE}" for analysis completed; a Diagnosis that changed or committed code reports diagnosis implementation completed, or stays Status: pending while blocked.`);
+                    }
+                }
+            }
+        }
+        return invalidFields;
     }
     if (kind === "test-report") {
         const result = readInlineField(content, "Test Result");

package/dist/shared/validation/artifact-contract.js

@@ -15,6 +15,11 @@ export const ARCHITECT_DEBUG_DISPOSITIONS = [
     ARCHITECT_DEBUG_NORMAL_PLAN_DISPOSITION,
     "user clarification required"
 ];
+export const ARCHITECTURE_DIAGNOSIS_STATUSES = ["pending", "completed"];
+export const ARCHITECTURE_DIAGNOSIS_ANALYSIS_ONLY_DISPOSITION = "analysis completed";
+// An analysis-only Diagnosis changes no code: these sections must be exactly
+// "None." for its final disposition.
+export const ARCHITECTURE_DIAGNOSIS_ANALYSIS_ONLY_SECTIONS = ["Changed Files And Public Surface", "Commit"];
 export const ARCHITECTURE_DIAGNOSIS_DISPOSITIONS = [
     "analysis completed",
     "diagnosis implementation completed",
@@ -31,6 +36,12 @@ export const L3_REQUIRED_VALUES = ["yes", "no"];
 export const L3_ACTIONS = ["run-existing", "updated", "added"];
 export const DOCS_REPORT_DECISIONS = ["synced", "unchanged", "blocked"];
 export const DOCS_UPDATE_COMMIT_PATTERN = /^[0-9a-f]{7,40}$/;
+// Subject prefix of the commits a durable-documentation assignment makes, so
+// Project Manager can tell these post-acceptance documentation commits apart.
+export const DURABLE_DOC_COMMIT_PREFIX = "[VCM Docs]";
+export function durableDocCommitSubjectPrefix(assignmentId) {
+    return `${DURABLE_DOC_COMMIT_PREFIX} ${assignmentId}:`;
+}
 export const DOCS_UPDATE_COMMIT_RULE = "When Decision is synced, Commit must contain only one bare lowercase hexadecimal commit hash (7-40 characters, for example abc1234) on a single line. No backticks, bullets, links, subjects, or extra lines; put explanations in Evidence Reviewed. An unchanged result does not require a new commit.";
 export const FINAL_ACCEPTANCE_DECISIONS = [
     "accepted",