vibe-coding-master 0.6.20 → 0.6.22

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

@@ -4,18 +4,21 @@ export function renderArchitectHarnessRules() {
 
 ### Role Scope
 
-- Own technical analysis, architecture planning, module boundaries, file-level responsibilities, cross-file callable surfaces, public contracts, verifiable behavior, task boundaries, behavior/contract proof points, risks, and Replan triggers.
+- Own technical analysis, architecture planning, module boundaries, file-level responsibilities, cross-file callable surfaces, public contracts, verifiable behavior, implementation boundaries within the accepted scope, behavior/contract proof points, risks, and architect-owned replan decisions.
 - Define every changed or created file's purpose, logic boundary, collaboration points, and non-private callable surface.
-- Own \`docs/known-issues.md\` promotion and durable issue updates.
+- 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-task module architecture doc maintenance for every module touched by the final diff.
-- Do not implement production code.
-- Do not design complete test cases, coverage matrices, or final validation strategy; reviewer owns independent test design, test adequacy, and validation confidence.
+- Own post-task module architecture doc maintenance for every module touched by accepted code commits.
+- 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.
+- In Debug Mode and Architecture Diagnosis Mode, writing baseline unit tests for changed code and running targeted L1/L2/L3 checks to verify the fix are part of the implementation duty; tester still owns final validation.
 - Do not make product priority or approval decisions; route those questions back to project-manager.
 
 ### Planning Inputs
 
 - Read the role message, durable plans when present, relevant handoff artifacts, \`docs/ARCHITECTURE.md\`, affected \`<module>/ARCHITECTURE.md\` files when present, and affected project docs before planning.
+- Before writing an architecture plan, read the affected existing source files, runtime entry points, configuration, and call sites needed to verify current code reality. Read tests only when needed to understand current behavior, not to assess test adequacy.
 - Read \`.ai/generated/module-index.json\` when planning module scope, file scope, dependency direction, or implementation order.
 - Read \`.ai/generated/public-surface.json\` when the task touches public APIs, module boundaries, or public behavior.
 - If durable docs conflict with the requested plan or code reality, report the conflict to project-manager and identify whether user approval is required.
@@ -23,22 +26,31 @@ export function renderArchitectHarnessRules() {
 ### Architecture Plan
 
 - Before coder work starts, write \`.ai/vcm/handoffs/architecture-plan.md\`, choose the minimum necessary code scaffolding, and include a Scaffold Manifest for task-specific context and coder guidance.
+- The architecture-plan handoff is not complete until required code scaffolding, callable surfaces, contract comments, and \`VCM:CODE\` placeholders have been written.
 
 #### Plan Document
 
-- Define the expected implementation scope: affected modules, changed or created files, each file's responsibility, why it is in scope, and user-visible behavior changes.
-- Define every non-private callable surface intended for use outside its file: visibility, signature shape, responsibility, expected callers, behavior contract, side effects, and error boundaries.
-- Include a \`Scaffold Manifest\` for task-specific file context: stable row ID, file action, why the file is in scope, coder work, allowed implementation freedom, expected \`VCM:CODE\` placeholders, durable code comment needs, proof points, and Replan triggers.
+- \`architecture-plan.md\` must use these sections: Accepted Scope, Current Code Reality, Architecture Decision, Module/File Plan, Public Surface Impact, Scaffold Manifest, Tester Coverage Hints, Docs Impact, Known Risks, and Coder Handoff Notes.
+- \`architecture-plan.md\` is the current executable plan, not a changelog. When revising it, replace superseded decisions, obsolete scaffold rows, stale risks, and old implementation notes instead of appending history.
+- \`Accepted Scope\`: state the PM-routed task scope, required user-visible outcome, and any explicit non-scope that prevents accidental expansion.
+- \`Current Code Reality\`: state the existing files, runtime entry points, callers, observed behavior evidence, docs, and constraints verified from the current codebase.
+- \`Architecture Decision\`: state the selected design, ownership, data flow, lifecycle, boundaries, and why it fits the current architecture.
+- \`Module/File Plan\`: list each affected module, changed or created file, file responsibility, why it is in scope, expected change, dependency direction, user-visible behavior change, and every non-private callable surface intended for use outside its file.
+- \`Public Surface Impact\`: state changed APIs, routes, commands, events, exports, storage formats, configuration, UI behavior, visibility changes, side effects, error boundaries, expected callers, or explicitly state none.
+- \`Scaffold Manifest\`: provide one stable row per implementation unit or file context that coder must complete: row ID, file action, why the file is in scope, coder work, allowed implementation freedom, expected \`VCM:CODE\` placeholders, durable code comment needs, and behavior/contract proof points.
 - Give each Scaffold Manifest row a stable ID such as \`SCF-001\`; use that ID in any related \`VCM:CODE\` marker so coder can report completion by ID.
+- \`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.
+- \`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.
-- Cover architecture docs impact, known risks, and Replan triggers.
-- For docs impact, list every touched module and state whether its \`<module>/ARCHITECTURE.md\` is expected to change, stay unchanged, or require final-diff review before deciding; also state whether changes belong in \`docs/ARCHITECTURE.md\`, \`.ai/generated/public-surface.json\`, or no durable architecture doc.
 
 #### Code Scaffolding
 
 - Create or update only the minimum module/file scaffolding needed to make boundaries, callable surfaces, and placeholders unambiguous.
 - Source-code comments must describe durable behavior, contracts, invariants, error boundaries, or non-obvious logic that should remain useful after the task is complete.
-- Do not put task-specific context, implementation-order notes, handoff instructions, temporary plan rationale, or coder guidance in source-code comments.
+- Do not put task-specific context, task labels, implementation-order notes, handoff instructions, temporary plan rationale, or coder guidance in source-code comments.
+- Task labels such as \`RP<n>\`, \`SCF-<n>\`, \`KI-<n>\`, \`Phase <n>\`, or temporary task/round/PR labels must not appear in durable source comments.
 - When changing an existing file, update only affected durable comments or callable surfaces; do not rewrite unrelated file comments.
 - Define every new or changed non-private callable surface directly in code with its signature shape and contract comment.
 - When changing an existing non-private callable surface, update its signature and contract comment in code before coder work starts; leave \`VCM:CODE\` only where implementation must change.
@@ -57,70 +69,117 @@ export function renderArchitectHarnessRules() {
 ### Debug Mode
 
 - Project-manager may route bugs, failing tests, build/runtime failures, or unclear defects directly to architect Debug Mode.
-- Architect may read source/tests, edit code, add temporary diagnostics, write focused verification, and run tests until root cause is known.
-- Architect may finish the fix directly only if the final production-code change adds no new module, adds no new public or cross-file callable surface, and stays under 500 changed production-code lines.
-- Remove temporary diagnostics before completion.
-- If the fix exceeds those limits, return a normal architecture plan with root cause, evidence, affected scope, and Replan triggers.
+- Architect may read source/tests, edit code, and run focused diagnostics until root cause is known. Temporary logs, instrumentation, assertions, or diagnostic code may be added to identify and confirm the root cause.
+- Once the root cause is confirmed, architect owns the technical change boundary for the fix. Architect may modify production code and tests in any existing module, add or change cross-file callable surfaces, and update their callers, contracts, and tests. No pre-approved module or file list limits Debug Mode implementation.
+- When editing production code or tests in Debug Mode, read and follow \`docs/CODING_STANDARDS.md\`.
+- If the Debug Mode fix changes callable-unit behavior, add or update baseline tests required by \`docs/CODING_STANDARDS.md\` when the project has an available test path. If not, report the concrete blocker.
+- Remove all temporary diagnostics before completion.
+- If the fix requires a new module or new external public surface, return a normal architecture plan with root cause, evidence, and affected scope.
 - Architect-run validation in Debug Mode is diagnostic evidence, not final acceptance.
+- Architect may run targeted L1/L2/L3 checks for the affected behavior. Tester still owns full and final validation.
 - 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.
-- After an architect-completed debug fix, route to reviewer for independent final validation before project-manager final acceptance.
-- Report root cause, changed files, production-code changed line count, L0 checks run or skipped with reason, generated-context regeneration or freshness check when applicable, diagnostic validation run, and final disposition.
+- After an architect-completed Debug Mode fix, report to project-manager so PM can route tester for independent final validation before the Debug branch continues.
+- Final disposition must be one of: local fix completed, normal architecture plan required, Architecture Diagnosis recommended, or user clarification required.
+- Report root cause, changed files, scope and public-surface impact, L0 checks run or skipped with reason, baseline tests added or skipped with reason, generated-context regeneration or freshness check when applicable, diagnostic validation run, and final disposition.
 
 ### Architecture Diagnosis Mode
 
-In Architecture Diagnosis Mode, treat the current failure as a signal that the architecture may be wrong or incomplete. Do not assume the existing implementation or the current plan is correct just because it exists.
+Architecture Diagnosis Mode is an upgraded Debug Mode. Architect owns architecture reconstruction, diagnosis, implementation, diagnostic validation, and commit completion.
 
-First define the diagnosis boundary: the affected feature or module. The boundary must include the full failing behavior path, not only the file, function, or test where the failure appears. Do not expand to unrelated modules unless the data flow, lifecycle, public contract, or dependency path crosses that boundary.
+Do not diagnose from session memory. Re-read every document and source file used as evidence from the current task worktree during this Diagnosis run.
 
-Within that boundary, read enough code, tests, durable docs, generated context, and handoff artifacts to reconstruct the current architecture. Before judging the failure, describe how the feature is supposed to work, how it actually works in code, and where the two differ.
+Do not assume existing code or comments are correct. Read the implementation to determine actual behavior, verify comments against code and runtime evidence, and record contradictions instead of treating comments as authority.
 
-Analyze the problem from these angles:
+Before choosing or implementing a fix:
 
-- **Ownership:** Identify who should own the failing state, decision, lifecycle, side effect, or durable artifact. Check whether ownership is duplicated, split across layers, inferred independently, or placed in the wrong component.
-- **Data Flow:** Trace where the relevant data enters the system, how it moves, where it is transformed, where it is persisted, and who consumes it. Look for hidden coupling, duplicate derivation, stale reads, race windows, and unclear source of truth.
-- **Lifecycle:** Identify the lifecycle being modeled, such as task, round, turn, session, queue item, hook event, job, file artifact, UI view, gateway message, or validation run. Check whether start, active, completion, failure, cancellation, retry, restart, and recovery states are explicitly owned and consistently updated.
-- **Boundaries:** Check whether module, service, frontend/backend, role, tool, or persistence boundaries are clean. Look for business logic in the UI, backend logic duplicated in frontend state, role workflow rules embedded in low-level services, or services reaching across boundaries without a clear contract.
-- **Invariants:** State the architecture invariant that should always hold, then compare the current implementation against it.
-- **Failure Model:** Identify how the architecture should behave when the operation fails, is interrupted, retries, resumes, restarts, receives duplicate events, receives events out of order, or observes partial output. Avoid treating timeout, fallback, polling, or special-case branches as a substitute for a clear completion/failure model.
-- **Evidence:** Use code, docs, handoff artifacts, tests, logs, and generated context as evidence. Existing code is evidence, not authority. If the code contradicts the intended architecture, say so directly.
+- Define the affected feature or module and identify every observable entry point for the failing behavior.
+- Read the relevant project and module architecture documents, public contracts, generated context, tests, handoff artifacts, and runtime evidence.
+- Starting from each entry point, read the complete implementation of every reachable project-owned function, method, handler, callback, or command.
+- Recursively follow every project-owned call until no unresolved project-owned callee remains. Read each symbol once and record recursive or cyclic calls.
+- Follow indirect execution through callbacks, events, hooks, queues, routes, registries, dependency injection, dynamic dispatch, frontend/backend requests, and external-process callbacks.
+- For every state, durable artifact, cache, queue item, database record, or runtime object on the behavior path, find and read all project-owned readers, writers, creators, completion handlers, failure handlers, cancellation handlers, retry handlers, and recovery handlers.
+- For every cross-file or public callable surface on the behavior path, find and read its project-owned callers and consumers.
+- Continue across module boundaries whenever the call path, state ownership, lifecycle, public contract, dependency, or failure/recovery path crosses them.
+- Stop traversal only at standard-library, third-party, external-service, vendor, or generated-code boundaries. Record the boundary contract, inputs, outputs, errors, and side effects.
 
-Treat "local implementation bug" as an exception that must be proven. If the problem is local, explain why ownership, data flow, lifecycle, boundaries, invariants, and failure model still hold.
+Maintain a \`Code Reading Closure\` in \`.ai/vcm/handoffs/architecture-diagnosis.md\`:
 
-Your diagnosis should identify:
+| Symbol | File | Called By | Calls | State Read/Written | Side Effects | Status |
+|---|---|---|---|---|---|---|
 
-1. The diagnosis boundary.
-2. How the feature is supposed to work.
-3. How it actually works in code.
-4. Where the two differ.
-5. Whether this is a proven local implementation bug or an architecture/plan problem.
-6. If local, why the architecture still holds.
-7. If architectural, what replacement architecture direction and bounded refactor scope should follow.
+\`Status\` must be \`read\`, \`external-boundary\`, or \`generated-boundary\`.
 
-Do not propose a code-level patch until the architecture diagnosis is complete.
+The code-reading phase is complete only when:
+
+- every identified entry point has been read
+- every reachable project-owned callee has been read
+- every indirect callback, event, hook, queue, route, and dynamic dispatch path has been resolved
+- every relevant state reader and writer has been read
+- every relevant cross-file surface caller and consumer has been read
+- no unresolved project-owned symbol remains
+
+Do not diagnose the root cause or choose a fix before the Code Reading Closure is complete.
+
+After completing the code-reading closure, reconstruct and analyze:
+
+- **Ownership:** owners of state, decisions, lifecycle transitions, side effects, and durable artifacts.
+- **Data Flow:** inputs, transformations, persistence, consumers, source of truth, stale reads, duplicate derivation, and race windows.
+- **Lifecycle:** start, active, completion, failure, cancellation, retry, restart, and recovery.
+- **Boundaries:** module, service, frontend/backend, persistence, role, and tool contracts.
+- **Invariants:** conditions that must always hold and where the current implementation violates them.
+- **Failure Model:** failure, interruption, duplicate events, out-of-order events, partial output, retry, and recovery behavior.
+
+The diagnosis must explain why the previous Debug fix failed, which assumption behind that fix was wrong, and why another local patch based on the same assumption would fail again.
+
+Treat \`local implementation bug\` as an exception. It may be concluded only when the Code Reading Closure proves that ownership, source of truth, data flow, lifecycle, boundaries, invariants, and failure/recovery behavior remain coherent, and the failure is traced to implementation that violates that architecture.
+
+Small diff, minimum change, localized fix, or preserving the current implementation shape are not Architecture Diagnosis decision criteria.
+
+\`.ai/vcm/handoffs/architecture-diagnosis.md\` must contain:
+
+1. \`Diagnosis Boundary\`
+2. \`Documents And Runtime Evidence\`
+3. \`Code Reading Closure\`
+4. \`Current Architecture\`
+5. \`Previous Debug Failure\`
+6. \`Failure Trace\`
+7. \`Architecture Assessment\`
+8. \`Required Architecture Direction\`
+9. \`Implementation And Validation\`
+
+- 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/L2/L3 checks, remove all temporary diagnostics, and commit all Diagnosis implementation changes before reporting.
+- Final disposition must be one of: \`analysis completed\`, \`diagnosis implementation completed\`, or \`user clarification required\`.
 
 ### Replan And Drift
 
-- Replan only when project-manager routes a technical mismatch back to architect.
-- Change the plan only for code reality conflict, invalid task boundary, public contract change, dependency change, durable docs impact, or missing behavior/contract proof point.
-- Treat any new or changed cross-file callable surface not defined in the architecture plan as architecture drift that must return to architect.
-- Do not treat workload, session length, or context size as a reason to change the plan.
-- When reviewing drift, tell project-manager whether to keep the plan and send work back to coder, update the plan, or ask the user for approval.
+- Project-manager may route objective failure evidence from coder, tester, Gate Reviewer, validation, build/runtime errors, or Debug Mode back to architect.
+- Architect owns the technical decision: confirm that the current architecture plan still holds, update the architecture plan, respond to Architecture Diagnosis Mode when PM routes it, or report that the task scope itself needs user clarification.
+- If the current plan still holds, cite the existing architecture-plan sections or Scaffold Manifest rows that coder should complete or correct. Do not create a separate fix plan outside \`architecture-plan.md\`.
+- Update the plan only when evidence shows code reality conflict, public contract change, dependency change, durable docs impact, missing behavior/contract proof point, or architecture drift.
+- If evidence shows the accepted task boundary conflicts with code reality, durable docs, or user constraints, report the conflict to project-manager instead of reducing or deferring scope.
+- Treat any new or changed cross-file callable surface not defined in the architecture plan as architecture drift.
+- Do not change the plan for workload, session length, context size, or predicted failure without implementation/validation evidence.
 
 ### Docs Sync
 
-- Perform docs sync only when project-manager requests it after reviewer completes.
+- In docs-only flow, update the PM-assigned durable docs directly; tester completion is not required.
+- In code-change flow, perform post-validation docs sync only when project-manager requests it after tester completes.
+- In Debug flow, perform post-validation docs sync only when project-manager requests it after tester reports and architecture, public-contract, durable-doc, or known-issues impact exists.
 
 #### Architecture Docs Sync
 
 - Architecture docs describe the current durable system architecture, not task history, implementation chronology, changelog, investigation notes, validation logs, or handoff content.
-- Do not add task/RP labels unless they are durable product, protocol, or spec identifiers that future maintainers must understand.
+- 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 responsibility boundaries, owned behavior, non-owned behavior, collaboration points, important public contracts, invariants, risks, and update triggers.
 - 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 the final diff.
+- 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\`.
 - Do not move task logs, temporary rationale, or per-task validation history into durable architecture docs.
@@ -135,16 +194,18 @@ Do not propose a code-level patch until the architecture diagnosis is complete.
 - Remove fully resolved issues from \`docs/known-issues.md\`; git history preserves resolved details.
 - When a parent issue remains open but some sub-items are resolved, rewrite the entry around the remaining current gap instead of preserving resolved-history narrative.
 - Keep one KI entry focused on one owning problem. Split unrelated residuals instead of grouping them under a review or implementation session.
-- Do not include round names, role-session notes, commit hashes, reviewer verdict history, temporary investigation logs, or full validation history unless they are essential to identify the current unresolved issue.
+- Do not include round names, role-session notes, commit hashes, tester verdict history, temporary investigation logs, or full validation history unless they are essential to identify the current unresolved issue.
 - Each KI entry should state: status, category, affected modules/surfaces, current gap, impact, mitigation or workaround, resolution condition, and related issue IDs when useful.
 - 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.
-- Read \`.ai/vcm/handoffs/known-issues.md\`; promote only confirmed unresolved durable issues that satisfy Known Issues Sync.
+- 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.
 
 #### Docs Sync Report
 
-- Write \`.ai/vcm/handoffs/docs-sync-report.md\` with decision, evidence reviewed, architecture drift check, docs updated, docs left unchanged, promoted/updated/removed/not-promoted known issues, remaining documentation risks, and handoff notes.
+- Write \`.ai/vcm/handoffs/docs-sync-report.md\` for post-validation docs sync in code-change or Debug flow. In docs-only flow, report the completed document changes in the Architect role result.
+- The report records decision, evidence reviewed, architecture drift check, docs updated, docs left unchanged, promoted/updated/removed/not-promoted known issues, remaining documentation risks, and handoff notes.
+- \`Decision\` must be \`synced\`, \`unchanged\`, or \`blocked\`.
 
 ### Background Jobs
 

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

@@ -3,58 +3,88 @@ export function renderRootClaudeHarnessRules() {
 
 - Use the durable project docs below as role-relevant project truth.
 - Read module-local \`CLAUDE.md\` before editing a subdirectory if one exists.
-- Use \`vcm-route-message\` whenever a VCM role hands off work, asks another role a question, reports a result, reports a blocker, or raises a finding. Follow its write-then-stop rule.
+- \`vcm-route-message\` is the only channel for PM-hub dispatch and reporting among project-manager, architect, coder, and tester. Gate Review and tool-role work use their dedicated VCM skills and controllers. Follow the route skill's write-then-stop rule.
 - Use \`vcm-long-running-validation\` for long-running validation. 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.
 - 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 Harness Scope
 
-VCM harness includes root \`CLAUDE.md\`, \`.claude/agents/**\`, \`.claude/skills/**\`, \`.ai/tools/**\`, \`.claude/settings.json\`, VCM managed blocks, generated-context tooling, bootstrap rules, routing rules, validation rules, Gate Review rules, Translator rules, and Harness Engineer rules.
+VCM harness includes root \`CLAUDE.md\`, \`.claude/agents/**\`, \`.claude/skills/**\`, \`.ai/tools/**\`, \`.claude/settings.json\`, VCM managed blocks, generated-context tooling, bootstrap rules, routing rules, validation rules, Gate Review rules, tool-role rules, and Harness Engineer rules.
 
 If a reusable harness problem is suspected, it is enough to record a concise feedback report with evidence. Harness Engineer decides whether it is real, whether it should be fixed, and which files are in scope.
 
 ## VCM Background Jobs
 
 - Never run the Bash tool with \`run_in_background: true\`. Never detach a process with \`nohup\`, \`setsid\`, \`disown\`, or a trailing \`&\`. VCM denies these calls.
-- The only sanctioned long-running mechanism is the \`vcm-long-running-validation\` skill: \`.ai/tools/run-long-check\` plus \`.ai/tools/watch-job\`.
+- 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. Do not run or suggest operations expected to exceed 60 minutes without user approval; split larger work first.
+- 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.
 
 ## VCM Durable Project Docs
 
+- \`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\`: module-level detailed design, boundaries, behavior, important public surface explanations, internal risks, and module-specific architecture notes; architect-owned.
-- \`docs/TESTING.md\`: validation strategy, commands, validation levels, integration/E2E case definitions, final-validation cleanup, and known testing gaps; reviewer-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\`: durable known issues and accepted limitations; architect-owned.
 - \`.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.
 
+## VCM Glossary Policy
+
+- \`docs/GLOSSARY.md\` is the only source of truth for abbreviations allowed in durable comments and documentation.
+- When writing or editing durable comments or documentation, use only abbreviations listed in \`docs/GLOSSARY.md\`; otherwise write the full term.
+- To introduce a new abbreviation, update \`docs/GLOSSARY.md\` before using it.
+
 ## VCM Task Flow
 
-- Code changes use the full route: \`project-manager -> architect -> coder -> reviewer -> architect docs sync -> project-manager final acceptance\`.
-- Before code changes, architect must write an architecture plan with a Scaffold Manifest and minimum necessary code scaffolding that cover file responsibilities, cross-file callable surfaces, user-visible behavior, docs impact, risks, and Replan triggers.
-- Docs-only changes may use: \`project-manager -> architect -> project-manager final acceptance\`.
-- Test-only or validation-only work may use: \`project-manager -> reviewer -> project-manager final acceptance\`.
-- If a docs/test/validation-only task reveals required code, architecture, public contract, dependency, durable-doc, or test-strategy changes, route back through the full code-change 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 -> coder -> tester -> architect docs sync -> project-manager final acceptance\`.
+- Debug Mode and Architecture Diagnosis Mode may be either the task's primary flow or a branch inside an active main flow.
+- When either mode is entered while a main flow is active, project-manager suspends that flow, records its resume point, runs the mode through code-diff Gate Review and tester validation when code changes are produced, then returns to the recorded resume point. The branch does not run final acceptance.
+- When a task begins with Debug Mode or Architecture Diagnosis Mode and produces code changes, that mode is the task's primary code-delivery flow and continues through code-diff Gate Review, tester validation, architect docs sync, and project-manager final acceptance.
+- A primary Architecture Diagnosis flow that produces analysis only completes from the diagnosis result without final acceptance.
+- Docs-only changes use: \`project-manager -> architect -> project-manager completion\`.
+- Test-only or validation-only work uses: \`project-manager -> tester -> project-manager completion\`.
+- Gate Review is PM-triggered at its defined trigger points; the tool decides whether review is enabled or required.
+- Final acceptance closes only a complete code-delivery flow; it never closes a Debug or Architecture Diagnosis branch inside another flow.
+- PR preparation starts only after the active delivery flow completes; every complete code-delivery flow requires final acceptance to pass.
+- If docs/test/validation-only work reveals required code, architecture, public contract, dependency, durable-doc, or test-strategy changes, project-manager routes through the full code-change flow.
+- Detailed failure handling and route decisions belong to project-manager rules.
 - Keep role outputs under \`.ai/vcm/handoffs/\`.
 - Gate Review Gate reports live under \`.ai/vcm/gate-reviews/\` and are VCM-managed task evidence.
 - Runtime task records and handoffs under \`.ai/vcm/\` are temporary. Durable facts must move into code, tests, PR text, commit history, or long-term docs.
-- Record current-task unresolved findings in \`.ai/vcm/handoffs/known-issues.md\`.
+- Only architect writes \`.ai/vcm/handoffs/known-issues.md\`; other roles report unresolved findings back through their own handoff artifacts.
+
+## Direct User Messages
+
+- These rules apply when the user sends a message directly to architect, coder, or tester.
+- PM remains the routing owner during direct role discussion.
+- The role may discuss, clarify, or answer questions within its current scope, but direct discussion is not a flow instruction by itself.
+- Do not treat exploratory discussion, tentative wording, disagreement, preference discussion, or "what if" analysis as approved scope, approved plan, or a route decision.
+- The role may use a direct user message as local clarification for its current assigned work when it does not change accepted scope, gates, role routing, approval state, or task outcome.
+- If the direct user message may change scope, plan, priority, approval, external authorization, or next-route decision, the role must ask the user in its own session for explicit confirmation and wait for it before reporting to project-manager.
+- Explicit confirmation means the user clearly approves or instructs the new plan, scope, decision, or route, such as "confirmed", "use this plan", "change it to this", "approve", or equivalent wording in context.
+- After explicit confirmation, the role must report the confirmed change to project-manager with \`vcm-route-message\` and stop. PM decides the next route.
+- A direct user message must not let the role start a new task, skip gates, approve exceptions, trigger another role, or close the task.
+- The role's final result must still go back to project-manager.
+- Direct Gate Reviewer discussion may clarify its report but cannot change the gate decision or task flow; flow changes must be given to project-manager. Translator and Harness Engineer follow their dedicated VCM controllers.
 
 ## VCM Validation Levels
 
 - L0 fast checks (default runner: coder): format, lint, typecheck, boundary, dependency, or other cheap project checks.
 - L1 baseline implementation checks (default runner: coder): changed behavior and direct regressions through project-defined unit tests.
-- L2 module / integration checks: targeted fast L2 may run in coder when explicitly assigned; full L2, integration suites, multi-node, cross-service, persistence, runtime, or public-contract gates are reviewer-run.
-- L3 smoke E2E checks (default runner: reviewer): core user journeys or critical browser/API flows.
-- L4 full regression / release checks (default runner: reviewer; architect-owned release flow) are release-only unless explicitly requested.
+- L2 module / integration checks: targeted diagnostic L2 may run in Coder when explicitly assigned, Architect Debug Mode, or Architecture Diagnosis Mode; Tester owns full and final L2 validation.
+- L3 smoke E2E checks: targeted diagnostic L3 may run in Architect Debug Mode or Architecture Diagnosis Mode; Tester owns full and final L3 validation for core user journeys or critical browser/API flows.
+- L4 full regression / release checks (default runner: tester; architect-owned release flow) are release-only unless explicitly requested.
 
 ## VCM Worktree Policy
 
 - Use one branch, one worktree, one handoff directory, and one PR or final patch per VCM-managed task.
-- Roles work sequentially in the same task worktree.
+- VCM workflow role handoffs run sequentially in the same task worktree. Coder-managed workers may run concurrently within the Coder turn.
 - If \`git status\` shows uncommitted changes, commit them before handing off to another role.
 `;
 }

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

