vibe-coding-master 0.7.5 → 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,6 +1,34 @@
+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
@@ -223,16 +251,27 @@ TBD
 
 TBD
 
-## Diagnostic And L0-L3 Validation
+## 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,19 +8,28 @@ ${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.
+- 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.
@@ -42,14 +51,17 @@ ${renderRoleMemoryRules("architect")}
 
 ### 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.
+- \`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.
@@ -61,6 +73,7 @@ ${renderRoleMemoryRules("architect")}
 - \`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
 
@@ -92,14 +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.
-- 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-L3 validation, generated-context status, and remaining failure evidence. 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, 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, final disposition, and the Debug completion evidence path when code was changed.
+- 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
 
@@ -165,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.
@@ -202,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.
@@ -219,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

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

@@ -1,14 +1,13 @@
 export function renderRootClaudeHarnessRules() {
-    return `@.ai/vcm/memory/shared.md
-
-## VCM Start Here
+    return `## 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.
 - \`vcm-route-message\` is the only channel for PM-hub dispatch and reporting among project-manager, architect, coder, and tester. Gate Review and tool-role work use their dedicated VCM skills and controllers. Follow the route skill's write-then-stop rule.
+- Project-manager uses \`vcm-task-state\` to declare the current workflow checkpoint. This state is recoverable context only; flow rules and task artifacts remain authoritative.
 - Use \`vcm-long-running-validation\` for long-running validation. Follow the background job limits below.
 - Use \`vcm-report-harness-issue\` when you notice a reusable VCM harness problem. Record feedback; do not contact Harness Engineer directly.
-- Treat \`.ai/vcm/memory/**\` as read-only. Use \`vcm-propose-memory\` only when VCM assigns a memory proposal during Task Harness Review.
+- The root \`<VCM-memory>\` block is shared project memory. Treat every \`<VCM-memory>\` block as read-only and use \`vcm-propose-memory\` only when VCM assigns a memory proposal during Task Harness Review.
 - Only the user may approve scope reduction, skipped required validation, Gate Review skip or override, skipped required docs sync, accepted unresolved task-scope risk, or weakening of baseline Harness rules. PM may record and route the user's approval but cannot grant it.
 - Project-manager runs \`vcm-gate-review\` unconditionally at every Gate Review trigger point and on VCM Gate Review callbacks; the tool reports the authoritative enable state.
 
@@ -28,14 +27,18 @@ If a reusable harness problem is suspected, it is enough to record a concise fee
 
 ## VCM Durable Project Docs
 
+- Durable project docs describe current project truth. Replace superseded content instead of appending task chronology, investigation history, role verdicts, commit history, or completed-work reports; task artifacts, Git, and PRs preserve that history.
 - \`docs/GLOSSARY.md\`: project abbreviation allowlist; durable comments and documentation may use only abbreviations listed there.
 - \`docs/CODING_STANDARDS.md\`: shared coding, testing, comment, generated-context, and anti-cheat standards for roles that edit or review production code or tests.
 - \`docs/ARCHITECTURE.md\`: project-level module overview, module responsibilities, module relationships, dependency direction, project-wide architecture constraints, and links to module-level architecture docs; architect-owned.
-- \`<module>/ARCHITECTURE.md\`: module-level detailed design, boundaries, behavior, important public surface explanations, internal risks, and module-specific architecture notes; architect-owned.
+- \`<module>/ARCHITECTURE.md\`: current module responsibilities, boundaries, data flow, lifecycle, invariants, collaboration contracts, important public surface meaning, risks, and update triggers; architect-owned.
 - \`docs/TESTING.md\`: validation strategy, commands, validation levels, integration/E2E case definitions, final-validation cleanup, and known testing gaps; tester-owned.
-- \`docs/known-issues.md\`: durable known issues and accepted limitations; architect-owned.
+- \`docs/known-issues.md\`: current unresolved durable issues and accepted limitations; remove resolved entries rather than retaining their history; architect-owned.
+- \`docs/plans/**\`: active or planned work only. Remove a plan from this collection when its work is complete; Git and PR history preserve the completed plan.
 - \`.ai/generated/module-index.json\`: generated module index; use it to find layers, modules, manifests, module docs, source files, test files, and workspace dependencies.
 - \`.ai/generated/public-surface.json\`: generated public surface index; use it to inspect module-to-module public APIs, routes, and source evidence.
+- Generated context is the source of truth for module inventories, source/test file inventories, dependency lists, and complete public-surface listings. Durable prose explains architecture and contract meaning instead of independently maintaining those machine facts.
+- Run \`.ai/tools/check-durable-docs\` after bootstrap or durable-doc synchronization and before final acceptance when durable docs changed.
 
 ## VCM Glossary Policy
 
@@ -46,36 +49,29 @@ If a reusable harness problem is suspected, it is enough to record a concise fee
 ## VCM Task Flow
 
 - All standard workflow routes among project-manager, architect, coder, and tester are PM-hub routes. Project-manager starts and advances every flow; architect, coder, and tester report blockers, failures, conflicts, incomplete work, and findings back to project-manager.
-- Code changes use: \`project-manager -> architect -> coder -> tester -> architect docs sync -> project-manager final acceptance\`.
-- Debug Mode and Architecture Diagnosis Mode may be either the task's primary flow or a branch inside an active main flow.
-- When either mode is entered while a main flow is active, project-manager suspends that flow, records its resume point, runs the mode through code-diff Gate Review and tester validation when code changes are produced, then returns to the recorded resume point. The branch does not run final acceptance.
-- When a task begins with Debug Mode or Architecture Diagnosis Mode and produces code changes, that mode is the task's primary code-delivery flow and continues through code-diff Gate Review, tester validation, architect docs sync, and project-manager final acceptance.
-- A primary Architecture Diagnosis flow that produces analysis only completes from the diagnosis result without final acceptance.
-- Docs-only changes use: \`project-manager -> architect -> project-manager completion\`.
-- Test-only or validation-only work uses: \`project-manager -> tester -> project-manager completion\`.
+- Code changes use: \`project-manager -> architect interview -> architect planning -> coder -> tester -> architect docs sync -> project-manager final acceptance\`.
+- Architect Debug Mode runs inside either Architect Debug Flow or Architect Debug Branch. Architecture Diagnosis Mode runs inside either Architecture Diagnosis Flow or Architecture Diagnosis Branch.
+- Architect Debug Flow and an Architecture Diagnosis Flow that produces code changes continue through code-diff Gate Review, tester validation, architect docs sync, and project-manager final acceptance. An analysis-only Architecture Diagnosis Flow completes from the diagnosis result.
+- Architect Debug Branch and Architecture Diagnosis Branch preserve the active parent flow and resume point, then return there after successful validation. They do not run their own final acceptance.
+- Docs-Only Flow uses: \`project-manager -> architect -> project-manager completion\`.
+- Validation-Only Flow uses: \`project-manager -> tester -> validation-adequacy Gate Review -> project-manager completion\`.
+- Communication-Only Flow uses: \`project-manager response or relay -> completion\`.
 - Gate Review is PM-triggered at its defined trigger points; the tool decides whether review is enabled or required.
-- Final acceptance closes only a complete code-delivery flow; it never closes a Debug or Architecture Diagnosis branch inside another flow.
-- PR preparation starts only after the active delivery flow completes; every complete code-delivery flow requires final acceptance to pass.
-- If docs/test/validation-only work reveals required code, architecture, public contract, dependency, durable-doc, or test-strategy changes, project-manager routes through the full code-change flow.
+- Final acceptance closes only a complete code-delivery flow; it never closes Architect Debug Branch or Architecture Diagnosis Branch.
+- PR-Preparation Flow starts only after the active delivery flow completes; every complete code-delivery flow requires final acceptance to pass.
+- If Docs-Only Flow or Validation-Only Flow reveals that the accepted outcome requires production-code, runtime-behavior, public-contract, dependency, or system-architecture changes, project-manager routes through the full Code-Change Flow.
 - Detailed failure handling and route decisions belong to project-manager rules.
 - Keep role outputs under \`.ai/vcm/handoffs/\`.
 - Gate Review Gate reports live under \`.ai/vcm/gate-reviews/\` and are VCM-managed task evidence.
 - Runtime task records and handoffs under \`.ai/vcm/\` are temporary. Durable facts must move into code, tests, PR text, commit history, or long-term docs.
 - Only architect writes \`.ai/vcm/handoffs/known-issues.md\`; other roles report unresolved findings back through their own handoff artifacts.
 
-## Direct User Messages
-
-- These rules apply when the user sends a message directly to architect, coder, or tester.
-- PM remains the routing owner during direct role discussion.
-- The role may discuss, clarify, or answer questions within its current scope, but direct discussion is not a flow instruction by itself.
-- Do not treat exploratory discussion, tentative wording, disagreement, preference discussion, or "what if" analysis as approved scope, approved plan, or a route decision.
-- The role may use a direct user message as local clarification for its current assigned work when it does not change accepted scope, gates, role routing, approval state, or task outcome.
-- If the direct user message may change scope, plan, priority, approval, external authorization, or next-route decision, the role must ask the user in its own session for explicit confirmation and wait for it before reporting to project-manager.
-- Explicit confirmation means the user clearly approves or instructs the new plan, scope, decision, or route, such as "confirmed", "use this plan", "change it to this", "approve", or equivalent wording in context.
-- After explicit confirmation, the role must report the confirmed change to project-manager with \`vcm-route-message\` and stop. PM decides the next route.
-- A direct user message must not let the role start a new task, skip gates, approve exceptions, trigger another role, or close the task.
-- The role's final result must still go back to project-manager.
-- Direct Gate Reviewer discussion may clarify its report but cannot change the gate decision or task flow; flow changes must be given to project-manager. Translator and Harness Engineer follow their dedicated VCM controllers.
+## User Communication
+
+- A message without a VCM marker is user communication.
+- When the user asks a question, answer only.
+- Do not modify files, run tests, update artifacts, send messages, report to project-manager, or advance the workflow unless the user explicitly instructs that action.
+- Perform only the actions explicitly requested by the user and remain within the current role's responsibilities.
 
 ## VCM Validation Levels