vibe-coding-master 0.8.5 → 0.8.7

package/README.md

@@ -589,10 +589,26 @@ before documentation work starts. VCM assigns architecture and known-issues
 documents to Architect and testing documentation to Tester. For another target,
 PM selects Architect, Coder, or Tester and asks the user only when ownership
 cannot be determined. These assignments are backend-dispatched work rather than
-a Docs-Only Flow. Each owner updates and commits the document, submits the exact
-assignment ID in `docs-update-report.md`, and finishes before the next assignment
-starts. Harness Studio shows assignment status and allows failed work to be
-retried.
+a Docs-Only Flow. Each owner submits `docs-update-report` through `vcm-artifact`
+with the exact assigned `--path` and Assignment ID. Reports are isolated under
+`.ai/vcm/memory-review/runs/<run-id>/assignments/<assignment-id>/report.md`.
+The reported commit must modify the target document within the assignment's
+original commit range; unrelated later commits do not invalidate it. Existing
+correct documentation can be reported as `unchanged` without a new commit.
+For `synced`, the entire `Commit` section is one bare lowercase hexadecimal
+hash (7-40 characters), without Markdown or explanatory text. The template,
+artifact submission, and assignment completion use the same format contract.
+
+Assignments run one at a time. A failed assignment does not block later items.
+After the remaining items finish, unresolved failures are reported in Harness
+Studio with their causes and individual Retry buttons. Retry preserves earlier
+committed work and the original baseline, including after a backend restart.
+An old assignment whose baseline was already overwritten is not automatically
+rebased; verify the current document and use `unchanged` when it already preserves
+the assigned content. Errors identify the reported commit and recorded range.
+Migration content and review snapshots remain in the task-local run directory;
+failures do not automatically restore removed memory. Turning Auto Memory off
+does not discard or cancel already-applied document migrations.
 
 When Auto Memory is disabled, Review Task Harness does not collect proposals or
 ask Harness Engineer to update memory. When enabled, both automatic and manual

package/dist/backend/server.js

