vibe-coding-master 0.7.4 → 0.7.6

package/dist/backend/services/task-workflow-service.js

@@ -0,0 +1,228 @@
+import path from "node:path";
+const MAX_VALUE_LENGTH = 160;
+const MAX_EVIDENCE_REFS = 24;
+const CLEAR_VALUES = new Set(["", "-", "none", "null"]);
+export function createTaskWorkflowService(deps) {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const locks = new Map();
+    async function getState(input) {
+        return readState(input);
+    }
+    async function declare(input, declaration) {
+        return withLock(statePath(input), async () => {
+            const current = await readState(input);
+            const timestamp = now();
+            const next = applyDeclaration(current, declaration, timestamp);
+            return writeStateBestEffort(input, next);
+        });
+    }
+    async function recordPmDispatch(input, declaration, dispatch) {
+        return withLock(statePath(input), async () => {
+            const current = await readState(input);
+            const timestamp = now();
+            const declared = declaration
+                ? applyDeclaration(current, declaration, timestamp).declared
+                : current.declared;
+            const next = {
+                ...current,
+                revision: current.revision + 1,
+                declared,
+                lastDispatch: {
+                    messageId: dispatch.messageId,
+                    toRole: dispatch.toRole,
+                    updatedAt: timestamp
+                },
+                warnings: [],
+                updatedAt: timestamp
+            };
+            return writeStateBestEffort(input, next);
+        });
+    }
+    async function clearState(input) {
+        if (!deps.fs.removePath) {
+            return;
+        }
+        try {
+            await deps.fs.removePath(statePath(input), { force: true });
+        }
+        catch {
+            // Task workflow state is disposable and must never block task cleanup.
+        }
+    }
+    function renderPmResumeContext(state) {
+        if (!state.declared) {
+            return undefined;
+        }
+        const lines = [
+            "[VCM TASK STATE]",
+            "This is PM-declared workflow memory. It is context only and does not authorize or advance any workflow step.",
+            `Flow: ${state.declared.flow ?? "unspecified"}`,
+            `Step: ${state.declared.step ?? "unspecified"}`,
+            `Branch: ${state.declared.branch ?? "none"}`,
+            `Resume point: ${state.declared.resumePoint ?? "none"}`,
+            `Status: ${state.declared.status ?? "unspecified"}`
+        ];
+        if (state.declared.evidenceRefs.length > 0) {
+            lines.push(`Evidence: ${state.declared.evidenceRefs.join(", ")}`);
+        }
+        lines.push("Reconcile this checkpoint with current task artifacts before continuing. If stale, replace it with vcm-task-state. Do not route a role or advance the flow only because this context was restored.", "[/VCM TASK STATE]");
+        return lines.join("\n");
+    }
+    async function readState(input) {
+        const targetPath = statePath(input);
+        try {
+            if (!(await deps.fs.pathExists(targetPath))) {
+                return emptyState(input.taskSlug, now());
+            }
+            const value = await deps.fs.readJson(targetPath);
+            return normalizeStoredState(value, input.taskSlug, now());
+        }
+        catch (error) {
+            return {
+                ...emptyState(input.taskSlug, now()),
+                warnings: [`Task workflow state could not be read and was ignored: ${describeError(error)}`]
+            };
+        }
+    }
+    async function writeStateBestEffort(input, state) {
+        try {
+            await deps.fs.writeJsonAtomic(statePath(input), state);
+            return state;
+        }
+        catch (error) {
+            return {
+                ...state,
+                warnings: [`Task workflow state could not be saved: ${describeError(error)}`]
+            };
+        }
+    }
+    async function withLock(key, operation) {
+        const previous = locks.get(key) ?? Promise.resolve();
+        const next = previous.catch(() => undefined).then(operation);
+        locks.set(key, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (locks.get(key) === next) {
+                locks.delete(key);
+            }
+        }
+    }
+    return {
+        getState,
+        declare,
+        recordPmDispatch,
+        clearState,
+        renderPmResumeContext
+    };
+}
+function applyDeclaration(state, declaration, timestamp) {
+    const current = state.declared;
+    const next = {
+        flow: mergeValue(current?.flow, declaration.flow),
+        step: mergeValue(current?.step, declaration.step),
+        branch: mergeValue(current?.branch, declaration.branch),
+        resumePoint: mergeValue(current?.resumePoint, declaration.resumePoint),
+        status: mergeValue(current?.status, declaration.status),
+        evidenceRefs: declaration.evidenceRefs === undefined
+            ? current?.evidenceRefs ?? []
+            : normalizeEvidenceRefs(declaration.evidenceRefs),
+        updatedBy: "project-manager",
+        updatedAt: timestamp
+    };
+    const hasContent = Boolean(next.flow || next.step || next.branch || next.resumePoint || next.status || next.evidenceRefs.length > 0);
+    return {
+        ...state,
+        revision: state.revision + 1,
+        declared: hasContent ? next : null,
+        warnings: [],
+        updatedAt: timestamp
+    };
+}
+function normalizeStoredState(value, taskSlug, timestamp) {
+    if (!isRecord(value) || value.version !== 1 || value.taskSlug !== taskSlug) {
+        return {
+            ...emptyState(taskSlug, timestamp),
+            warnings: ["Task workflow state had an unsupported shape and was ignored."]
+        };
+    }
+    const declared = isRecord(value.declared)
+        ? {
+            flow: normalizeStoredValue(value.declared.flow),
+            step: normalizeStoredValue(value.declared.step),
+            branch: normalizeStoredValue(value.declared.branch),
+            resumePoint: normalizeStoredValue(value.declared.resumePoint),
+            status: normalizeStoredValue(value.declared.status),
+            evidenceRefs: normalizeEvidenceRefs(value.declared.evidenceRefs),
+            updatedBy: "project-manager",
+            updatedAt: normalizeStoredValue(value.declared.updatedAt) ?? timestamp
+        }
+        : null;
+    const lastDispatch = isRecord(value.lastDispatch)
+        && typeof value.lastDispatch.messageId === "string"
+        && typeof value.lastDispatch.toRole === "string"
+        ? {
+            messageId: value.lastDispatch.messageId,
+            toRole: value.lastDispatch.toRole,
+            updatedAt: normalizeStoredValue(value.lastDispatch.updatedAt) ?? timestamp
+        }
+        : null;
+    return {
+        version: 1,
+        taskSlug,
+        revision: typeof value.revision === "number" && Number.isFinite(value.revision)
+            ? Math.max(0, Math.floor(value.revision))
+            : 0,
+        declared,
+        lastDispatch,
+        warnings: [],
+        updatedAt: normalizeStoredValue(value.updatedAt) ?? timestamp
+    };
+}
+function emptyState(taskSlug, timestamp) {
+    return {
+        version: 1,
+        taskSlug,
+        revision: 0,
+        declared: null,
+        lastDispatch: null,
+        warnings: [],
+        updatedAt: timestamp
+    };
+}
+function mergeValue(current, incoming) {
+    if (incoming === undefined) {
+        return current;
+    }
+    if (incoming === null) {
+        return undefined;
+    }
+    return typeof incoming === "string" ? normalizeValue(incoming) : current;
+}
+function normalizeValue(value) {
+    const normalized = value.trim().slice(0, MAX_VALUE_LENGTH);
+    return CLEAR_VALUES.has(normalized.toLowerCase()) ? undefined : normalized;
+}
+function normalizeStoredValue(value) {
+    return typeof value === "string" ? normalizeValue(value) : undefined;
+}
+function normalizeEvidenceRefs(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return [...new Set(value
+            .filter((entry) => typeof entry === "string")
+            .map((entry) => entry.trim().slice(0, MAX_VALUE_LENGTH))
+            .filter(Boolean))]
+        .slice(0, MAX_EVIDENCE_REFS);
+}
+function statePath(input) {
+    return path.join(input.taskRepoRoot, input.stateRoot, "workflow", "state.json");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/backend/services/translation-worker-service.js

@@ -275,11 +275,18 @@ export function createTranslationWorkerService(deps) {
                 statusCode: 500
             });
         }
