vibe-coding-master 0.6.16 → 0.6.18

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

@@ -1656,7 +1656,7 @@ Required work:
 - Run .ai/tools/generate-public-surface from the target task worktree after module-index.json exists.
 - Add or update project-specific Project Context and Project Constraints in target CLAUDE.md above the VCM managed block.
 - Fill target docs/ARCHITECTURE.md with project-level module overview, responsibilities, relationships, dependency direction, project-wide constraints, and links to module-level architecture docs.
-- Create or update target module-level ARCHITECTURE.md files for clear module boundaries listed by module-index.json.
+- Create or update target module-level ARCHITECTURE.md files for clear non-root module boundaries with architectureDoc paths in module-index.json.
 - Fill target docs/TESTING.md with project-native validation levels, commands, validation selection rules, final-validation cleanup, test layout, integration/E2E case lists, generated-context freshness checks, and known testing gaps.
 - Review git status and git diff in the target task worktree.
 - Stage only allowed bootstrap harness changes and create a commit in the target task worktree.

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

@@ -8,7 +8,6 @@ import { createTranslationQueueRegistry } from "./translation-queue.js";
 const TRANSLATION_SOURCE_LANGUAGE = "auto";
 const TRANSLATION_INPUT_MODE = "review-before-send";
 const TRANSLATION_CONTEXT_ENABLED = false;
-const TRANSLATION_TIMEOUT_MS = 120000;
 const TRANSLATION_PROVIDER = "claude-code";
 const TRANSLATION_MODEL = "translator";
 const OUTPUT_TRANSLATION_BATCH_DELAY_MS = 10000;
