vibe-coding-master 0.7.42 → 0.7.44

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

@@ -5,7 +5,7 @@ import { resolveRepoPath } from "../adapters/filesystem.js";
 import { VcmError } from "../errors.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { readVcmMemoryBlock, replaceVcmMemoryBlock } from "../templates/harness/memory-block.js";
-import { ARCHITECT_PLANNING_MEMORY_CANDIDATE_PATH, architectPlanningCandidateSnapshotPath, MEMORY_REVIEW_RUNS_ROOT, MEMORY_REVIEW_STATE_PATH } from "./memory-review-paths.js";
+import { ARCHITECT_PLANNING_MEMORY_CANDIDATE_PATH, architectPlanningCandidateSnapshotPath, memoryReviewRoleDraftPath, MEMORY_REVIEW_RUNS_ROOT, MEMORY_REVIEW_STATE_PATH } from "./memory-review-paths.js";
 import { parseMemoryProposal, validateMemoryProposal } from "./memory-proposal-validation.js";
 const MEMORY_FILE_DEFINITIONS = [
     { path: "CLAUDE.md", title: "Shared Memory" },
@@ -122,7 +122,7 @@ export function createAutoMemoryService(deps) {
             listRuns(taskRepoRoot),
             listMemoryFiles(taskRepoRoot)
         ]);
