vibe-coding-master 0.7.16 → 0.7.17

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

@@ -130,6 +130,11 @@ export function createMessageService(deps) {
             }).catch(() => undefined);
         }
         scheduleDispatchConfirmation(input, delivered, session.id);
+        await deps.onRouteDelivered?.({
+            repoRoot: input.repoRoot,
+            taskSlug: input.taskSlug,
+            message: delivered
+        });
         return {
             message: delivered,
             delivered: true,

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

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import path from "node:path";
 import { ROLE_NAMES, isDispatchableRole } from "../../shared/constants.js";
 import { CCR_GPT_SESSION_MODEL, isCcrSessionModel } from "../../shared/types/session.js";
@@ -80,7 +81,7 @@ export function createSessionService(deps) {
                 ? claudeTranscriptPath(taskRepoRoot, resumeClaudeSessionId, persisted?.claudeConfigDir)
                 : undefined;
         const startCommand = {
-            ...deps.claude.buildRoleStartCommand(role, config.claudeCommand, permissionMode, resumeClaudeSessionId, launchMode === "resume", model, effort, modelSettingsOverride),
+            ...deps.claude.buildRoleStartCommand(role, config.claudeCommand, permissionMode, resumeClaudeSessionId, launchMode === "resume", model, effort, modelSettingsOverride, input.appendSystemPrompt),
             cwd: taskRepoRoot
         };
         const runtimeSession = await deps.runtime.createSession({
@@ -97,7 +98,7 @@ export function createSessionService(deps) {
                 VCM_TASK_SLUG: taskSlug,
                 VCM_ROLE: role,
                 VCM_SESSION_ID: claudeSessionId || undefined
-            }, modelEnvironment),
+            }, modelEnvironment, buildUsageTelemetryEnvironment(deps.apiUrl, role, model)),
             cols: input.cols,
             rows: input.rows
         });
@@ -224,7 +225,7 @@ export function createSessionService(deps) {
                 VCM_TASK_SLUG: PROJECT_TRANSLATOR_SCOPE,
                 VCM_ROLE: TRANSLATOR_ROLE,
                 VCM_SESSION_ID: claudeSessionId || undefined
-            }, modelEnvironment),
+            }, modelEnvironment, buildUsageTelemetryEnvironment(deps.apiUrl, TRANSLATOR_ROLE, model)),
             cols: input.cols,
             rows: input.rows
         });
@@ -337,7 +338,7 @@ export function createSessionService(deps) {
                 VCM_TASK_SLUG: PROJECT_HARNESS_ENGINEER_SCOPE,
                 VCM_ROLE: HARNESS_ENGINEER_ROLE,
                 VCM_SESSION_ID: claudeSessionId || undefined
-            }, modelEnvironment),
+            }, modelEnvironment, buildUsageTelemetryEnvironment(deps.apiUrl, HARNESS_ENGINEER_ROLE, model)),
             cols: input.cols,
             rows: input.rows
         });