@@ -246,7 +246,7 @@ export function createDefaultServerDeps(options = {}) {
     const workflowControlService = createWorkflowControlService({ fs });
     const artifactService = createArtifactService(fs, {
         workflowControlService,
-        isRoleMemoryTurn: (taskRepoRoot, role) => autoMemoryService.isRoleMemoryTurn(taskRepoRoot, role)
+        getDurableDocAssignment: (taskRepoRoot, role) => autoMemoryService.getDurableDocAssignment(taskRepoRoot, role)
     });
     const projectService = createProjectService({ fs, git, appSettings });
     const taskService = createTaskService({ fs, git, artifactService, projectService });

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

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { DISPATCHABLE_ROLES } from "../../shared/constants.js";
-import { checkMarkdownArtifact } from "../../shared/validation/artifact-check.js";
+import { checkMarkdownArtifact, readArtifactSectionValue } from "../../shared/validation/artifact-check.js";
 import { getManagedArtifactDefinition, isArtifactKind, isManagedArtifactKind } from "../../shared/validation/artifact-registry.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
@@ -208,10 +208,21 @@ export function createArtifactService(fs, deps = {}) {
                 });
             }
             if (isArtifactKind(input.kind)) {
-                if (input.artifactPath?.trim()) {
+                const assignment = input.kind === "docs-update-report"
+                    ? await deps.getDurableDocAssignment?.(input.repoRoot, input.role)
+                    : undefined;
+                if (assignment) {
+                    if (input.artifactPath !== assignment.reportPath) {
+                        throw artifactRejected(input.kind, [`Use the assigned --path ${assignment.reportPath}.`]);
+                    }
+                    if (readArtifactSectionValue(normalized, "Assignment ID")?.trim() !== assignment.id) {
+                        throw artifactRejected(input.kind, [`Assignment ID must be exactly ${assignment.id}.`]);
+                    }
+                }
+                else if (input.artifactPath?.trim()) {
                     throw artifactRejected(input.kind, ["--path is not allowed for fixed artifact kinds."]);
                 }
-                const artifactPath = path.posix.join(input.handoffDir, definition.fileName ?? "");
+                const artifactPath = assignment?.reportPath ?? path.posix.join(input.handoffDir, definition.fileName ?? "");
                 const validation = validateManagedArtifactContent(input.kind, normalized, {
                     path: artifactPath,
                     mode: input.mode
@@ -222,9 +233,7 @@ export function createArtifactService(fs, deps = {}) {
                 if ((input.kind === "docs-update-report" || input.kind === "docs-sync-report")
                     && deps.workflowControlService) {
                     // Memory-owned documentation work is independent of PM's active dispatch.
-                    const memoryUpdate = input.kind === "docs-update-report"
-                        && await deps.isRoleMemoryTurn?.(input.repoRoot, input.role);
-                    if (!memoryUpdate) {
+                    if (!assignment) {
                         await deps.workflowControlService.assertDocsArtifactAllowed({
                             taskRepoRoot: input.repoRoot,
                             stateRoot: input.stateRoot ?? ".ai/vcm",

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

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
 import path from "node:path";
-import { checkMarkdownArtifact, readArtifactSectionValue } from "../../shared/validation/artifact-check.js";
+import { checkMarkdownArtifact, readArtifactSectionContent, readArtifactSectionValue } from "../../shared/validation/artifact-check.js";
+import { DOCS_UPDATE_COMMIT_RULE } from "../../shared/validation/artifact-contract.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { VcmError } from "../errors.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { readVcmMemoryHostFrame, readVcmMemoryBlock, replaceVcmMemoryBlock } from "../templates/harness/memory-block.js";
-import { ARCHITECT_PLANNING_MEMORY_CANDIDATE_PATH, architectPlanningCandidateSnapshotPath, memoryReviewRoleDraftPath, MEMORY_REVIEW_RUNS_ROOT, MEMORY_REVIEW_STATE_PATH } from "./memory-review-paths.js";
+import { ARCHITECT_PLANNING_MEMORY_CANDIDATE_PATH, architectPlanningCandidateSnapshotPath, durableDocAssignmentReportPath, 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" },
@@ -18,6 +19,20 @@ const MEMORY_FILE_DEFINITIONS = [
 ];
 export function createAutoMemoryService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
+    const taskLocks = new Map();
+    async function withTaskLock(taskRepoRoot, operation) {
+        const previous = taskLocks.get(taskRepoRoot) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(operation);
+        taskLocks.set(taskRepoRoot, current);
+        try {
+            return await current;
+        }
+        finally {
+            if (taskLocks.get(taskRepoRoot) === current) {
+                taskLocks.delete(taskRepoRoot);
+            }
+        }
+    }
     async function readMemorySet(repoRoot) {
         const memory = {};
         for (const definition of MEMORY_FILE_DEFINITIONS) {
@@ -151,7 +166,7 @@ export function createAutoMemoryService(deps) {
             else if (active?.status === "reviewing" && active.reviewPromptDispatchedAt) {
                 return getState(input.baseRepoRoot, input.taskRepoRoot);
             }
-            else if (active) {
+            else if (active && !preserveDisabledReview(active)) {
                 await discardActiveReview(input.taskRepoRoot, active);
             }
             return getState(input.baseRepoRoot, input.taskRepoRoot);
@@ -361,6 +376,11 @@ export function createAutoMemoryService(deps) {
         }
         return assignment.status === "running" && assignment.owner === role;
     }
+    async function getDurableDocAssignment(taskRepoRoot, role) {
+        const state = await loadActiveState(taskRepoRoot);
+        const assignment = state?.status === "documenting" ? currentDurableDocAssignment(state) : undefined;
+        return assignment?.status === "running" && assignment.owner === role ? assignment : undefined;
+    }
     async function handleRoleHook(input) {
         const state = await loadActiveState(input.taskRepoRoot);
         if (!(await deps.appSettings.getPreferences()).autoMemoryEnabled && !preserveDisabledReview(state)) {
@@ -522,12 +542,19 @@ export function createAutoMemoryService(deps) {
                 statusCode: 409
             });
         }
+        if (state.assignments.length > 0) {
+            throw new VcmError({
+                code: "DURABLE_DOC_ASSIGNMENTS_FAILED",
+                message: "Memory was already applied. Retry the failed durable-document assignments individually.",
+                statusCode: 409
+            });
+        }
         await clearActiveState(taskRepoRoot);
         return getState(baseRepoRoot, taskRepoRoot);
     }
     async function retryDurableDocAssignment(baseRepoRoot, taskRepoRoot, assignmentId) {
         const state = await loadActiveState(taskRepoRoot);
-        const assignment = state?.status === "documenting"
+        const assignment = state && (state.status === "documenting" || state.status === "failed")
             ? state.assignments.find((candidate) => candidate.id === assignmentId)
             : undefined;
         if (!state || !assignment || assignment.status !== "failed") {
@@ -539,11 +566,10 @@ export function createAutoMemoryService(deps) {
         }
         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;
+        state.status = "documenting";
+        delete state.error;
         await persistMemoryAssignmentState(taskRepoRoot, state);
         await dispatchCurrentDurableDocAssignment(baseRepoRoot, taskRepoRoot, state);
         return getState(baseRepoRoot, taskRepoRoot);
@@ -620,6 +646,7 @@ export function createAutoMemoryService(deps) {
             assignment.error = `${input.role} durable-document assignment turn failed.`;
             assignment.updatedAt = now();
             await persistMemoryAssignmentState(input.taskRepoRoot, state);
+            await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, state);
             return true;
         }
         if (input.eventName !== "Stop") {
@@ -644,13 +671,6 @@ export function createAutoMemoryService(deps) {
             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";
@@ -658,11 +678,13 @@ export function createAutoMemoryService(deps) {
             assignment.updatedAt = now();
             await persistMemoryAssignmentState(input.taskRepoRoot, state);
         }
+        await dispatchCurrentDurableDocAssignment(input.baseRepoRoot, input.taskRepoRoot, state);
         return true;
     }
     async function dispatchCurrentDurableDocAssignment(baseRepoRoot, taskRepoRoot, state) {
-        const assignment = currentDurableDocAssignment(state);
-        if (!assignment || assignment.status === "failed") {
+        let assignment = currentDurableDocAssignment(state);
+        if (!assignment) {
+            await finishDurableDocAssignments(taskRepoRoot, state);
             return;
         }
         if (assignment.status === "running" || assignment.status === "resolving-owner") {
@@ -678,28 +700,50 @@ export function createAutoMemoryService(deps) {
             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") {
+        while (assignment) {
+            try {
+                await dispatchDurableDocAssignment(baseRepoRoot, taskRepoRoot, state, assignment);
                 return;
             }
-            assignment.status = assignment.owner ? "running" : "resolving-owner";
+            catch (error) {
+                assignment.status = "failed";
+                assignment.error = `Unable to dispatch durable-document assignment: ${errorMessage(error)}`;
+                assignment.updatedAt = now();
+                await persistMemoryAssignmentState(taskRepoRoot, state);
+                assignment = currentDurableDocAssignment(state);
+            }
+        }
+        await finishDurableDocAssignments(taskRepoRoot, state);
+    }
+    async function dispatchDurableDocAssignment(baseRepoRoot, taskRepoRoot, state, assignment) {
+        const session = await ensureWorkflowRoleSession(baseRepoRoot, state.taskSlug, assignment.owner ?? "project-manager");
+        if (session.activityStatus === "running") {
+            return;
+        }
+        assignment.status = assignment.owner ? "running" : "resolving-owner";
+        assignment.reportPath = durableDocAssignmentReportPath(assignment.runId, assignment.id);
+        if (!assignment.baseCommit) {
             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();
+        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));
+    }
+    async function finishDurableDocAssignments(taskRepoRoot, state) {
+        const failed = state.assignments.filter((assignment) => assignment.status === "failed");
+        if (failed.length > 0) {
+            state.status = "failed";
+            state.error = `Memory was applied, but ${failed.length} durable-document assignment(s) failed: ${failed.map((assignment) => assignment.targetPath).join(", ")}. Retry the failed assignments; their content is retained in the memory review run.`;
             await persistMemoryAssignmentState(taskRepoRoot, state);
+            return;
         }
+        delete state.error;
+        await persistMemoryAssignmentState(taskRepoRoot, state);
+        await clearActiveState(taskRepoRoot);
     }
     async function validateDurableDocAssignmentCompletion(taskRepoRoot, assignment) {
         const reportAbsolutePath = resolveRepoPath(taskRepoRoot, assignment.reportPath);
@@ -727,22 +771,46 @@ export function createAutoMemoryService(deps) {
         if (decision !== "synced" && decision !== "unchanged") {
             throw new Error("Decision must be synced or unchanged");
         }
+        if (!(await deps.fs.pathExists(resolveRepoPath(taskRepoRoot, assignment.targetPath)))) {
+            throw new Error(`target document is missing: ${assignment.targetPath}`);
+        }
         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 validateDurableDocCommit(taskRepoRoot, assignment, reportContent, currentHead);
         }
         return currentHead;
     }
+    async function validateDurableDocCommit(taskRepoRoot, assignment, reportContent, currentHead) {
+        const reportedCommit = readArtifactSectionContent(reportContent, "Commit");
+        let commit;
+        try {
+            commit = (await deps.git.getCommitInfo(taskRepoRoot, reportedCommit)).sha;
+        }
+        catch (error) {
+            const detail = error instanceof VcmError && error.hint ? `${errorMessage(error)} ${error.hint}` : errorMessage(error);
+            throw new Error(`Commit ${reportedCommit} could not be resolved to a unique Git commit: ${detail}`);
+        }
+        const existingContentHint = `If ${assignment.targetPath} already preserves the assigned content, report unchanged with verification evidence; do not create a redundant commit.`;
+        if (!assignment.baseCommit) {
+            throw new Error(`Assignment ${assignment.id} has no recorded commit baseline; cannot validate Commit ${commit}. ${existingContentHint}`);
+        }
+        if (currentHead === assignment.baseCommit) {
+            throw new Error(`No commits follow assignment baseline ${assignment.baseCommit} (HEAD is the same commit); received Commit ${commit}. The document may already have been committed before this baseline. ${existingContentHint}`);
+        }
+        const commits = await deps.git.getCommitList(taskRepoRoot, `${assignment.baseCommit}..${currentHead}`);
+        if (!commits.some((candidate) => candidate.sha === commit)) {
+            throw new Error(`Commit ${commit} exists but is outside assignment range ${assignment.baseCommit}..${currentHead}. ${existingContentHint}`);
+        }
+        const commitPaths = await deps.git.getChangedPaths(taskRepoRoot, `${commit}^`, commit);
+        if (!commitPaths.includes(assignment.targetPath)) {
+            throw new Error(`reported commit ${commit} does not modify ${assignment.targetPath}`);
+        }
+        const changedPaths = await deps.git.getChangedPaths(taskRepoRoot, assignment.baseCommit, currentHead);
+        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.`);
+        }
+        return commit;
+    }
     async function hashOptionalFile(taskRepoRoot, relativePath) {
         const absolutePath = resolveRepoPath(taskRepoRoot, relativePath);
         return await deps.fs.pathExists(absolutePath)
@@ -756,6 +824,7 @@ export function createAutoMemoryService(deps) {
         await persistRun(taskRepoRoot, {
             ...run,
             assignments: state.assignments,
+            error: state.error,
             updatedAt: state.updatedAt
         });
     }
@@ -897,7 +966,7 @@ export function createAutoMemoryService(deps) {
                 evidence: assignment.evidence,
                 ...(owner ? { owner } : {}),
                 status: owner ? "pending" : "waiting-owner",
-                reportPath: ".ai/vcm/handoffs/docs-update-report.md",
+                reportPath: durableDocAssignmentReportPath(state.runId, `${state.runId}-doc-${index + 1}`),
                 createdAt: timestamp,
                 updatedAt: timestamp
             };
@@ -1317,20 +1386,21 @@ export function createAutoMemoryService(deps) {
         return `sha256:${sha256(content)}`;
     }
     return {
-        reconcileTask,
+        reconcileTask: (input) => withTaskLock(input.taskRepoRoot, () => reconcileTask(input)),
         getState,
         getTaskRetrospectiveReadiness,
         getFile,
         updateFile,
         revertRun,
         retryFailedReview,
-        retryDurableDocAssignment,
-        resolveDurableDocAssignmentOwner,
+        retryDurableDocAssignment: (base, task, id) => withTaskLock(task, () => retryDurableDocAssignment(base, task, id)),
+        resolveDurableDocAssignmentOwner: (base, task, id, owner) => withTaskLock(task, () => resolveDurableDocAssignmentOwner(base, task, id, owner)),
         prepareTaskRetrospectiveReview,
         cancelTaskRetrospectiveReview,
         isRoleMemoryTurn,
-        handleRoleHook,
-        handleHarnessEngineerHook,
+        getDurableDocAssignment,
+        handleRoleHook: (input) => withTaskLock(input.taskRepoRoot, () => handleRoleHook(input)),
+        handleHarnessEngineerHook: (input) => withTaskLock(input.taskRepoRoot, () => handleHarnessEngineerHook(input)),
         assertHarnessEngineerAvailable
     };
 }
@@ -1350,11 +1420,12 @@ function currentDraft(state) {
     return state.drafts.find((draft) => draft.status !== "completed");
 }
 function preserveDisabledReview(state) {
-    return state?.status === "documenting"
+    return Boolean(state?.assignments.length)
         || (state?.status === "reviewing" && Boolean(state.reviewPromptDispatchedAt));
 }
 function currentDurableDocAssignment(state) {
-    return state.assignments.find((assignment) => assignment.status !== "completed");
+    return state.assignments.find((assignment) => assignment.status === "running" || assignment.status === "resolving-owner")
+        ?? state.assignments.find((assignment) => assignment.status === "pending" || assignment.status === "waiting-owner");
 }
 function toReviewCandidates(source, currentRole, items) {
     return items.map((item) => ({
@@ -1435,7 +1506,12 @@ 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.",
-        "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.",
+        `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.",
+        DOCS_UPDATE_COMMIT_RULE,
+        "For synced, record the commit that changed the target document; it need not be HEAD. If the document already preserves the content, use unchanged with evidence; do not create a redundant commit.",
+        ...(assignment.error ? [`Previous failure: ${assignment.error}`] : []),
         "End the turn after VCM accepts the report."
     ].join("\n");
 }

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

@@ -160,6 +160,7 @@ export function createClaudeHookService(deps) {
                 taskSlug: activeTask.taskSlug,
                 eventName,
                 memoryReviewStatus: memoryState?.status ?? "idle",
+                memoryReviewHasAssignments: Boolean(memoryState?.active?.assignments.length),
                 memoryReviewError: memoryState?.active?.error
             })
             : false;

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

@@ -164,6 +164,7 @@ export function createHarnessFeedbackService(deps) {
             await persistTaskRetrospectiveMarker(repoRoot, {
                 ...processedMarker,
                 status: "failed",
+                durableDocFailure: input.memoryReviewHasAssignments,
                 failedAt: timestamp,
                 updatedAt: timestamp,
                 error: input.memoryReviewError
@@ -185,17 +186,26 @@ export function createHarnessFeedbackService(deps) {
     }
     async function completeWaitingTaskRetrospective(repoRoot, taskSlug, memoryStatus) {
         const marker = await loadTaskRetrospectiveMarker(repoRoot, taskSlug);
-        if (!marker || marker.status !== "waiting-docs") {
+        if (!marker || (marker.status !== "waiting-docs" && !(marker.status === "failed" && marker.durableDocFailure))) {
             return false;
         }
         if (memoryStatus === "documenting") {
+            if (marker.status === "failed") {
+                await persistTaskRetrospectiveMarker(repoRoot, {
+                    ...marker, status: "waiting-docs", updatedAt: now(), error: undefined, failedAt: undefined
+                });
+            }
             return true;
         }
         if (memoryStatus === "failed") {
+            if (marker.status === "failed") {
+                return true;
+            }
             const timestamp = now();
             await persistTaskRetrospectiveMarker(repoRoot, {
                 ...marker,
                 status: "failed",
+                durableDocFailure: true,
                 failedAt: timestamp,
                 updatedAt: timestamp,
                 error: "Task Harness Retrospective durable-document assignment failed."
@@ -214,6 +224,9 @@ export function createHarnessFeedbackService(deps) {
         await persistTaskRetrospectiveMarker(repoRoot, {
             ...processedMarker,
             status: "completed",
+            durableDocFailure: undefined,
+            error: undefined,
+            failedAt: undefined,
             completedAt: timestamp,
             updatedAt: timestamp
         });

package/dist/backend/services/memory-review-paths.js

@@ -6,6 +6,9 @@ const MEMORY_REVIEW_ROLE_DRAFT_PATTERN = new RegExp(`^${escapeRegExp(MEMORY_REVI
 export function memoryReviewRoleDraftPath(runId, role) {
     return `${MEMORY_REVIEW_RUNS_ROOT}/${runId}/drafts/${role}.md`;
 }
+export function durableDocAssignmentReportPath(runId, assignmentId) {
+    return `${MEMORY_REVIEW_RUNS_ROOT}/${runId}/assignments/${assignmentId}/report.md`;
+}
 export function isMemoryProposalSubmissionPath(artifactPath, role) {
     if (artifactPath === ARCHITECT_PLANNING_MEMORY_CANDIDATE_PATH) {
         return role === "architect";

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_SYNC_CORRECTION_OWNERS, 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_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, DOCS_UPDATE_COMMIT_RULE, DOCS_SYNC_CORRECTION_OWNERS, 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}
@@ -534,6 +534,8 @@ export function renderDocsUpdateReportTemplate(taskSlug, assignmentId = "docs-on
 
 ${CURRENT_HANDOFF_NOTICE}
 
+${DOCS_UPDATE_COMMIT_RULE}
+
 ## Summary
 
 TBD

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

@@ -301,7 +301,8 @@ Each rewritten \`architecture-diagnosis.md\` must be a complete, self-contained
 - 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.
+  assigned Assignment ID. Use \`vcm-artifact docs-update-report --path <assigned-report-path>\`;
+  do not use the shared Docs-Only report path. 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.

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

@@ -82,7 +82,8 @@ ${renderRoleMemoryRules("coder")}
 - For a \`[VCM Durable Documentation Assignment]\`, verify and update the assigned
   durable document and directly related documentation, run applicable 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.
+  Assignment ID. Use \`vcm-artifact docs-update-report --path <assigned-report-path>\`;
+  do not use the shared Docs-Only report path. This backend assignment does not start Docs-Only Flow.
 
 - In Docs-Only Flow, commit the documentation changes and submit \`.ai/vcm/handoffs/docs-update-report.md\` through \`vcm-artifact\` with the decision, changed and reviewed documents, evidence, checks, commit, and remaining documentation issues. Do not submit \`coder-completion.md\` for Docs-Only work.
 - Submit \`.ai/vcm/handoffs/coder-completion.md\` before routing back to project-manager: write a candidate outside \`.ai/vcm\`, then run \`.ai/tools/vcm-artifact coder-completion --file <candidate> --mode draft|final\`. This file is the complete, self-contained current implementation completion evidence, not a log. Each revision must restate every Scaffold Manifest disposition, changed file, helper, deviation, generated-context result, baseline-test change, L0/L1 command and result, worker result, commit, and objective failure still needed to review the current implementation without a prior revision. Replace stale content instead of appending history.

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

@@ -42,8 +42,8 @@ ${renderRoleMemoryRules("tester")}
 - For a \`[VCM Durable Documentation Assignment]\`, verify and 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.
+  with the exact assigned Assignment ID. Use \`vcm-artifact docs-update-report --path <assigned-report-path>\`;
+  do not use the shared Docs-Only report path. This backend assignment does not start Docs-Only Flow.
 
 - Verify the assigned documentation against current project evidence, update the required documentation, run applicable documentation checks, and commit the changes.
 - Submit \`.ai/vcm/handoffs/docs-update-report.md\` through \`vcm-artifact\` with the decision, changed and reviewed documents, evidence, checks, commit, and remaining documentation issues.

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_SYNC_CORRECTION_OWNERS, 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_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_REPORT_DECISIONS, DOCS_UPDATE_COMMIT_PATTERN, DOCS_UPDATE_COMMIT_RULE, DOCS_SYNC_CORRECTION_OWNERS, 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 = {}) {
@@ -252,7 +252,13 @@ function validateArtifactFields(kind, content, mode) {
         return invalidFields;
     }
     if (kind === "docs-update-report") {
-        return validateDecision(content, DOCS_REPORT_DECISIONS);
+        const invalidFields = validateDecision(content, DOCS_REPORT_DECISIONS);
+        const decision = readArtifactSectionContent(content, "Decision")?.trim().toLowerCase();
+        const commit = readArtifactSectionContent(content, "Commit");
+        if (mode === "final" && decision === "synced" && !DOCS_UPDATE_COMMIT_PATTERN.test(commit ?? "")) {
+            invalidFields.push(`${DOCS_UPDATE_COMMIT_RULE} Received Commit: ${JSON.stringify(commit ?? "")}.`);
+        }
+        return invalidFields;
     }
     if (kind === "docs-sync-report") {
         const invalidFields = validateDecision(content, DOCS_REPORT_DECISIONS);

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

@@ -30,6 +30,8 @@ export const TEST_INFRASTRUCTURE_STATUSES = [
 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}$/;
+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 DOCS_SYNC_CORRECTION_OWNERS = ["none", "architect", "coder", "tester"];
 export const FINAL_ACCEPTANCE_DECISIONS = [
     "accepted",