-        if (active && !(await deps.appSettings.getPreferences()).autoMemoryEnabled) {
+        if (active && !preserveDisabledReview(active) && !(await deps.appSettings.getPreferences()).autoMemoryEnabled) {
             await discardActiveReview(taskRepoRoot, active);
             active = undefined;
             runs = await listRuns(taskRepoRoot);
@@ -140,7 +140,13 @@ export function createAutoMemoryService(deps) {
         const active = await loadActiveState(input.taskRepoRoot);
         const preferences = await deps.appSettings.getPreferences();
         if (!preferences.autoMemoryEnabled) {
-            if (active) {
+            if (active?.status === "documenting") {
+                await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, active);
+            }
+            else if (active?.status === "reviewing" && active.reviewPromptDispatchedAt) {
+                return getState(input.baseRepoRoot, input.taskRepoRoot);
+            }
+            else if (active) {
                 await discardActiveReview(input.taskRepoRoot, active);
             }
             return getState(input.baseRepoRoot, input.taskRepoRoot);
@@ -153,6 +159,10 @@ export function createAutoMemoryService(deps) {
         if (active?.status === "reviewing") {
             return getState(input.baseRepoRoot, input.taskRepoRoot);
         }
+        if (active?.status === "documenting") {
+            await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, active);
+            return getState(input.baseRepoRoot, input.taskRepoRoot);
+        }
         if (active || !input.roundReady || !input.requestTrigger) {
             return getState(input.baseRepoRoot, input.taskRepoRoot);
         }
@@ -175,7 +185,7 @@ export function createAutoMemoryService(deps) {
         const runId = createRunId(timestamp, "auto");
         const drafts = roles.map((role) => ({
             role,
-            path: `${MEMORY_REVIEW_RUNS_ROOT}/${runId}/drafts/${role}.md`,
+            path: memoryReviewRoleDraftPath(runId, role),
             status: "pending"
         }));
         const state = {
@@ -187,7 +197,8 @@ export function createAutoMemoryService(deps) {
             trigger: input.requestTrigger,
             createdAt: timestamp,
             updatedAt: timestamp,
-            drafts
+            drafts,
+            assignments: []
         };
         const before = await readMemorySet(input.taskRepoRoot);
         await writeRunMemorySet(input.taskRepoRoot, runId, "before", before);
@@ -304,6 +315,7 @@ export function createAutoMemoryService(deps) {
             roleDraftsPath: path.join(runRoot, "drafts"),
             currentMemoryPath: path.join(runRoot, "before"),
             activeMemoryPaths: memoryPaths.map((memoryPath) => resolveRepoPath(taskRepoRoot, memoryPath)),
+            reviewResultPath: path.join(runRoot, "review-result.json"),
             proposalCandidates,
             ...(planningCandidatePath
                 ? { planningCandidatePath: resolveRepoPath(taskRepoRoot, planningCandidatePath) }
@@ -324,17 +336,30 @@ export function createAutoMemoryService(deps) {
     async function isRoleMemoryTurn(taskRepoRoot, role) {
         const state = await loadActiveState(taskRepoRoot);
         const draft = state?.status === "collecting" ? currentDraft(state) : undefined;
-        return draft?.role === role && draft.status === "dispatched";
+        if (draft?.role === role && draft.status === "dispatched") {
+            return true;
+        }
+        const assignment = state?.status === "documenting" ? currentDurableDocAssignment(state) : undefined;
+        if (!assignment) {
+            return false;
+        }
+        if (assignment.status === "resolving-owner") {
+            return role === "project-manager";
+        }
+        return assignment.status === "running" && assignment.owner === role;
     }
     async function handleRoleHook(input) {
         const state = await loadActiveState(input.taskRepoRoot);
-        if (!(await deps.appSettings.getPreferences()).autoMemoryEnabled) {
+        if (!(await deps.appSettings.getPreferences()).autoMemoryEnabled && !preserveDisabledReview(state)) {
             if (state) {
                 await discardActiveReview(input.taskRepoRoot, state);
                 return true;
             }
             return false;
         }
+        if (state?.status === "documenting") {
+            return handleDurableDocRoleHook(input, state);
+        }
         const draft = state?.status === "collecting" ? currentDraft(state) : undefined;
         if (!state || !draft || draft.role !== input.role) {
             return false;
@@ -375,7 +400,7 @@ export function createAutoMemoryService(deps) {
     }
     async function handleHarnessEngineerHook(input) {
         const state = await loadActiveState(input.taskRepoRoot);
-        if (!(await deps.appSettings.getPreferences()).autoMemoryEnabled) {
+        if (!(await deps.appSettings.getPreferences()).autoMemoryEnabled && !preserveDisabledReview(state)) {
             if (state) {
                 await discardActiveReview(input.taskRepoRoot, state);
                 return true;
@@ -404,6 +429,9 @@ export function createAutoMemoryService(deps) {
             }
             try {
                 await recordHarnessEngineerMemoryResult(input.taskRepoRoot, state);
+                if (state.assignments.length > 0) {
+                    await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, state);
+                }
             }
             catch (error) {
                 await failReview(input.taskRepoRoot, state, `Harness Engineer memory result could not be recorded: ${errorMessage(error)}`);
@@ -484,9 +512,49 @@ export function createAutoMemoryService(deps) {
         await clearActiveState(taskRepoRoot);
         return getState(baseRepoRoot, taskRepoRoot);
     }
+    async function retryDurableDocAssignment(baseRepoRoot, taskRepoRoot, assignmentId) {
+        const state = await loadActiveState(taskRepoRoot);
+        const assignment = state?.status === "documenting"
+            ? state.assignments.find((candidate) => candidate.id === assignmentId)
+            : undefined;
+        if (!state || !assignment || assignment.status !== "failed") {
+            throw new VcmError({
+                code: "DURABLE_DOC_ASSIGNMENT_NOT_FAILED",
+                message: `There is no failed durable-document assignment to retry: ${assignmentId}`,
+                statusCode: 409
+            });
+        }
+        assignment.status = assignment.owner ? "pending" : "waiting-owner";
+        assignment.updatedAt = now();
+        delete assignment.error;
+        delete assignment.requestedOwner;
+        delete assignment.dispatchedAt;
+        delete assignment.baseCommit;
+        delete assignment.reportHashBefore;
+        await persistMemoryAssignmentState(taskRepoRoot, state);
+        await dispatchCurrentDurableDocAssignment(baseRepoRoot, taskRepoRoot, state);
+        return getState(baseRepoRoot, taskRepoRoot);
+    }
+    async function resolveDurableDocAssignmentOwner(baseRepoRoot, taskRepoRoot, assignmentId, owner) {
+        const state = await loadActiveState(taskRepoRoot);
+        const assignment = state?.status === "documenting"
+            ? currentDurableDocAssignment(state)
+            : undefined;
+        if (!state || !assignment || assignment.id !== assignmentId || assignment.status !== "resolving-owner") {
+            throw new VcmError({
+                code: "DURABLE_DOC_OWNER_RESOLUTION_NOT_ACTIVE",
+                message: `Durable-document assignment is not waiting for PM owner resolution: ${assignmentId}`,
+                statusCode: 409
+            });
+        }
+        assignment.requestedOwner = owner;
+        assignment.updatedAt = now();
+        await persistMemoryAssignmentState(taskRepoRoot, state);
+        return getState(baseRepoRoot, taskRepoRoot);
+    }
     async function assertHarnessEngineerAvailable(taskRepoRoot) {
         const state = await loadActiveState(taskRepoRoot);
-        if (state && !(await deps.appSettings.getPreferences()).autoMemoryEnabled) {
+        if (state && !preserveDisabledReview(state) && !(await deps.appSettings.getPreferences()).autoMemoryEnabled) {
             await discardActiveReview(taskRepoRoot, state);
             return;
         }
@@ -502,7 +570,7 @@ export function createAutoMemoryService(deps) {
     }
     async function assertNoActiveReview(taskRepoRoot) {
         const state = await loadActiveState(taskRepoRoot);
-        if (state && !(await deps.appSettings.getPreferences()).autoMemoryEnabled) {
+        if (state && !preserveDisabledReview(state) && !(await deps.appSettings.getPreferences()).autoMemoryEnabled) {
             await discardActiveReview(taskRepoRoot, state);
             return;
         }
@@ -518,6 +586,166 @@ export function createAutoMemoryService(deps) {
                 : "Wait for the active memory review to finish."
         });
     }
+    async function handleDurableDocRoleHook(input, state) {
+        const assignment = currentDurableDocAssignment(state);
+        if (!assignment) {
+            return false;
+        }
+        const expectedRole = assignment.status === "resolving-owner"
+            ? "project-manager"
+            : assignment.status === "running"
+                ? assignment.owner
+                : undefined;
+        if (expectedRole !== input.role) {
+            return false;
+        }
+        if (input.eventName === "UserPromptSubmit" || input.eventName === "PostCompact") {
+            return true;
+        }
+        if (input.eventName === "StopFailure") {
+            assignment.status = "failed";
+            assignment.error = `${input.role} durable-document assignment turn failed.`;
+            assignment.updatedAt = now();
+            await persistMemoryAssignmentState(input.taskRepoRoot, state);
+            return true;
+        }
+        if (input.eventName !== "Stop") {
+            return true;
+        }
+        if (assignment.status === "resolving-owner") {
+            if (!assignment.requestedOwner) {
+                return true;
+            }
+            assignment.owner = assignment.requestedOwner;
+            delete assignment.requestedOwner;
+            assignment.status = "pending";
+            assignment.updatedAt = now();
+            await persistMemoryAssignmentState(input.taskRepoRoot, state);
+            await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, state);
+            return true;
+        }
+        try {
+            assignment.commit = await validateDurableDocAssignmentCompletion(input.taskRepoRoot, assignment);
+            assignment.status = "completed";
+            assignment.completedAt = now();
+            assignment.updatedAt = assignment.completedAt;
+            delete assignment.error;
+            await persistMemoryAssignmentState(input.taskRepoRoot, state);
+            const next = currentDurableDocAssignment(state);
+            if (next) {
+                await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, state);
+            }
+            else {
+                await clearActiveState(input.taskRepoRoot);
+            }
+        }
+        catch (error) {
+            assignment.status = "failed";
+            assignment.error = `Durable-document assignment could not be completed: ${errorMessage(error)}`;
+            assignment.updatedAt = now();
+            await persistMemoryAssignmentState(input.taskRepoRoot, state);
+        }
+        return true;
+    }
+    async function dispatchCurrentDurableDocAssignment(baseRepoRoot, taskRepoRoot, state) {
+        const assignment = currentDurableDocAssignment(state);
+        if (!assignment || assignment.status === "failed") {
+            return;
+        }
+        if (assignment.status === "running" || assignment.status === "resolving-owner") {
+            const role = assignment.status === "resolving-owner" ? "project-manager" : assignment.owner;
+            if (!role) {
+                return;
+            }
+            const existing = await deps.sessionService.getRoleSession(baseRepoRoot, state.taskSlug, role);
+            if (existing?.activityStatus === "running" && deps.runtime.getSession(existing.id)) {
+                return;
+            }
+            assignment.status = assignment.owner ? "pending" : "waiting-owner";
+            assignment.updatedAt = now();
+            await persistMemoryAssignmentState(taskRepoRoot, state);
+        }
+        const role = assignment.owner ?? "project-manager";
+        try {
+            const session = await ensureWorkflowRoleSession(baseRepoRoot, state.taskSlug, role);
+            if (session.activityStatus === "running") {
+                return;
+            }
+            assignment.status = assignment.owner ? "running" : "resolving-owner";
+            assignment.baseCommit = await deps.git.getHeadCommit(taskRepoRoot);
+            assignment.reportHashBefore = await hashOptionalFile(taskRepoRoot, assignment.reportPath);
+            assignment.dispatchedAt = now();
+            assignment.updatedAt = assignment.dispatchedAt;
+            await persistMemoryAssignmentState(taskRepoRoot, state);
+            await submitTerminalInput(deps.runtime, session.id, assignment.owner
+                ? buildDurableDocAssignmentPrompt(taskRepoRoot, assignment)
+                : buildDurableDocOwnerPrompt(taskRepoRoot, assignment));
+        }
+        catch (error) {
+            assignment.status = "failed";
+            assignment.error = `Unable to dispatch durable-document assignment: ${errorMessage(error)}`;
+            assignment.updatedAt = now();
+            await persistMemoryAssignmentState(taskRepoRoot, state);
+        }
+    }
+    async function validateDurableDocAssignmentCompletion(taskRepoRoot, assignment) {
+        const reportAbsolutePath = resolveRepoPath(taskRepoRoot, assignment.reportPath);
+        if (!(await deps.fs.pathExists(reportAbsolutePath))) {
+            throw new Error(`required report is missing: ${assignment.reportPath}`);
+        }
+        const reportContent = await deps.fs.readText(reportAbsolutePath);
+        const reportHash = sha256(reportContent);
+        if (assignment.reportHashBefore && reportHash === assignment.reportHashBefore) {
+            throw new Error(`${assignment.reportPath} was not updated for assignment ${assignment.id}`);
+        }
+        const check = checkMarkdownArtifact("docs-update-report", assignment.reportPath, reportContent);
+        if (check.status !== "ok") {
+            const reasons = [
+                ...check.missingHeadings.map((heading) => `missing heading ${heading}`),
+                ...check.invalidFields
+            ];
+            throw new Error(`${assignment.reportPath} is invalid: ${reasons.join("; ") || check.status}`);
+        }
+        const assignmentId = readArtifactSectionValue(reportContent, "Assignment ID")?.trim();
+        if (assignmentId !== assignment.id) {
+            throw new Error(`Assignment ID must be exactly ${assignment.id}`);
+        }
+        const decision = readArtifactSectionValue(reportContent, "Decision")?.trim().toLowerCase();
+        if (decision !== "synced" && decision !== "unchanged") {
+            throw new Error("Decision must be synced or unchanged");
+        }
+        const currentHead = await deps.git.getHeadCommit(taskRepoRoot);
+        if (decision === "synced") {
+            if (!assignment.baseCommit || currentHead === assignment.baseCommit) {
+                throw new Error("documentation changes were not committed");
+            }
+            const changedPaths = await deps.git.getChangedPaths(taskRepoRoot, assignment.baseCommit, currentHead);
+            if (!changedPaths.includes(assignment.targetPath)) {
+                throw new Error(`documentation commit does not include ${assignment.targetPath}`);
+            }
+            const reportedCommit = readArtifactSectionValue(reportContent, "Commit")?.trim();
+            if (!reportedCommit || reportedCommit === "TBD" || !currentHead.startsWith(reportedCommit)) {
+                throw new Error(`Commit must identify the current documentation commit ${currentHead}`);
+            }
+        }
+        return currentHead;
+    }
+    async function hashOptionalFile(taskRepoRoot, relativePath) {
+        const absolutePath = resolveRepoPath(taskRepoRoot, relativePath);
+        return await deps.fs.pathExists(absolutePath)
+            ? sha256(await deps.fs.readText(absolutePath))
+            : undefined;
+    }
+    async function persistMemoryAssignmentState(taskRepoRoot, state) {
+        state.updatedAt = now();
+        await persistActiveState(taskRepoRoot, state);
+        const run = await readRun(taskRepoRoot, state.runId);
+        await persistRun(taskRepoRoot, {
+            ...run,
+            assignments: state.assignments,
+            updatedAt: state.updatedAt
+        });
+    }
     async function dispatchCurrentDraft(baseRepoRoot, taskRepoRoot, state) {
         const draft = currentDraft(state);
         if (!draft || draft.status !== "pending") {
@@ -641,8 +869,27 @@ export function createAutoMemoryService(deps) {
                 hint: "Remove the unnecessary memory commits or leave memory unchanged without committing."
             });
         }
-        await writeRunMemorySet(taskRepoRoot, state.runId, "after", after);
+        const reviewResult = await readAndValidateHarnessMemoryReviewResult(taskRepoRoot, state, before, after, currentHead, changedMemoryPaths);
         const timestamp = now();
+        const assignments = reviewResult.durableDocAssignments.map((assignment, index) => {
+            const owner = inferDurableDocAssignmentOwner(assignment.targetPath);
+            return {
+                id: `${state.runId}-doc-${index + 1}`,
+                runId: state.runId,
+                sourceMemoryPath: assignment.sourceMemoryPath,
+                sourceEntry: assignment.sourceEntry,
+                targetPath: normalizeProjectRelativePath(assignment.targetPath),
+                content: assignment.content,
+                reason: assignment.reason,
+                evidence: assignment.evidence,
+                ...(owner ? { owner } : {}),
+                status: owner ? "pending" : "waiting-owner",
+                reportPath: ".ai/vcm/handoffs/docs-update-report.md",
+                createdAt: timestamp,
+                updatedAt: timestamp
+            };
+        });
+        await writeRunMemorySet(taskRepoRoot, state.runId, "after", after);
         const diff = renderMemoryDiff(before, after);
         const run = await readRun(taskRepoRoot, state.runId);
         await persistRun(taskRepoRoot, {
@@ -651,10 +898,225 @@ export function createAutoMemoryService(deps) {
             updatedAt: timestamp,
             appliedAt: timestamp,
             afterHashes: hashMemorySet(after),
-            diff
+            diff,
+            assignments
         });
         await deps.fs.writeText(resolveRepoPath(taskRepoRoot, `${MEMORY_REVIEW_RUNS_ROOT}/${state.runId}/applied.patch`), diff);
-        await clearActiveState(taskRepoRoot);
+        if (assignments.length === 0) {
+            await clearActiveState(taskRepoRoot);
+            return;
+        }
+        state.status = "documenting";
+        state.assignments = assignments;
+        state.updatedAt = timestamp;
+        delete state.error;
+        await persistActiveState(taskRepoRoot, state);
+    }
+    async function readAndValidateHarnessMemoryReviewResult(taskRepoRoot, state, before, after, currentHead, changedMemoryPaths) {
+        const resultPath = resolveRepoPath(taskRepoRoot, `${MEMORY_REVIEW_RUNS_ROOT}/${state.runId}/review-result.json`);
+        if (!(await deps.fs.pathExists(resultPath))) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_RESULT_MISSING",
+                message: "Harness Engineer did not write review-result.json.",
+                statusCode: 409,
+                hint: `Write the validated memory decisions to ${resultPath} before ending the retrospective turn.`
+            });
+        }
+        const result = await deps.fs.readJson(resultPath);
+        const shapeError = validateMemoryReviewResultShape(result, state.runId);
+        if (shapeError) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_RESULT_INVALID",
+                message: `Harness Engineer review-result.json is invalid: ${shapeError}`,
+                statusCode: 409
+            });
+        }
+        if (changedMemoryPaths.length > 0 && result.memoryCommit !== currentHead) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_RESULT_COMMIT_MISMATCH",
+                message: `review-result.json memoryCommit must be the current memory commit: ${currentHead}`,
+                statusCode: 409
+            });
+        }
+        if (changedMemoryPaths.length === 0 && result.memoryCommit !== "none") {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_RESULT_COMMIT_UNEXPECTED",
+                message: "review-result.json memoryCommit must be none when memory is unchanged.",
+                statusCode: 409
+            });
+        }
+        const candidates = await readReviewCandidates(taskRepoRoot, state);
+        const proposalDecisions = result.decisions.filter((decision) => decision.source === "proposal");
+        for (const candidate of candidates) {
+            const matches = proposalDecisions.filter((decision) => decision.itemId === candidate.id);
+            if (matches.length !== 1) {
+                throw new VcmError({
+                    code: "MEMORY_REVIEW_PROPOSAL_DECISION_MISSING",
+                    message: `review-result.json must contain exactly one decision for proposal ${candidate.id}.`,
+                    statusCode: 409
+                });
+            }
+            validateProposalDecision(candidate, matches[0], after);
+        }
+        const unknownProposal = proposalDecisions.find((decision) => !candidates.some((candidate) => candidate.id === decision.itemId));
+        if (unknownProposal) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_PROPOSAL_DECISION_UNKNOWN",
+                message: `review-result.json contains an unknown proposal decision: ${unknownProposal.itemId}`,
+                statusCode: 409
+            });
+        }
+        for (const decision of result.decisions.filter((candidate) => candidate.source === "existing")) {
+            const memoryPath = memoryTargetToPath(decision.target);
+            if (!substantiveMemoryEntries(before[memoryPath]).includes(decision.entry)) {
+                throw new VcmError({
+                    code: "MEMORY_REVIEW_EXISTING_DECISION_UNKNOWN",
+                    message: `review-result.json contains an unknown existing-memory decision: ${decision.itemId}`,
+                    statusCode: 409
+                });
+            }
+        }
+        for (const definition of MEMORY_FILE_DEFINITIONS) {
+            const target = memoryPathToTarget(definition.path);
+            for (const entry of substantiveMemoryEntries(before[definition.path])) {
+                const matches = result.decisions.filter((decision) => decision.source === "existing"
+                    && decision.target === target
+                    && decision.entry === entry);
+                if (matches.length !== 1) {
+                    throw new VcmError({
+                        code: "MEMORY_REVIEW_EXISTING_DECISION_MISSING",
+                        message: `review-result.json must contain exactly one decision for existing memory entry in ${definition.path}: ${entry}`,
+                        statusCode: 409
+                    });
+                }
+                validateExistingMemoryDecision(definition.path, entry, matches[0], after);
+            }
+        }
+        const moveDecisions = result.decisions.filter((decision) => decision.decision === "move-to-durable-doc");
+        if (moveDecisions.length !== result.durableDocAssignments.length) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_ASSIGNMENT_COUNT_MISMATCH",
+                message: "Every move-to-durable-doc decision must have exactly one durableDocAssignment.",
+                statusCode: 409
+            });
+        }
+        const assignmentKeys = new Set();
+        for (const assignment of result.durableDocAssignments) {
+            validateDurableDocAssignmentInput(assignment, after);
+            const key = `${assignment.sourceMemoryPath}\n${assignment.sourceEntry}\n${assignment.targetPath}`;
+            if (assignmentKeys.has(key)) {
+                throw new VcmError({
+                    code: "MEMORY_REVIEW_ASSIGNMENT_DUPLICATE",
+                    message: `Duplicate durableDocAssignment for ${assignment.targetPath}: ${assignment.sourceEntry}`,
+                    statusCode: 409
+                });
+            }
+            assignmentKeys.add(key);
+            const matchingDecision = moveDecisions.find((decision) => (memoryTargetToPath(decision.target) === assignment.sourceMemoryPath
+                && decision.entry === assignment.sourceEntry
+                && decision.durableDocPath === assignment.targetPath));
+            if (!matchingDecision) {
+                throw new VcmError({
+                    code: "MEMORY_REVIEW_ASSIGNMENT_DECISION_MISSING",
+                    message: `durableDocAssignment has no matching move decision: ${assignment.targetPath}`,
+                    statusCode: 409
+                });
+            }
+        }
+        return result;
+    }
+    function validateProposalDecision(candidate, decision, after) {
+        const expectedEntry = candidate.content ?? candidate.existing ?? "";
+        if (decision.entry !== expectedEntry || decision.target !== candidate.target) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_PROPOSAL_DECISION_MISMATCH",
+                message: `Proposal decision does not match assigned candidate ${candidate.id}.`,
+                statusCode: 409
+            });
+        }
+        const afterEntries = new Set(substantiveMemoryEntries(after[memoryTargetToPath(decision.target)]));
+        if (candidate.operation === "remove") {
+            if (decision.decision !== "remove" && decision.decision !== "retain") {
+                throw new VcmError({
+                    code: "MEMORY_REVIEW_PROPOSAL_DECISION_INVALID",
+                    message: `Remove proposal ${candidate.id} must use remove or retain.`,
+                    statusCode: 409
+                });
+            }
+            if (decision.decision === "remove" && afterEntries.has(expectedEntry)) {
+                throw new VcmError({
+                    code: "MEMORY_REVIEW_PROPOSAL_REMOVAL_MISMATCH",
+                    message: `Accepted removal is still present for proposal ${candidate.id}.`,
+                    statusCode: 409
+                });
+            }
+            if (decision.decision === "retain" && !afterEntries.has(expectedEntry)) {
+                throw new VcmError({
+                    code: "MEMORY_REVIEW_PROPOSAL_RETAIN_MISMATCH",
+                    message: `Rejected removal is missing from memory for proposal ${candidate.id}.`,
+                    statusCode: 409
+                });
+            }
+            return;
+        }
+        if (!new Set(["keep-in-memory", "keep-memory-reference", "move-to-durable-doc", "reject"]).has(decision.decision)) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_PROPOSAL_DECISION_INVALID",
+                message: `Add or update proposal ${candidate.id} uses an invalid decision: ${decision.decision}`,
+                statusCode: 409
+            });
+        }
+        if ((decision.decision === "keep-in-memory" || decision.decision === "keep-memory-reference")
+            && !afterEntries.has(decision.finalContent)) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_PROPOSAL_CONTENT_MISSING",
+                message: `Accepted proposal content is missing from memory for ${candidate.id}.`,
+                statusCode: 409
+            });
+        }
+    }
+    function validateExistingMemoryDecision(memoryPath, entry, decision, after) {
+        const afterEntries = new Set(substantiveMemoryEntries(after[memoryPath]));
+        if (decision.decision === "retain" && !afterEntries.has(entry)) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_RETAIN_MISMATCH",
+                message: `Retained memory entry is missing from ${memoryPath}: ${entry}`,
+                statusCode: 409
+            });
+        }
+        if ((decision.decision === "remove" || decision.decision === "move-to-durable-doc") && afterEntries.has(entry)) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_REMOVAL_MISMATCH",
+                message: `Removed memory entry is still present in ${memoryPath}: ${entry}`,
+                statusCode: 409
+            });
+        }
+        if (decision.decision === "update") {
+            if (!decision.finalContent || decision.finalContent === "none" || !afterEntries.has(decision.finalContent)) {
+                throw new VcmError({
+                    code: "MEMORY_REVIEW_UPDATE_MISMATCH",
+                    message: `Updated memory content is missing from ${memoryPath}: ${decision.finalContent}`,
+                    statusCode: 409
+                });
+            }
+        }
+    }
+    function validateDurableDocAssignmentInput(assignment, after) {
+        if (!MEMORY_FILE_DEFINITIONS.some((definition) => definition.path === assignment.sourceMemoryPath)) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_ASSIGNMENT_SOURCE_INVALID",
+                message: `Unknown memory source path: ${assignment.sourceMemoryPath}`,
+                statusCode: 409
+            });
+        }
+        if (substantiveMemoryEntries(after[assignment.sourceMemoryPath]).includes(assignment.sourceEntry)) {
+            throw new VcmError({
+                code: "MEMORY_REVIEW_ASSIGNMENT_SOURCE_NOT_REMOVED",
+                message: `Move-to-durable-doc must remove memory before assignment: ${assignment.sourceEntry}`,
+                statusCode: 409
+            });
+        }
+        assertDurableDocPath(assignment.targetPath);
     }
     async function createAppliedRun(taskRepoRoot, taskSlug, source, before, after) {
         assertCompleteMemorySet(after);
@@ -663,7 +1125,7 @@ export function createAutoMemoryService(deps) {
         await writeRunMemorySet(taskRepoRoot, runId, "before", before);
         await writeRunMemorySet(taskRepoRoot, runId, "after", after);
         try {
-            await applyAndCommitMemorySet(taskRepoRoot, before, after, "chore: update VCM memory");
+            await applyAndCommitMemorySet(taskRepoRoot, before, after, "[VCM Harness] Update VCM memory");
             const diff = renderMemoryDiff(before, after);
             await persistRun(taskRepoRoot, {
                 version: 1,
@@ -729,6 +1191,7 @@ export function createAutoMemoryService(deps) {
                 finalAcceptanceHash: run.finalAcceptanceHash,
                 trigger: run.trigger,
                 diff: run.diff ?? "",
+                assignments: run.assignments ?? [],
                 canRevert: run.status === "applied" && !run.revertedAt && Boolean(run.afterHashes),
                 error: run.error
             });
@@ -780,6 +1243,7 @@ export function createAutoMemoryService(deps) {
         const migrated = stored.drafts.some((draft) => draft.status === "running");
         const state = {
             ...stored,
+            assignments: stored.assignments ?? [],
             drafts: stored.drafts.map((draft) => ({
                 ...draft,
                 status: draft.status === "running" ? "dispatched" : draft.status
@@ -840,6 +1304,8 @@ export function createAutoMemoryService(deps) {
         updateFile,
         revertRun,
         retryFailedReview,
+        retryDurableDocAssignment,
+        resolveDurableDocAssignmentOwner,
         prepareTaskRetrospectiveReview,
         cancelTaskRetrospectiveReview,
         isRoleMemoryTurn,
@@ -863,6 +1329,13 @@ export async function assertMemoryBlocksInstalled(fs, taskRepoRoot) {
 function currentDraft(state) {
     return state.drafts.find((draft) => draft.status !== "completed");
 }
+function preserveDisabledReview(state) {
+    return state?.status === "documenting"
+        || (state?.status === "reviewing" && Boolean(state.reviewPromptDispatchedAt));
+}
+function currentDurableDocAssignment(state) {
+    return state.assignments.find((assignment) => assignment.status !== "completed");
+}
 function toReviewCandidates(source, currentRole, items) {
     return items.map((item) => ({
         id: `${source}:${item.operation}:${item.ordinal}`,
@@ -883,6 +1356,7 @@ function toActiveReview(state) {
         updatedAt: state.updatedAt,
         currentRole: state.status === "collecting" ? currentDraft(state)?.role : undefined,
         drafts: state.drafts,
+        assignments: state.assignments,
         trigger: state.trigger,
         error: state.error
     };
@@ -913,6 +1387,160 @@ function buildRoleDraftPrompt(taskRepoRoot, state, draft, planningCandidatePath)
         "End the turn after VCM accepts the proposal."
     ].join("\n");
 }
+function buildDurableDocOwnerPrompt(taskRepoRoot, assignment) {
+    return [
+        "[VCM Durable Documentation Owner Resolution]",
+        "",
+        `Task worktree: ${taskRepoRoot}`,
+        `Assignment ID: ${assignment.id}`,
+        `Target document: ${assignment.targetPath}`,
+        `Content to preserve: ${assignment.content}`,
+        `Reason: ${assignment.reason}`,
+        "",
+        "Choose architect, coder, or tester as the document owner. If the correct owner cannot be determined, ask the user and wait for the answer.",
+        `After deciding, run: .ai/tools/resolve-durable-doc-assignment --assignment ${assignment.id} --owner <architect|coder|tester>`,
+        "End the turn after VCM accepts the owner."
+    ].join("\n");
+}
+function buildDurableDocAssignmentPrompt(taskRepoRoot, assignment) {
+    return [
+        "[VCM Durable Documentation Assignment]",
+        "",
+        `Task worktree: ${taskRepoRoot}`,
+        `Assignment ID: ${assignment.id}`,
+        `Target document: ${assignment.targetPath}`,
+        `Content to preserve: ${assignment.content}`,
+        `Reason: ${assignment.reason}`,
+        "Evidence:",
+        ...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.",
+        "Submit .ai/vcm/handoffs/docs-update-report.md through vcm-artifact. Set its Assignment ID to the exact ID above and record the final commit.",
+        "End the turn after VCM accepts the report."
+    ].join("\n");
+}
+function inferDurableDocAssignmentOwner(targetPath) {
+    const normalized = normalizeProjectRelativePath(targetPath);
+    if (normalized === "docs/TESTING.md") {
+        return "tester";
+    }
+    if (normalized === "docs/ARCHITECTURE.md"
+        || normalized === "docs/known-issues.md"
+        || normalized.endsWith("/ARCHITECTURE.md")) {
+        return "architect";
+    }
+    return undefined;
+}
+function memoryPathToTarget(memoryPath) {
+    if (memoryPath === "CLAUDE.md") {
+        return "shared";
+    }
+    const definition = MEMORY_FILE_DEFINITIONS.find((candidate) => candidate.path === memoryPath);
+    if (!definition || !("role" in definition)) {
+        throw new Error(`Unknown memory path: ${memoryPath}`);
+    }
+    return definition.role;
+}
+function memoryTargetToPath(target) {
+    if (target === "shared") {
+        return "CLAUDE.md";
+    }
+    const definition = MEMORY_FILE_DEFINITIONS.find((candidate) => "role" in candidate && candidate.role === target);
+    if (!definition) {
+        throw new Error(`Unknown memory target: ${target}`);
+    }
+    return definition.path;
+}
+function substantiveMemoryEntries(content) {
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean);
+}
+function assertDurableDocPath(targetPath) {
+    const normalized = normalizeProjectRelativePath(targetPath);
+    if (!normalized
+        || normalized.startsWith("../")
+        || path.posix.isAbsolute(normalized)
+        || normalized.startsWith(".ai/vcm/")
+        || !normalized.endsWith(".md")) {
+        throw new VcmError({
+            code: "MEMORY_REVIEW_DURABLE_DOC_PATH_INVALID",
+            message: `Durable-document target must be a project-relative Markdown path outside .ai/vcm: ${targetPath}`,
+            statusCode: 409
+        });
+    }
+}
+function normalizeProjectRelativePath(filePath) {
+    return filePath.trim().replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function validateMemoryReviewResultShape(result, runId) {
+    if (!result || typeof result !== "object") {
+        return "root value must be an object";
+    }
+    if (result.version !== 1) {
+        return "version must be 1";
+    }
+    if (result.runId !== runId) {
+        return `runId must be ${runId}`;
+    }
+    if (typeof result.memoryCommit !== "string" || !result.memoryCommit.trim()) {
+        return "memoryCommit must be a non-empty string";
+    }
+    if (!Array.isArray(result.decisions) || !Array.isArray(result.durableDocAssignments)) {
+        return "decisions and durableDocAssignments must be arrays";
+    }
+    const allowedSources = new Set(["existing", "proposal"]);
+    const allowedTargets = new Set(["shared", "project-manager", "architect", "coder", "tester", "reviewer", "harness-engineer"]);
+    const allowedDecisions = new Set([
+        "retain",
+        "update",
+        "remove",
+        "move-to-durable-doc",
+        "keep-in-memory",
+        "keep-memory-reference",
+        "reject"
+    ]);
+    for (const decision of result.decisions) {
+        if (!decision
+            || typeof decision.itemId !== "string"
+            || !allowedSources.has(decision.source)
+            || !allowedTargets.has(decision.target)
+            || typeof decision.entry !== "string"
+            || !decision.entry.trim()
+            || !allowedDecisions.has(decision.decision)
+            || typeof decision.reason !== "string"
+            || !decision.reason.trim()
+            || typeof decision.impactIfAbsent !== "string"
+            || !decision.impactIfAbsent.trim()
+            || !Array.isArray(decision.evidence)
+            || decision.evidence.length === 0
+            || decision.evidence.some((item) => typeof item !== "string" || !item.trim())
+            || typeof decision.finalContent !== "string"
+            || !decision.finalContent.trim()
+            || typeof decision.durableDocPath !== "string"
+            || !decision.durableDocPath.trim()) {
+            return "every decision must use the complete review-result decision schema";
+        }
+    }
+    for (const assignment of result.durableDocAssignments) {
+        if (!assignment
+            || typeof assignment.sourceMemoryPath !== "string"
+            || typeof assignment.sourceEntry !== "string"
+            || !assignment.sourceEntry.trim()
+            || typeof assignment.targetPath !== "string"
+            || typeof assignment.content !== "string"
+            || !assignment.content.trim()
+            || typeof assignment.reason !== "string"
+            || !assignment.reason.trim()
+            || !Array.isArray(assignment.evidence)
+            || assignment.evidence.length === 0
+            || assignment.evidence.some((item) => typeof item !== "string" || !item.trim())) {
+            return "every durableDocAssignment must use the complete assignment schema";
+        }
+    }
+    return undefined;
+}
 function requireMemoryFileDefinition(filePath) {
     const normalized = filePath.replaceAll("\\", "/").replace(/^\.\//, "");
     const definition = MEMORY_FILE_DEFINITIONS.find((candidate) => candidate.path === normalized);