@@ -529,7 +530,7 @@ export function createSessionService(deps) {
                 VCM_TASK_SLUG: normalizeProjectScopedRecordForPersistence(session).taskSlug,
                 VCM_ROLE: session.role,
                 VCM_SESSION_ID: session.claudeSessionId
-            }, modelEnvironment)
+            }, modelEnvironment, buildUsageTelemetryEnvironment(deps.apiUrl, session.role, model))
         });
         if ((await waitForSessionInputReady(runtimeSession.id)) === "exited") {
             deps.registry.remove(runtimeSession.id);
@@ -1536,13 +1537,40 @@ function formatClaudeCdCommand(targetCwd) {
 function isExitedStatus(status) {
     return status === "exited" || status === "crashed" || status === "missing";
 }
-function withClaudeCodeRuntimeEnv(env, modelEnvironment = {}) {
+function withClaudeCodeRuntimeEnv(env, modelEnvironment = {}, telemetryEnvironment = {}) {
     return {
         ...env,
         ...modelEnvironment,
+        ...telemetryEnvironment,
         CLAUDE_CODE_DISABLE_AUTO_MEMORY
     };
 }
+function buildUsageTelemetryEnvironment(apiUrl, role, model) {
+    const disabled = {
+        CLAUDE_CODE_ENABLE_TELEMETRY: undefined,
+        OTEL_LOGS_EXPORTER: "none",
+        OTEL_METRICS_EXPORTER: "none",
+        OTEL_TRACES_EXPORTER: "none",
+        OTEL_EXPORTER_OTLP_LOGS_PROTOCOL: undefined,
+        OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: undefined,
+        OTEL_RESOURCE_ATTRIBUTES: undefined,
+        OTEL_LOG_USER_PROMPTS: "0",
+        OTEL_LOG_ASSISTANT_RESPONSES: "0",
+        OTEL_LOG_TOOL_DETAILS: "0",
+        OTEL_LOG_RAW_API_BODIES: "0"
+    };
+    if (!apiUrl || isCcrSessionModel(model)) {
+        return disabled;
+    }
+    return {
+        ...disabled,
+        CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+        OTEL_LOGS_EXPORTER: "otlp",
+        OTEL_EXPORTER_OTLP_LOGS_PROTOCOL: "http/json",
+        OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: `${apiUrl.replace(/\/+$/, "")}/api/telemetry/v1/logs`,
+        OTEL_RESOURCE_ATTRIBUTES: `vcm.role=${role},vcm.launch_id=${randomUUID()}`
+    };
+}
 function delay(ms) {
     if (ms <= 0) {
         return Promise.resolve();

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

@@ -5,6 +5,7 @@ export function createTaskCloseService(deps) {
         async closeTask(repoRoot, taskSlug) {
             const task = await deps.taskService.markTaskCleaned(repoRoot, taskSlug);
             const warnings = [];
+            deps.architectRestartService?.clear(repoRoot, taskSlug);
             await stopTaskRoleSessions(repoRoot, taskSlug, warnings);
             await bestEffort("Unable to stop task translation runtime", () => deps.translationService.stopTask(getTaskRuntimeRepoRoot(task), taskSlug, { clearCache: true }), warnings);
             await bestEffort("Unable to clear task round runtime", () => deps.roundService.stopTask(taskSlug), warnings);

package/dist/backend/services/usage-analytics-service.js

@@ -0,0 +1,346 @@
+import path from "node:path";
+import { ROLE_NAMES, isRoleName } from "../../shared/constants.js";
+const USAGE_FILE = path.join("telemetry", "usage.json");
+export function createUsageAnalyticsService(deps) {
+    const now = deps.now ?? (() => new Date().toISOString());
+    const writeQueues = new Map();
+    return {
+        async ingest(taskRepoRoot, stateRoot, payload) {
+            const events = extractApiRequestEvents(payload);
+            if (events.length === 0) {
+                return;
+            }
+            const usagePath = getUsagePath(taskRepoRoot, stateRoot);
+            await enqueueWrite(writeQueues, usagePath, async () => {
+                const state = await loadState(deps.fs, usagePath);
+                const seen = new Set(state.seenEvents);
+                let changed = false;
+                for (const event of events) {
+                    if (seen.has(event.eventKey)) {
+                        continue;
+                    }
+                    seen.add(event.eventKey);
+                    state.seenEvents.push(event.eventKey);
+                    addEvent(state, event);
+                    changed = true;
+                }
+                if (!changed) {
+                    return;
+                }
+                state.updatedAt = now();
+                await deps.fs.writeJsonAtomic(usagePath, state);
+            });
+        },
+        async getReport(taskRepoRoot, stateRoot, taskSlug) {
+            const usagePath = getUsagePath(taskRepoRoot, stateRoot);
+            await writeQueues.get(usagePath);
+            if (!(await deps.fs.pathExists(usagePath))) {
+                return emptyReport(taskSlug);
+            }
+            const state = normalizeStoredState(await deps.fs.readJson(usagePath));
+            return toReport(taskSlug, state);
+        }
+    };
+}
+function extractApiRequestEvents(payload) {
+    if (!isObject(payload) || !Array.isArray(payload.resourceLogs)) {
+        return [];
+    }
+    const events = [];
+    for (const resourceLog of payload.resourceLogs) {
+        if (!isObject(resourceLog)) {
+            continue;
+        }
+        const resourceAttributes = readAttributes(isObject(resourceLog.resource) ? resourceLog.resource.attributes : undefined);
+        if (!Array.isArray(resourceLog.scopeLogs)) {
+            continue;
+        }
+        for (const scopeLog of resourceLog.scopeLogs) {
+            if (!isObject(scopeLog) || !Array.isArray(scopeLog.logRecords)) {
+                continue;
+            }
+            for (const logRecord of scopeLog.logRecords) {
+                if (!isObject(logRecord)) {
+                    continue;
+                }
+                const attributes = {
+                    ...resourceAttributes,
+                    ...readAttributes(logRecord.attributes)
+                };
+                if (readString(attributes["event.name"]) !== "api_request") {
+                    continue;
+                }
+                const roleValue = readString(attributes["vcm.role"]);
+                const launchId = readString(attributes["vcm.launch_id"]);
+                if (!roleValue || !isRoleName(roleValue) || !launchId) {
+                    continue;
+                }
+                const model = normalizeModel(readString(attributes.model));
+                if (isCcrModel(model)) {
+                    continue;
+                }
+                const sequence = readInteger(attributes["event.sequence"]);
+                const sessionId = readString(attributes["session.id"]) || launchId;
+                const requestId = readString(attributes.request_id);
+                const timestamp = readString(logRecord.timeUnixNano) || readString(logRecord.observedTimeUnixNano);
+                const fallbackIdentity = [sessionId, requestId, timestamp, model].join(":");
+                const eventKey = `${launchId}:${sequence ?? fallbackIdentity}`;
+                const costUsdMicros = readNonNegativeInteger(attributes.cost_usd_micros)
+                    ?? Math.round((readNonNegativeNumber(attributes.cost_usd) ?? 0) * 1_000_000);
+                events.push({
+                    eventKey,
+                    role: roleValue,
+                    model,
+                    sessionId,
+                    inputTokens: readNonNegativeInteger(attributes.input_tokens) ?? 0,
+                    outputTokens: readNonNegativeInteger(attributes.output_tokens) ?? 0,
+                    cacheReadTokens: readNonNegativeInteger(attributes.cache_read_tokens) ?? 0,
+                    cacheCreationTokens: readNonNegativeInteger(attributes.cache_creation_tokens) ?? 0,
+                    costUsdMicros
+                });
+            }
+        }
+    }
+    return events;
+}
+function addEvent(state, event) {
+    addTotals(state.totals, event);
+    state.byRole[event.role] ??= emptyStoredTotals();
+    addTotals(state.byRole[event.role], event);
+    state.byModel[event.model] ??= emptyStoredTotals();
+    addTotals(state.byModel[event.model], event);
+    addUnique(state.sessionsByRole, event.role, event.sessionId);
+    addUnique(state.sessionsByModel, event.model, event.sessionId);
+}
+function addTotals(target, event) {
+    target.inputTokens += event.inputTokens;
+    target.outputTokens += event.outputTokens;
+    target.cacheReadTokens += event.cacheReadTokens;
+    target.cacheCreationTokens += event.cacheCreationTokens;
+    target.costUsdMicros += event.costUsdMicros;
+    target.requestCount += 1;
+}
+function addUnique(target, key, value) {
+    const values = target[key] ?? [];
+    if (!values.includes(value)) {
+        values.push(value);
+    }
+    target[key] = values;
+}
+async function loadState(fs, usagePath) {
+    if (!(await fs.pathExists(usagePath))) {
+        return emptyStoredState();
+    }
+    return normalizeStoredState(await fs.readJson(usagePath));
+}
+function normalizeStoredState(input) {
+    return {
+        version: 1,
+        updatedAt: typeof input.updatedAt === "string" ? input.updatedAt : new Date(0).toISOString(),
+        seenEvents: Array.isArray(input.seenEvents) ? input.seenEvents.filter((value) => typeof value === "string") : [],
+        sessionsByRole: normalizeRoleStringLists(input.sessionsByRole),
+        sessionsByModel: normalizeStringLists(input.sessionsByModel),
+        totals: normalizeStoredTotals(input.totals),
+        byRole: normalizeRoleTotals(input.byRole),
+        byModel: normalizeModelTotals(input.byModel)
+    };
+}
+function normalizeRoleStringLists(input) {
+    if (!isObject(input)) {
+        return {};
+    }
+    const result = {};
+    for (const role of ROLE_NAMES) {
+        const values = input[role];
+        if (Array.isArray(values)) {
+            result[role] = values.filter((value) => typeof value === "string");
+        }
+    }
+    return result;
+}
+function normalizeStringLists(input) {
+    const result = {};
+    if (!isObject(input)) {
+        return result;
+    }
+    for (const [key, values] of Object.entries(input)) {
+        if (isSafeGroupKey(key) && Array.isArray(values)) {
+            result[key] = values.filter((value) => typeof value === "string");
+        }
+    }
+    return result;
+}
+function normalizeRoleTotals(input) {
+    if (!isObject(input)) {
+        return {};
+    }
+    const result = {};
+    for (const role of ROLE_NAMES) {
+        if (isObject(input[role])) {
+            result[role] = normalizeStoredTotals(input[role]);
+        }
+    }
+    return result;
+}
+function normalizeModelTotals(input) {
+    const result = {};
+    if (!isObject(input)) {
+        return result;
+    }
+    for (const [key, totals] of Object.entries(input)) {
+        if (isSafeGroupKey(key) && isObject(totals)) {
+            result[key] = normalizeStoredTotals(totals);
+        }
+    }
+    return result;
+}
+function normalizeStoredTotals(input) {
+    const value = isObject(input) ? input : {};
+    return {
+        inputTokens: readNonNegativeInteger(value.inputTokens) ?? 0,
+        outputTokens: readNonNegativeInteger(value.outputTokens) ?? 0,
+        cacheReadTokens: readNonNegativeInteger(value.cacheReadTokens) ?? 0,
+        cacheCreationTokens: readNonNegativeInteger(value.cacheCreationTokens) ?? 0,
+        costUsdMicros: readNonNegativeInteger(value.costUsdMicros) ?? 0,
+        requestCount: readNonNegativeInteger(value.requestCount) ?? 0
+    };
+}
+function toReport(taskSlug, state) {
+    const allSessions = new Set(Object.values(state.sessionsByRole).flatMap((values) => values ?? []));
+    const byRole = ROLE_NAMES.map((role) => ({
+        role,
+        ...toPublicTotals(state.byRole[role] ?? emptyStoredTotals(), state.sessionsByRole[role]?.length ?? 0)
+    }));
+    const byModel = Object.keys(state.byModel)
+        .sort((left, right) => left.localeCompare(right))
+        .map((model) => ({
+        model,
+        ...toPublicTotals(state.byModel[model], state.sessionsByModel[model]?.length ?? 0)
+    }));
+    return {
+        version: 1,
+        taskSlug,
+        updatedAt: state.updatedAt,
+        totals: toPublicTotals(state.totals, allSessions.size),
+        byRole,
+        byModel
+    };
+}
+function emptyReport(taskSlug) {
+    return {
+        version: 1,
+        taskSlug,
+        updatedAt: null,
+        totals: toPublicTotals(emptyStoredTotals(), 0),
+        byRole: ROLE_NAMES.map((role) => ({ role, ...toPublicTotals(emptyStoredTotals(), 0) })),
+        byModel: []
+    };
+}
+function toPublicTotals(totals, sessionCount) {
+    return {
+        inputTokens: totals.inputTokens,
+        outputTokens: totals.outputTokens,
+        cacheReadTokens: totals.cacheReadTokens,
+        cacheCreationTokens: totals.cacheCreationTokens,
+        costUsd: totals.costUsdMicros / 1_000_000,
+        requestCount: totals.requestCount,
+        sessionCount
+    };
+}
+function emptyStoredState() {
+    return {
+        version: 1,
+        updatedAt: new Date(0).toISOString(),
+        seenEvents: [],
+        sessionsByRole: {},
+        sessionsByModel: {},
+        totals: emptyStoredTotals(),
+        byRole: {},
+        byModel: {}
+    };
+}
+function emptyStoredTotals() {
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        costUsdMicros: 0,
+        requestCount: 0
+    };
+}
+function getUsagePath(taskRepoRoot, stateRoot) {
+    return path.join(taskRepoRoot, stateRoot, USAGE_FILE);
+}
+async function enqueueWrite(queues, key, operation) {
+    const previous = queues.get(key) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(operation);
+    queues.set(key, current);
+    try {
+        await current;
+    }
+    finally {
+        if (queues.get(key) === current) {
+            queues.delete(key);
+        }
+    }
+}
+function readAttributes(input) {
+    const result = {};
+    if (!Array.isArray(input)) {
+        return result;
+    }
+    for (const entry of input) {
+        if (!isObject(entry) || typeof entry.key !== "string") {
+            continue;
+        }
+        result[entry.key] = readAnyValue(entry.value);
+    }
+    return result;
+}
+function readAnyValue(input) {
+    if (!isObject(input)) {
+        return input;
+    }
+    for (const key of ["stringValue", "intValue", "doubleValue", "boolValue"]) {
+        if (key in input) {
+            return input[key];
+        }
+    }
+    return undefined;
+}
+function readString(input) {
+    if (typeof input === "string") {
+        return input.trim() || undefined;
+    }
+    if (typeof input === "number" || typeof input === "bigint") {
+        return String(input);
+    }
+    return undefined;
+}
+function readInteger(input) {
+    const value = typeof input === "number" ? input : typeof input === "string" ? Number(input) : Number.NaN;
+    return Number.isSafeInteger(value) ? value : undefined;
+}
+function readNonNegativeInteger(input) {
+    const value = readInteger(input);
+    return value !== undefined && value >= 0 ? value : undefined;
+}
+function readNonNegativeNumber(input) {
+    const value = typeof input === "number" ? input : typeof input === "string" ? Number(input) : Number.NaN;
+    return Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function normalizeModel(input) {
+    const model = input?.slice(0, 200).trim();
+    return model && isSafeGroupKey(model) ? model : "unknown";
+}
+function isCcrModel(model) {
+    const normalized = model.toLowerCase();
+    return normalized.startsWith("gpt-") || normalized.startsWith("ccr:") || normalized.includes("codex api/");
+}
+function isSafeGroupKey(value) {
+    return value !== "__proto__" && value !== "prototype" && value !== "constructor";
+}
+function isObject(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input);
+}

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

@@ -8,7 +8,7 @@ ${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.
+- Own \`.ai/vcm/handoffs/architecture-brief.md\` and \`.ai/vcm/handoffs/architecture-evidence.md\` during Architect Interview and preserve them as planning inputs.
 - 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.
@@ -21,15 +21,15 @@ ${renderRoleMemoryRules("architect")}
 
 ### 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.
+- Before the first Architecture Planning step of Code-Change Flow, use \`vcm-architecture-interview\` and complete \`.ai/vcm/handoffs/architecture-brief.md\` and \`.ai/vcm/handoffs/architecture-evidence.md\`.
 - 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.
+- After confirmation and evidence completion, report both artifacts to project-manager and stop. Project-manager must route Architect planning separately.
 
 ### Planning Inputs
 
-- 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 the role message, confirmed \`.ai/vcm/handoffs/architecture-brief.md\`, complete \`.ai/vcm/handoffs/architecture-evidence.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.
@@ -45,13 +45,13 @@ ${renderRoleMemoryRules("architect")}
 - 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.
+- Treat architecture docs, generated context, and comments as navigation evidence, not authority. Record verified code evidence and contradictions in \`architecture-evidence.md\`.
 - 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.
+- Do not mark \`Architecture Evidence Status: complete\`, 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\`.
+- Do not begin Architecture Decision, Code Scaffolding, or a complete architecture plan unless \`architecture-brief.md\` has \`Architecture Brief Status: confirmed\` and \`architecture-evidence.md\` has \`Architecture Evidence Status: complete\`.
 - 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 every \`create\`, \`change\`, and \`delete\` ledger item, every new or changed non-private callable surface, contract comments, and all \`VCM:CODE\` placeholders have been scaffolded and committed, and the scaffolded workspace passes the project's compile/typecheck L0 check.
@@ -59,8 +59,8 @@ ${renderRoleMemoryRules("architect")}
 
 #### Planning Work Plan
 
-- When starting architecture planning for a confirmed brief, first write a \`Current Code Reality / Scope Discovery\` row to \`.ai/vcm/handoffs/planning-progress.md\`, with its scope, deliverable, done criterion, and status. Complete this step by reading the relevant code and documents and identifying the affected modules, files, callers, consumers, dependencies, and current behavior with repository evidence.
-- After \`Current Code Reality / Scope Discovery\` is complete, add the remaining planning steps: one head step for cross-module work (architecture decision, boundaries, ownership, invariants, build-configuration proofs), one middle step per affected module from the module index in dependency order — split a module into per-file steps when it exceeds one round — and one tail step for cross-module wiring, whole-plan ledger reconciliation, and final build evidence. A small task degrades to head, one middle step, and tail.
+- When starting architecture planning, first write an \`Architecture Evidence Verification\` row to \`.ai/vcm/handoffs/planning-progress.md\`, with the evidence artifact, verified worktree revision, done criterion, and status. Complete it by checking that the evidence covers the accepted feature boundary and still matches the current worktree.
+- After \`Architecture Evidence Verification\` is complete, add the remaining planning steps: one head step for cross-module work (architecture decision, boundaries, ownership, invariants, build-configuration proofs), one middle step per affected module from the module index in dependency order — split a module into per-file steps when it exceeds one round — and one tail step for cross-module wiring, whole-plan ledger reconciliation, and final build evidence. A small task degrades to head, one middle step, and tail.
 - Bind every step to repository facts and machine checks: scope is module or file paths from the module index; deliverable is plan sections or ledger ID ranges; done criterion is a tool output or recorded check result — never a self-assessment.
 - Update \`planning-progress.md\` at the end of every planning round: mark completed steps with their evidence and leave remaining steps unchanged. Do not shrink, merge, or drop a remaining step without recording the change and its reason.
 - If the round ends before all steps are done, report \`Planning Result: incomplete\` with the progress record; project-manager routes continuation. Never compress remaining enumeration or scaffolding into summary rows to reach \`Planning Result: complete\` within the current round — an honest \`incomplete\` with recorded progress is the required outcome.
@@ -72,7 +72,7 @@ ${renderRoleMemoryRules("architect")}
 - Use \`Planning Result: complete\` only when: the plan document is complete; the Scaffold Manifest ledger reconciles one to one against the committed markers; and \`Scaffold Build Evidence\` records a green compile/typecheck run at the current scaffold commit hash. 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 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. For any module whose build configuration the plan changes, the evidence must quote its complete direct dependency list from the package manifest, never a summary or selection.
+- \`Current Code Reality\`: cite \`architecture-evidence.md\` and summarize only the verified facts that constrain the architecture decision. Do not duplicate the full evidence inventory. For any module whose build configuration the plan changes, the evidence artifact must quote its complete direct dependency list from the package manifest, never a summary or selection.
 - Any enumeration the plan presents as complete over the codebase — call-site inventories, module or file lists, symbol sets — must either record the deterministic, repository-local command that generates it (run at the scaffold commit, the set transcribed from its output) or be explicitly marked as judgment-derived with the evidence basis for its completeness. A complete-claimed enumeration with neither is not evidence.
 - \`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, durable comment needs, and every non-private callable surface intended for use outside its file.
@@ -94,6 +94,9 @@ ${renderRoleMemoryRules("architect")}
 
 #### Code Scaffolding
 
+- Use the Agent tool to invoke \`vcm-architect-scaffold-worker\` in the foreground after the plan and Scaffold Manifest are complete. Give it the exact plan path and require it to return before this Architect turn continues.
+- Use one scaffold worker. Do not run it in the background or end the Architect turn while it is active.
+- Review the worker commit, actual diff, callable surfaces, marker placement, ledger reconciliation, and L0 results yourself. Architect owns every final scaffold claim and must correct any worker error before marking planning complete.
 - Create or update only the minimum module/file scaffolding needed to make boundaries, callable surfaces, and placeholders unambiguous. Minimum limits depth (no business implementation), never breadth: every \`create\`, \`change\`, and \`delete\` item must be scaffolded.
 - When a required configuration, package manifest, or build-definition change cannot safely contain a \`VCM:CODE\` marker, complete and commit it directly as Architect-owned scaffold work. Record it in the Module/File Plan and Scaffold Build Evidence. Do not add it to the Scaffold Manifest.
 - When the plan introduces a new cross-module call path or seam — a module invoking surfaces it does not invoke today — scaffold one wired exemplar that materializes the full path shape: the imports, interface implementations, and conditional-compilation gating the intended body needs, with placeholder bodies only. Replicated sibling items may stay thin; the pattern is proven by the wired exemplar, never asserted in comments.
@@ -108,6 +111,11 @@ ${renderRoleMemoryRules("architect")}
 - 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.
 
+#### Planning Completion
+
+- After the complete plan, scaffold, reconciliation, L0 evidence, and commits are ready, use the \`restart-architect\` skill before writing the completed Architect-to-PM route message.
+- After VCM reports the restart is scheduled, write the route message with both architecture artifacts and the plan, then end the turn. Do not wait for or inspect the replacement session.
+
 ### Complete Task Planning
 
 - Plan the full accepted task scope routed by PM.

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

@@ -0,0 +1,23 @@
+export function renderArchitectScaffoldWorkerHarnessRules() {
+    return `
+## VCM Architect Scaffold Worker Rules
+
+You are \`vcm-architect-scaffold-worker\`, a foreground subagent invoked by Architect after the architecture plan and Scaffold Manifest are complete.
+
+### Scope
+
+- Execute only the scaffold work assigned by Architect from the current \`.ai/vcm/handoffs/architecture-plan.md\`.
+- Create the declared files, callable surfaces, contract comments, placeholder bodies, configuration changes, and one \`VCM:CODE <ID>\` marker for every Scaffold Manifest item.
+- Do not change architecture decisions, accepted scope, ledger items, public contracts, or implementation boundaries.
+- Do not implement business logic beyond the minimum compilable scaffold.
+- Follow \`docs/CODING_STANDARDS.md\` for every code or test edit.
+
+### Validation And Commit
+
+- Run \`.ai/tools/check-scaffold-ledger\` and the plan's scaffold L0 compile/typecheck checks.
+- Commit only the scaffold changes after the ledger reconciles and required checks pass.
+- Return the commit hash, changed files, ledger result, and exact check results to Architect.
+- If the assigned scaffold cannot be completed, return the concrete failure evidence without changing the plan.
+
+Architect reviews the worker's commit and remains responsible for the final scaffold, plan, and evidence.`;
+}

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

@@ -84,7 +84,7 @@ If a reusable harness problem is suspected, it is enough to record a concise fee
 ## VCM Worktree Policy
 
 - Use one branch, one worktree, one handoff directory, and one PR or final patch per VCM-managed task.
-- VCM workflow role handoffs run sequentially in the same task worktree. Coder-managed workers may run concurrently within the Coder turn.
+- VCM workflow role handoffs run sequentially in the same task worktree. Coder-managed workers may run concurrently within the Coder turn; Architect may run one foreground scaffold worker inside its planning turn.
 - If \`git status\` shows uncommitted changes, commit them before handing off to another role.
 `;
 }

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

@@ -63,7 +63,8 @@ automates it). Run this on every review round, including revision rounds:
 
 For \`architecture-plan\`, reconstruct the proposed architecture and look for
 design flaws before checking formatting. Read the confirmed
-\`.ai/vcm/handoffs/architecture-brief.md\`, \`.ai/vcm/handoffs/architecture-plan.md\`,
+\`.ai/vcm/handoffs/architecture-brief.md\`, \`.ai/vcm/handoffs/architecture-evidence.md\`,
+\`.ai/vcm/handoffs/architecture-plan.md\`,
 \`.claude/agents/architect.md\`, root \`CLAUDE.md\`, \`docs/ARCHITECTURE.md\`,
 affected module \`ARCHITECTURE.md\` files, \`.ai/generated/module-index.json\`,
 \`.ai/generated/public-surface.json\` when public surface may change, and the
@@ -446,7 +447,11 @@ REPORTS = {
     "code-diff": ".ai/vcm/gate-reviews/code-diff-review.md",
 }
 SOURCE_ARTIFACTS = {
-    "architecture-plan": [".ai/vcm/handoffs/architecture-plan.md"],
+    "architecture-plan": [
+        ".ai/vcm/handoffs/architecture-brief.md",
+        ".ai/vcm/handoffs/architecture-evidence.md",
+        ".ai/vcm/handoffs/architecture-plan.md",
+    ],
     "validation-adequacy": [
         ".ai/vcm/handoffs/architecture-plan.md",
         ".ai/vcm/handoffs/test-report.md",

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

@@ -88,7 +88,7 @@ PM may leave this path only through the allowed branches below.
 
 #### Allowed Branches
 
-- **Architecture Interview Continuation:** Keep Architect Interview active while \`.ai/vcm/handoffs/architecture-brief.md\` is \`interviewing\`. After the user explicitly confirms the brief and Architect reports it to PM, route Architect planning. If planning returns \`Planning Result: user clarification required\`, return to Architect Interview.
+- **Architecture Interview Continuation:** Keep Architect Interview active while \`.ai/vcm/handoffs/architecture-brief.md\` is \`interviewing\` or \`.ai/vcm/handoffs/architecture-evidence.md\` is incomplete. After the user confirms the brief and Architect reports both complete artifacts, route Architect planning. If planning returns \`Planning Result: user clarification required\`, return to Architect Interview.
 - **Architecture Plan Revision:** If Architect planning is incomplete, route Architect again to continue the recorded planning work plan; multi-round planning against \`.ai/vcm/handoffs/planning-progress.md\` is the normal path for large plans, and PM must not press for completion within one round or accept summary-row compression in place of remaining steps. If the architecture-plan Gate returns \`request_changes\`, route the complete report to Architect, then rerun the full architecture-plan Gate after the plan and scaffold are revised.
 - **Coder Continuation:** If Coder returns \`Decision: incomplete\`, lacks the required completion artifact, or has not completed implementation and L0/L1 validation, route Coder again — this is the only route for an in-progress sweep. Problems recorded inside an incomplete report are sweep state, not routable failures; PM routes problems onward only from a post-sweep \`failed\` report carrying the consolidated per-item disposition.
 - **Coder Failure Debug:** If Coder returns \`Decision: failed\` with compile, typecheck, or L0/L1 failure evidence after implementation, suspend the main flow and enter Architect Debug Branch.