vibe-coding-master 0.6.21 → 0.6.22

package/dist/backend/cli/install-vcm-harness.js

@@ -216,7 +216,7 @@ const WHOLE_FILES = [
         path: ".claude/skills/vcm-final-acceptance/SKILL.md",
         category: "skill",
         mode: 0o644,
-        content: renderSkillFile("VCM Final Acceptance Skill", "vcm-final-acceptance", "Use when project-manager is ready to close a complete VCM code-change flow.", renderVcmFinalAcceptanceSkillRules())
+        content: renderSkillFile("VCM Final Acceptance Skill", "vcm-final-acceptance", "Use when project-manager is ready to close a complete VCM code-delivery flow.", renderVcmFinalAcceptanceSkillRules())
     },
     {
         path: ".claude/skills/vcm-harness-bootstrap/SKILL.md",

package/dist/backend/services/gate-review-service.js

@@ -30,6 +30,9 @@ const CODE_DIFF_SOURCE_ARTIFACTS = {
     ],
     "architect-debug": [
         ".ai/vcm/handoffs/role-commands/architect.md"
+    ],
+    "architect-diagnosis": [
+        ".ai/vcm/handoffs/architecture-diagnosis.md"
     ]
 };
 const CORE_INPUT_ARTIFACTS = {
@@ -94,7 +97,7 @@ export function createGateReviewService(deps) {
             return { status: "running", gate, record, message: "Gate review is already running." };
         }
         if (gate === "code-diff" && !codeDiffSource) {
-            const message = "code-diff requires --source coder or --source architect-debug.";
+            const message = "code-diff requires --source coder, --source architect-debug, or --source architect-diagnosis.";
             index = applyGateState(index, gate, {
                 status: "failed",
                 decision: undefined,

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

@@ -106,7 +106,7 @@ const HARNESS_FILES = [
         kind: "skill-vcm-final-acceptance",
         path: ".claude/skills/vcm-final-acceptance/SKILL.md",
         title: "VCM Final Acceptance Skill",
-        frontmatter: renderSkillFrontmatter("vcm-final-acceptance", "Use when project-manager is ready to close a complete VCM code-change flow."),
+        frontmatter: renderSkillFrontmatter("vcm-final-acceptance", "Use when project-manager is ready to close a complete VCM code-delivery flow."),
         ownership: "whole-file",
         renderRules: renderVcmFinalAcceptanceSkillRules
     },

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

@@ -9,10 +9,10 @@ export function renderArchitectHarnessRules() {
 - 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 accepted code commits.
-- Outside Debug Mode, do not implement production code.
+- 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, writing baseline unit tests for changed code and running targeted L1/L2 checks to verify the fix are part of the implementation duty; tester still owns final validation.
+- 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
@@ -69,13 +69,14 @@ 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 fix stays within the accepted task scope, addresses the confirmed root cause, adds no new module, and adds no new public or cross-file callable surface.
+- 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 temporary diagnostics before completion.
-- If the fix exceeds those limits, return a normal architecture plan with root cause, evidence, and affected scope.
+- 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 Mode fix, report to project-manager so PM can route tester for independent final validation before the Debug branch continues.
@@ -84,37 +85,73 @@ export function renderArchitectHarnessRules() {
 
 ### 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\`:
 
-Write \`.ai/vcm/handoffs/architecture-diagnosis.md\` for every Architecture Diagnosis Mode run before reporting back to project-manager. This file is the current diagnosis, not a log; replace stale content instead of appending history.
+| Symbol | File | Called By | Calls | State Read/Written | Side Effects | Status |
+|---|---|---|---|---|---|---|
 
-The diagnosis file must identify:
+\`Status\` must be \`read\`, \`external-boundary\`, or \`generated-boundary\`.
 
-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.
+The code-reading phase is complete only when:
 
-Do not propose a code-level patch until the architecture diagnosis is complete.
+- 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
 

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

@@ -43,13 +43,15 @@ If a reusable harness problem is suspected, it is enough to record a concise fee
 
 - 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 work is a branch inside the code-change flow: \`project-manager -> architect Debug Mode -> tester -> architect docs sync when needed -> 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\`.
-- Architecture Diagnosis is a PM-triggered branch inside code/debug work: \`project-manager -> architect Architecture Diagnosis Mode -> project-manager route decision\`.
 - Gate Review is PM-triggered at its defined trigger points; the tool decides whether review is enabled or required.
-- Final acceptance closes only the complete code-change flow, including a completed Debug branch.
-- PR preparation starts only after the active delivery flow completes; code-change flow also requires final acceptance to pass.
+- 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/\`.
@@ -75,8 +77,8 @@ If a reusable harness problem is suspected, it is enough to record a concise fee
 
 - 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 diagnostic L2 may run in Coder when explicitly assigned or in Architect Debug Mode; Tester owns full and final L2 validation.
-- L3 smoke E2E checks (default runner: tester): core user journeys or critical browser/API flows.
+- 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

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

@@ -46,11 +46,18 @@ commit range named in the VCM prompt.
 Use the code source named in the VCM prompt. For \`coder\`, compare the commits
 against the approved architecture plan and coder completion evidence. For
 \`architect-debug\`, compare the commits against the current Architect route
-command. Apply project coding standards in both cases. Do not expand review to
-the whole task, whole branch, or PR.
-
-Check that the commits match their source evidence, have no unapproved
-surface/dependency/docs changes, no \`VCM:CODE\`, no task-process comments or task
+command. For \`architect-diagnosis\`, compare the commits against
+\`.ai/vcm/handoffs/architecture-diagnosis.md\`. Apply project coding standards
+in all cases. Do not expand review to the whole task, whole branch, or PR.
+
+For \`architect-diagnosis\`, verify that the commits implement the diagnosed
+ownership, data flow, lifecycle, boundaries, invariants, and failure model.
+Request changes when the implementation leaves the diagnosed architecture
+problem in place, contradicts the required architecture direction, or only
+adds a local workaround for the surface failure.
+
+Check that the commits match their source evidence, account for
+surface/dependency/docs changes, have no \`VCM:CODE\`, no task-process comments or task
 labels, no weakened tests or bypassed real behavior, and no unhandled fallible
 paths.
 
@@ -160,7 +167,7 @@ Use this skill at every project-manager Gate Review trigger point and whenever V
 
 - \`architecture-plan\`: after architect writes \`.ai/vcm/handoffs/architecture-plan.md\`, before coder dispatch.
 - \`validation-adequacy\`: after tester writes \`.ai/vcm/handoffs/test-report.md\`, before docs sync, final acceptance, or validation-only completion.
-- \`code-diff\`: after Coder returns \`Decision: ready_for_review\`, or after Architect Debug Mode completes a code fix, before PM routes to the next role or flow gate. Identify the source with \`--source coder\` or \`--source architect-debug\`.
+- \`code-diff\`: after Coder returns \`Decision: ready_for_review\`, Architect Debug Mode completes a code fix, or Architecture Diagnosis Mode completes a code fix, before PM routes to Tester. Identify the source with \`--source coder\`, \`--source architect-debug\`, or \`--source architect-diagnosis\`.
 
 ## Request
 
@@ -168,7 +175,7 @@ Run this unconditionally at each trigger point (do not first check whether Gate
 
 \`\`\`sh
 .ai/tools/request-gate-review --gate <architecture-plan|validation-adequacy>
-.ai/tools/request-gate-review --gate code-diff --source <coder|architect-debug>
+.ai/tools/request-gate-review --gate code-diff --source <coder|architect-debug|architect-diagnosis>
 \`\`\`
 
 Interpret the first output line:
@@ -206,7 +213,7 @@ from pathlib import Path
 
 
 GATES = ("architecture-plan", "validation-adequacy", "code-diff")
-CODE_DIFF_SOURCES = ("coder", "architect-debug")
+CODE_DIFF_SOURCES = ("coder", "architect-debug", "architect-diagnosis")
 REPORTS = {
     "architecture-plan": ".ai/vcm/gate-reviews/architecture-plan-review.md",
     "validation-adequacy": ".ai/vcm/gate-reviews/validation-adequacy-review.md",
@@ -226,6 +233,7 @@ CODE_DIFF_SOURCE_ARTIFACTS = {
         ".ai/vcm/handoffs/coder-completion.md",
     ],
     "architect-debug": [".ai/vcm/handoffs/role-commands/architect.md"],
+    "architect-diagnosis": [".ai/vcm/handoffs/architecture-diagnosis.md"],
 }
 CORE_INPUT_ARTIFACTS = {
     "architecture-plan": ".ai/vcm/handoffs/architecture-plan.md",
@@ -621,7 +629,7 @@ def main() -> int:
     args = parser.parse_args()
 
     if args.gate == "code-diff" and not args.source:
-        print_result("failed_to_start", gate=args.gate, reason="code-diff requires --source coder or --source architect-debug")
+        print_result("failed_to_start", gate=args.gate, reason="code-diff requires --source coder, --source architect-debug, or --source architect-diagnosis")
         return 2
     if args.gate != "code-diff" and args.source:
         print_result("failed_to_start", gate=args.gate, reason="--source is valid only for code-diff")

package/dist/backend/templates/harness/project-coding-standards.js

@@ -5,19 +5,19 @@ Project-specific rules may be added outside the VCM managed block when they make
 ## Applies To
 
 - Coder and Coder Worker implementation.
-- Architect Debug Mode when it edits production code or tests.
+- Architect Debug Mode and Architecture Diagnosis Mode when they edit production code or tests.
 - Tester changes to tests, fixtures, and test-only helpers, plus test-integrity review.
 
 ## Implementation Discipline
 
-- Follow the accepted task scope, role message, architecture plan, and scaffold when present.
-- Do not change file responsibilities, callable-surface signatures, visibility, exports, contracts, or architect-defined intent unless the approved plan allows it.
+- Coder and Coder Worker follow the accepted task scope, role message, architecture plan, and scaffold. Architect Debug Mode and Architecture Diagnosis Mode follow their confirmed root cause and PM-routed evidence.
+- Coder and Coder Worker must not change file responsibilities, callable-surface signatures, visibility, exports, contracts, or architect-defined intent unless the approved plan allows it. In Debug Mode or Architecture Diagnosis Mode, Architect may change file responsibilities and callable surfaces after confirming the root cause, and must update affected callers, contracts, and tests.
 - Complete assigned \`VCM:CODE\` placeholders and remove them 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 approved plan explicitly changes it.
+- Coder and Coder Worker keep the diff inside the approved plan. In Debug Mode or Architecture Diagnosis Mode, Architect owns the technical change boundary after confirming the root cause.
+- Preserve existing behavior unless the approved plan or a confirmed Debug/Diagnosis root cause changes it.
 
 ## Comments
 

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

@@ -33,12 +33,15 @@ PM Managed Mode applies only when the user explicitly asks to complete the curre
 PM owns task flow selection. Every user request that asks VCM to perform delivery work must enter one of these flows or branches:
 
 - Code-change flow: PM -> Architect -> Coder -> Tester -> Architect docs sync -> Final Acceptance.
-- Debug branch inside code-change flow: PM -> Architect Debug Mode -> Tester -> Architect docs sync when needed -> Final Acceptance.
+- Primary Debug/Diagnosis code-delivery flow: PM -> Architect Debug Mode or Architecture Diagnosis Mode -> code-diff Gate Review -> Tester -> Architect docs sync -> Final Acceptance.
+- Debug/Diagnosis branch inside an active main flow: suspend the main flow -> Architect Debug Mode or Architecture Diagnosis Mode -> code-diff Gate Review -> Tester -> restore the recorded main-flow resume point.
 - Docs-only flow: PM -> Architect -> PM completes the flow from Architect's result.
 - Validation-only flow: PM -> Tester -> PM completes the flow from Tester's result.
-- PR-prep flow: PM prepares or updates a PR only after the active delivery flow completes; code-change flow also requires Final Acceptance to pass.
+- PR-prep flow: PM prepares or updates a PR only after the active delivery flow completes; every complete code-delivery flow requires Final Acceptance to pass.
 - Communication-only flow: PM answers status questions, summarizes existing role results, or relays user clarification to the active role. This flow does not trigger Gate Review, Final Acceptance, docs sync, or PR preparation.
 
+- Determine Debug/Diagnosis context from the current task flow, not from who requested the mode. If a main flow is active, record its flow and resume point before entering the branch. If no main flow is suspended, Debug/Diagnosis is the task's primary flow.
+- A primary Architecture Diagnosis flow that produces analysis only completes from the diagnosis result. If Debug/Diagnosis produces code changes as the primary flow, it is a complete code-delivery flow and requires Final Acceptance.
 - Do not skip a flow step because the task looks small. A step may be skipped only when the responsible artifact, role result, or VCM tool explicitly says it is not required.
 - A branch flow must return to one of these flows, repeat the current responsible role, or pause for user decision.
 
@@ -70,38 +73,40 @@ PM handles branch flows by classifying the latest role result, tool result, or u
 
 Every branch must end in exactly one of these outcomes:
 
-- return to the current main flow
+- return to the recorded main-flow resume point
 - repeat the current responsible role
 - route to Architect Debug Mode
 - route to Architecture Diagnosis Mode
 - pause for user decision
-- proceed to Final Acceptance when closing the complete code-change flow
-- complete the active docs-only or validation-only flow from its required role result
 
 ### Debug Routing
 
 - Route bugs, failing checks, build/runtime errors, unclear defects, and tester failure evidence to architect Debug Mode.
 - Do not diagnose root cause or judge fix size; provide symptom, reproduction steps, failing command or log, expected vs actual behavior, task/worktree, and user constraints.
-- If architect completes a Debug Mode fix, route to tester for independent final validation before the Debug branch continues.
-- If architect reports that the fix cannot be completed in Debug Mode because it falls outside accepted task scope, lacks a confirmed root cause, or requires new module, new public surface, or new cross-file callable surface, resume the normal code-change flow: architect plan -> coder -> tester.
-- After Tester completes the Debug branch, request Architect docs sync only when architecture, public-contract, durable-doc, or known-issues impact exists, then proceed to Final Acceptance.
+- Preserve whether Debug Mode is the primary flow or a branch. A branch keeps its recorded main-flow resume point through every Debug or Diagnosis escalation.
+- If architect completes a Debug Mode fix, run \`code-diff --source architect-debug\`, then route to tester for independent validation.
+- If architect reports that the fix requires a new module or new external public surface, resume the normal code-change flow: architect plan -> coder -> tester.
+- After Tester passes a Debug branch, return to the recorded main-flow resume point. Do not run Final Acceptance from the branch.
+- After Tester passes a primary Debug code-delivery flow, request Architect docs sync and proceed to that flow's Final Acceptance.
 
 ### Architecture Diagnosis Routing
 
-Within the same task, route to architect Architecture Diagnosis Mode when either condition is true:
+Route to architect Architecture Diagnosis Mode when it is selected as the task's primary flow or when either branch condition is true:
 
-- Tester reports \`Test Result: fail\` for the implementation for the second time.
+- Tester reports \`Test Result: fail\` for an Architect Debug Mode fix whose final disposition was \`local fix completed\`.
 - Architect reports that the architecture plan must be updated or replaced for the second time.
 
-PM counts these events within the current task from Architect reports and Tester test results.
+PM counts architecture plan update or replacement reports within the current task.
 
-Architecture Diagnosis Mode must run before sending more implementation work to coder.
+Architecture Diagnosis Mode must run before another Debug Mode fix or Coder dispatch.
 
-After Architecture Diagnosis Mode:
-
-- If architect reports no architecture change is needed, continue the existing Debug Mode or Replan flow.
-- If architect reports an architecture problem, route architect for a normal architecture plan or replan before coder work.
-- If the implementation produced from that diagnosis still fails Tester validation with blocking issues, pause the workflow and report to the user.
+- Preserve the current flow context when entering Architecture Diagnosis Mode. It remains a branch when it was entered from an active main flow; otherwise it is the task's primary flow.
+- Architect owns diagnosis, implementation, diagnostic validation, and commit completion in this mode. Do not route the implementation to Coder or back to ordinary Debug Mode.
+- When Architect completes code changes, run \`code-diff --source architect-diagnosis\`, then route to Tester.
+- If a Diagnosis branch produces analysis only, return to the recorded main-flow resume point. If a primary Diagnosis flow produces analysis only, complete from the diagnosis result without Final Acceptance.
+- After Tester passes a Diagnosis branch, return to the recorded main-flow resume point. Do not run Final Acceptance from the branch.
+- After Tester passes a primary Diagnosis code-delivery flow, request Architect docs sync and proceed to that flow's Final Acceptance.
+- If the implementation produced from that diagnosis receives \`Test Result: fail\` from Tester, pause the workflow and report to the user.
 
 PM should summarize:
 
@@ -152,17 +157,18 @@ When Architect, Coder, or Tester reports a confirmed direct user message:
 ### Flow Gates
 
 - In normal code-change flow, track the architecture plan, test report, docs-sync report, required Gate Review results, known-issues disposition when present, and final acceptance report.
-- In a Debug branch, track the Architect result, test report, required Gate Review results, docs-sync report when required, and final acceptance report.
+- In a Debug or Architecture Diagnosis branch, track the parent flow, resume point, Architect result, test report, and required Gate Review results. Do not require a branch-level final acceptance report.
+- In a primary Debug or Architecture Diagnosis code-delivery flow, track the Architect result, test report, required Gate Review results, docs-sync report, and final acceptance report.
 - In docs-only flow, complete from Architect's role result. In validation-only flow, complete from Tester's test report.
 - Advance to the next gate only when the required role artifact/result is complete and PM routing rules allow that gate.
 - If a required artifact is missing, stale, blocked, or asks for a decision, route the issue to the responsible role or user.
-- In normal code-change flow, request Architect post-validation docs sync after Tester completes. In Debug flow, request it only when architecture, public-contract, durable-doc, or known-issues impact exists.
+- In normal and primary Debug/Diagnosis code-delivery flows, request Architect post-validation docs sync after Tester completes. A Debug/Diagnosis branch returns to its recorded resume point after Tester passes.
 
 ### Gate Review Gates
 
 - Gate Review requests are mandatory and unconditional. At every trigger point, use the \`vcm-gate-review\` skill to run \`.ai/tools/request-gate-review\` with the matching gate and code source arguments without first judging whether Gate Review is enabled. The tool (via VCM) is the single source of truth for enable state; never skip the run because you assume Gate Review is off or because the worktree has no gate-review index yet.
 - The tool's first output line decides the next step: \`disabled\`, \`not_required\`, or \`already_approved\` continue the normal VCM flow; \`started\` or \`running\` stop the turn and wait for the VCM callback; \`failed_to_start\` is a hard stop — report it to the user and do not silently proceed past the gate.
-- Trigger points (run each unconditionally): before coder dispatch run \`architecture-plan\`; before docs sync, final acceptance, or validation-only completion run \`validation-adequacy\`; after any Coder \`Decision: ready_for_review\` result run \`code-diff --source coder\` before routing to Tester; after any Architect Debug Mode completed code fix run \`code-diff --source architect-debug\` before routing to Tester.
+- Trigger points (run each unconditionally): before coder dispatch run \`architecture-plan\`; before docs sync, final acceptance, or validation-only completion run \`validation-adequacy\`; after any Coder \`Decision: ready_for_review\` result run \`code-diff --source coder\`; after any Architect Debug Mode completed code fix run \`code-diff --source architect-debug\`; after any Architecture Diagnosis Mode completed code fix run \`code-diff --source architect-diagnosis\`. Run code-diff before routing to Tester.
 - PM does not inspect commits or decide whether code changes exist. At a \`code-diff\` trigger point, run the tool; the tool decides \`disabled\`, \`not_required\`, \`already_approved\`, or starts review.
 - Do not run \`code-diff\` for incomplete, failed, planning-only, docs-only, test-only, PR-only, or Communication-only flow.
 - Gate Review trigger points apply only when the active delivery flow reaches that milestone. Do not run Gate Review for Communication-only flow.
@@ -180,16 +186,16 @@ When Architect, Coder, or Tester reports a confirmed direct user message:
 
 ### Final Acceptance
 
-- Use the \`vcm-final-acceptance\` skill only to close the complete code-change flow, including a completed Debug branch.
-- Do not run Final Acceptance for docs-only, validation-only, Communication-only, PR-prep, or an unfinished Debug, Replan, or Architecture Diagnosis branch.
+- Use the \`vcm-final-acceptance\` skill only to close a complete code-delivery flow, including a primary Debug or Architecture Diagnosis flow that produced code changes.
+- Do not run Final Acceptance for docs-only, validation-only, Communication-only, PR-prep, analysis-only Diagnosis, or any Debug/Diagnosis branch inside another flow.
 - Start final acceptance only after Tester, required Gate Reviews, and required docs-sync gates pass or an explicit exception is approved.
-- Confirm applicable evidence exists: architecture plan when required, test result, required Gate Review decisions, docs-sync decision when required, unresolved risks, known-issues disposition, and cleanup status.
+- Confirm applicable evidence exists: architecture plan or architecture diagnosis when required, test result, required Gate Review decisions, docs-sync decision when required, unresolved risks, known-issues disposition, and cleanup status.
 - Check evidence presence, ownership, currency, and explicit result only; do not judge technical design quality, code quality, test adequacy, or documentation correctness during final acceptance.
 - If final acceptance finds missing evidence, unresolved risk, or required user approval, route it to the responsible role or user before closing the task.
 
 ### PR Preparation
 
-- Prepare or update a GitHub PR only after the active delivery flow completes. For code-change flow, Final Acceptance must pass first.
+- Prepare or update a GitHub PR only after the active delivery flow completes. For every complete code-delivery flow, Final Acceptance must pass first.
 - Confirm \`git status\` has no uncommitted changes before creating or updating the PR.
 - Use \`.github/pull_request_template.md\` when present.
 - Fill only the checklist items applicable to the completed delivery flow.

package/dist/backend/templates/harness/vcm-final-acceptance-skill.js

@@ -1,9 +1,9 @@
 export function renderVcmFinalAcceptanceSkillRules() {
     return `## Purpose
 
-Use this skill only when project-manager is ready to close a complete VCM code-change flow, including a completed Debug branch.
+Use this skill only when project-manager is ready to close a complete VCM code-delivery flow, including a primary Debug or Architecture Diagnosis flow that produced code changes.
 
-Do not use it for docs-only, validation-only, Communication-only, or PR-prep flow, or for an unfinished Debug, Replan, or Architecture Diagnosis branch.
+Do not use it for docs-only, validation-only, Communication-only, PR-prep, analysis-only Diagnosis, or any Debug/Diagnosis branch inside another flow.
 
 This skill is a final evidence audit. It does not replace architect docs sync, tester validation acceptance, coder implementation responsibility, or user approval for high-risk decisions.
 
@@ -15,6 +15,7 @@ Read the relevant task evidence before deciding:
 
 - original user request, PM route message, or durable plan when present
 - \`.ai/vcm/handoffs/architecture-plan.md\` when the task required architect planning
+- \`.ai/vcm/handoffs/architecture-diagnosis.md\` when the flow used Architecture Diagnosis Mode
 - \`.ai/vcm/handoffs/test-report.md\` when tester validation was required
 - \`.ai/vcm/handoffs/docs-sync-report.md\` when durable docs could be affected
 - \`.ai/vcm/handoffs/known-issues.md\` when unresolved findings were recorded
@@ -28,7 +29,7 @@ Check whether the required role evidence exists, is current, and gives a clear r
 
 Acceptable evidence must show:
 
-- architect plan or docs-sync decision when architecture, public contracts, durable docs, or known issues changed
+- architect plan, architecture diagnosis, or docs-sync decision when required by the completed flow
 - tester \`Test Result: pass|fail\` and validation evidence when code, behavior, tests, or generated context changed
 - required Gate Review decisions, skip reasons, or override reasons when Gate Reviews were enabled
 - known-issues disposition when unresolved findings were recorded
@@ -40,7 +41,7 @@ Do not claim to prove that every diff hunk exactly matches the task.
 
 Review the changed file list only, then classify files:
 
-- expected files: directly named by the user request, route message, durable plan, or architecture plan
+- expected files: directly named by the user request, route message, durable plan, architecture plan, or architecture diagnosis
 - supporting files: tests, fixtures, generated context, docs, or wiring needed for expected files
 - approved deviations: files explained by Replan, tester follow-up, docs-sync, or explicit user / project-manager approval
 - unexplained files: files with no traceable reason in the task evidence
@@ -56,7 +57,7 @@ Check:
 
 - required route was followed, or an explicit exception is recorded
 - required handoff artifacts exist and are current
-- architecture plan completion, Replan, or architect follow-up decision is recorded when architecture planning was required
+- architecture plan, Architecture Diagnosis, Replan, or architect follow-up completion is recorded when required by the flow
 - tester report records \`Test Result: pass|fail\`, validation commands, results, and skipped checks with reasons
 - required Gate Reviews are approved, skipped with a recorded reason, or overridden with a recorded reason
 - Gate Review enable state is confirmed authoritatively: do not infer that no Gate Reviews were required from an absent or empty \`.ai/vcm/gate-reviews/index.json\`. When Gate Review is enabled, a missing index or a required gate without a recorded decision means the gate was skipped — run the matching command from the \`vcm-gate-review\` skill, including the code source for \`code-diff\`, and do not accept until each required gate returns \`approve\`/\`already_approved\`, \`disabled\`/\`not_required\`, or a recorded skip/override

package/dist/shared/types/gate-review.js

@@ -5,5 +5,6 @@ export const GATE_REVIEW_GATES = [
 ];
 export const CODE_DIFF_SOURCES = [
     "coder",
-    "architect-debug"
+    "architect-debug",
+    "architect-diagnosis"
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.6.21",
+  "version": "0.6.22",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [