vibe-coding-master 0.7.43 → 0.7.45

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

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

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

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

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

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { ROLE_NAMES, isDispatchableRole } from "../../shared/constants.js";
-import { CCR_GPT_SESSION_MODEL, isCcrSessionModel } from "../../shared/types/session.js";
+import { isCodexBridgeSessionModel } from "../../shared/types/session.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
@@ -598,21 +598,21 @@ export function createSessionService(deps) {
         return migrateRunningProjectToolSessionCwd(repoRoot, resumed, targetCwd);
     }
     async function getModelLaunchEnvironment(model) {
-        if (!deps.ccrIntegration) {
-            if (isCcrSessionModel(model)) {
+        if (!deps.codexBridgeIntegration) {
+            if (isCodexBridgeSessionModel(model)) {
                 throw new VcmError({
-                    code: "CCR_UNAVAILABLE",
-                    message: "CCR integration is not available in this VCM runtime.",
+                    code: "CODEX_BRIDGE_UNAVAILABLE",
+                    message: "Codex Bridge integration is not available in this VCM runtime.",
                     statusCode: 409,
-                    hint: "Enable and configure CCR GPT models before starting this session."
+                    hint: "Enable and configure Codex Bridge before starting this session."
                 });
             }
             return {};
         }
-        return deps.ccrIntegration.getLaunchEnvironment(model);
+        return deps.codexBridgeIntegration.getLaunchEnvironment(model);
     }
     async function getModelLaunchSettingsOverride(model) {
-        return deps.ccrIntegration?.getLaunchSettingsOverride(model);
+        return deps.codexBridgeIntegration?.getLaunchSettingsOverride(model);
     }
     function isRuntimeSessionAlive(session) {
         if (!session || isExitedStatus(session.status) || session.pid === undefined) {
@@ -1642,7 +1642,7 @@ function normalizeClaudeModel(value) {
         || value === "claude-opus-4-8"
         || value === "sonnet"
         || value === "fable"
-        || value === CCR_GPT_SESSION_MODEL) {
+        || isCodexBridgeSessionModel(value)) {
         return value;
     }
     return "default";
@@ -1660,20 +1660,20 @@ function normalizeClaudeEffort(value) {
 }
 function assertResumeProviderCompatible(session, requestedModel) {
     const persistedModel = normalizeClaudeModel(session.model);
-    if (isCcrSessionModel(persistedModel) !== isCcrSessionModel(requestedModel)) {
+    if (isCodexBridgeSessionModel(persistedModel) !== isCodexBridgeSessionModel(requestedModel)) {
         throw new VcmError({
             code: "SESSION_PROVIDER_SWITCH_REQUIRES_RESTART",
             message: `Cannot resume ${session.role} with a different model provider.`,
             statusCode: 409,
-            hint: "Use Restart to switch between native Claude and CCR models."
+            hint: "Use Restart to switch between native Claude and Codex Bridge models."
         });
     }
-    if (isCcrSessionModel(requestedModel) && !session.claudeConfigDir) {
+    if (isCodexBridgeSessionModel(requestedModel) && !session.claudeConfigDir) {
         throw new VcmError({
-            code: "CCR_SESSION_CONFIG_MISSING",
-            message: `${session.role} was created before isolated CCR session storage was enabled.`,
+            code: "CODEX_BRIDGE_SESSION_CONFIG_MISSING",
+            message: `${session.role} was created without isolated Codex Bridge session storage.`,
             statusCode: 409,
-            hint: "Restart this role once to create an isolated CCR session."
+            hint: "Restart this role once to create an isolated Codex Bridge session."
         });
     }
 }
@@ -1713,7 +1713,7 @@ function buildUsageTelemetryEnvironment(apiUrl, role, model) {
         OTEL_LOG_TOOL_DETAILS: "0",
         OTEL_LOG_RAW_API_BODIES: "0"
     };
-    if (!apiUrl || isCcrSessionModel(model)) {
+    if (!apiUrl || isCodexBridgeSessionModel(model)) {
         return disabled;
     }
     return {

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

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

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

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

package/dist/backend/services/usage-analytics-service.js

@@ -76,7 +76,7 @@ function extractApiRequestEvents(payload) {
                     continue;
                 }
                 const model = normalizeModel(readString(attributes.model));
-                if (isCcrModel(model)) {
+                if (isCodexBridgeModel(model)) {
                     continue;
                 }
                 const sequence = readInteger(attributes["event.sequence"]);
@@ -334,9 +334,9 @@ function normalizeModel(input) {
     const model = input?.slice(0, 200).trim();
     return model && isSafeGroupKey(model) ? model : "unknown";
 }
-function isCcrModel(model) {
+function isCodexBridgeModel(model) {
     const normalized = model.toLowerCase();
-    return normalized.startsWith("gpt-") || normalized.startsWith("ccr:") || normalized.includes("codex api/");
+    return normalized.startsWith("gpt-") || normalized.startsWith("codex-bridge:");
 }
 function isSafeGroupKey(value) {
     return value !== "__proto__" && value !== "prototype" && value !== "constructor";

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

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

package/dist/backend/templates/handoff.js

@@ -1,4 +1,4 @@
-import { ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_SYNC_DECISIONS, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
+import { ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
 const CURRENT_HANDOFF_NOTICE = "<!-- VCM current handoff: replace this file with one complete, self-contained snapshot of the current result. Restate all still-relevant evidence; do not refer to a prior revision, route message, Session, or transcript as evidence. -->";
 export function renderArchitectureBriefTemplate(taskSlug) {
     return `# Architecture Brief: ${taskSlug}
@@ -518,7 +518,49 @@ TBD
 
 ## Decision
 
-${renderArtifactOptions(DOCS_SYNC_DECISIONS)}
+${renderArtifactOptions(DOCS_REPORT_DECISIONS)}
+`;
+}
+export function renderDocsUpdateReportTemplate(taskSlug, assignmentId = "docs-only") {
+    return `# Docs Update Report: ${taskSlug}
+
+${CURRENT_HANDOFF_NOTICE}
+
+## Summary
+
+TBD
+
+## Assignment ID
+
+${assignmentId}
+
+## Documents Updated
+
+TBD
+
+## Documents Reviewed And Left Unchanged
+
+TBD
+
+## Evidence Reviewed
+
+TBD
+
+## Checks Performed
+
+TBD
+
+## Commit
+
+TBD
+
+## Remaining Documentation Issues
+
+TBD
+
+## Decision
+
+${renderArtifactOptions(DOCS_REPORT_DECISIONS)}
 `;
 }
 export function renderWorkflowProgressTemplate(taskSlug) {

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

@@ -24,8 +24,9 @@ ${renderRoleMemoryRules("architect")}
 - Follow the preloaded \`vcm-code-navigation\` skill whenever work requires code definitions, implementations, references, callers, callees, or behavior paths. This applies in every Architect mode and in direct user communication.
 - LSP is mandatory and directly available for navigating project source code. Start source-code navigation with LSP. If it is unavailable, report a VCM LSP configuration failure; do not substitute source text search.
 - Use LSP definitions, implementations, references, document or workspace symbols, and incoming or outgoing calls for all source-code symbol and relationship queries.
-- Do not use the built-in \`Grep\` tool or shell text-search commands such as \`grep\`, \`rg\`, \`git grep\`, \`ag\`, or \`ack\` to search project source code, test code, or executable scripts. This prohibition includes locating or inferring definitions, implementations, references, callers, callees, symbols, and behavior paths.
-- Use Glob to locate files and Read to inspect complete code. Text search is allowed only for non-source artifacts that LSP does not model, such as documentation, configuration or data files, generated context, and logs. To inspect source comments, locate the source through LSP or Glob and use Read.
+- LSP reference results are symbol-specific. An accessor, its backing field, a trait declaration, its implementation method, a wrapper, and an alias are separate symbols. Query every relevant symbol separately; one symbol's reference result cannot prove a complete semantic class. When starting from an accessor or wrapper, read its implementation, resolve its backing field, delegate, or trait item with LSP, then query those symbols too.
+- Do not use the built-in \`Grep\` tool or shell text-search commands such as \`grep\`, \`rg\`, \`git grep\`, \`ag\`, or \`ack\` to search project source code, test code, or executable scripts, except for the bounded fallback below. This prohibition includes locating or inferring definitions, implementations, references, callers, callees, symbols, and behavior paths.
+- Use Glob to locate files and Read to inspect complete code. Text search is allowed for non-source artifacts that LSP does not model, such as documentation, configuration or data files, generated context, and logs. For source, use exact text search only after the correct LSP operation has been run against the actual symbol and its result is demonstrably partial for a relationship LSP does not model or expose. Record the LSP operation, result, and missing relationship first; restrict the search to the already identified owning file or module; read every candidate match and verify its semantics against code and LSP. Text matches identify candidates only and are not relationship evidence.
 - Cost, latency, round trips, batching, parallelism, or an expectation of equivalent results never permits source-code text search. Wait for the role-session LSP and follow the skill's bounded retry procedure.
 - If LSP cannot resolve a required project-owned relationship, record it as unresolved. Do not replace semantic evidence with text matches.
 
@@ -109,7 +110,7 @@ ${renderRoleMemoryRules("architect")}
 - \`Scaffold Manifest\`: an item ledger — one entry per implementation item. Use columns in the exact order \`ID | Action | File | ...\`; use an ID matching \`AA-1\` through \`AAAAAA-9999\`, an Action of exactly \`create\`, \`change\`, or \`delete\`, and a backticked repo-relative File path. An item is one created body or surface, one required change site — one contiguous edit region inside an existing body or surface — or one deletion of a body, site, or file. An item not in the ledger is not in the plan; coder must not implement it. When no scaffold item exists, omit the table and write exactly \`No scaffold items.\`; an empty table is invalid.
 - Each ledger entry carries, in this column order: a unique stable ID such as \`SCF-001\`, action, exact file path, symbol or site, coder work, allowed implementation freedom, and a behavior/contract proof point. Per-file evidence, why-in-scope, and durable-comment needs live in the Module/File Plan, not in the ledger. Open-ended coverage language ("as work proceeds", "replicate", "etc.", "and others") is forbidden anywhere in the ledger.
 - IDs and markers correspond one to one: every \`create\`, \`change\`, and \`delete\` entry has exactly one \`VCM:CODE <ID>\` marker pre-placed at its declared file and site; a \`delete\` marker sits on the code to be removed and leaves with it.
-- The Scaffold Manifest is complete only when the ledger ID set and the tree's \`VCM:CODE\` ID set are equal, each ID appears exactly once on each side, and each marker sits in its declared file (\`.ai/tools/check-scaffold-ledger\` automates the check). Any mismatch means the plan is not complete.
+- The Scaffold Manifest is complete only when the ledger ID set and the tree's \`VCM:CODE\` ID set are equal, each ID appears exactly once on each side, and each marker sits in its declared file (\`.ai/tools/check-scaffold-ledger --mode scaffold\` automates the check). Any mismatch means the plan is not complete.
 - \`Scaffold Build Evidence\`: the exact compile/typecheck commands run on the committed scaffold, their results, and the scaffold commit hash. A missing, red, or stale-hash result means the plan is not complete.
 - When the plan introduces or changes a build configuration — a new compilation target, a feature-gated or restricted-runtime variant, a new artifact type, or a build-environment constraint — scaffold that configuration and add to \`Scaffold Build Evidence\` one named check per configuration that fails when the claim is false, run green at the scaffold commit; choose proving checks from the project coding standards when defined there. A build-configuration claim without its named green check means the plan is not complete.
 - The compile/typecheck and build-configuration checks in \`Scaffold Build Evidence\` must cover every wired exemplar, so each new cross-module call path is proven compilable at the scaffold stage. A call path that exists only in plan prose, over stub scaffold that never names the surfaces it will invoke, is not proven and the plan is not complete.
@@ -212,7 +213,7 @@ The code-reading phase is complete only when:
 - every indirect callback, event, hook, queue, route, and dynamic dispatch path has been resolved
 - every relevant state reader and writer has been read
 - every relevant cross-file surface caller and consumer has been read
-- every semantic relationship records LSP, runtime, external-boundary, or generated-boundary evidence
+- every semantic relationship records LSP, runtime, verified bounded source, external-boundary, or generated-boundary evidence
 - no unresolved project-owned symbol remains
 
 Do not diagnose the root cause or choose a fix before the Code Reading Closure is complete.
@@ -281,7 +282,12 @@ Each rewritten \`architecture-diagnosis.md\` must be a complete, self-contained
 
 ### Docs Sync
 
-- In Docs-Only Flow, verify claims against current code and durable docs, update the PM-assigned project documents directly, run applicable documentation checks, and commit the changes; tester completion is not required.
+- For a \`[VCM Durable Documentation Assignment]\`, update the assigned durable
+  document and directly related documentation, run applicable documentation
+  checks, commit the result, and submit \`docs-update-report.md\` with the exact
+  assigned Assignment ID. This backend assignment does not start Docs-Only Flow.
+
+- In Docs-Only Flow, verify claims against current code and durable docs, update the PM-assigned project documents and related documentation needed for consistency, run applicable documentation checks, commit the changes, and submit \`.ai/vcm/handoffs/docs-update-report.md\` through \`vcm-artifact\` before reporting to PM.
 - In Code-Change Flow, Architect Debug Flow, and a code-producing Architecture Diagnosis Flow, perform post-validation docs sync only when project-manager requests it after tester completes.
 - Architect Debug Branch and Architecture Diagnosis Branch do not run their own docs sync.
 
@@ -336,8 +342,8 @@ Each rewritten \`architecture-diagnosis.md\` must be a complete, self-contained
 
 #### Docs Sync Report
 
-- Write \`.ai/vcm/handoffs/docs-sync-report.md\` as the final result of Docs-Only Flow and for post-validation docs sync in Code-Change Flow, Architect Debug Flow, or a code-producing Architecture Diagnosis Flow. Do not write it for a Debug/Diagnosis Branch.
-- In Docs-Only Flow, submit the complete report before returning to PM. The report must record the decision, changed documents, evidence reviewed, checks performed, and commit.
+- Write \`.ai/vcm/handoffs/docs-sync-report.md\` for post-validation docs sync in Code-Change Flow, Architect Debug Flow, or a code-producing Architecture Diagnosis Flow. Do not write it for Docs-Only Flow or a Debug/Diagnosis Branch.
+- In Docs-Only Flow, submit the complete \`.ai/vcm/handoffs/docs-update-report.md\` before returning to PM. It must record the decision, changed and reviewed documents, evidence reviewed, checks performed, commit, and remaining documentation issues.
 - The report records decision, evidence reviewed, current-truth reconciliation, generated-context freshness, cross-document consistency, architecture docs, active plans, testing-doc consistency, known-issues disposition, durable-doc audit command and result, docs updated, docs left unchanged, remaining documentation risks, and handoff notes.
 - Each rewritten \`docs-sync-report.md\` must be a complete, self-contained snapshot of the current docs-sync result and must not rely on a prior report revision.
 - \`Decision\` must be \`synced\`, \`unchanged\`, or \`blocked\`.

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

@@ -14,7 +14,7 @@ You are \`vcm-architect-scaffold-worker\`, a foreground subagent invoked by Arch
 
 ### Validation And Commit
 
-- Run \`.ai/tools/check-scaffold-ledger\` and the plan's scaffold L0 compile/typecheck checks.
+- Run \`.ai/tools/check-scaffold-ledger --mode scaffold\` and the plan's scaffold L0 compile/typecheck checks.
 - Commit only the scaffold changes after the ledger reconciles and required checks pass.
 - Return the commit hash, changed files, ledger result, and exact check results to Architect.
 - If the assigned scaffold cannot be completed, return the concrete failure evidence without changing the plan.