@@ -30,8 +29,7 @@ export function createTranslationService(deps) {
             targetLanguage: preferences.translationTargetLanguage,
             inputMode: TRANSLATION_INPUT_MODE,
             outputMode: preferences.translationOutputMode,
-            contextEnabled: TRANSLATION_CONTEXT_ENABLED,
-            requestTimeoutMs: TRANSLATION_TIMEOUT_MS
+            contextEnabled: TRANSLATION_CONTEXT_ENABLED
         };
     }
     function getState(sessionId) {
@@ -400,7 +398,7 @@ export function createTranslationService(deps) {
                 }
                 for (const { item, job } of jobs) {
                     try {
-                        const result = await waitForConversationResult(item.repoRoot, job, item.config.requestTimeoutMs);
+                        const result = await waitForConversationResult(item.repoRoot, job);
                         const completed = {
                             ...item.entry,
                             status: "translated",
@@ -1076,7 +1074,7 @@ export function createTranslationService(deps) {
         },
         async translateGatewayOutput(input) {
             const config = await loadConfig();
-            const reusable = await findReusableGatewayOutputTranslation(input, config);
+            const reusable = await findReusableGatewayOutputTranslation(input);
             if (reusable) {
                 return reusable.trim();
             }
@@ -1197,7 +1195,7 @@ export function createTranslationService(deps) {
         }
         return leftTime.localeCompare(rightTime);
     }
-    async function findReusableGatewayOutputTranslation(input, config) {
+    async function findReusableGatewayOutputTranslation(input) {
         const graceDeadline = Date.now() + (input.sourceEntryIds?.length ? GATEWAY_TRANSLATION_REUSE_GRACE_MS : 0);
         while (true) {
             const lookup = await lookupGatewayOutputTranslation(input);
@@ -1205,7 +1203,7 @@ export function createTranslationService(deps) {
                 return lookup.text;
             }
             if (lookup.kind === "active") {
-                return waitForReusableGatewayOutputTranslation(input, config);
+                return waitForReusableGatewayOutputTranslation(input);
             }
             if (!input.sourceEntryIds?.length || Date.now() >= graceDeadline) {
                 return undefined;
@@ -1213,9 +1211,8 @@ export function createTranslationService(deps) {
             await delay(GATEWAY_TRANSLATION_REUSE_POLL_MS);
         }
     }
-    async function waitForReusableGatewayOutputTranslation(input, config) {
-        const deadline = Date.now() + config.requestTimeoutMs;
-        while (Date.now() <= deadline) {
+    async function waitForReusableGatewayOutputTranslation(input) {
+        while (true) {
             const lookup = await lookupGatewayOutputTranslation(input);
             if (lookup.kind === "translated") {
                 return lookup.text;
@@ -1225,11 +1222,6 @@ export function createTranslationService(deps) {
             }
             await delay(GATEWAY_TRANSLATION_REUSE_POLL_MS);
         }
-        throw new VcmError({
-            code: "TRANSLATION_TIMEOUT",
-            message: "Gateway output translation timed out while waiting for the existing PM reply translation.",
-            statusCode: 504
-        });
     }
     async function lookupGatewayOutputTranslation(input) {
         const states = await getGatewayOutputCandidateStates(input);
@@ -1352,7 +1344,7 @@ export function createTranslationService(deps) {
     }
     async function translateText(input) {
         const job = await createConversationJob(input);
-        const result = await waitForConversationResult(input.repoRoot, job, input.config.requestTimeoutMs);
+        const result = await waitForConversationResult(input.repoRoot, job);
         return {
             text: result.translatedText
         };
@@ -1382,14 +1374,30 @@ export function createTranslationService(deps) {
             deferDispatch: input.deferDispatch
         });
     }
-    async function waitForConversationResult(repoRoot, job, timeoutMs) {
-        const deadline = Date.now() + timeoutMs;
-        let lastError;
-        while (Date.now() <= deadline) {
+    async function waitForConversationResult(repoRoot, job) {
+        while (true) {
             const state = await deps.translationWorkerService.getState(repoRoot);
             const item = job.queueItemId
                 ? state.queue.items.find((candidate) => candidate.id === job.queueItemId)
                 : undefined;
+            if (!item) {
+                try {
+                    return await deps.translationWorkerService.validateConversationResult(repoRoot, {
+                        resultPath: job.resultPath,
+                        sourceHash: job.sourceHash,
+                        targetLanguage: job.targetLanguage
+                    });
+                }
+                catch (error) {
+                    throw new VcmError({
+                        code: "TRANSLATION_FAILED",
+                        message: error instanceof Error
+                            ? `translation queue item is unavailable: ${error.message}`
+                            : "translation queue item is unavailable.",
+                        statusCode: 502
+                    });
+                }
+            }
             if (item && ["failed", "cancelled", "interrupted", "skipped"].includes(item.status)) {
                 throw new VcmError({
                     code: "TRANSLATION_FAILED",
@@ -1398,7 +1406,7 @@ export function createTranslationService(deps) {
                 });
             }
             if (item && item.status !== "completed") {
-                await delay(Math.min(500, Math.max(25, timeoutMs)));
+                await delay(500);
                 continue;
             }
             try {
@@ -1409,18 +1417,12 @@ export function createTranslationService(deps) {
                 });
             }
             catch (error) {
-                lastError = error;
                 if (item?.status === "completed") {
                     throw error;
                 }
             }
-            await delay(Math.min(500, Math.max(25, timeoutMs)));
+            await delay(500);
         }
-        throw new VcmError({
-            code: "TRANSLATION_TIMEOUT",
-            message: lastError instanceof Error ? `translation timed out: ${lastError.message}` : "translation timed out.",
-            statusCode: 504
-        });
     }
 }
 function delay(ms) {

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

@@ -17,14 +17,6 @@ const CONVERSATION_BATCHES_DIR = `${CONVERSATION_RUNTIME_DIR}/batches`;
 const MEMORY_UPDATE_RUNTIME_DIR = `${TRANSLATIONS_RUNTIME_DIR}/memory-updates`;
 const DEFAULT_PROFILE = "default";
 const DEFAULT_CHUNK_SOURCE_TOKEN_TARGET = 80000;
-// In-flight conversation queue items normally finalize when the Translator
-// session's Stop/StopFailure hook reaches the backend. If that hook is lost
-// (session crash, backend restart/reconnect) a conversation item with no result
-// on disk would block the queue head forever. Treat such an item as stuck once it
-// has been in-flight past this bound and release it so later items can dispatch.
-// Kept comfortably above a normal short composer translation, so a genuinely
-// running conversation turn is never released mid-flight.
-const STALE_CONVERSATION_ITEM_MS = 90000;
 const BOOTSTRAP_DEFAULT_LIMIT = 12;
 const MEMORY_TOTAL_LIMIT_BYTES = 80 * 1024;
 const MEMORY_INITIALIZED_MIN_FILES = 2;
@@ -439,12 +431,22 @@ export function createTranslationWorkerService(deps) {
             await validateActiveQueueItem(repoRoot);
             return true;
         }
-        if (active.type === "conversation" && isStaleActiveItem(active)) {
+        if (await translatorSessionSettled(repoRoot)) {
             await validateActiveQueueItem(repoRoot);
             return true;
         }
         return false;
     }
+    async function reconcileActiveItemFromSessionState(repoRoot) {
+        const queue = await loadQueue(repoRoot);
+        const active = queue.activeItemId
+            ? queue.items.find((item) => item.id === queue.activeItemId)
+            : undefined;
+        if (!active || !["dispatching", "running"].includes(active.status)) {
+            return;
+        }
+        await reconcileStuckActiveItem(repoRoot, active);
+    }
     async function activeItemResultAvailable(repoRoot, item) {
         if (item.type === "conversation") {
             return conversationResultAvailable(repoRoot, item);
@@ -486,12 +488,12 @@ export function createTranslationWorkerService(deps) {
         }
         return deps.fs.readText(resultPath);
     }
-    function isStaleActiveItem(item) {
-        const updatedAtMs = Date.parse(item.updatedAt ?? "");
-        if (!Number.isFinite(updatedAtMs)) {
-            return true;
+    async function translatorSessionSettled(repoRoot) {
+        if (!deps.sessionService?.getProjectTranslatorSession) {
+            return false;
         }
-        return Date.now() - updatedAtMs >= STALE_CONVERSATION_ITEM_MS;
+        const session = await deps.sessionService.getProjectTranslatorSession(repoRoot);
+        return !session || session.status !== "running";
     }
     async function validateActiveQueueItem(repoRoot) {
         const queue = await loadQueue(repoRoot);
@@ -537,13 +539,6 @@ export function createTranslationWorkerService(deps) {
         const batchItems = queue.items.filter((item) => item.type === "conversation" &&
             item.batchId === active.batchId &&
             ["dispatching", "running", "validating"].includes(item.status));
-        const validatingAt = now();
-        for (const item of batchItems) {
-            item.status = "validating";
-            item.updatedAt = validatingAt;
-        }
-        queue.updatedAt = validatingAt;
-        await saveQueue(repoRoot, queue);
         const completedAt = now();
         for (const item of batchItems) {
             const index = item.batchIndex ?? 0;
@@ -909,6 +904,7 @@ export function createTranslationWorkerService(deps) {
         async getState(repoRoot, options = {}) {
             await ensureLayout(repoRoot);
             await cleanupCompletedRuntime(repoRoot);
+            await reconcileActiveItemFromSessionState(repoRoot);
             const [queue, fileIndex, bootstrapIndex, memoryInitialized] = await Promise.all([
                 loadQueue(repoRoot),
                 loadFileIndex(repoRoot),

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

@@ -4,7 +4,7 @@ export function renderArchitectHarnessRules() {
 
 ### Role Scope
 
-- Own technical analysis, architecture planning, module boundaries, file-level responsibilities, cross-file callable surfaces, public contracts, verifiable behavior, phase boundaries, behavior/contract proof points, risks, and Replan triggers.
+- Own technical analysis, architecture planning, module boundaries, file-level responsibilities, cross-file callable surfaces, public contracts, verifiable behavior, task boundaries, behavior/contract proof points, risks, and Replan triggers.
 - Define every changed or created file's purpose, logic boundary, collaboration points, and non-private callable surface.
 - Own \`docs/known-issues.md\` promotion and durable issue updates.
 - Own architecture docs sync across \`docs/ARCHITECTURE.md\` and affected \`<module>/ARCHITECTURE.md\` files.
@@ -16,7 +16,7 @@ export function renderArchitectHarnessRules() {
 ### 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.
-- Read \`.ai/generated/module-index.json\` when planning module scope, file scope, dependency direction, or phased work.
+- 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.
 
@@ -30,7 +30,7 @@ export function renderArchitectHarnessRules() {
 - Define every non-private callable surface intended for use outside its file: visibility, signature shape, responsibility, expected callers, behavior contract, side effects, and error boundaries.
 - Include a \`Scaffold Manifest\` for task-specific file context: stable row ID, file action, why the file is in scope, coder work, allowed implementation freedom, expected \`VCM:CODE\` placeholders, durable code comment needs, proof points, and Replan triggers.
 - 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.
-- Put task context, phase notes, handoff instructions, temporary rationale, and coder guidance in the \`Scaffold Manifest\`, not in source-code comments.
+- Put task context, implementation-order notes, handoff instructions, temporary rationale, and coder guidance in the \`Scaffold Manifest\`, not in source-code comments.
 - Cover architecture docs impact, known risks, and Replan triggers.
 - For docs impact, list every touched module and state whether its \`<module>/ARCHITECTURE.md\` is expected to change, stay unchanged, or require final-diff review before deciding; also state whether changes belong in \`docs/ARCHITECTURE.md\`, \`.ai/generated/public-surface.json\`, or no durable architecture doc.
 
@@ -38,7 +38,7 @@ export function renderArchitectHarnessRules() {
 
 - Create or update only the minimum module/file scaffolding needed to make boundaries, callable surfaces, and placeholders unambiguous.
 - Source-code comments must describe durable behavior, contracts, invariants, error boundaries, or non-obvious logic that should remain useful after the task is complete.
-- Do not put task-specific context, phase notes, handoff instructions, temporary plan rationale, or coder guidance in source-code comments.
+- Do not put task-specific context, implementation-order notes, handoff instructions, temporary plan rationale, or coder guidance in source-code comments.
 - When changing an existing file, update only affected durable comments or callable surfaces; do not rewrite unrelated file comments.
 - Define every new or changed non-private callable surface directly in code with its signature shape and contract comment.
 - When changing an existing non-private callable surface, update its signature and contract comment in code before coder work starts; leave \`VCM:CODE\` only where implementation must change.
@@ -47,18 +47,12 @@ export function renderArchitectHarnessRules() {
 - Architect scaffolding may include modules, files, signatures, type shapes, durable comments, and placeholder bodies, but not real business implementation beyond minimal scaffold code.
 - Coder may add private implementation helpers, but must not add or change cross-file callable surface without architect replan.
 
-### Phase Planning
+### Complete Task Planning
 
-- Do not create phases for small, single-scope changes; use phases only when the task spans multiple modules, public contracts, migrations, high-risk integrations, or more work than one reliable coder handoff should carry.
-- For complex tasks, first provide an overall solution outline and recommended phases, but keep detailed implementation planning limited to the current phase.
-- Treat \`.ai/vcm/handoffs/architecture-plan.md\` as the executable plan for the current phase, not an accumulating history of all phases.
-- When moving to a new phase, rewrite \`architecture-plan.md\` for that phase: remove previous phase detailed scope, Scaffold Manifest rows, \`VCM:CODE\` guidance, and completed phase instructions.
-- Keep only the minimum overall roadmap and prior-phase context needed to understand the current phase.
-- Durable decisions discovered in previous phases must be promoted to durable docs when needed, not preserved as old task detail inside \`architecture-plan.md\`.
-- Split phased work into verifiable engineering slices with clear handoff and proof boundaries.
-- Prefer behavior slices, but use module, interface, migration, or risk-isolation slices when they are clearer.
-- Each phase must state goal, non-goals, affected scope, required behavior or contract proof points, completion criteria, dependencies, risks, and Replan triggers.
-- Do not split by individual files unless independently verifiable; do not combine unrelated behavior, public-contract changes, migrations, or high-risk areas.
+- Plan the full accepted task scope routed by PM.
+- \`architecture-plan.md\` must describe the complete implementation for that scope.
+- Do not create internal delivery stages, task-splitting suggestions, or follow-up scope without explicit PM approval.
+- Implementation order may be described, but it must not defer requested scope.
 
 ### Debug Mode
 
@@ -73,10 +67,37 @@ export function renderArchitectHarnessRules() {
 - After an architect-completed debug fix, route to reviewer for independent final validation before project-manager final acceptance.
 - Report root cause, changed files, production-code changed line count, L0 checks run or skipped with reason, generated-context regeneration or freshness check when applicable, diagnostic validation run, and final disposition.
 
+### 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.
+
+Your job is to diagnose the architecture behind the failure before proposing implementation work.
+
+Analyze the problem from these angles:
+
+- **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.
+
+Your diagnosis must answer:
+
+1. What is the surface failure?
+2. What architecture assumption is broken?
+3. What current ownership, data flow, lifecycle, boundary, invariant, or failure model is wrong or missing?
+4. Why would a local patch fail or create more patches?
+5. What architecture direction should replace it?
+6. What bounded refactor direction or replan scope should follow?
+
+Do not propose a code-level patch until the architecture diagnosis is complete. If the problem is truly only a local implementation bug, say that explicitly, explain why no architecture change is needed, and keep the follow-up scope local.
+
 ### Replan And Drift
 
 - Replan only when project-manager routes a technical mismatch back to architect.
-- Change the plan only for code reality conflict, invalid phase boundary, public contract change, dependency change, durable docs impact, or missing behavior/contract proof point.
+- Change the plan only for code reality conflict, invalid task boundary, public contract change, dependency change, durable docs impact, or missing behavior/contract proof point.
 - Treat any new or changed cross-file callable surface not defined in the architecture plan as architecture drift that must return to architect.
 - Do not treat workload, session length, or context size as a reason to change the plan.
 - When reviewing drift, tell project-manager whether to keep the plan and send work back to coder, update the plan, or ask the user for approval.
@@ -88,7 +109,7 @@ export function renderArchitectHarnessRules() {
 #### Architecture Docs Sync
 
 - Architecture docs describe the current durable system architecture, not task history, implementation chronology, changelog, investigation notes, validation logs, or handoff content.
-- Do not add phase/task/RP labels unless they are durable product, protocol, or spec identifiers that future maintainers must understand.
+- Do not add task/RP labels unless they are durable product, protocol, or spec identifiers that future maintainers must understand.
 - Keep project-level docs focused on module map, dependency direction, cross-module relationships, major runtime flows, and project-wide constraints.
 - Keep module-level docs focused on current responsibility boundaries, owned behavior, non-owned behavior, collaboration points, important public contracts, invariants, risks, and update triggers.
 - Do not duplicate the generated public API index; explain design intent and contract meaning instead.
@@ -108,7 +129,7 @@ export function renderArchitectHarnessRules() {
 - Promote only unresolved durable issues or accepted limitations that can affect future architecture, implementation, validation, operation, or release decisions.
 - Remove fully resolved issues from \`docs/known-issues.md\`; git history preserves resolved details.
 - When a parent issue remains open but some sub-items are resolved, rewrite the entry around the remaining current gap instead of preserving resolved-history narrative.
-- Keep one KI entry focused on one owning problem. Split unrelated residuals instead of grouping them under a phase, review, or implementation session.
+- Keep one KI entry focused on one owning problem. Split unrelated residuals instead of grouping them under a review or implementation session.
 - Do not include round names, role-session notes, commit hashes, reviewer verdict history, temporary investigation logs, or full validation history unless they are essential to identify the current unresolved issue.
 - Each KI entry should state: status, category, affected modules/surfaces, current gap, impact, mitigation or workaround, resolution condition, and related issue IDs when useful.
 - Distinguish product/protocol issues from dev-environment, test-infra, harness, or VCM-tooling issues. Do not mix them in one KI entry.

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

@@ -4,7 +4,7 @@ export function renderCoderHarnessRules() {
 
 ### Role Scope
 
-- Own implementation and baseline implementation tests inside the approved task scope, current phase, role message, and architecture plan.
+- Own implementation and baseline implementation tests inside the approved task scope, role message, and architecture plan.
 - Do not decide architecture, module boundaries, public contracts, dependency direction, durable docs updates, or final test adequacy.
 
 ### Coder Implementation Discipline
@@ -16,7 +16,7 @@ export function renderCoderHarnessRules() {
 - Keep the diff inside approved scope: no unrelated rewrites, drive-by refactors, renamed symbols, moved files, or formatting churn.
 - Preserve existing behavior unless the architecture plan explicitly changes it; keep existing call sites and shared code paths working.
 - Maintain code documentation: preserve durable architect-written contract comments, keep comments consistent with changed behavior, and update affected durable comments when logic changes.
-- Do not copy Scaffold Manifest task context, phase notes, handoff instructions, temporary rationale, or coder guidance into source comments.
+- Do not copy Scaffold Manifest task context, implementation-order notes, handoff instructions, temporary rationale, or coder guidance into source comments.
 - Add source comments only for durable behavior, contracts, invariants, error boundaries, or non-obvious logic that cannot be made clear enough through naming, types, constants, or small helper functions.
 - Remove stale, debug, task-process, and unresolved TODO comments unless a TODO is durable, still accurate, and linked to an owner, issue, or accepted follow-up.
 
@@ -32,7 +32,7 @@ export function renderCoderHarnessRules() {
 
 ### Inputs
 
-- Before editing, read the role message, the architecture plan, current phase when present, affected code/tests, and validation instructions from the role message or project docs.
+- Before editing, read the role message, the architecture plan, affected code/tests, and validation instructions from the role message or project docs.
 - Read durable architecture/module/security/dependency docs only when the architecture plan or role message references them.
 - Stop before editing when the architecture plan, role message, allowed write scope, public contract, or validation expectation is missing or unclear; reply to project-manager instead of inferring it.
 - Use \`.ai/generated/module-index.json\` to locate approved module source and test files.
@@ -45,6 +45,12 @@ export function renderCoderHarnessRules() {
 - When changing tests, keep assertions tied to the approved behavior contract; do not relax expectations, remove meaningful coverage, or rewrite tests merely to match the current implementation.
 - Record confirmed out-of-scope issues found during implementation in \`.ai/vcm/handoffs/known-issues.md\`.
 
+### Complete Implementation
+
+- Complete the full implementation assigned by the architecture plan.
+- Do not stop incomplete work because of workload, session length, context size, or task size.
+- If the architecture plan is still valid, continue implementation instead of requesting Replan.
+
 ### Handoff
 
 - In the route message back to project-manager, include a \`Scaffold Completion\` section when the architecture plan contains a Scaffold Manifest.
@@ -65,7 +71,7 @@ export function renderCoderHarnessRules() {
 ### Replan And Continuation
 
 - Stop and request Replan through project-manager when the approved plan conflicts with code reality.
-- Request Replan only for architecture, public contract, dependency, phase-boundary, validation-boundary, or durable-doc changes that must be decided before implementation can continue.
+- Request Replan only for architecture, public contract, dependency, task-boundary, validation-boundary, or durable-doc changes that must be decided before implementation can continue.
 - Do not request Replan because of workload, session length, or context size.
 - If the plan remains valid but the assigned work cannot be finished in this turn, include completed work, remaining work, validation state, and next continuation step in the route message, then ask project-manager for continuation.
 - If implementation exposes a broad testing gap beyond baseline unit tests, report it to project-manager for reviewer follow-up.

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

@@ -23,7 +23,7 @@ PM Managed Mode applies only when the user explicitly asks to complete the curre
 
 - PM must drive the task to completion according to the user's request.
 - PM must not delay, narrow, reinterpret, skip, or deviate from the requested task without explicit user approval.
-- Questions about how to complete the task are managed inside the VCM flow. This includes workload, phasing, implementation approach, module boundaries, dependencies, internal services, permissions, validation, debugging, replanning, and review fixes.
+- Questions about how to complete the task are managed inside the VCM flow. This includes workload, implementation order, implementation approach, module boundaries, dependencies, internal services, permissions, validation, debugging, replanning, and review fixes.
 - Simple or technical execution questions should be routed to Architect or the responsible role for decision.
 - Ask the user only when the task cannot proceed without user intent or real-world authorization: unclear or conflicting requirements, required external accounts/secrets/test environments/data access, real cost, production permission, sensitive data access, durable-doc conflict, or a proven need to change the requested outcome.
 - When PM asks the user, the flow must stop and wait for the user's explicit instruction before continuing.
@@ -44,6 +44,20 @@ PM Managed Mode applies only when the user explicitly asks to complete the curre
 - If architect reports that the fix exceeds Debug Mode limits or requires new module, new public surface, or new cross-file callable surface, resume the normal code-change flow: architect plan -> coder -> reviewer.
 - If Debug Mode finds durable docs or known-issues impact, keep the normal docs-sync gate after reviewer.
 
+### Architecture Diagnosis Routing
+
+Within the same task, route to architect Architecture Diagnosis Mode when either condition is true:
+
+- Reviewer rejects the implementation for the second time.
+- Architect Replan is required for the second time.
+
+Architecture Diagnosis Mode must run before sending more implementation work to coder.
+
+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.
+
 ### Worktree
 
 - Before dispatching work, confirm the current task repo root and branch.
@@ -66,14 +80,12 @@ PM may lightly rewrite the user's words to:
 - translate the user's intent into clear role-facing language
 - state whether this is confirmation, rejection, preference, or a small constraint
 
-### Phased Tasks
+### Complete Task Scope
 
-- When architect provides a phased plan, dispatch only one phase at a time.
-- Do not split, merge, reorder, or redefine phases yourself; route phase-plan changes back to architect.
-- Each coder phase must complete its assigned implementation before PM dispatches the next phase.
-- Phase validation may require evidence up to L2, but route by runner: coder gets L0/L1 and explicitly assigned targeted fast L2 only; reviewer gets full L2, integration, multi-node, cross-service, persistence, runtime, public-contract, L3, and L4 gates.
-- Reserve full L3 validation for final task acceptance unless reviewer says a narrow phase smoke is needed.
-- Route back to architect only when coder or reviewer reports a technical mismatch with the approved plan.
+- Once PM starts routing a user request, drive the accepted scope to completion unless the user explicitly changes it.
+- Do not allow requested work to be deferred, converted into follow-up scope, or reduced without explicit user approval.
+- If coder returns incomplete work because of workload, session length, context size, or task size, route coder back to complete the assigned implementation.
+- Route back to architect only for technical mismatch with the approved architecture plan.
 
 ### Flow Gates
 

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

@@ -32,6 +32,8 @@ export function renderReviewerHarnessRules() {
 - Add anti-hardcode coverage when risk warrants it: use non-fixture inputs, boundary values, negative cases, repeated actions, and assertions through public/runtime paths.
 - Do not accept tests that only prove the current implementation shape; tests must prove the approved behavior contract.
 - If task-specific process comments appear in changed code while reviewing behavior, report them as a maintainability gap; task context belongs in handoff artifacts, not durable code comments.
+- Treat architect-flagged public contracts, migrations, auth, data flow, routing, or dependency changes as inputs for reviewer-owned validation design.
+- Record skipped L3 checks in \`.ai/vcm/handoffs/review-report.md\` with the reason.
 - Update \`docs/TESTING.md\` when validation strategy, commands, level mapping, integration/E2E case definitions, selection rules, final-validation cleanup, test gaps, or test expectations change.
 
 ### Testing Documentation
@@ -43,14 +45,6 @@ export function renderReviewerHarnessRules() {
 - Keep historical investigation details, superseded failures, temporary diagnostics, and per-task validation logs out of \`docs/TESTING.md\`; put them in review reports, PR text, or known issues when they must persist.
 - When updating \`docs/TESTING.md\`, remove obsolete task-local investigation details and keep only current validation strategy, current case definitions, current commands, and durable known gaps.
 
-### Phase Validation
-
-- For phase review, run the strongest practical validation up to L2 that is relevant to the phase scope.
-- Reserve full L3 E2E / browser / integration validation for the final phase or whole-task acceptance.
-- Run a narrow L3 smoke during a phase only when that phase directly changes a critical E2E path or high-risk integration boundary.
-- Treat architect-flagged public contracts, migrations, auth, data flow, routing, or dependency changes as inputs for reviewer-owned validation design.
-- Record skipped L3 checks in \`.ai/vcm/handoffs/review-report.md\` with the reason and the planned final validation point.
-
 ### Outputs
 
 - Write \`.ai/vcm/handoffs/review-report.md\` with decision, evidence reviewed, tests added or updated, commands run or checked, validation results, failed expectations, reproduction steps, skipped checks with reasons, coverage gaps, and required follow-ups.

package/dist/backend/templates/harness/vcm-harness-bootstrap-skill.js

@@ -17,7 +17,7 @@ This skill is an operating procedure. It does not replace the deterministic VCM
 1. Generate context when supported: run \`.ai/tools/generate-module-index\`, then run \`.ai/tools/generate-public-surface\` after \`module-index.json\` exists.
 2. Inspect the project:  read \`README.md\`, read \`CLAUDE.md\`, durable project docs, project manifests/config, source layout, tests, and existing validation commands.
 3. Fill project context: add or update non-managed project facts in \`CLAUDE.md\` above the VCM managed block.
-4. Fill durable docs: update \`docs/ARCHITECTURE.md\`, module-level \`ARCHITECTURE.md\` files, and \`docs/TESTING.md\` with detailed project-specific content.
+4. Fill durable docs: update \`docs/ARCHITECTURE.md\`, module-level \`ARCHITECTURE.md\` files for clear non-root module boundaries, and \`docs/TESTING.md\` with detailed project-specific content.
 5. Preserve user-authored content and VCM managed blocks.
 6. Review \`git status\` and \`git diff\`.
 7. Stage only allowed bootstrap harness changes and create a commit in the active task worktree.
@@ -29,7 +29,7 @@ This skill is an operating procedure. It does not replace the deterministic VCM
 - \`docs/ARCHITECTURE.md\`
 - \`docs/TESTING.md\`
 - \`docs/known-issues.md\` only for confirmed durable issues
-- module-level \`ARCHITECTURE.md\` files
+- module-level \`ARCHITECTURE.md\` files for clear non-root module boundaries
 - \`.ai/generated/module-index.json\`
 - \`.ai/generated/public-surface.json\`
 
@@ -55,7 +55,8 @@ This skill is an operating procedure. It does not replace the deterministic VCM
 
 ### Module-Level \`ARCHITECTURE.md\`
 
-- Create or update one module-level \`ARCHITECTURE.md\` for each clear module boundary.
+- Create or update one module-level \`ARCHITECTURE.md\` for each clear non-root module boundary with an \`architectureDoc\` path in \`.ai/generated/module-index.json\`.
+- Do not create a root-level \`ARCHITECTURE.md\` only because the root package exists.
 - Document module boundaries, responsibilities, allowed dependencies, important behavior, important public surface explanations, risks, and update triggers.
 - Keep complete public API listings in \`.ai/generated/public-surface.json\`; module docs should explain meaning and design intent, not duplicate the full generated index.
 

package/package.json

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

package/scripts/harness-tools/generate-module-index

@@ -327,22 +327,21 @@ def build_node_index(project_root: Path, node_root: Path) -> dict:
             layer_by_name[layer_name] = layer
             layers.append(layer)
 
-        layer_by_name[layer_name]["modules"].append(
-            {
-                "name": record["name"],
-                "path": module_path,
-                "manifest": manifest_rel,
-                "architectureDoc": f"{module_path}/ARCHITECTURE.md"
-                if module_path != "."
-                else "ARCHITECTURE.md",
-                "workspaceDependencies": record["workspaceDependencies"],
-                "language": "typescript",
-                "files": {
-                    "source": source_files,
-                    "tests": test_files,
-                },
-            }
-        )
+        module_entry = {
+            "name": record["name"],
+            "path": module_path,
+            "manifest": manifest_rel,
+            "workspaceDependencies": record["workspaceDependencies"],
+            "language": "typescript",
+            "files": {
+                "source": source_files,
+                "tests": test_files,
+            },
+        }
+        if module_path != ".":
+            module_entry["architectureDoc"] = f"{module_path}/ARCHITECTURE.md"
+
+        layer_by_name[layer_name]["modules"].append(module_entry)
 
     return {
         "schemaVersion": 1,
@@ -441,21 +440,20 @@ def build_cargo_index(project_root: Path, cargo_root: Path) -> dict:
             layer_by_name[layer_name] = layer
             layers.append(layer)
 
-        layer_by_name[layer_name]["modules"].append(
-            {
-                "name": record["name"],
-                "path": module_path,
-                "manifest": manifest_rel,
-                "architectureDoc": f"{module_path}/ARCHITECTURE.md"
-                if module_path != "."
-                else "ARCHITECTURE.md",
-                "workspaceDependencies": record["workspaceDependencies"],
-                "files": {
-                    "source": rust_files_under(module_dir, project_root, "src"),
-                    "tests": rust_files_under(module_dir, project_root, "tests"),
-                },
-            }
-        )
+        module_entry = {
+            "name": record["name"],
+            "path": module_path,
+            "manifest": manifest_rel,
+            "workspaceDependencies": record["workspaceDependencies"],
+            "files": {
+                "source": rust_files_under(module_dir, project_root, "src"),
+                "tests": rust_files_under(module_dir, project_root, "tests"),
+            },
+        }
+        if module_path != ".":
+            module_entry["architectureDoc"] = f"{module_path}/ARCHITECTURE.md"
+
+        layer_by_name[layer_name]["modules"].append(module_entry)
 
     return {
         "schemaVersion": 1,