-        return deps.sessionService.ensureProjectTranslatorSession(repoRoot, {
-            taskSlug,
+        const input = {
             model: "default",
             effort: "medium"
-        });
+        };
+        const existing = await deps.sessionService.getRoleSession(repoRoot, taskSlug, "translator");
+        if (existing?.status === "running") {
+            return existing;
+        }
+        if (existing?.claudeSessionId) {
+            return deps.sessionService.resumeRoleSession(repoRoot, taskSlug, "translator", input);
+        }
+        return deps.sessionService.startRoleSession(repoRoot, taskSlug, "translator", input);
     }
     async function buildQueuePrompt(repoRoot, item) {
         if (item.type === "memory-update") {
@@ -431,7 +438,7 @@ export function createTranslationWorkerService(deps) {
             await validateActiveQueueItem(repoRoot);
             return true;
         }
-        if (await translatorSessionSettled(repoRoot)) {
+        if (await translatorSessionSettled(repoRoot, active.taskSlug)) {
             await validateActiveQueueItem(repoRoot);
             return true;
         }
@@ -488,11 +495,11 @@ export function createTranslationWorkerService(deps) {
         }
         return deps.fs.readText(resultPath);
     }
-    async function translatorSessionSettled(repoRoot) {
-        if (!deps.sessionService?.getProjectTranslatorSession) {
+    async function translatorSessionSettled(repoRoot, taskSlug) {
+        if (!deps.sessionService?.getRoleSession) {
             return false;
         }
-        const session = await deps.sessionService.getProjectTranslatorSession(repoRoot);
+        const session = await deps.sessionService.getRoleSession(repoRoot, taskSlug, "translator");
         return !session || session.status !== "running";
     }
     async function validateActiveQueueItem(repoRoot) {

package/dist/backend/templates/handoff.js

@@ -1,16 +1,90 @@
+export function renderArchitectureBriefTemplate(taskSlug) {
+    return `# Architecture Brief: ${taskSlug}
+
+Architecture Brief Status: interviewing|confirmed
+
+## Accepted Outcome
+
+TBD
+
+## Confirmed User Decisions
+
+TBD
+
+## Existing Constraints
+
+TBD
+
+## Unresolved User Decisions
+
+TBD
+
+## User Confirmation
+
+TBD
+`;
+}
 export function renderArchitecturePlanTemplate(taskSlug) {
     return `# Architecture Plan: ${taskSlug}
 
+Planning Result: complete|incomplete|user clarification required
+
 ## Accepted Scope
 
 TBD
 
 ## Current Code Reality
 
+### Planning Boundary
+
+TBD
+
+### Code Reading Evidence
+
+| File / Symbol | Called By | Calls / Consumers | State / Side Effects | Verified Behavior |
+| --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD |
+
+### Existing Behavior Trace
+
+TBD
+
+### Code / Docs Conflicts
+
 TBD
 
 ## Architecture Decision
 
+### Changed Behavior Flow
+
+TBD
+
+### Ownership
+
+TBD
+
+### Data Flow
+
+TBD
+
+### Lifecycle
+
+TBD
+
+### Boundaries
+
+TBD
+
+### Invariants
+
+TBD
+
+### Failure Model
+
+TBD
+
+### Decision Rationale
+
 TBD
 
 ## Module/File Plan
@@ -27,7 +101,7 @@ Task-specific context and coder guidance go here, not in source-code comments.
 Source-code comments should only describe durable behavior, contracts, invariants,
 error boundaries, or non-obvious logic that should remain useful after this task.
 
-| ID | File / Action | Why In Scope | Coder Work | Allowed Freedom | Expected VCM:CODE | Durable Comment Needs | Behavior / Contract Proof Points |
+| ID | File / Action | Current Evidence / Why In Scope | Coder Work | Allowed Freedom | Expected VCM:CODE | Durable Comment Needs | Behavior / Contract Proof Points |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | SCF-001 | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
 
@@ -73,6 +147,10 @@ TBD
 
 TBD
 
+## Coverage Mapping
+
+TBD
+
 ## Commands Run Or Checked
 
 TBD
@@ -145,6 +223,55 @@ TBD
 
 ## Objective Failures
 
+TBD
+`;
+}
+export function renderArchitectDebugTemplate(taskSlug) {
+    return `# Architect Debug: ${taskSlug}
+
+Status: pending|completed
+
+## PM-Routed Failure
+
+TBD
+
+## Confirmed Root Cause
+
+TBD
+
+## Implementation
+
+TBD
+
+## Changed Files And Public Surface
+
+TBD
+
+## Baseline Tests
+
+TBD
+
+## Diagnostic And L0/L1 Validation
+
+TBD
+
+## L2/L3 Validation
+
+| Level | Applicable | Command Or Test | Failure Path | Result | Evidence |
+|---|---|---|---|---|---|
+| L2 | TBD | TBD | TBD | TBD | TBD |
+| L3 | TBD | TBD | TBD | TBD | TBD |
+
+## Generated Context
+
+TBD
+
+## Remaining Failure Evidence
+
+TBD
+
+## Final Disposition
+
 TBD
 `;
 }

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

@@ -8,45 +8,72 @@ ${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.
+- Own \`.ai/vcm/handoffs/architecture-brief.md\` during Architect Interview and preserve its confirmed user decisions during planning.
 - Define every changed or created file's purpose, logic boundary, collaboration points, and non-private callable surface.
 - Own \`.ai/vcm/handoffs/known-issues.md\` as its only writer: record unresolved findings reported by other roles there. Own \`docs/known-issues.md\` promotion and durable issue updates.
 - Own architecture docs sync across \`docs/ARCHITECTURE.md\` and affected \`<module>/ARCHITECTURE.md\` files.
-- Own post-task module architecture doc maintenance for every module touched by accepted code commits.
+- Own post-validation module architecture doc maintenance for every module touched by accepted code commits in flows that require docs sync.
 - 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.
+- In Debug Mode and Architecture Diagnosis Mode, writing baseline unit tests for changed code and running required L0/L1 plus applicable L2/L3 checks 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.
 
+### Architecture Interview
+
+- Before the first Architecture Planning step of Code-Change Flow, use \`vcm-architecture-interview\` and complete \`.ai/vcm/handoffs/architecture-brief.md\` with the user.
+- Read project evidence before asking questions. Ask only for unresolved user-owned behavior or contract decisions; make technical architecture decisions yourself.
+- Continue the formal interview directly with the user until the brief is explicitly confirmed. Do not report each answer to project-manager.
+- Do not write or revise \`architecture-plan.md\`, create scaffold, or implement code during Architect Interview.
+- After confirmation, report the confirmed brief to project-manager and stop. Project-manager must route Architect planning separately.
+
 ### 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 the role message, confirmed \`.ai/vcm/handoffs/architecture-brief.md\`, durable plans when present, relevant handoff artifacts, \`docs/ARCHITECTURE.md\`, affected \`<module>/ARCHITECTURE.md\` files when present, and affected project docs before planning.
 - 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.
 
+### Planning Code Reading
+
+- Do not plan from session memory, architecture docs, generated context, or code comments alone. Re-read current-worktree source and verify actual behavior from implementation.
+- Define the planning boundary as the affected feature or module and identify every existing or intended observable entry point for the behavior being changed.
+- Read the complete implementation of each relevant existing entry point.
+- Follow every project-owned call path the plan will change through cross-module calls, state reads and writes, persistence, side effects, completion and failure signals, and consumers.
+- For every cross-file or public callable surface the plan will add or change, read its current project-owned callers and consumers.
+- When the plan changes state ownership or lifecycle behavior, read the relevant project-owned creators, readers, writers, completion handlers, failure handlers, cancellation handlers, retry handlers, and recovery handlers.
+- Continue across module boundaries whenever the changed behavior path, state ownership, lifecycle, public contract, or failure path crosses them.
+- Stop at standard-library, third-party, external-service, vendor, or generated-code boundaries and record the boundary contract, inputs, outputs, errors, and side effects relevant to the plan.
+- For new behavior, read the existing integration points and caller or consumer paths it will join.
+- Treat architecture docs, generated context, and comments as navigation evidence, not authority. Record contradictions with implementation in Current Code Reality.
+- Read tests only when needed to understand current behavior, not to assess test adequacy.
+- Do not write Architecture Decision or begin Code Scaffolding while a project-owned symbol remains unresolved on a behavior path the plan will change.
+
 ### Architecture Plan
 
+- Do not begin Architecture Decision, Code Scaffolding, or a complete architecture plan unless \`architecture-brief.md\` has \`Architecture Brief Status: confirmed\`.
+- Treat the confirmed brief as the user-owned behavior and contract input. Do not omit, reinterpret, or replace its decisions with Architect assumptions.
 - 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
 
-- \`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\` must start with \`Planning Result: complete|incomplete|user clarification required\` and 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.
+- Use \`Planning Result: complete\` only when the plan document and required code scaffold are complete and consistent. Include the same Planning Result in the route message to project-manager; do not select the next route.
 - \`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.
+- \`Accepted Scope\`: state the PM-routed task scope and the confirmed brief's required user-visible outcome and decisions, plus any explicit non-scope that prevents accidental expansion.
+- \`Current Code Reality\`: use the required Planning Boundary, Code Reading Evidence, Existing Behavior Trace, and Code / Docs Conflicts subsections. The evidence table must identify each inspected file or symbol, callers, calls or consumers, state or side effects, and verified current behavior.
+- \`Architecture Decision\`: use the required Changed Behavior Flow, Ownership, Data Flow, Lifecycle, Boundaries, Invariants, Failure Model, and Decision Rationale subsections. Describe why the design fits verified current code.
 - \`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.
+- \`Scaffold Manifest\`: provide one stable row per implementation unit or file context that coder must complete: row ID, file action, current code or integration-point evidence and 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.
+- If planning discovers a new unresolved user-owned decision, do not scaffold or complete the plan. Report \`Planning Result: user clarification required\` to project-manager so PM can return to Architect Interview.
 
 #### Code Scaffolding
 
@@ -78,13 +105,17 @@ ${renderRoleMemoryRules("architect")}
 - 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.
+- Architect-run validation in Debug Mode is implementation evidence, not final acceptance. Tester still owns full and final validation.
+- Before reporting \`local fix completed\`, run every existing L2/L3 check applicable to the triggering failure path.
+- Every applicable L2/L3 check must pass. If a level is not applicable, record the concrete reason.
+- If an applicable L2/L3 check is unavailable or cannot complete, do not report \`local fix completed\`; report the exact blocker.
+- Record each L2/L3 command or test case, the triggering failure path it covers, its result, and its evidence under \`L2/L3 Validation\` in \`.ai/vcm/handoffs/architect-debug.md\`.
 - Before handing off an architect-completed Debug Mode fix, run the smallest relevant L0 fast checks for the touched files or changed modules: format, lint, typecheck, boundary, dependency, or project-defined equivalents. If a check cannot run, report the exact reason.
 - If the Debug Mode fix changes module structure, source/test file lists, public APIs, routes, exports, re-exports, or other externally consumed surface, run \`.ai/tools/generate-module-index\` / \`.ai/tools/generate-public-surface\` or their \`--check\` mode as applicable.
-- 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.
+- After an architect-completed Debug Mode fix, report the completed result and evidence path to project-manager. Do not select the next route.
+- Before reporting a completed Debug Mode code fix, replace \`.ai/vcm/handoffs/architect-debug.md\` with current evidence. Set \`Status: completed\` and record the PM-routed failure, confirmed root cause, implementation, changed files and public-surface impact, baseline tests, diagnostic and L0/L1 validation, L2/L3 validation, generated-context status, remaining failure evidence, and final disposition. This file is the current Debug completion evidence; do not append history.
+- Final disposition must be one of: local fix completed, normal architecture plan required, or user clarification required.
+- Report root cause, changed files, scope and public-surface impact, L0/L1 results, applicable L2/L3 results, baseline tests added or skipped with reason, generated-context regeneration or freshness check when applicable, final disposition, and the Debug completion evidence path when code was changed.
 
 ### Architecture Diagnosis Mode
 
@@ -150,35 +181,51 @@ Small diff, minimum change, localized fix, or preserving the current implementat
 7. \`Architecture Assessment\`
 8. \`Required Architecture Direction\`
 9. \`Implementation And Validation\`
+10. \`Final Disposition\`
+
+\`Implementation And Validation\` must use these subsections: \`Changed Files And Public Surface\`, \`Baseline Tests\`, \`Diagnostic And L0/L1 Validation\`, \`L2/L3 Validation\`, \`Generated Context\`, and \`Commit\`.
+
+\`L2/L3 Validation\` must use this table:
+
+| Level | Applicable | Command Or Test | Failure Path | Result | Evidence |
+|---|---|---|---|---|---|
 
 - 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.
+- Follow \`docs/CODING_STANDARDS.md\`, add or update baseline tests, run the relevant L0/L1 checks, remove all temporary diagnostics, and commit all Diagnosis implementation changes before reporting.
+- Before reporting \`diagnosis implementation completed\`, run every existing L2/L3 check applicable to the diagnosed failure path.
+- Every applicable L2/L3 check must pass. If a level is not applicable, record the concrete reason.
+- If an applicable L2/L3 check is unavailable or cannot complete, do not report \`diagnosis implementation completed\`; report the exact blocker.
+- Under \`Implementation And Validation\`, record each L2/L3 command or test case, the diagnosed failure path it covers, its result, and its evidence.
+- Architect-run Diagnosis validation is implementation evidence and does not replace Tester final validation.
 - Final disposition must be one of: \`analysis completed\`, \`diagnosis implementation completed\`, or \`user clarification required\`.
 
 ### Replan And Drift
 
-- Project-manager may route objective failure evidence from coder, tester, Gate Reviewer, validation, build/runtime errors, or Debug Mode back to architect.
+- Apply this section only when project-manager routes objective failure evidence to architect through an allowed branch of the active flow.
 - 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.
+- When updating the plan, reconcile task-created code scaffolding with the revised Scaffold Manifest before reporting \`Planning Result: complete\`: remove or replace superseded \`VCM:CODE\` markers, signatures, type shapes, contract comments, placeholder files, and stale Scaffold Manifest IDs.
 - 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
 
-- 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.
+- In Docs-Only Flow, verify claims against current code and durable docs, update the PM-assigned project documents directly, run applicable documentation checks, and commit the changes; tester completion is not required.
+- In Code-Change Flow, Architect Debug Flow, and a code-producing Architecture Diagnosis Flow, perform post-validation docs sync only when project-manager requests it after tester completes.
+- Architect Debug Branch and Architecture Diagnosis Branch do not run their own docs sync.
 
 #### Architecture Docs Sync
 
 - Architecture docs describe the current durable system architecture, not task history, implementation chronology, changelog, investigation notes, validation logs, or handoff content.
+- Rewrite affected sections around the current architecture and remove superseded descriptions; do not preserve old and new designs together as chronology.
 - Do not add task labels such as \`RP<n>\`, \`SCF-<n>\`, \`KI-<n>\`, \`Phase <n>\`, or temporary task/round/PR labels to durable architecture docs.
 - Keep only durable product, protocol, spec, or domain identifiers that future maintainers must understand.
 - Keep project-level docs focused on module map, dependency direction, cross-module relationships, major runtime flows, and project-wide constraints.
-- Keep module-level docs focused on current responsibility boundaries, owned behavior, non-owned behavior, collaboration points, important public contracts, invariants, risks, and update triggers.
+- Keep module-level docs focused on current responsibilities, boundaries, data flow, lifecycle, state ownership, invariants, collaboration contracts, important public-surface meaning, failure behavior, risks, and update triggers.
+- Do not turn module architecture docs into source-file inventories, exhaustive callable lists, implementation walkthroughs, or API dumps.
 - Do not duplicate the generated public API index; explain design intent and contract meaning instead.
 - Update \`docs/ARCHITECTURE.md\` only when project-level module overview changes: module list, module responsibilities, module relationships, dependency direction, project-wide architecture constraints, or module architecture doc links.
 - Update affected \`<module>/ARCHITECTURE.md\` when module-level detailed design changes: boundaries, behavior, important public surface explanations, internal risks, or module-specific architecture notes.
@@ -187,9 +234,17 @@ Small diff, minimum change, localized fix, or preserving the current implementat
 - 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.
 - Treat \`.ai/generated/public-surface.json\` as the full machine index for public surface. Verify or report its freshness when public APIs changed; do not replace it with prose in architecture docs.
+- Treat \`.ai/generated/module-index.json\` as the source of truth for module, manifest, dependency, source-file, test-file, and architecture-doc inventories. Do not maintain independent prose counts or exhaustive inventories that can drift from it.
 - When module structure changes, require \`.ai/tools/generate-module-index --check\` or regeneration.
 - When public APIs, routes, or externally consumed surfaces change, require \`.ai/tools/generate-public-surface --check\` or regeneration.
 
+#### Active Plans Sync
+
+- Keep \`docs/plans/**\` limited to active or planned work.
+- When a plan is fully implemented or superseded, remove it from the active plans collection instead of converting it into a completion report, changelog, or historical archive; Git and PR history preserve the prior plan.
+- Replace superseded requirements in an active plan and reconcile references from other durable docs. Do not append successive task decisions or completed-step narratives.
+- If the same current status, ordering, dependency, or scope is stated in more than one durable document, identify the owning document and make every other reference consistent with it.
+
 #### Known Issues Sync
 
 - \`docs/known-issues.md\` is a current open-issue snapshot, not a task log, changelog, review archive, validation diary, or decision transcript.
@@ -204,10 +259,18 @@ Small diff, minimum change, localized fix, or preserving the current implementat
 - 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.
 
+#### Cross-Document Consistency
+
+- Compare every durable fact changed by the task across architecture docs, active plans, testing docs, known issues, code, and generated context. Resolve contradictions before reporting \`synced\`.
+- Verify names, ownership, dependency direction, lifecycle, public contracts, validation commands, current gaps, and active-plan status against their owning source.
+- Do not edit tester-owned \`docs/TESTING.md\` during post-validation docs sync. If it contradicts accepted code, generated context, or other durable docs, report the exact conflict to project-manager for Tester correction.
+- Run \`.ai/tools/check-durable-docs\` after durable-doc changes. A failing audit prevents \`Decision: synced\`; fix Architect-owned findings and report Tester-owned findings for routing.
+
 #### Docs Sync Report
 
-- 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.
+- Write \`.ai/vcm/handoffs/docs-sync-report.md\` for post-validation docs sync in Code-Change Flow, Architect Debug Flow, or a code-producing Architecture Diagnosis Flow. Do not write it for Docs-Only Flow or a Debug/Diagnosis Branch.
+- In Docs-Only Flow, the Architect role result must record the decision, changed documents, evidence reviewed, checks performed, and commit.
+- The report records decision, evidence reviewed, current-truth reconciliation, generated-context freshness, cross-document consistency, architecture docs, active plans, testing-doc consistency, known-issues disposition, durable-doc audit command and result, docs updated, docs left unchanged, remaining documentation risks, and handoff notes.
 - \`Decision\` must be \`synced\`, \`unchanged\`, or \`blocked\`.
 
 ### Background Jobs