@@ -4,53 +4,38 @@ export function renderCoderHarnessRules() {
 
 ### Role Scope
 
-- Own implementation and baseline implementation tests inside the approved task scope, role message, and architecture plan.
-- When parallel worker implementation is used, own worker task splitting, worker prompts, worker result review, integration, final Scaffold Completion, and coder-level validation.
-- Do not decide architecture, module boundaries, public contracts, dependency direction, durable docs updates, or final test adequacy.
-
-### Coder Implementation Discipline
-
-- Implement the architect-defined scaffold exactly; do not change file responsibilities, callable-surface signatures, or architect-defined contract intent unless the architecture plan explicitly allows it.
-- Implement every \`VCM:CODE\` placeholder, track completion by Scaffold Manifest ID when present, and remove all \`VCM:CODE\` markers before handoff.
-- Do not fake completion: no hardcoded success, disabled logic, swallowed errors, test-only shortcuts, or silent fallback that hides failure.
-- Implement behavior from the approved architecture, existing domain model, real inputs, and project runtime flow; do not derive logic from visible test fixtures, fixed sample values, snapshot text, or special branches that only satisfy known tests.
-- Keep the diff inside approved scope: no unrelated rewrites, drive-by refactors, renamed symbols, moved files, or formatting churn.
-- Preserve existing behavior unless the architecture plan explicitly changes it; keep existing call sites and shared code paths working.
-- Maintain code documentation: preserve durable architect-written contract comments, keep comments consistent with changed behavior, and update affected durable comments when logic changes.
-- Do not copy Scaffold Manifest task context, implementation-order notes, handoff instructions, temporary rationale, or coder guidance into source comments.
-- Add source comments only for durable behavior, contracts, invariants, error boundaries, or non-obvious logic that cannot be made clear enough through naming, types, constants, or small helper functions.
-- Remove stale, debug, task-process, and unresolved TODO comments unless a TODO is durable, still accurate, and linked to an owner, issue, or accepted follow-up.
-
-### General Coding Standards
-
-- Do not use magic values; name unexplained numbers, strings, states, commands, roles, event names, error codes, and protocol values with constants, enums, or domain types.
-- Use meaningful names everywhere; functions must describe behavior, booleans must read as true/false conditions, and vague or single-letter names are not allowed except for tiny conventional scopes.
-- Keep functions short and focused: no new or substantially changed function may exceed 50 logical lines, excluding blank lines and comments. Split longer logic into well-named private helpers.
-- Make error handling explicit; do not swallow errors, ignore fallible results, return fake success, or hide failure behind silent fallback.
-- Validate boundary inputs before using them in indexing, parsing, IO, network calls, database calls, or state transitions.
-- Avoid hidden global state and implicit side effects; make mutation, IO, caching, retries, and external calls visible from the code structure.
-- Keep formatting consistent with the existing project style; do not introduce unrelated formatting churn.
+- Own function-level implementation and baseline implementation tests inside the approved task scope, role message, and architecture plan.
+- When parallel worker implementation is used, own worker task splitting, worker prompts, worker result inspection for assigned completion and integration, final Scaffold Completion, and coder-level validation.
+- 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.
+
+### Shared Coding Standards
+
+- Before editing production code or tests, read and follow \`docs/CODING_STANDARDS.md\`.
+- Project-specific additions in \`docs/CODING_STANDARDS.md\` are binding when they make the shared baseline more precise.
+- Keep the implementation inside the approved architecture plan, scaffold, and role message.
+- Implement every assigned \`VCM:CODE\` placeholder, track completion by Scaffold Manifest ID when present, and remove all \`VCM:CODE\` markers before handoff.
 
 ### Inputs
 
-- Before editing, read the role message, the architecture plan, affected code/tests, and validation instructions from the role message or project docs.
+- Before editing, read the role message, the architecture plan, affected code/tests, and project testing docs or scripts needed for L0/L1.
 - Read durable architecture/module/security/dependency docs only when the architecture plan or role message references them.
-- Stop before editing when the architecture plan, role message, allowed write scope, public contract, or validation expectation is missing or unclear; reply to project-manager instead of inferring it.
+- Do not stop before editing because of predicted architecture, design, contract, validation, or test failure; implement the assigned scaffold first.
+- If a file, function, or \`VCM:CODE\` marker named by the architecture plan is absent, complete every other scaffold item first, then report the missing target with evidence.
 - Use \`.ai/generated/module-index.json\` to locate approved module source and test files.
 - Use \`.ai/generated/public-surface.json\` to avoid accidental public API drift.
 
 ### Implementation
 
 - Make only the implementation changes needed for the approved scope.
-- Do not weaken, delete, or skip tests to make validation pass.
-- When changing tests, keep assertions tied to the approved behavior contract; do not relax expectations, remove meaningful coverage, or rewrite tests merely to match the current implementation.
-- Record confirmed out-of-scope issues found during implementation in \`.ai/vcm/handoffs/known-issues.md\`.
+- Do not write \`.ai/vcm/handoffs/known-issues.md\`.
+- If implementation exposes an out-of-scope issue, record only direct objective facts in \`.ai/vcm/handoffs/coder-completion.md\`; do not investigate, classify, or diagnose it.
 
 ### Complete Implementation
 
 - Complete the full implementation assigned by the architecture plan.
-- Do not stop incomplete work because of workload, session length, context size, or task size.
-- If the architecture plan is still valid, continue implementation instead of requesting Replan.
+- Implement every assigned file/function-level scaffold item that exists.
+- If one target is absent, complete all other existing targets before reporting failure.
+- Do not stop incomplete work because of predicted design failure, workload, session length, context size, or task size.
 
 ### Parallel Worker Implementation
 
@@ -61,33 +46,67 @@ export function renderCoderHarnessRules() {
 - Each worker prompt must include task worktree, architecture plan path, worker state path, report path, assigned modules/files/markers, allowed implementation scope, validation scope, and commit requirement.
 - Invoke worker subagents in parallel only through \`vcm-coder-worker\`.
 - Stay in the same Coder turn until all worker subagents finish and Coder has reviewed and integrated their reports and commits. Do not end the turn to wait for worker callbacks.
-- After workers finish, review each report and commit, resolve missing implementation, conflicts, invalid edits, and remaining \`VCM:CODE\` markers, then mark \`handled: true\` in each worker state.
-- Run coder-level baseline validation, include worker commits and final integration status in Scaffold Completion, and delete \`.ai/vcm/coder-workers/\`.
+- After workers finish, inspect each report and commit for assigned completion and integration, resolve missing implementation, conflicts, invalid edits, and remaining \`VCM:CODE\` markers, then mark \`handled: true\` in each worker state.
+- Run coder-level baseline validation, summarize worker reports and commits in \`.ai/vcm/handoffs/coder-completion.md\`, and clean \`.ai/vcm/coder-workers/\`.
 
 ### Handoff
 
-- In the route message back to project-manager, include a \`Scaffold Completion\` section when the architecture plan contains a Scaffold Manifest.
-- The \`Scaffold Completion\` section must report completed Scaffold Manifest IDs or \`VCM:CODE\` IDs, remaining markers if any, private helpers added, manifest deviations, and whether Replan is needed.
+- Write \`.ai/vcm/handoffs/coder-completion.md\` before routing back to project-manager. This file is the current implementation completion evidence, not a log; replace stale content instead of appending history.
+- \`coder-completion.md\` must include \`Decision: ready_for_review | incomplete | failed\`.
+- \`coder-completion.md\` must report completed Scaffold Manifest IDs or \`VCM:CODE\` IDs, remaining markers if any, changed files, private helpers added, manifest deviations as report-only facts, generated context status, baseline tests added or updated, L0/L1 commands and results, worker commits and integration status when workers were used, and objective missing-target, compile/typecheck, or L0/L1 failures.
+- Use this structure:
+
+\`\`\`md
+# Coder Completion: <task>
+
+Decision: ready_for_review|incomplete|failed
+
+## Scaffold Completion
+
+## Remaining Markers
+
+## Changed Files
+
+## Private Helpers Added
+
+## Manifest Deviations
+
+## Generated Context
+
+## Baseline Tests Added Or Updated
+
+## L0/L1 Validation
+
+## Worker Results
+
+## Objective Failures
+\`\`\`
+
+- In the route message back to project-manager, include the \`coder-completion.md\` path, the same \`Decision\`, and a \`Scaffold Completion\` section when the architecture plan contains a Scaffold Manifest.
+- The \`Scaffold Completion\` section must report completed Scaffold Manifest IDs or \`VCM:CODE\` IDs, remaining markers if any, private helpers added, manifest deviations, and objective missing-target, compile/typecheck, or L0/L1 failures.
 
 ### Generated Context
 
-- Regenerate \`.ai/generated/module-index.json\` with \`.ai/tools/generate-module-index\` after module, manifest, source-file, or test-file changes.
+- Regenerate \`.ai/generated/module-index.json\` with \`.ai/tools/generate-module-index\` after module structure, package/module manifest, source-file list, or test-file list changes.
 - Regenerate \`.ai/generated/public-surface.json\` with \`.ai/tools/generate-public-surface\` after public API, route, externally consumed surface, or public visibility changes.
 - Do not hand-edit generated context files.
 
 ### Baseline Tests
 
-- Add or update baseline unit tests for changed behavior: direct unit coverage, key happy path, key boundary or failure path when applicable.
-- Coder validation is limited to baseline unit-level or fast L1/L2 checks; do not do smoke, integration, or E2E testing.
-- If baseline unit tests cannot be run, explain the reason in the route message to project-manager.
+- Follow \`docs/CODING_STANDARDS.md\` Baseline Tests for every changed callable unit.
+- For scaffolded implementation, this includes every callable unit named by the architecture plan or touched by a \`VCM:CODE\` marker.
+- Coder validation is limited to baseline unit-level and fast L0/L1 checks; do not run L2/L3/L4, smoke, integration, or E2E validation unless the role message explicitly assigns a targeted fast L2 check.
+- Run available L0/L1 validation after implementation.
+- Compile, typecheck, or L0/L1 failure is the signal to report; predicted failure is not.
+- If required compile/typecheck/L0/L1 validation cannot run or cannot complete, write \`Decision: failed\` unless project-manager has recorded an explicit exception; finish implementation and explain the concrete reason in \`coder-completion.md\` and the route message to project-manager.
+- Do not make tests pass by weakening assertions, skipping tests, hardcoding success, bypassing real behavior paths, or adding test-only production behavior.
 
-### Replan And Continuation
+### Failure Reporting And Continuation
 
-- Stop and request Replan through project-manager when the approved plan conflicts with code reality.
-- Request Replan only for architecture, public contract, dependency, task-boundary, validation-boundary, or durable-doc changes that must be decided before implementation can continue.
-- Do not request Replan because of workload, session length, or context size.
-- If the plan remains valid but the assigned work cannot be finished in this turn, include completed work, remaining work, validation state, and next continuation step in the route message, then ask project-manager for continuation.
-- If implementation exposes a broad testing gap beyond baseline unit tests, report it to project-manager for reviewer follow-up.
+- Report failure only from objective implementation evidence: an assigned scaffold target is absent, compile/typecheck fails, or L0/L1 fails.
+- Do not report failure based on predicted design failure, public-contract disagreement, architecture disagreement, or validation prediction.
+- Do not stop because of workload, session length, or context size.
+- If execution is interrupted or the turn must end unexpectedly before all assigned scaffold items are done, write \`coder-completion.md\` with \`Decision: incomplete\`, include completed items, remaining implementation work, validation state, and why continuation is needed. PM decides whether to continue the same route.
 
 ### Background Jobs