vibe-coding-master 0.6.21 → 0.6.23

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

@@ -97,6 +97,28 @@ export function createClaudeHookService(deps) {
             transcriptPath: stringOrUndefined(input.event.transcript_path),
             cwd: stringOrUndefined(input.event.cwd) ?? stringOrUndefined(input.event.new_cwd)
         });
+        const activeTask = deps.autoMemoryService
+            ? (await deps.taskService.listTasks(context.project.repoRoot))
+                .find((task) => task.cleanupStatus !== "cleaned")
+            : undefined;
+        const memoryHandled = activeTask
+            ? await deps.autoMemoryService?.handleHarnessEngineerHook({
+                baseRepoRoot: context.project.repoRoot,
+                taskRepoRoot: getTaskRuntimeRepoRoot(activeTask),
+                taskSlug: activeTask.taskSlug,
+                eventName
+            })
+            : false;
+        if (memoryHandled) {
+            return {
+                ok: true,
+                eventName,
+                taskSlug: activeTask?.taskSlug ?? input.taskSlug,
+                role: input.role,
+                sessionUpdated: Boolean(session),
+                dispatchedCount: 0
+            };
+        }
         await deps.harnessService?.recordHarnessBootstrapHook(context.project.repoRoot, {
             eventName,
             sessionId: session?.id,
@@ -131,6 +153,10 @@ export function createClaudeHookService(deps) {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
+        const memoryResult = await processAutoMemoryRoleHook(input, context, eventName);
+        if (memoryResult) {
+            return memoryResult;
+        }
         const boundToTask = await isHookSessionBoundToTask(context, input.role);
         if (boundToTask) {
             deps.jobGuard?.notePromptSubmitted({
@@ -194,6 +220,10 @@ export function createClaudeHookService(deps) {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
+        const memoryResult = await processAutoMemoryRoleHook(input, context, eventName);
+        if (memoryResult) {
+            return memoryResult;
+        }
         await clearStopFailureRecoveryState(context, input.role);
         if (options.allowBlock && deps.jobGuard) {
             const verdict = await deps.jobGuard.evaluateStop({
@@ -228,6 +258,10 @@ export function createClaudeHookService(deps) {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
+        const memoryResult = await processAutoMemoryRoleHook(input, context, eventName);
+        if (memoryResult) {
+            return memoryResult;
+        }
         const routeDispatchInput = createRouteDispatchInput(input, context);
         const pending = await deps.messageService.listPendingRouteFiles(routeDispatchInput);
         const hasCompletionEvidence = pending.some((routeFile) => routeFile.fromRole === input.role);
@@ -284,6 +318,10 @@ export function createClaudeHookService(deps) {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
+        const memoryResult = await processAutoMemoryRoleHook(input, context, eventName);
+        if (memoryResult) {
+            return memoryResult;
+        }
         const session = await deps.sessionService.recordClaudeHookEvent(context.project.repoRoot, {
             taskSlug: context.taskSlug,
             role: input.role,
@@ -380,6 +418,34 @@ export function createClaudeHookService(deps) {
             dispatchedCount: dispatched.filter((result) => result.delivered).length
         };
     }
+    async function processAutoMemoryRoleHook(input, context, eventName) {
+        if (!deps.autoMemoryService || !(await deps.autoMemoryService.isRoleMemoryTurn(context.taskRepoRoot, input.role))) {
+            return undefined;
+        }
+        const session = await deps.sessionService.recordClaudeHookEvent(context.project.repoRoot, {
+            taskSlug: context.taskSlug,
+            role: input.role,
+            eventName,
+            claudeSessionId: stringOrUndefined(input.event.session_id),
+            transcriptPath: stringOrUndefined(input.event.transcript_path),
+            cwd: stringOrUndefined(input.event.cwd) ?? stringOrUndefined(input.event.new_cwd)
+        });
+        await deps.autoMemoryService.handleRoleHook({
+            baseRepoRoot: context.project.repoRoot,
+            taskRepoRoot: context.taskRepoRoot,
+            taskSlug: context.taskSlug,
+            role: input.role,
+            eventName
+        });
+        return {
+            ok: true,
+            eventName,
+            taskSlug: context.taskSlug,
+            role: input.role,
+            sessionUpdated: Boolean(session),
+            dispatchedCount: 0
+        };
+    }
     function createRouteDispatchInput(input, context, stoppedRole) {
         return {
             repoRoot: context.project.repoRoot,

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/services/runtime-coordinator-service.js

@@ -55,8 +55,12 @@ export function createRuntimeCoordinatorService(deps) {
                 else {
                     await deps.translationService.stopTask(taskRepoRoot, activeTask.taskSlug).catch(() => undefined);
                 }
+                await reconcileAutoMemory(repoRoot, activeTask);
                 if (preferences.autoTaskHarnessReviewEnabled) {
-                    await maybeStartTaskHarnessRetrospective(repoRoot, activeTask);
+                    const memoryReadiness = await getTaskRetrospectiveMemoryReadiness(repoRoot, activeTask);
+                    if (memoryReadiness.ready) {
+                        await maybeStartTaskHarnessRetrospective(repoRoot, activeTask);
+                    }
                 }
                 return { activeTask, gatewayStatus };
             });
@@ -159,4 +163,33 @@ export function createRuntimeCoordinatorService(deps) {
             throw error;
         }
     }
+    async function reconcileAutoMemory(repoRoot, task) {
+        const stateRoot = await deps.getStateRoot(repoRoot);
+        const taskRepoRoot = getTaskRuntimeRepoRoot(task);
+        const roundState = await deps.roundService.getSessionRoundState({
+            repoRoot,
+            stateRepoRoot: taskRepoRoot,
+            stateRoot,
+            taskSlug: task.taskSlug
+        });
+        return deps.autoMemoryService.reconcileTask({
+            baseRepoRoot: repoRoot,
+            taskRepoRoot,
+            taskSlug: task.taskSlug,
+            handoffDir: task.handoffDir,
+            roundReady: roundState.status === "stopped"
+                && Boolean(roundState.roundId)
+                && roundState.roleRecovery?.status !== "failed"
+        });
+    }
+    async function getTaskRetrospectiveMemoryReadiness(repoRoot, task) {
+        const taskRepoRoot = getTaskRuntimeRepoRoot(task);
+        return deps.autoMemoryService.getTaskRetrospectiveReadiness({
+            baseRepoRoot: repoRoot,
+            taskRepoRoot,
+            taskSlug: task.taskSlug,
+            handoffDir: task.handoffDir,
+            roundReady: true
+        });
+    }
 }

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

@@ -3,6 +3,7 @@ import { VCM_ROLE_NAMES, isDispatchableRole } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
+import { ensureTaskMemorySnapshot } from "./auto-memory-service.js";
 import { claudeTranscriptPath } from "./claude-transcript-service.js";
 import { readHarnessRevisionState } from "./harness-revision.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
@@ -49,6 +50,7 @@ export function createSessionService(deps) {
         const config = await deps.projectService.loadConfig(repoRoot);
         const task = await deps.taskService.loadTask(repoRoot, taskSlug);
         const taskRepoRoot = getTaskRuntimeRepoRoot(task);
+        await ensureTaskMemorySnapshot(deps.fs, repoRoot, taskRepoRoot);
         const paths = deps.artifactService.getHandoffPaths(taskRepoRoot, task.handoffDir);
         const persisted = await loadPersistedRoleRecordForRole(deps.fs, repoRoot, taskRepoRoot, config.stateRoot, taskSlug, role);
         const permissionMode = normalizeClaudePermissionMode(input.permissionMode ?? persisted?.permissionMode);
@@ -235,6 +237,7 @@ export function createSessionService(deps) {
     }
     async function launchProjectHarnessEngineerSession(repoRoot, input, launchMode) {
         const taskContext = await resolveProjectToolTaskContext(repoRoot, input, "Harness Engineer");
+        await ensureTaskMemorySnapshot(deps.fs, repoRoot, taskContext.taskRepoRoot);
         const live = toRoleSessionRecordView(getRegisteredProjectHarnessEngineerSession(deps.registry, deps.runtime), deps.runtime);
         if (live && live.status === "running") {
             return withHarnessRevisionView(repoRoot, await migrateRunningProjectToolSessionCwd(repoRoot, live, taskContext.taskRepoRoot));

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

@@ -1,7 +1,10 @@
+import { renderRoleMemoryRules } from "./role-memory.js";
 export function renderArchitectHarnessRules() {
     return `
 ## VCM Architect Rules
 
+${renderRoleMemoryRules("architect")}
+
 ### Role Scope
 
 - 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.
@@ -9,10 +12,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 +72,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 +88,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.
+
+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.
+
+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.
+
+Before choosing or implementing a fix:
+
+- 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.
+
+Maintain a \`Code Reading Closure\` in \`.ai/vcm/handoffs/architecture-diagnosis.md\`:
+
+| Symbol | File | Called By | Calls | State Read/Written | Side Effects | Status |
+|---|---|---|---|---|---|---|
+
+\`Status\` must be \`read\`, \`external-boundary\`, or \`generated-boundary\`.
+
+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
 
-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 the root cause or choose a fix before the Code Reading Closure is complete.
 
-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.
+After completing the code-reading closure, reconstruct and analyze:
 
-Analyze the problem from these angles:
+- **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.
 
-- **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.
+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 that must be proven. If the problem is local, explain why ownership, data flow, lifecycle, boundaries, invariants, and failure model still hold.
+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.
 
-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.
+Small diff, minimum change, localized fix, or preserving the current implementation shape are not Architecture Diagnosis decision criteria.
 
-The diagnosis file must identify:
+\`.ai/vcm/handoffs/architecture-diagnosis.md\` must contain:
 
-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.
+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\`
 
-Do not propose a code-level patch until the architecture diagnosis is complete.
+- 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

@@ -1,5 +1,7 @@
 export function renderRootClaudeHarnessRules() {
-    return `## VCM Start Here
+    return `@.ai/vcm/memory/shared.md
+
+## VCM Start Here
 
 - Use the durable project docs below as role-relevant project truth.
 - Read module-local \`CLAUDE.md\` before editing a subdirectory if one exists.
@@ -43,13 +45,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 +79,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/coder-agent.js

@@ -1,7 +1,10 @@
+import { renderRoleMemoryRules } from "./role-memory.js";
 export function renderCoderHarnessRules() {
     return `
 ## VCM Coder Rules
 
+${renderRoleMemoryRules("coder")}
+
 ### Role Scope
 
 - Own function-level implementation and baseline implementation tests inside the approved task scope, role message, and architecture plan.

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

@@ -1,8 +1,11 @@
+import { renderRoleMemoryRules } from "./role-memory.js";
 export function renderGateReviewerAgentRules() {
     return `## Role
 
 You are VCM \`gate-reviewer\`.
 
+${renderRoleMemoryRules("gate-reviewer")}
+
 Review only the gate in the VCM prompt. Use the task and worktree paths named there. Project memory may orient you, but only current worktree evidence can decide the gate.
 
 Use only these decisions:
@@ -46,11 +49,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 +170,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 +178,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 +216,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 +236,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 +632,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/harness-engineer-agent.js

@@ -1,3 +1,4 @@
+import { renderRoleMemoryRules } from "./role-memory.js";
 export function renderHarnessEngineerHarnessRules() {
     return `## Role
 
@@ -7,6 +8,8 @@ Maintain and improve this repository's VCM harness. Understand both VCM fixed
 harness rules and project-specific harness customization before proposing any
 change.
 
+${renderRoleMemoryRules("harness-engineer")}
+
 ## Scope
 
 You may inspect:
@@ -22,7 +25,8 @@ You may inspect:
   \`docs/known-issues.md\`
 - task evidence such as handoffs, route messages, commits, commit diffs,
   generated context, validation reports, Gate Review reports, final acceptance
-  artifacts, and user corrections
+  artifacts, memory drafts and diffs under .ai/vcm/memory-review, current memory
+  under .ai/vcm/memory, and user corrections
 
 You are not part of the task workflow round state.
 
@@ -33,18 +37,21 @@ You are not part of the task workflow round state.
 - Bootstrap Apply Mode: when VCM explicitly asks for bootstrap apply work, make
   permitted bootstrap edits directly in the active task worktree and commit them
   yourself.
-- Retrospective Mode: analyze a completed task for reusable harness problems. Do
-  not edit files.
+- Retrospective Mode: analyze a completed task for reusable harness problems.
+  Do not edit harness files; proven repeated findings may update VCM memory.
+- Memory Review Mode: review role memory drafts or proven retrospective memory
+  findings and write only the memory files assigned by VCM.
 - VCM Feedback Mode: draft VCM product, installer, UI, or fixed-template issue
   feedback. Do not submit without explicit in-session user authorization.
 
 ## Change Policy
 
-- Apply edits only in Bootstrap Apply Mode or when VCM explicitly asks you to
-  apply an approved harness change.
+- Apply edits only in Bootstrap Apply Mode, Memory Review Mode, or when VCM
+  explicitly asks you to apply an approved harness change.
 - When applying edits, work only in the active task worktree named by VCM. Do not
   edit the base repository root unless VCM explicitly says so.
-- In Proposal Mode and Retrospective Mode, do not edit files.
+- In Proposal Mode, do not edit files. In Retrospective Mode, do not edit
+  harness files; only the memory exception above may write files.
 - Commit every applied harness change yourself before ending your turn.
 - Do not overwrite VCM fixed managed blocks.
 - Keep project-specific customization outside VCM managed blocks.
@@ -54,6 +61,22 @@ You are not part of the task workflow round state.
   validation recommendations with every proposal.
 - Do not edit production source code as part of harness maintenance.
 
+## Memory Management
+
+- Own VCM-managed project memory under \`.ai/vcm/memory/**\`.
+- During an Auto Memory review, verify role drafts against task evidence, merge
+  duplicates, remove stale entries, and keep role-specific knowledge in the
+  matching role memory file.
+- Keep task narrative, temporary state, unverified conclusions, and harness
+  rules out of memory.
+- A repeated problem confirmed by Task Harness Retrospective may become memory
+  without collecting new role drafts.
+- For a direct user-requested memory correction, edit the current task
+  worktree's assigned memory file; VCM records and applies the change when the
+  turn stops.
+- When VCM assigns review output paths, edit only those paths. VCM applies the
+  reviewed memory and records the diff.
+
 ## Task Harness Retrospective
 
 After a complete code-change flow passes Final Acceptance, you may be asked to
@@ -67,7 +90,8 @@ complete correctly.
 Inspect the active task worktree as needed. Useful evidence may include
 handoffs, route messages, commits, commit diffs, durable docs, generated
 context, validation reports, Gate Review reports, final acceptance artifacts,
-and user corrections during the task.
+memory drafts, applied memory diffs, current memory, and user corrections during
+the task.
 
 For each finding, decide whether it is:
 
@@ -79,7 +103,7 @@ Do not create new rules from weak evidence, one-off execution mistakes, or role
 behavior that existing harness rules already cover. If no reusable harness
 problem is proven, say so clearly.
 
-Do not edit files during retrospective analysis. Write a concise analysis with:
+Do not edit harness files during retrospective analysis. Write a concise analysis with:
 
 - finding
 - evidence

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