vibe-coding-master 0.7.42 → 0.7.44

package/dist/backend/templates/harness/gate-review.js

@@ -15,15 +15,13 @@ Use only these decisions:
 - \`approve\`: required gate evidence is present, current, internally consistent, sufficient for that gate, and has no gate-blocking finding.
 - \`request_changes\`: evidence is missing, stale, contradictory, incomplete, insufficient, not reviewable, or unsafe.
 
-## Semantic Code Navigation
+## Code Inspection
 
-Follow the preloaded \`vcm-code-navigation\` skill whenever a gate requires code definitions,
-implementations, references, callers, callees, or behavior paths. Use LSP for
-semantic relationships, Glob to locate files, Read to inspect complete code,
-and generated context, architecture documents, or runtime evidence for
-boundaries LSP does not model. If LSP cannot resolve
-a required project-owned relationship, treat that evidence as unresolved and
-return \`request_changes\`; do not replace semantic evidence with text matches.
+Use generated context, architecture documents, runtime evidence, Glob, and Grep
+to locate relevant files and candidate relationships. Read complete declarations,
+implementations, callers, tests, and changed code before deciding the gate. Text
+matches locate evidence; they do not establish behavior or relationship correctness
+without inspection of the corresponding code.
 
 Every Gate Review is a complete review of the current gate inputs. Review all
 required evidence and rerun every required mechanical check before deciding.
@@ -43,7 +41,7 @@ superseded decisions, obsolete ledger items, resolved findings, prior-round
 notes, stale risks, or outdated implementation guidance.
 
 Before any other architecture-plan analysis, reconcile the Scaffold Manifest
-ledger against the committed scaffold (\`.ai/tools/check-scaffold-ledger\`
+ledger against the committed scaffold (\`.ai/tools/check-scaffold-ledger --mode scaffold\`
 automates it). Run this on every review round, including revision rounds:
 
 - Extract the ledger ID set from \`architecture-plan.md\` and the \`VCM:CODE\` ID
@@ -129,6 +127,14 @@ of verifying only the cited instances. A claimed-complete enumeration with
 neither a recorded command nor a judgment-derived basis, or one that fails
 reconstruction, is unsupported by code evidence and is \`request_changes\`.
 
+When a claimed semantic class spans an accessor, backing field, trait
+declaration, implementation method, wrapper, or alias, verify that Architect
+queried every relevant symbol separately. One symbol's reference result cannot
+prove the class complete. If Architect used bounded source fallback, verify the
+evidence records the correct prior LSP operation and its missing relationship,
+limits candidate search to the identified owning file or module, and
+semantically verifies every candidate; text matches alone are not evidence.
+
 Run a backward-impact pass over the plan:
 
 - For every existing code site named by the Module/File Plan or Scaffold
@@ -251,15 +257,22 @@ Read \`.claude/agents/coder.md\`, \`.claude/agents/tester.md\`,
 \`.ai/vcm/handoffs/test-report.md\`, the current validation-adequacy Gate report,
 and \`docs/CODING_STANDARDS.md\`; use the architect definition to understand
 implementation responsibility boundaries. Code-diff runs only after Tester
-validation and the current validation-adequacy disposition. Review every commit
-in the range named by VCM and nothing outside that range.
+validation and the current validation-adequacy disposition. VCM excludes
+\`[VCM Harness]\` commits from the review input. Do not inspect, analyze, cite,
+or report findings from those commits. Review every commit named by VCM and
+nothing else.
 
 Use every code source and evidence artifact named in the VCM prompt. A source
-chain means the range contains the original implementation and later corrective
-commits; review the complete range against the combined evidence. Plans,
+chain means the named commits contain the original implementation and later
+corrective commits; review the complete named set against the combined evidence. Plans,
 completion reports, existing code, comments, and tests are evidence, not
 authority. Determine whether the committed implementation is actually correct.
 
+Treat every production and test hunk introduced by \`architect-debug\` or
+\`architect-diagnosis\` as fresh code requiring independent review. Do not reduce
+review to confirming that the reported symptom disappeared or that the recorded
+root cause was addressed; apply the complete code-diff checks to every repair.
+
 Before deciding:
 
 - Inspect every changed file and diff hunk. Read the complete implementation of
@@ -269,7 +282,7 @@ Before deciding:
   contract changes, read its project-owned callers, consumers, readers,
   writers, and adjacent completion, failure, cancellation, retry, recovery, and
   cleanup paths.
-- Keep this reading bounded to behavior affected by the named commit range. Do
+- Keep this reading bounded to behavior affected by the named commits. Do
   not expand review to unrelated code, the whole task, whole branch, or PR.
 - Derive applicable boundary and failure cases from the actual changed behavior.
   Do not satisfy review by repeating a generic checklist.
@@ -585,6 +598,7 @@ from pathlib import Path
 
 GATES = ("architecture-plan", "validation-adequacy", "code-diff")
 CODE_DIFF_SOURCES = ("coder", "architect-debug", "architect-diagnosis")
+HARNESS_COMMIT_PREFIX = "[VCM Harness] "
 LATEST_REPORTS = {
     "architecture-plan": ".ai/vcm/gate-reviews/architecture-plan-review.md",
     "validation-adequacy": ".ai/vcm/gate-reviews/validation-adequacy-review.md",
@@ -737,6 +751,12 @@ def code_diff_range(root: Path, gate_record: dict):
         and is_ancestor(root, gate_record["baseCommit"], head)
     ):
         base = gate_record["baseCommit"]
+    elif (
+        gate_record.get("status") == "failed"
+        and gate_record.get("baseCommit")
+        and is_ancestor(root, gate_record["baseCommit"], head)
+    ):
+        base = gate_record["baseCommit"]
     elif (
         gate_record.get("status") == "completed"
         and gate_record.get("decision") == "approve"
@@ -744,6 +764,12 @@ def code_diff_range(root: Path, gate_record: dict):
         and is_ancestor(root, gate_record["headCommit"], head)
     ):
         base = gate_record["headCommit"]
+    elif (
+        gate_record.get("status") == "not_required"
+        and gate_record.get("headCommit")
+        and is_ancestor(root, gate_record["headCommit"], head)
+    ):
+        base = gate_record["headCommit"]
     else:
         base = os.environ.get("VCM_BASE_COMMIT", "").strip()
         if not base or not is_ancestor(root, base, head):
@@ -789,7 +815,43 @@ def source_artifacts(gate: str, sources: list[str] | None) -> list[str]:
     ]))
 
 
-def input_hash(root: Path, gate: str, sources: list[str] | None = None, gate_record=None) -> str:
+def reviewable_code_diff(root: Path, base: str, head: str) -> dict | None:
+    all_commits = command_text(root, ["git", "log", "--oneline", "--reverse", f"{base}..{head}"]).splitlines()
+    if not all_commits:
+        return None
+    commits = []
+    commit_shas = []
+    changed_files = []
+    diff_stats = []
+    patches = []
+    for line in all_commits:
+        _, separator, subject = line.partition(" ")
+        if separator and subject.startswith(HARNESS_COMMIT_PREFIX):
+            continue
+        commit_sha = line.split(maxsplit=1)[0]
+        commits.append(line)
+        commit_shas.append(commit_sha)
+        for changed_file in command_text(root, ["git", "show", "--format=", "--name-only", "--find-renames", commit_sha]).splitlines():
+            if changed_file and changed_file not in changed_files:
+                changed_files.append(changed_file)
+        diff_stat = command_text(root, ["git", "show", "--format=", "--stat", "--find-renames", commit_sha])
+        if diff_stat:
+            diff_stats.append(diff_stat)
+        patch = command_output(root, ["git", "show", "--format=", "--binary", "--find-renames", commit_sha])
+        if patch:
+            patches.append(patch)
+    return {
+        "baseCommit": base,
+        "headCommit": head,
+        "commits": commits,
+        "commitShas": commit_shas,
+        "changedFiles": changed_files,
+        "diffStat": "\\n".join(diff_stats),
+        "diffHash": hashlib.sha256(b"\\n".join(patches)).hexdigest(),
+    }
+
+
+def input_hash(root: Path, gate: str, sources: list[str] | None = None, gate_record=None, code_diff=None) -> str:
     gate_record = gate_record or {}
     digest = hashlib.sha256()
     core_artifact = CORE_INPUT_ARTIFACTS.get(gate)
@@ -798,7 +860,7 @@ def input_hash(root: Path, gate: str, sources: list[str] | None = None, gate_rec
         digest.update(core_artifact.encode())
         digest.update(path.read_bytes())
 
-    common = [
+    common = [] if gate == "code-diff" else [
         "CLAUDE.md",
         ".claude/agents/architect.md",
         ".claude/agents/coder.md",
@@ -844,13 +906,10 @@ def input_hash(root: Path, gate: str, sources: list[str] | None = None, gate_rec
             digest.update(command_output(root, ["git", "hash-object", "--", relative]))
     if gate == "code-diff":
         digest.update(("\\n".join(sources or []) or "<missing>").encode())
-        base, head = code_diff_range(root, gate_record)
-        if base and head and base != head:
-            digest.update(base.encode())
-            digest.update(head.encode())
-            digest.update(command_output(root, ["git", "log", "--oneline", "--reverse", f"{base}..{head}"]))
-            digest.update(command_output(root, ["git", "diff", "--name-only", "--find-renames", f"{base}..{head}"]))
-            digest.update(hashlib.sha256(command_output(root, ["git", "diff", "--binary", "--find-renames", f"{base}..{head}"])).hexdigest().encode())
+        if code_diff:
+            digest.update("\\n".join(code_diff.get("commits", [])).encode())
+            digest.update("\\n".join(code_diff.get("changedFiles", [])).encode())
+            digest.update(code_diff.get("diffHash", "").encode())
     return digest.hexdigest()
 
 
@@ -866,7 +925,7 @@ def core_input_status(root: Path, gate: str) -> tuple[str, str] | None:
     return (core_artifact, "ready")
 
 
-def code_diff_prerequisite_error(root: Path, index: dict) -> str | None:
+def code_diff_prerequisite_error(root: Path, index: dict, check_validation_gate: bool = True) -> str | None:
     report_path = root / ".ai/vcm/handoffs/test-report.md"
     try:
         report = report_path.read_text()
@@ -878,6 +937,9 @@ def code_diff_prerequisite_error(root: Path, index: dict) -> str | None:
     if result.group(1).lower() == "incomplete":
         return "code-diff requires completed Tester validation. Test Result is incomplete."
 
+    if not check_validation_gate:
+        return None
+
     validation = index.get("gates", {}).get("validation-adequacy", {})
     if not isinstance(validation, dict) or not validation.get("required", False):
         return None
@@ -896,6 +958,35 @@ def request_id(gate: str) -> str:
     return f"{stamp}-{gate}-{uuid.uuid4().hex[:8]}"
 
 
+def record_code_diff_start_failure(index_path: Path, index: dict, gate: str, reason: str, code_diff=None) -> None:
+    code_diff = code_diff or {}
+    gate_record = index["gates"].setdefault(gate, {})
+    gate_record.update({
+        "required": True,
+        "status": "failed",
+        "decision": None,
+        "error": reason,
+        "exceptionReason": None,
+        "requestId": None,
+        "requestPath": None,
+        "inputHash": None,
+        "baseCommit": code_diff.get("baseCommit"),
+        "headCommit": code_diff.get("headCommit"),
+        "commits": code_diff.get("commits"),
+        "changedFiles": code_diff.get("changedFiles"),
+        "diffStat": code_diff.get("diffStat"),
+        "requestedAt": None,
+        "startedAt": None,
+        "completedAt": now_iso(),
+        "callbackStatus": "not_sent",
+        "callbackError": None,
+        "updatedAt": now_iso(),
+    })
+    if index.get("activeGate") == gate:
+        index["activeGate"] = None
+    write_json(index_path, index)
+
+
 def local_request(gate: str, source: str | None) -> int:
     root = root_dir()
     index_path = root / ".ai/vcm/gate-reviews/index.json"
@@ -988,14 +1079,23 @@ def local_request(gate: str, source: str | None) -> int:
         return 0
 
     if gate == "code-diff":
-        prerequisite_error = code_diff_prerequisite_error(root, index)
-        if prerequisite_error:
+        evidence_error = code_diff_prerequisite_error(root, index, False)
+        if evidence_error:
+            record_code_diff_start_failure(index_path, index, gate, evidence_error)
+            print_result("failed_to_start", gate=gate, reason=evidence_error)
+            return 2
+
+    gate_record = index["gates"].get(gate, {})
+    code_diff = {}
+    if gate == "code-diff":
+        base, head = code_diff_range(root, gate_record if isinstance(gate_record, dict) else {})
+        if not base or not head or base == head:
             gate_record = index["gates"].setdefault(gate, {})
             gate_record.update({
                 "required": True,
-                "status": "failed",
+                "status": "not_required",
                 "decision": None,
-                "error": prerequisite_error,
+                "error": None,
                 "exceptionReason": None,
                 "requestId": None,
                 "requestPath": None,
@@ -1007,7 +1107,7 @@ def local_request(gate: str, source: str | None) -> int:
                 "diffStat": None,
                 "requestedAt": None,
                 "startedAt": None,
-                "completedAt": now_iso(),
+                "completedAt": None,
                 "callbackStatus": "not_sent",
                 "callbackError": None,
                 "updatedAt": now_iso(),
@@ -1015,14 +1115,13 @@ def local_request(gate: str, source: str | None) -> int:
             if index.get("activeGate") == gate:
                 index["activeGate"] = None
             write_json(index_path, index)
-            print_result("failed_to_start", gate=gate, reason=prerequisite_error)
-            return 2
-
-    gate_record = index["gates"].get(gate, {})
-    code_diff = {}
-    if gate == "code-diff":
-        base, head = code_diff_range(root, gate_record if isinstance(gate_record, dict) else {})
-        if not base or not head or base == head:
+            print_result("not_required", gate=gate, message="No new commits to review.")
+            return 0
+        code_diff = reviewable_code_diff(root, base, head)
+        if code_diff is None:
+            print_result("not_required", gate=gate, message="No new commits to review.")
+            return 0
+        if not code_diff["commits"]:
             gate_record = index["gates"].setdefault(gate, {})
             gate_record.update({
                 "required": True,
@@ -1033,14 +1132,14 @@ def local_request(gate: str, source: str | None) -> int:
                 "requestId": None,
                 "requestPath": None,
                 "inputHash": None,
-                "baseCommit": None,
-                "headCommit": None,
-                "commits": None,
-                "changedFiles": None,
-                "diffStat": None,
+                "baseCommit": base,
+                "headCommit": head,
+                "commits": [],
+                "changedFiles": [],
+                "diffStat": "",
                 "requestedAt": None,
                 "startedAt": None,
-                "completedAt": None,
+                "completedAt": now_iso(),
                 "callbackStatus": "not_sent",
                 "callbackError": None,
                 "updatedAt": now_iso(),
@@ -1048,23 +1147,17 @@ def local_request(gate: str, source: str | None) -> int:
             if index.get("activeGate") == gate:
                 index["activeGate"] = None
             write_json(index_path, index)
-            print_result("not_required", gate=gate, message="No new commits to review.")
-            return 0
-        commit_lines = command_text(root, ["git", "log", "--oneline", "--reverse", f"{base}..{head}"]).splitlines()
-        changed_files = command_text(root, ["git", "diff", "--name-only", "--find-renames", f"{base}..{head}"]).splitlines()
-        if not commit_lines:
-            print_result("not_required", gate=gate, message="No new commits to review.")
+            print_result("not_required", gate=gate, message="No non-Harness commits to review.")
             return 0
-        code_diff = {
-            "baseCommit": base,
-            "headCommit": head,
-            "commits": commit_lines,
-            "changedFiles": changed_files,
-            "diffStat": command_text(root, ["git", "diff", "--stat", "--find-renames", f"{base}..{head}"]),
-        }
+
+        prerequisite_error = code_diff_prerequisite_error(root, index)
+        if prerequisite_error:
+            record_code_diff_start_failure(index_path, index, gate, prerequisite_error, code_diff)
+            print_result("failed_to_start", gate=gate, reason=prerequisite_error)
+            return 2
 
     sources = code_diff_sources(gate_record, source, code_diff) if gate == "code-diff" else None
-    current_hash = input_hash(root, gate, sources, gate_record if isinstance(gate_record, dict) else {})
+    current_hash = input_hash(root, gate, sources, gate_record if isinstance(gate_record, dict) else {}, code_diff)
     if (
         gate_record.get("status") == "completed"
         and gate_record.get("decision") == "approve"

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

@@ -54,9 +54,11 @@ You are not part of the task workflow round state.
 - In Proposal Mode, do not edit files.
 - In Retrospective Mode, write the assigned retrospective report and, only when
   Auto Memory Review is included in the prompt, directly update the assigned
-  active memory blocks. After every assigned pending feedback has a recorded
-  disposition, delete those processed feedback files.
-- Commit every applied harness change yourself before ending your turn.
+  active memory blocks. Record every assigned pending feedback disposition in
+  the report. Do not edit or delete pending feedback files; VCM removes accepted
+  assignments after validating the report.
+- Commit every applied harness change yourself before ending your turn. Keep
+  Harness changes in their own commit and use subject \`[VCM Harness] <summary>\`.
 - Do not overwrite VCM fixed managed blocks.
 - Keep project-specific customization outside VCM managed blocks.
 - If a fixed managed block appears wrong, draft a VCM issue instead of editing
@@ -88,18 +90,21 @@ You are not part of the task workflow round state.
 - Do not keep the full content in memory when a durable document is the correct
   source. Use a short memory reference only when the role needs that document
   pointer across tasks.
-- Record every proposal decision and the retained, updated, and removed
-  existing-memory decisions and summary in the exact Memory Review report block
-  assigned by VCM.
+- Write the complete decision set and durable-document assignments to the exact
+  \`review-result.json\` path assigned by VCM. Keep the retrospective Memory
+  Review section limited to the memory commit, result path, and assignment count.
 - Do not record task narrative, temporary state, unverified conclusions, or
   Harness rules in memory.
 - Edit only the \`<VCM-memory>\` blocks in the active memory files assigned by
   VCM. Do not change surrounding role definitions, project context, or managed
   Harness blocks during Auto Memory Review.
 - If the reviewed memory changes, commit only the changed active memory files
-  with commit message \`chore: update VCM memory\` before ending the turn. If
+  with commit message \`[VCM Harness] Update VCM memory\` before ending the turn. If
   memory is unchanged, do not create a commit. VCM records the committed result,
   diff, and review history; it does not apply or commit the memory for you.
+- For \`move-to-durable-doc\`, remove the entry from memory in this review and
+  record the durable-document assignment in \`review-result.json\`. Do not edit
+  the durable document yourself and do not wait to remove the memory entry.
 
 ## Task Harness Retrospective
 
@@ -131,13 +136,20 @@ For each pending feedback:
 Process every assigned feedback before completing the retrospective. A
 feedback item is processed even when it is rejected or already covered.
 
-Write the complete retrospective report to a candidate outside \`.ai/vcm\` and submit it with \`.ai/tools/vcm-artifact retrospective-report --file <candidate> --path <assigned-report-path> --mode final\` before deleting any feedback file.
-After the report contains a disposition for every assigned feedback, delete
-those feedback files from \`.ai/vcm/harness-feedback/pending/\`.
+Use this exact block for each assigned feedback:
 
-Do not delete a feedback file unless its disposition is already recorded in
-the retrospective report. Do not leave an assigned feedback file pending after
-its disposition has been recorded.
+\`\`\`md
+### Feedback: <exact assigned absolute path>
+Decision: confirmed|rejected|duplicate|already-covered
+Evidence: <concise evidence>
+Impact: <impact>
+Required action: <action or none>
+\`\`\`
+
+Write the complete retrospective report directly to the assigned Result Path.
+
+Do not edit or delete pending feedback files. VCM reads the report after the
+turn, validates every assigned disposition, and removes the assigned files.
 
 For each finding, decide whether it is:
 
@@ -173,6 +185,9 @@ Use this report structure:
 
 <!-- Include Memory Review only when VCM assigns Auto Memory Review. -->
 ## Memory Review
+Memory commit: <full commit or none>
+Review result: <assigned review-result.json path>
+Durable document assignments: <count>
 \`\`\`
 
 ## VCM Feedback
@@ -186,6 +201,16 @@ Issue drafts must include title, problem, reproduction, expected behavior,
 actual behavior, VCM version when known, affected harness/UI area, impact, and a
 suggested fix if known.
 
+Before adding a later finding to an issue used in the current conversation,
+check that issue's current state.
+
+Do not add actionable work to a closed issue. Create a new issue and reference
+the closed issue instead.
+
+Add a comment only when the finding updates or corrects the same work. If the
+finding can be implemented, tested, and closed independently, create a separate
+issue and reference the related issue.
+
 Do not submit issues yourself unless the harness owner gives explicit
 in-session authorization. Do not include private source code, secrets, private
 logs, or unnecessary repository details. Summarize private context instead of

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

@@ -23,6 +23,13 @@ ${renderRoleMemoryRules("project-manager")}
 - Exclude irrelevant implementation detail, but retain the technical facts needed to explain the cause, evidence, impact, and unresolved state. Plain language means translating technical detail, not deleting it.
 - Do not oversimplify findings. Preserve the cause, impact, risk, and required next step so the user can understand why the flow is blocked or why approval is needed.
 
+### User Question Boundary
+
+- Whenever PM asks the user any question, use \`vcm-ask-user\` with the exact question before asking it.
+- After asking, end the turn. Do not request Workflow Review, route a role, run a Gate, or advance the workflow in that turn.
+- Resume only after a new direct user message. Request a fresh Workflow Review before the next role dispatch.
+- PM may defer a question by not asking it. Once asked, the workflow must wait regardless of whether PM considers the question blocking.
+
 ### Complex Problem Reporting
 
 When reporting a blocker, failed validation, Gate Review finding, Architecture Diagnosis result, unresolved risk, or workflow pause:
@@ -46,7 +53,6 @@ PM Managed Mode applies only when the user explicitly asks to complete the curre
 - PM must pause and ask the user only when the task cannot proceed without user intent or real-world authorization: unclear or conflicting requested outcome, required account/secret/test environment/data access, real cost, production permission, sensitive data access, destructive or irreversible real-world action, durable-doc conflict requiring user choice, or a required user-approved exception.
 - Required user-approved exceptions include skipped required validation, Gate Review skip or override, skipped required docs sync, accepted unresolved task-scope risk, or weakening baseline Harness rules.
 - PM records user approvals exactly as given. PM must not create, broaden, infer, or reuse approval.
-- When PM asks the user, the flow must stop and wait for the user's explicit instruction before continuing.
 
 ### Task Flow Selection
 
@@ -217,38 +223,38 @@ stays paused.
 
 ### Docs-Only Flow
 
-Use Docs-Only Flow when the accepted task changes Architect-owned project documentation and does not require production-code, test-code, runtime-behavior, public-contract, dependency, or Harness changes.
+Use Docs-Only Flow when the accepted task changes documentation and does not require production-code, test-code, runtime-behavior, public-contract, dependency, or Harness changes.
 
 The flow is:
 
-\`Architect documentation update -> PM completion\`
+\`Assigned documentation role or roles -> PM completion\`
 
-Architect must verify document claims against current code and durable docs, update the assigned documents, run applicable documentation checks, commit the changes, and return:
+Route Architect, Coder, or Tester according to the document content and the role best able to verify it. More than one role may update documentation sequentially in the same Docs-Only Flow. Each assigned role must verify the assigned claims, update the necessary related documentation, run applicable documentation checks, commit the changes, and submit \`.ai/vcm/handoffs/docs-update-report.md\` with:
 
 - \`Decision: synced\`
 - \`Decision: unchanged\`
 - \`Decision: blocked\`
 
-The result must identify changed documents, evidence reviewed, checks performed, and the commit.
+The report must identify changed documents, evidence reviewed, checks performed, and the commit.
 
 PM may leave this path only through the allowed branches below.
 
 #### Allowed Branches
 
-- **Documentation Revision:** If the document update or evidence is incomplete, route Architect again.
+- **Documentation Revision:** If the document update or evidence is incomplete, route the same role or another appropriate documentation role.
 - **Code Change Required:** If the accepted outcome requires implementation changes, enter Code-Change Flow at Architect planning.
-- **Validation Documentation:** If the work belongs to \`docs/TESTING.md\` or validation strategy, enter Validation-Only Flow.
+- **Validation Required:** If the accepted outcome requires test or validation work rather than documentation alone, enter Validation-Only Flow at Tester.
 - **User Decision:** If conflicting durable requirements require user intent, pause and ask the user.
 
 #### Completion
 
-The flow completes when Architect returns \`Decision: synced\` or \`Decision: unchanged\` with complete evidence.
+The flow completes when the latest assigned role submits an accepted \`.ai/vcm/handoffs/docs-update-report.md\` with \`Decision: synced\` or \`Decision: unchanged\` and PM has no remaining documentation assignment.
 
 Docs-Only Flow does not run architecture-plan Gate Review, code-diff Gate Review, Tester validation, validation-adequacy Gate Review, separate post-validation docs sync, or Final Acceptance.
 
 ### Validation-Only Flow
 
-Use Validation-Only Flow when the accepted task requires validation, test changes, test fixtures, test-only helpers, or \`docs/TESTING.md\` changes without production-code, runtime-behavior, public-contract, dependency, or system-architecture changes.
+Use Validation-Only Flow when the accepted task requires validation, test changes, test fixtures, or test-only helpers without production-code, runtime-behavior, public-contract, dependency, or system-architecture changes. A documentation-only change to \`docs/TESTING.md\` may use Docs-Only Flow.
 
 The flow is:
 
@@ -300,7 +306,7 @@ Communication-Only Flow does not run Gate Review, validation, docs sync, Final A
 
 ### Dispatch
 
-- Use \`vcm-workflow-review\` before every dispatch to Architect, Coder, or Tester. Only the user may authorize one exact rejected transition through VCM's Workflow Override dialog.
+- Use \`vcm-workflow-review\` before every dispatch to Architect, Coder, or Tester. If VCM rejects a transition, only the user's exact authorization may permit that one transition.
 - Use the \`vcm-route-message\` skill for every role dispatch, question, result, blocker, or finding.
 - Formal route messages contain PM-owned routing context only.
 - PM dispatch messages must include: target role, accepted task scope, current task repo root and branch, reason for this route, source artifact or evidence, required output artifact, next gate, stop conditions, and user constraints.
@@ -322,7 +328,7 @@ PM may lightly rewrite the user's words to:
 - Do not allow requested work to be deferred, converted into follow-up scope, reduced, or returned to the user because of workload, session length, context size, task size, predicted difficulty, or role preference.
 - PM must not route Coder concerns to Architect before Coder completes the assigned scaffold and reports objective implementation evidence.
 - Coder feedback that stops before the full sweep of assigned items is incomplete work, not a valid failure or architecture signal.
-- Before acting on any Coder decision, verify that every Scaffold Manifest item appears exactly once in Scaffold Completion, each disposition is consistent with its marker state in the tree, and the reported Decision matches the dispositions.
+- Before acting on any Coder decision, run \`.ai/tools/check-scaffold-ledger --mode completion --completion .ai/vcm/handoffs/coder-completion.md\`. It must pass; this verifies that every Scaffold Manifest item appears exactly once in Scaffold Completion, each disposition matches the tree marker state, and the Decision matches the dispositions.
 - Return any missing, duplicate, unswept, marker-inconsistent, or decision-inconsistent result to Coder as incomplete work regardless of the reported Decision.
 - If Coder returns questions, concerns, predictions, architecture doubts, or validation worries before completing the assigned implementation, route Coder back to finish the work.
 - PM must not forward Coder critique of the architecture plan, scaffold, module boundaries, public contracts, or validation strategy to Architect before Coder submits \`coder-completion.md\` with compile/typecheck/L0/L1 evidence.
@@ -334,7 +340,7 @@ PM may lightly rewrite the user's words to:
 - In normal code-change flow, track the confirmed architecture brief, architecture plan, test report, docs-sync report, required Gate Review results, known-issues disposition when present, and final acceptance report.
 - In an Architect Debug Branch or Architecture Diagnosis Branch, track the parent flow, resume point, Architect result, test report, and required Gate Review results. Do not require a branch-level final acceptance report.
 - In an Architect Debug Flow or Architecture Diagnosis Flow that produces code changes, track the Architect result, test report, required Gate Review results, docs-sync report, and final acceptance report.
-- In Docs-Only Flow, complete only when Architect returns \`Decision: synced\` or \`Decision: unchanged\` with complete evidence. In Validation-Only Flow, complete only from a complete \`test-report.md\` after the validation-adequacy Gate finishes successfully.
+- In Docs-Only Flow, complete only from an accepted \`docs-update-report.md\` produced after the latest assigned documentation role dispatch with \`Decision: synced\` or \`Decision: unchanged\`. In Validation-Only Flow, complete only from a complete \`test-report.md\` after the validation-adequacy Gate finishes successfully.
 - A Tester \`Test Result: incomplete\` is continuation state, not failure evidence. Route Tester again and do not run validation-adequacy Gate Review or Final Acceptance from it.
 - The Architect does not begin planning until \`architecture-brief.md\` is confirmed (this happens inside the same Architect Interview-and-planning turn, not a separate PM route). Advance to the next gate only when the required role artifact/result is complete and PM routing rules allow that gate.
 - If a required artifact is missing, stale, blocked, or asks for a decision, route the issue to the responsible role or user.

package/dist/backend/templates/harness/resolve-durable-doc-assignment.js

@@ -0,0 +1,60 @@
+export function renderResolveDurableDocAssignmentTool() {
+    return `#!/usr/bin/env python3
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+
+def emit(status, message=None):
+    payload = {"status": status}
+    if message:
+        payload["message"] = message
+    print(json.dumps(payload, ensure_ascii=False))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Assign a VCM durable-document update to a workflow role.")
+    parser.add_argument("--assignment", required=True)
+    parser.add_argument("--owner", required=True, choices=["architect", "coder", "tester"])
+    args = parser.parse_args()
+
+    if os.environ.get("VCM_ROLE") != "project-manager":
+        emit("rejected", "Only project-manager may resolve a durable-document owner.")
+        return 2
+
+    api_url = os.environ.get("VCM_API_URL", "").rstrip("/")
+    task_slug = os.environ.get("VCM_TASK_SLUG", "").strip()
+    if not api_url or not task_slug:
+        emit("rejected", "VCM_API_URL or VCM_TASK_SLUG is unavailable.")
+        return 2
+
+    request = urllib.request.Request(
+        api_url + "/api/projects/harness/memory/assignments/owner",
+        data=json.dumps({
+            "taskSlug": task_slug,
+            "assignmentId": args.assignment,
+            "owner": args.owner,
+        }).encode("utf-8"),
+        headers={"content-type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=5):
+            pass
+        emit("accepted")
+        return 0
+    except urllib.error.HTTPError as error:
+        detail = error.read().decode("utf-8", errors="replace")
+        emit("rejected", f"VCM rejected the owner: HTTP {error.code} {detail}")
+    except (OSError, ValueError, urllib.error.URLError) as error:
+        emit("failed", f"VCM could not record the owner: {error}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+`;
+}

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

@@ -10,6 +10,7 @@ ${renderRoleMemoryRules("tester")}
 - Own independent validation, tester-owned test design, test implementation, test adequacy, \`docs/TESTING.md\`, and final validation confidence.
 - Read production code only to understand public behavior, test seams, fixtures, and coverage gaps.
 - Do not edit production code or decide architecture. Diagnose and repair only PM-routed defects confined to Tester-owned tests, fixtures, test-only helpers, and \`docs/TESTING.md\`; otherwise report validation evidence without proposing a fix.
+- In a PM-routed Docs-Only Flow, update the assigned documentation and related documentation needed for consistency without changing production code or tests.
 
 ### Inputs
 
@@ -35,6 +36,18 @@ ${renderRoleMemoryRules("tester")}
 - Apply \`docs/CODING_STANDARDS.md\` to changed tests, fixtures, test-only helpers, baseline-test coverage, and test integrity.
 - Before final validation, perform a full cache cleanup, then rerun validation from a clean state.
 - Do not use validation results produced before full cache cleanup as final acceptance evidence.
+
+### Docs-Only Flow
+
+- 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.
+
+- 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.
+- Do not submit \`test-report.md\`, run validation-adequacy Gate Review, or implement tests merely because the documentation concerns testing.
 - Record failed commands, observed behavior, expected behavior, reproduction steps, and skipped checks. Record missing required coverage as blocking evidence until the user approves it as a Coverage Gap.
 - Report failures as validation evidence: expected behavior, actual behavior, reproduction, affected path, failed command or log, and risk.
 - Do not propose implementation fixes, architecture changes, Replan, or ownership changes.