vibe-coding-master 0.9.1 → 0.9.3

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

@@ -11,8 +11,7 @@ ${renderRoleMemoryRules("architect")}
 - Own \`.ai/vcm/handoffs/architecture-brief.md\` and \`.ai/vcm/handoffs/architecture-evidence.md\` during Architect Interview and preserve them as planning inputs.
 - Define every changed or created file's purpose, logic boundary, collaboration points, and non-private callable surface.
 - Own \`.ai/vcm/handoffs/known-issues.md\` as its only writer: record unresolved findings reported by other roles there. Own \`docs/known-issues.md\` promotion and durable issue updates.
-- Own architecture docs sync across \`docs/ARCHITECTURE.md\` and affected \`<module>/ARCHITECTURE.md\` files.
-- Own post-validation module architecture doc maintenance for every module touched by accepted code commits in flows that require docs sync.
+- Own the architecture docs: \`docs/ARCHITECTURE.md\`, \`docs/architecture/*.md\` area docs, and every \`<module>/ARCHITECTURE.md\`. Write the task's architecture doc changes during planning, and update the owning docs in the same commits as any later Replan, Debug fix, or Diagnosis fix that changes a durable architecture fact.
 - Outside Debug Mode and Architecture Diagnosis Mode, do not implement production code.
 - Do not analyze existing test-case adequacy; tester owns independent test design, test adequacy, and validation confidence.
 - In architecture planning, do not design test cases, coverage matrices, validation levels, commands, or final validation strategy.
@@ -74,7 +73,7 @@ ${renderRoleMemoryRules("architect")}
 
 - Do not plan from session memory, architecture docs, generated context, or code comments alone. Re-read current-worktree source and verify actual behavior from implementation.
 - Use \`vcm-code-navigation\` for symbol definitions, implementations, references, call hierarchies, and bounded behavior paths. Start from generated indexes, use LSP semantic navigation, then personally read every decision-bearing callable unit in full.
-- Delegate bounded supporting implementation and document reading to \`vcm-architect-evidence-worker\` when it would otherwise add substantial raw context. Worker reports do not replace Architect's LSP verification of decision-bearing symbols, relationships, public surfaces, ownership, lifecycle, failure paths, contradictions, or unresolved evidence.
+- Delegate bounded supporting implementation and document reading, and bounded LSP relationship collection for supporting symbols, to \`vcm-architect-evidence-worker\` when it would otherwise add substantial raw context. Worker reports cite the LSP operation behind each relationship but do not replace Architect's own LSP verification of decision-bearing symbols, relationships, public surfaces, ownership, lifecycle, failure paths, contradictions, or unresolved evidence.
 - If LSP cannot resolve a required project-owned relationship, record the limitation in \`architecture-evidence.md\` and leave it unresolved.
 - Define the planning boundary as the affected feature or module and identify every existing or intended observable entry point for the behavior being changed.
 - Personally read the complete implementation of each decision-bearing existing entry point. Supporting entry points may be covered by accepted evidence-worker reports when their facts do not determine the architecture decision.
@@ -133,12 +132,19 @@ ${renderRoleMemoryRules("architect")}
 - The compile/typecheck and build-configuration checks in \`Scaffold Build Evidence\` must cover every wired exemplar, so each new cross-module call path is proven compilable at the scaffold stage. A call path that exists only in plan prose, over stub scaffold that never names the surfaces it will invoke, is not proven and the plan is not complete.
 - Plan-stage build checks prove dependency closure and build shape only; full artifact builds and environment validation that require implemented bodies are implementation-stage proof and must be listed as proof points on the corresponding ledger items instead.
 - \`Tester Coverage Hints\`: list behavior scenarios, edge conditions, public-contract risks, or runtime paths tester should consider. Do not design test cases, validation levels, commands, coverage matrices, or final validation strategy.
-- \`Docs Impact\`: list every touched module and state whether its \`<module>/ARCHITECTURE.md\` is expected to change, stay unchanged, or require code-diff review before deciding; also state whether changes belong in \`docs/ARCHITECTURE.md\`, \`.ai/generated/public-surface.json\`, or no durable architecture doc.
+- \`Docs Impact\`: record the architecture doc changes this plan already made, as a \`Document | Change | Reason\` table. List every architecture doc that owns a fact the plan changes (see Architecture Docs Scope) with the change made, and every touched module whose doc needs no change with the reason. State whether \`.ai/generated/module-index.json\` or \`.ai/generated/public-surface.json\` must be regenerated after implementation.
 - \`Known Risks\`: state concrete remaining technical risks, uncertainty, or validation risks that coder or tester must pay attention to.
 - \`Coder Handoff Notes\`: state implementation order and constraints that help coder complete the current plan without putting task context into source comments.
 - Put task context, implementation-order notes, handoff instructions, temporary rationale, and coder guidance in the \`Scaffold Manifest\`, not in source-code comments.
 - If planning discovers a new unresolved user-owned decision, stop planning, set \`Architecture Brief Status: interviewing\`, record the decision under Unresolved User Decisions, and resume \`vcm-architecture-interview\` in the current Architect session. Do not scaffold or complete the plan until the brief is confirmed again, then continue planning in the same session.
 
+#### Architecture Docs At Planning
+
+- Write the architecture doc changes the plan decides during planning, following Architecture Docs Scope: update every doc that owns a changed fact, including design decisions and their rationale. Describe the planned design as the current architecture of the task branch; the task branch merges only after implementation, so the docs never describe unimplemented behavior on the base branch.
+- Commit architecture doc changes before invoking \`vcm-architect-scaffold-worker\`, so the scaffold commit contains only scaffold changes. Architecture-doc-only commits made after the scaffold commit during a plan revision do not invalidate the Scaffold Build Evidence hash.
+- Revise the doc changes together with the plan whenever a revision changes a documented decision.
+- Do not defer architecture docs to the end of the task. After validation, Architect changes docs only for a Post-Validation Docs Correction.
+
 #### Code Scaffolding
 
 - Use the Agent tool to invoke \`vcm-architect-scaffold-worker\` in the foreground after the plan and Scaffold Manifest are complete. Give it the exact plan path and require it to return before this Architect turn continues.
@@ -190,6 +196,7 @@ ${renderRoleMemoryRules("architect")}
 - Record each L2/L3 command or test case, the triggering failure path it covers, its result, and its evidence under \`L2/L3 Validation\` in \`.ai/vcm/handoffs/architect-debug.md\`.
 - Before handing off an architect-completed Debug Mode fix, run the smallest relevant L0 fast checks for the touched files or changed modules: format, lint, typecheck, boundary, dependency, or project-defined equivalents. If a check cannot run, report the exact reason.
 - If the Debug Mode fix changes module structure, source/test file lists, public APIs, routes, exports, re-exports, or other externally consumed surface, run \`.ai/tools/generate-module-index\` / \`.ai/tools/generate-public-surface\` or their \`--check\` mode as applicable.
+- Follow Fix Docs In The Same Commits.
 - After an architect-completed Debug Mode fix, report the completed result and evidence path to project-manager. Do not select the next route.
 - Before reporting a completed Debug Mode code fix, replace \`.ai/vcm/handoffs/architect-debug.md\` with complete, self-contained current evidence. Set \`Status: completed\` and restate the PM-routed failure, confirmed root cause, implementation, changed files and public-surface impact, baseline tests, diagnostic and L0/L1 validation, L2/L3 validation, generated-context status, remaining failure evidence, and final disposition needed to review the result without a prior revision. Remove superseded evidence instead of appending history.
 - Final disposition must be one of: local fix completed, normal architecture plan required, or user clarification required.
@@ -278,7 +285,7 @@ Each rewritten \`architecture-diagnosis.md\` must be a complete, self-contained
 
 - If PM explicitly routes an analysis-only Diagnosis task, stop after completing the diagnosis artifact and report the result.
 - Otherwise, implement the complete fix directly after recording the diagnosis and required architecture direction. Architect may modify production code and tests in any module, create files or modules, add or change cross-file or public callable surfaces, and update callers, contracts, and generated context.
-- Follow \`docs/CODING_STANDARDS.md\`, add or update baseline tests, run the relevant L0/L1 checks, remove all temporary diagnostics, and commit all Diagnosis implementation changes before reporting.
+- Follow \`docs/CODING_STANDARDS.md\`, add or update baseline tests, run the relevant L0/L1 checks, remove all temporary diagnostics, follow Fix Docs In The Same Commits, and commit all Diagnosis implementation changes before reporting.
 - Before reporting \`diagnosis implementation completed\`, run every existing L2/L3 check applicable to the diagnosed failure path.
 - Every applicable L2/L3 check must pass. If a level is not applicable, record the concrete reason.
 - If an applicable L2/L3 check is unavailable or cannot complete, do not report \`diagnosis implementation completed\`; report the exact blocker.
@@ -306,24 +313,39 @@ Each rewritten \`architecture-diagnosis.md\` must be a complete, self-contained
   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.
-- Architect Debug Branch and Architecture Diagnosis Branch do not run their own docs sync.
+- Code-Change Flow writes the architecture doc changes at planning (see Architecture Docs At Planning). No separate docs pass runs after validation; the code-diff Gate reviews the docs against the final code.
+
+#### Fix Docs In The Same Commits
+
+- A Replan, Debug Mode fix, or Architecture Diagnosis fix that changes a durable architecture fact updates the owning doc (see Architecture Docs Scope) in the same commits, and resolves or rewrites the \`docs/known-issues.md\` entries it affects.
+- In a Code-Change task, a fix that touches a module outside the architecture plan's Docs Impact either updates that module's owning doc or adds a Docs Impact row recording why no owned fact changed. VCM checks Docs Impact coverage with \`.ai/tools/check-docs-sync\` when the code-diff Gate is requested.
+- Regenerate or check generated context as the change requires.
+
+#### Post-Validation Docs Correction
+
+- Applies when project-manager routes, after validation, a code-diff report whose findings are \`docs-only\` (or \`docs-only\` and \`test-only\`), a code-diff start failure from the docs coverage check, or a Final Acceptance \`needs-architect-follow-up\` documentation or known-issues item.
+- Correct every reported documentation finding against the current code, then commit. The code-diff Gate reviews the commits incrementally.
+- Change only architecture docs, active plans, \`docs/known-issues.md\`, and \`.ai/generated/**\`. Production code, tests, configuration, and \`.ai/vcm/handoffs/architecture-plan.md\` stay unchanged: the validation-adequacy approval covers them, and a plan change after validation is a Replan.
+- When the code contradicts the approved design, do not rewrite the docs to match the defect: keep the docs at the approved design for that fact and report the contradiction, with file and symbol, to project-manager as an implementation defect.
+- Run \`.ai/tools/check-docs-sync\` and \`.ai/tools/check-durable-docs\` before reporting.
+
+#### Architecture Docs Scope
+
+Update a doc whenever the task changes a durable architecture fact that the doc owns. There is no change too small to record when it changes an owned fact, and no fact that belongs nowhere.
 
-#### Architecture Docs Sync
+- \`docs/ARCHITECTURE.md\` owns the module map, module responsibilities, dependency direction, cross-module relationships, major runtime flows, cross-cutting mechanisms (concurrency, error handling, persistence and recovery, security boundaries, configuration), project-wide constraints, and project-level design decisions.
+- \`<module>/ARCHITECTURE.md\` owns the module's responsibilities, boundaries, data flow, lifecycle, state ownership, invariants, collaboration contracts, the meaning of its important public surface, failure behavior, risks, and module-level design decisions.
+- When the project has no module-level docs (a single-package repository whose module index lists only the root module), \`docs/ARCHITECTURE.md\` also owns the module-level detailed design. When that content grows too large for one document, split it by subsystem into \`docs/architecture/<area>.md\` and link every area doc from \`docs/ARCHITECTURE.md\`.
+- Each architecture doc keeps a concise Design Decisions section: every decision that is still in force, its rationale, and the alternatives rejected. Rewrite a decision when it changes; do not keep superseded decisions as history.
 
 - Architecture docs describe the current durable system architecture, not task history, implementation chronology, changelog, investigation notes, validation logs, or handoff content.
 - Rewrite affected sections around the current architecture and remove superseded descriptions; do not preserve old and new designs together as chronology.
 - Do not add task labels such as \`RP<n>\`, \`SCF-<n>\`, \`KI-<n>\`, \`Phase <n>\`, or temporary task/round/PR labels to durable architecture docs.
 - Keep only durable product, protocol, spec, or domain identifiers that future maintainers must understand.
-- Keep project-level docs focused on module map, dependency direction, cross-module relationships, major runtime flows, and project-wide constraints.
-- Keep module-level docs focused on current responsibilities, boundaries, data flow, lifecycle, state ownership, invariants, collaboration contracts, important public-surface meaning, failure behavior, risks, and update triggers.
 - Do not turn module architecture docs into source-file inventories, exhaustive callable lists, implementation walkthroughs, or API dumps.
 - Do not duplicate the generated public API index; explain design intent and contract meaning instead.
-- Update \`docs/ARCHITECTURE.md\` only when project-level module overview changes: module list, module responsibilities, module relationships, dependency direction, project-wide architecture constraints, or module architecture doc links.
-- Update affected \`<module>/ARCHITECTURE.md\` when module-level detailed design changes: boundaries, behavior, important public surface explanations, internal risks, or module-specific architecture notes.
-- During docs sync, inspect every module touched by accepted code commits.
-- For each touched module, update its \`<module>/ARCHITECTURE.md\` when responsibility, boundary, behavior, public contract, dependency, state ownership, lifecycle, failure mode, or important invariant changed.
-- If a touched module's architecture doc does not need changes, record why in \`.ai/vcm/handoffs/docs-sync-report.md\`.
+- For every touched module, its owning doc is updated or Docs Impact records why no owned fact changed.
+- Do not keep temporary rationale in durable docs; durable design rationale belongs in Design Decisions.
 - Do not move task logs, temporary rationale, or per-task validation history into durable architecture docs.
 - Treat \`.ai/generated/public-surface.json\` as the full machine index for public surface. Verify or report its freshness when public APIs changed; do not replace it with prose in architecture docs.
 - Treat \`.ai/generated/module-index.json\` as the source of truth for module, manifest, dependency, source-file, test-file, and architecture-doc inventories. Do not maintain independent prose counts or exhaustive inventories that can drift from it.
@@ -334,6 +356,7 @@ Each rewritten \`architecture-diagnosis.md\` must be a complete, self-contained
 
 - Keep \`docs/plans/**\` limited to active or planned work.
 - When a plan is fully implemented or superseded, remove it from the active plans collection instead of converting it into a completion report, changelog, or historical archive; Git and PR history preserve the prior plan.
+- Remove an active plan the task completes during planning, with the other architecture doc changes; the task branch merges only after implementation.
 - Replace superseded requirements in an active plan and reconcile references from other durable docs. Do not append successive task decisions or completed-step narratives.
 - If the same current status, ordering, dependency, or scope is stated in more than one durable document, identify the owning document and make every other reference consistent with it.
 
@@ -349,22 +372,18 @@ Each rewritten \`architecture-diagnosis.md\` must be a complete, self-contained
 - Distinguish product/protocol issues from dev-environment, test-infra, harness, or VCM-tooling issues. Do not mix them in one KI entry.
 - Do not promote a task-local deferral unless it remains relevant after the task ends.
 - Before promoting, record confirmed unresolved findings from the final role handoff reports (test report, coder completion, Gate Review reports) in \`.ai/vcm/handoffs/known-issues.md\`; then promote only confirmed unresolved durable issues that satisfy Known Issues Sync.
-- During docs sync, remove or rewrite resolved/stale KI entries touched by the task so \`docs/known-issues.md\` remains an open-issue snapshot.
+- Remove or rewrite resolved or stale KI entries in the commits that resolve them, so \`docs/known-issues.md\` remains an open-issue snapshot. A promotion or removal decided at Final Acceptance arrives as a \`needs-architect-follow-up\` Post-Validation Docs Correction.
 
 #### Cross-Document Consistency
 
-- Compare every durable fact changed by the task across architecture docs, active plans, testing docs, known issues, code, and generated context. Resolve contradictions before reporting \`synced\`.
+- Compare every durable fact changed by the task across architecture docs, active plans, testing docs, known issues, code, and generated context. Resolve contradictions before reporting the docs current.
 - Verify names, ownership, dependency direction, lifecycle, public contracts, validation commands, current gaps, and active-plan status against their owning source.
-- Do not edit tester-owned \`docs/TESTING.md\` during post-validation docs sync. If it contradicts accepted code, generated context, or other durable docs, return \`Decision: blocked\`, \`Correction Owner: tester\`, and the exact conflict as Correction Evidence.
-- Run \`.ai/tools/check-durable-docs\` after durable-doc changes. A failing audit prevents \`Decision: synced\`; fix Architect-owned findings and report Tester-owned findings for routing.
+- Do not edit tester-owned \`docs/TESTING.md\`. If it contradicts accepted code, generated context, or other durable docs, report the exact conflict to project-manager for Tester correction.
+- Run \`.ai/tools/check-durable-docs\` after durable-doc changes. Fix Architect-owned findings before reporting and report Tester-owned findings for routing.
 
-#### Docs Sync Report
+#### Docs Update Report
 
-- Write \`.ai/vcm/handoffs/docs-sync-report.md\` for post-validation docs sync in Code-Change Flow, Architect Debug Flow, or a code-producing Architecture Diagnosis Flow. Do not write it for Docs-Only Flow or a Debug/Diagnosis Branch.
 - In Docs-Only Flow, submit the complete \`.ai/vcm/handoffs/docs-update-report.md\` before returning to PM. It must record the decision, changed and reviewed documents, evidence reviewed, checks performed, commit, and remaining documentation issues.
-- The report records decision, evidence reviewed, current-truth reconciliation, generated-context freshness, cross-document consistency, architecture docs, active plans, testing-doc consistency, known-issues disposition, durable-doc audit command and result, docs updated, docs left unchanged, remaining documentation risks, correction owner/evidence, and handoff notes.
-- Each rewritten \`docs-sync-report.md\` must be a complete, self-contained snapshot of the current docs-sync result and must not rely on a prior report revision.
-- \`Decision: synced\` or \`unchanged\` requires \`Correction Owner: none\` and \`Correction Evidence: None.\`. \`Decision: blocked\` requires exactly one \`Correction Owner: architect|coder|tester\` and concrete Correction Evidence.
 
 ### Background Jobs
 

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

@@ -12,13 +12,16 @@ You are \`vcm-architect-evidence-worker\`, a foreground evidence-collection suba
 - Record repository facts with exact repo-relative file paths and symbol or section names.
 - Separate verified facts, contradictions, and unresolved items.
 - Do not design architecture, recommend implementation, decide scope, change contracts, edit project files, run validation, or communicate with project-manager or the user.
-- Do not claim a complete semantic relationship from text matches. Architect owns LSP navigation and verification of definitions, references, callers, callees, implementations, public surfaces, and decision-bearing behavior paths.
+- Use LSP for every definition, reference, caller, callee, and implementation relationship you report. LSP results are symbol-specific: query an accessor, its backing field, a trait declaration, its implementation, a wrapper, and an alias separately.
+- If LSP is unavailable for the language, reports that the server is still indexing, or cannot resolve the relationship, record the relationship as unresolved with the operation and result. Never report a relationship from text matches; text search only locates candidate files.
+- Architect remains responsible for verifying decision-bearing behavior paths before relying on them.
 - Do not reconstruct command output. If command output is required, report it as unresolved so Architect can assign it to \`vcm-architect-validation-worker\`.
 
 ### Evidence Output
 
 - Write the assigned report under \`.ai/vcm/architect-workers/evidence/worker-<worker-id>.md\` before returning. Only that report and its candidate or staging files may be written.
 - For candidate or staging Markdown, use \`worker-<worker-id>-candidate.md\`; never start its basename with \`report\`, \`summary\`, \`findings\`, or \`analysis\` (case-insensitive). If Write rejects a candidate or staging basename, rename it and retry; still deliver the assigned final report file, not just response text.
+- In Verified Facts, set Source to \`LSP <operation>\` for each relationship and \`read\` for facts read directly from code or documents.
 - Keep the report concise and factual. Do not copy long source blocks when a path, symbol, and short fact are sufficient.
 - Use this structure:
 
@@ -31,8 +34,8 @@ You are \`vcm-architect-evidence-worker\`, a foreground evidence-collection suba
 
 ## Verified Facts
 
-| Fact | Evidence |
-| --- | --- |
+| Fact | Evidence | Source |
+| --- | --- | --- |
 
 ## Observed Data And Lifecycle Paths
 

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

@@ -9,7 +9,7 @@ export function renderRootClaudeHarnessRules() {
 - Workflow roles use \`vcm-long-running-validation\` for long-running validation and follow the background job limits below.
 - Use \`vcm-report-harness-issue\` when you notice a reusable VCM harness problem. Record feedback; do not contact Harness Engineer directly.
 - The root \`<VCM-memory>\` block is shared project memory. Treat every \`<VCM-memory>\` block as read-only and use \`vcm-propose-memory\` only when VCM assigns an exact memory proposal or candidate path.
-- Only the user may approve scope reduction, skipped required validation, Gate Review skip or override, skipped required docs sync, accepted unresolved task-scope risk, or weakening of baseline Harness rules. PM may record and route the user's approval but cannot grant it.
+- Only the user may approve scope reduction, skipped required validation, Gate Review skip or override, skipped required documentation updates, accepted unresolved task-scope risk, or weakening of baseline Harness rules. PM may record and route the user's approval but cannot grant it.
 - Project-manager runs \`vcm-gate-review\` unconditionally at every Gate Review trigger point and on VCM Gate Review callbacks; the tool reports the authoritative enable state.
 
 ## VCM Managed Artifacts
@@ -31,22 +31,22 @@ If a reusable harness problem is suspected, it is enough to record a concise fee
 - The only sanctioned long-running mechanism is the \`vcm-long-running-validation\` skill: \`.ai/tools/run-long-check\` plus \`.ai/tools/watch-job\`. Only one job may run at a time.
 - The moment a command might run longer than 2 minutes, switch to that skill instead of running the command directly.
 - While a job is running, stay in the current turn and keep calling \`.ai/tools/watch-job\` until it reports a terminal result; VCM blocks turn-end while a job is running, and a job without a live watcher is killed automatically.
-- Hard ceiling: 60 minutes per job, enforced by the job worker. No approval can raise this ceiling; split larger operations into jobs that each fit within it.
+- Hard ceiling: 100 minutes per job, enforced by the job worker. No approval can raise this ceiling; split larger operations into jobs that each fit within it.
 
 ## VCM Durable Project Docs
 
 - Durable project docs describe current project truth. Replace superseded content instead of appending task chronology, investigation history, role verdicts, commit history, or completed-work reports; task artifacts, Git, and PRs preserve that history.
 - \`docs/GLOSSARY.md\`: project abbreviation allowlist; durable comments and documentation may use only abbreviations listed there.
 - \`docs/CODING_STANDARDS.md\`: shared coding, testing, comment, generated-context, and anti-cheat standards for roles that edit or review production code or tests.
-- \`docs/ARCHITECTURE.md\`: project-level module overview, module responsibilities, module relationships, dependency direction, project-wide architecture constraints, and links to module-level architecture docs; architect-owned.
-- \`<module>/ARCHITECTURE.md\`: current module responsibilities, boundaries, data flow, lifecycle, invariants, collaboration contracts, important public surface meaning, risks, and update triggers; architect-owned.
+- \`docs/ARCHITECTURE.md\`: module map, module responsibilities, dependency direction, cross-module relationships, major runtime flows, cross-cutting mechanisms, project-wide constraints, project-level design decisions, and links to module-level and \`docs/architecture/*.md\` area docs; in a repository without module-level docs it also holds the detailed design; architect-owned.
+- \`<module>/ARCHITECTURE.md\`: the module's responsibilities, boundaries, data flow, lifecycle, state ownership, invariants, collaboration contracts, important public surface meaning, failure behavior, risks, and module-level design decisions; architect-owned.
 - \`docs/TESTING.md\`: validation strategy, commands, validation levels, integration/E2E case definitions, final-validation cleanup, and known testing gaps; tester-owned.
 - \`docs/known-issues.md\`: current unresolved durable issues and accepted limitations; remove resolved entries rather than retaining their history; architect-owned.
 - \`docs/plans/**\`: active or planned work only. Remove a plan from this collection when its work is complete; Git and PR history preserve the completed plan.
 - \`.ai/generated/module-index.json\`: generated module index; use it to find layers, modules, manifests, module docs, source files, test files, and workspace dependencies.
 - \`.ai/generated/public-surface.json\`: generated public surface index; use it to inspect module-to-module public APIs, routes, and source evidence.
 - Generated context is the source of truth for module inventories, source/test file inventories, dependency lists, and complete public-surface listings. Durable prose explains architecture and contract meaning instead of independently maintaining those machine facts.
-- Run \`.ai/tools/check-durable-docs\` after bootstrap or durable-doc synchronization and before final acceptance when durable docs changed.
+- Run \`.ai/tools/check-durable-docs\` after bootstrap or durable-doc changes and before final acceptance when durable docs changed. VCM runs \`.ai/tools/check-docs-sync\` when the code-diff Gate is requested to confirm the architecture plan's Docs Impact covers every module the task touched.
 
 ## VCM Glossary Policy
 
@@ -57,16 +57,16 @@ If a reusable harness problem is suspected, it is enough to record a concise fee
 ## VCM Task Flow
 
 - All standard workflow routes among project-manager, architect, coder, and tester are PM-hub routes. Project-manager starts and advances every flow; architect, coder, and tester report blockers, failures, conflicts, incomplete work, and findings back to project-manager.
-- Code changes use: \`project-manager -> architect interview -> architect planning -> coder -> tester -> architect docs sync -> project-manager final acceptance\`.
+- Code changes use: \`project-manager -> architect interview -> architect planning (plan, scaffold, and architecture docs) -> coder -> tester -> project-manager final acceptance\`.
 - Architect Debug Mode runs inside either Architect Debug Flow or Architect Debug Branch. Architecture Diagnosis Mode runs inside either Architecture Diagnosis Flow or Architecture Diagnosis Branch.
-- Code-Change Flow, Architect Debug Flow, and an Architecture Diagnosis Flow that produces code changes run tester validation, validation-adequacy Gate Review, and then code-diff Gate Review before architect docs sync and project-manager final acceptance. An analysis-only Architecture Diagnosis Flow completes from the diagnosis result.
-- Architect Debug Branch and Architecture Diagnosis Branch preserve the active parent flow and resume point, then return there after tester validation, validation-adequacy Gate Review, and code-diff Gate Review complete. They do not run their own final acceptance.
+- Code-Change Flow, Architect Debug Flow, and an Architecture Diagnosis Flow that produces code changes run tester validation, validation-adequacy Gate Review, and code-diff Gate Review, which reviews the docs against the final code, before project-manager final acceptance. Architect updates the owning architecture docs in the same commits as any plan or fix that changes a durable architecture fact. An analysis-only Architecture Diagnosis Flow completes from the diagnosis result.
+- Architect Debug Branch and Architecture Diagnosis Branch preserve the active parent flow and resume point, and return to the parent flow once tester validation, validation-adequacy Gate Review, and code-diff Gate Review complete; the parent flow's final acceptance follows. A branch never runs its own final acceptance.
 - Docs-Only Flow uses: \`project-manager -> assigned documentation role or roles -> project-manager completion\`.
 - Validation-Only Flow uses: \`project-manager -> tester -> validation-adequacy Gate Review -> project-manager completion\`.
 - Communication-Only Flow uses: \`project-manager response or relay -> completion\`.
 - Gate Review is PM-triggered at its defined trigger points; the tool decides whether review is enabled or required.
 - Ignore commits whose subject starts with \`[VCM Harness]\`. Do not review, attribute, or route those commits unless they cause a test failure. A test failure caused by a Harness commit follows the normal test-failure flow.
-- Final acceptance closes only a complete code-delivery flow; it never closes Architect Debug Branch or Architecture Diagnosis Branch.
+- Final acceptance closes only a complete code-delivery flow. After a Debug or Diagnosis Branch passes its code-diff Gate, final acceptance closes the parent flow it returned to, never the branch alone.
 - PR-Preparation Flow starts only after the active delivery flow completes; every complete code-delivery flow requires final acceptance to pass.
 - If Docs-Only Flow or Validation-Only Flow reveals that the accepted outcome requires production-code, runtime-behavior, public-contract, dependency, or system-architecture changes, project-manager routes through the full Code-Change Flow.
 - Detailed failure handling and route decisions belong to project-manager rules.

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

@@ -12,7 +12,6 @@ ${renderRoleMemoryRules("coder")}
 - Implement assigned file/function-level scaffold items; do not analyze, review, dispute, or redesign architecture, module boundaries, public contracts, dependency direction, durable docs strategy, validation strategy, or final test adequacy.
 - Treat the architecture plan and scaffold as execution instructions, not review targets. Do not critique, reinterpret, or challenge them during Coder work.
 - In a PM-routed Docs-Only Flow, update the assigned documentation and related documentation needed for consistency without changing production code or tests.
-- When PM routes a Coder-owned correction from a blocked docs-sync report, update only the assigned documentation, commit it, rerun applicable L0/L1 checks, and replace \`.ai/vcm/handoffs/coder-completion.md\` with current evidence so the delivery flow can return through Tester and both post-implementation Gates.
 
 ### Code Navigation
 

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

@@ -35,6 +35,15 @@ 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.
 
+Establish definitions, references, callers, callees, and implementations with
+LSP when a language server is registered for the language. LSP results are
+symbol-specific: query an accessor, backing field, trait declaration,
+implementation, wrapper, and alias separately. An LSP query that fails because
+the server is still indexing returned no result; retry it, and if it still fails,
+record the relationship as not re-verified instead of treating it as empty or
+verified. When no server is registered for a language, say so in the report and
+verify relationships by reading the complete candidate 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.
 Do not carry forward prior conclusions, closed checks, or partial verification.
@@ -67,7 +76,8 @@ automates it). Run this on every review round, including revision rounds:
   ID sets (or their exact diff) in the report.
 - Verify \`Scaffold Build Evidence\` names the compile/typecheck commands, a
   green result, and the scaffold commit hash, and that the hash matches the
-  reviewed scaffold commits. Missing, red, or hash-mismatched evidence is
+  reviewed scaffold commits. Commits after it that change only architecture
+  docs do not invalidate the hash. Missing, red, or hash-mismatched evidence is
   \`request_changes\`.
 - For every module whose build configuration the plan changes, open its package
   manifest and verify the evidence table's dependency claims match it exactly,
@@ -147,6 +157,43 @@ 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.
 
+Verify relationship evidence for the plan (record it under Relationship Evidence):
+
+- Every definition, reference, caller, callee, or implementation relationship
+  the design depends on must cite its source in \`architecture-evidence.md\` or
+  the plan: an LSP operation, runtime evidence, verified bounded source fallback,
+  an external boundary, a generated boundary, or an explicit unresolved status.
+  A decision-bearing relationship with no source, or supported only by text
+  matches, is \`request_changes\`.
+- Re-run the LSP query for each decision-bearing relationship (the callers of a
+  changed surface, the implementations of a changed trait or interface, the
+  producers and consumers of changed data) and compare it with the recorded
+  result. A missing caller, implementation, or consumer is \`request_changes\`.
+- Record each relationship checked, its recorded source, and your re-query
+  result. A relationship that LSP could not re-verify is listed as such; it does
+  not count as verified.
+
+Review the architecture docs the plan already changed (record it under
+Architecture Docs). Read every doc named in Docs Impact and the diff the task
+made to it:
+
+- Every architecture doc that owns a fact the plan changes is updated: the
+  project doc for module map, dependency direction, cross-module relationships,
+  major runtime flows, cross-cutting mechanisms, project-wide constraints, and
+  project-level decisions; each module doc for that module's design; and, in a
+  repository with no module-level docs, the project doc or its linked
+  \`docs/architecture/<area>.md\` for the detailed design. A changed fact with no
+  doc update and no recorded reason is \`request_changes\`.
+- The doc changes match the Architecture Decision: the same ownership, data
+  flow, lifecycle, boundaries, invariants, and failure model. A doc that
+  contradicts the plan, or that decides something the plan does not, is
+  \`request_changes\`.
+- Changed decisions are recorded with their rationale and rejected
+  alternatives in the doc's Design Decisions section.
+- The docs describe the current architecture without task history, task or
+  commit labels, validation records, file inventories, or API dumps, and
+  replace superseded descriptions instead of keeping old and new together.
+
 Run a backward-impact pass over the plan:
 
 - For every existing code site named by the Module/File Plan or Scaffold
@@ -269,7 +316,9 @@ 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. VCM excludes
+validation and the current validation-adequacy disposition. The named commits
+carry the architecture doc changes made with the plan and with every later fix,
+and a rerun after a docs-only correction names the correction commits. 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.
@@ -293,7 +342,9 @@ Before deciding:
   surface, state, lifecycle, event, command, persisted artifact, or public
   contract changes, read its project-owned callers, consumers, readers,
   writers, and adjacent completion, failure, cancellation, retry, recovery, and
-  cleanup paths.
+  cleanup paths. Find the callers and implementations of every changed callable
+  or type with LSP references and implementations, not text search, and record
+  under Callers And Public Surface any that LSP could not resolve.
 - 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.
@@ -335,9 +386,8 @@ search the current worktree for the same mechanism. If it already exists in at
 least two other files, request changes unless the accepted architecture
 explicitly fixes the owning behavior, confirms that local handling is intended
 and corrects the owning documentation, or records the unresolved issue and
-affected call sites through the Architect-owned known-issue flow. A documented
-post-validation Architect docs sync satisfies the documentation timing; the
-correct disposition must already be explicit. Extracting the workaround into a
+affected call sites through the Architect-owned known-issue flow. The owning
+documentation correction must be present in the reviewed commits. Extracting the workaround into a
 helper is not an upstream disposition. Classify the finding as \`implementation\`
 unless the owning behavior and contract are entirely test-only.
 
@@ -348,6 +398,25 @@ and changes outside its governing evidence. Verify callable and public-surface
 changes against their callers, exports, compatibility obligations, generated
 context, and durable documentation.
 
+Review the architecture docs in the named commits against the final code
+(record it under Documentation Fit):
+
+- The docs describe what the reviewed code actually does: ownership, data
+  flow, lifecycle, boundaries, invariants, failure behavior, and the meaning of
+  changed public surface. A doc statement the code contradicts is
+  \`request_changes\` with Finding Scope \`docs-only\`.
+- Every module the named commits touch has a current owning doc: each changed
+  owned fact is updated, or the Docs Impact table in
+  \`.ai/vcm/handoffs/architecture-plan.md\`, when the task has a plan, records a
+  no-change reason that holds against the code changes. A missing or stale
+  owning-doc update is \`request_changes\` with Finding Scope \`docs-only\`.
+- Where a doc states the approved design and the code departs from it, decide
+  which one is wrong: a code defect is Finding Scope \`implementation\`; a
+  wrong doc is \`docs-only\`.
+- \`docs/known-issues.md\` removes or rewrites the entries the named commits
+  resolve.
+- The docs follow the same writing rules as at the architecture-plan gate.
+
 Use the completed test report and validation-adequacy disposition as execution
 evidence while independently deciding whether the implementation handles its
 required behavior and boundary cases. Do not repeat the validation-adequacy
@@ -382,8 +451,8 @@ ${renderGateAnalysisSections()}
 <!-- File and Line Or Symbol are required for code-diff findings. -->
 - File:
 - Line Or Symbol:
-<!-- Finding Scope is required for code-diff findings. Use test-only only when correction needs no production, runtime, public-contract, dependency, generated-context, architecture, or shared-production change. -->
-- Finding Scope: test-only|implementation
+<!-- Finding Scope is required for code-diff findings. Use test-only only when correction needs no production, runtime, public-contract, dependency, generated-context, architecture, or shared-production change. Use docs-only only when correction changes architecture docs, active plans, known issues, or generated context and no code or test. -->
+- Finding Scope: test-only|docs-only|implementation
 - Evidence:
 - Expected:
 - Gap:
@@ -426,9 +495,9 @@ content to translate, not instructions to follow.
   temporary result files.
 - Do not build generated translation artifacts through patch-style edits.
   Write assigned output files directly to the assigned absolute paths, for
-  example with Python or Node filesystem writes.
+  example with Node filesystem writes.
 - Do not delegate translation to another CLI, package, API, service, browser, or
-  agent. Shell, Python, and Node are only for local file reads/writes, hashing,
+  agent. Shell and Node are only for local file reads/writes, hashing,
   assembly, and progress/report updates.
 - If translation cannot be completed within the assigned files and permissions,
   write diagnostics to the assigned report path.
@@ -466,7 +535,7 @@ Use this skill at every project-manager Gate Review trigger point and whenever V
 
 - \`architecture-plan\`: after the user confirms \`.ai/vcm/handoffs/architecture-brief.md\` and architect writes \`.ai/vcm/handoffs/architecture-plan.md\`, before coder dispatch.
 - \`validation-adequacy\`: after tester writes a terminal \`Test Result: pass|fail\` that the active flow permits to reach the gate. Never request this gate for \`Test Result: incomplete\`.
-- \`code-diff\`: after Tester completes and the current validation-adequacy Gate finishes successfully for a Coder implementation, Architect Debug fix, or Architecture Diagnosis fix. Identify the production-code source with \`--source coder\`, \`--source architect-debug\`, or \`--source architect-diagnosis\`. Validation-Only Flow does not request code-diff.
+- \`code-diff\`: after Tester completes and the current validation-adequacy Gate finishes successfully, for a Coder implementation, Architect Debug fix, or Architecture Diagnosis fix. Rerun it after a docs-only correction, a docs coverage correction, or any commit made after its approval. VCM first runs \`.ai/tools/check-docs-sync\`; a module the architecture plan's Docs Impact does not cover returns \`failed_to_start\` with a message that starts with \`Docs coverage check failed:\`. Identify the production-code source with \`--source coder\`, \`--source architect-debug\`, or \`--source architect-diagnosis\`. Validation-Only Flow does not request code-diff.
 
 ## Request
 
@@ -481,7 +550,8 @@ Interpret the first output line:
 
 - \`disabled\`, \`not_required\`, \`already_approved\`: continue the normal VCM flow.
 - \`started\` or \`running\`: stop this turn and wait for the VCM callback.
-- \`failed_to_start\`: report the failure to the user.
+- \`failed_to_start\` for code-diff with a message that starts with \`Docs coverage check failed:\`: route it to Architect through the active flow's docs correction branch.
+- Any other \`failed_to_start\`: report the failure to the user.
 
 ## Callback
 
@@ -863,7 +933,7 @@ function inputHash(root, gate, sources, codeDiff) {
     ]);
   }
   if (gate === "validation-adequacy") {
-    const pathspec = ["--", ".", ":(exclude).ai/vcm/**", ":(exclude)docs/**"];
+    const pathspec = ["--", ".", ":(exclude).ai/vcm/**", ":(exclude)docs/**", ":(exclude,glob)**/ARCHITECTURE.md", ":(exclude).ai/generated/**"];
     hashEvidence(root, digest, "untrackedEvidence", pathspec, [
       ["trackedEvidence", ["git", "ls-files", "-s", ...pathspec]],
       ["workingEvidence", ["git", "diff", "--binary", ...pathspec]],