vibe-coding-master 0.2.6 → 0.2.8

package/dist/backend/services/job-guard-service.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const ACTIVE_JOB_STATUSES = new Set(["queued", "starting", "running"]);
+const QUEUED_JOB_FRESH_MS = 120_000;
+export const MAX_CONSECUTIVE_STOP_BLOCKS = 3;
+export function createJobGuardService(deps = {}) {
+    const isProcessAlive = deps.isProcessAlive ?? defaultIsProcessAlive;
+    const now = deps.now ?? Date.now;
+    const blockStates = new Map();
+    async function findActiveJobs(taskRepoRoot) {
+        const jobsRoot = path.join(taskRepoRoot, ".ai/vcm/jobs");
+        let entries;
+        try {
+            entries = await fs.readdir(jobsRoot);
+        }
+        catch {
+            return [];
+        }
+        const jobs = [];
+        for (const entry of entries.sort()) {
+            const statusPath = path.join(jobsRoot, entry, "status.json");
+            let status;
+            try {
+                status = JSON.parse(await fs.readFile(statusPath, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            if (typeof status.status !== "string" || !ACTIVE_JOB_STATUSES.has(status.status)) {
+                continue;
+            }
+            const processId = numberOrUndefined(status.processId);
+            const workerPid = numberOrUndefined(status.workerPid);
+            const pid = processId ?? workerPid;
+            if (pid !== undefined) {
+                if (!isProcessAlive(pid)) {
+                    continue;
+                }
+            }
+            else {
+                // queued entry whose worker has not reported a pid yet: only trust it briefly
+                try {
+                    const stat = await fs.stat(statusPath);
+                    if (now() - stat.mtimeMs > QUEUED_JOB_FRESH_MS) {
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            let leaseMtimeMs;
+            try {
+                leaseMtimeMs = (await fs.stat(path.join(jobsRoot, entry, "lease"))).mtimeMs;
+            }
+            catch {
+                leaseMtimeMs = undefined;
+            }
+            jobs.push({
+                jobId: typeof status.jobId === "string" ? status.jobId : entry,
+                status: status.status,
+                startedAt: typeof status.startedAt === "string" ? status.startedAt : undefined,
+                timeoutSeconds: numberOrUndefined(status.timeoutSeconds),
+                processId,
+                workerPid,
+                leaseMtimeMs
+            });
+        }
+        return jobs;
+    }
+    return {
+        findActiveJobs,
+        async evaluateStop(input) {
+            const key = stateKey(input);
+            const jobs = await findActiveJobs(input.taskRepoRoot);
+            if (jobs.length === 0) {
+                blockStates.delete(key);
+                return { behavior: "allow" };
+            }
+            const leaseMtimeMs = jobs.reduce((latest, job) => job.leaseMtimeMs !== undefined && (latest === undefined || job.leaseMtimeMs > latest)
+                ? job.leaseMtimeMs
+                : latest, undefined);
+            let state = blockStates.get(key) ?? { count: 0 };
+            const watcherProgressed = state.count > 0
+                && leaseMtimeMs !== undefined
+                && state.lastLeaseMtimeMs !== undefined
+                && leaseMtimeMs > state.lastLeaseMtimeMs;
+            if (watcherProgressed) {
+                state = { count: 0 };
+            }
+            if (state.count >= MAX_CONSECUTIVE_STOP_BLOCKS) {
+                // The role keeps trying to stop without watching; let it stop so the
+                // round can settle. The job worker lease will reap the job itself.
+                blockStates.delete(key);
+                return { behavior: "allow" };
+            }
+            blockStates.set(key, { count: state.count + 1, lastLeaseMtimeMs: leaseMtimeMs });
+            return { behavior: "block", reason: buildBlockReason(jobs) };
+        },
+        notePromptSubmitted(input) {
+            blockStates.delete(stateKey(input));
+        }
+    };
+}
+function stateKey(input) {
+    return `${input.repoRoot}::${input.taskSlug}::${input.role}`;
+}
+function buildBlockReason(jobs) {
+    const first = jobs[0];
+    const listing = jobs.map((job) => `${job.jobId} (${job.status})`).join(", ");
+    return `VCM: validation job ${listing} is still running. Do not end the turn while a validation job is running. `
+        + `Run \`.ai/tools/watch-job ${first.jobId}\` again now and keep watching until it reports a terminal result `
+        + `(success, failed, timeout, or orphaned), then record the result.`;
+}
+function numberOrUndefined(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}

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

@@ -18,8 +18,8 @@ export function createRoundService(deps) {
                 version: 1,
                 taskSlug: input.taskSlug,
                 totalRoundCount: 0,
-                totalPromptSubmitCount: 0,
-                totalStopCount: 0,
+                totalTurnCount: 0,
+                totalCompletedTurnCount: 0,
                 totalCcActiveMs: 0,
                 updatedAt: now()
             };
@@ -29,26 +29,40 @@ export function createRoundService(deps) {
     async function save(input, state) {
         await deps.fs.writeJsonAtomic(getRoundStatePath(input), state);
     }
+    async function updateSessionStatus(input, status) {
+        if (!input.repoRoot || !deps.onSessionStatusChange) {
+            return;
+        }
+        await deps.onSessionStatusChange({
+            repoRoot: input.repoRoot,
+            taskSlug: input.taskSlug,
+            status
+        });
+    }
     async function settleIfNeeded(input, state, timestamp) {
         const current = state.currentRound;
-        if (current?.status !== "settling" || !current.settleDeadlineAt) {
+        if (current?.status !== "running" ||
+            !current.settleDeadlineAt ||
+            current.activeTurnStartedAt) {
             return state;
         }
         if (timestamp < current.settleDeadlineAt) {
             return state;
         }
-        const paused = {
+        const stopped = {
             ...current,
-            status: "paused",
-            pausedAt: current.settleDeadlineAt
+            status: "stopped",
+            stoppedAt: current.settleDeadlineAt,
+            settleDeadlineAt: undefined
         };
         const next = {
             ...state,
-            currentRound: paused,
-            lastPausedRound: paused,
+            currentRound: stopped,
+            lastStoppedRound: stopped,
             updatedAt: timestamp
         };
         await save(input, next);
+        await updateSessionStatus(input, "stopped");
         return next;
     }
     async function settleIfStillCurrent(input, roundId, settleDeadlineAt, settleGuard) {
@@ -56,8 +70,9 @@ export function createRoundService(deps) {
             const state = await load(input);
             const current = state.currentRound;
             if (current?.id !== roundId ||
-                current.status !== "settling" ||
-                current.settleDeadlineAt !== settleDeadlineAt) {
+                current.status !== "running" ||
+                current.settleDeadlineAt !== settleDeadlineAt ||
+                current.activeTurnStartedAt) {
                 return;
             }
             const timestamp = maxIsoTimestamp(now(), settleDeadlineAt);
@@ -105,7 +120,9 @@ export function createRoundService(deps) {
         }
     }
     function scheduleSettleTimer(input, round, timestamp, settleGuard) {
-        if (round.status !== "settling" || !round.settleDeadlineAt) {
+        if (round.status !== "running" ||
+            !round.settleDeadlineAt ||
+            round.activeTurnStartedAt) {
             clearSettleTimer(input);
             return;
         }
@@ -132,10 +149,10 @@ export function createRoundService(deps) {
         }
     }
     return {
-        async getTaskRoundState(input) {
+        async getSessionRoundState(input) {
             return withTaskLock(input, async () => {
                 const timestamp = now();
-                return toTaskRoundState(await load(input), timestamp);
+                return toSessionRoundState(await load(input), timestamp);
             });
         },
         async recordClaudeHookEvent(input) {
@@ -143,7 +160,7 @@ export function createRoundService(deps) {
                 const timestamp = now();
                 const settled = await settleIfNeeded(input, await load(input), timestamp);
                 const current = settled.currentRound;
-                const shouldStartNewRound = input.eventName === "UserPromptSubmit" && (!current || current.status === "paused");
+                const shouldStartNewRound = input.eventName === "UserPromptSubmit" && (!current || current.status === "stopped");
                 const next = applyRoundHookEvent({
                     state: settled,
                     taskSlug: input.taskSlug,
@@ -156,11 +173,12 @@ export function createRoundService(deps) {
                 await save(input, next);
                 if (input.eventName === "UserPromptSubmit") {
                     clearSettleTimer(input);
+                    await updateSessionStatus(input, "running");
                 }
                 else if (next.currentRound) {
                     scheduleSettleTimer(input, next.currentRound, timestamp, input.settleGuard);
                 }
-                return toTaskRoundState(next, timestamp);
+                return toSessionRoundState(next, timestamp);
             });
         },
         stopSession() { },
@@ -177,7 +195,7 @@ export function applyRoundHookEvent(input) {
 }
 function applyPromptSubmitted(input) {
     const current = input.state.currentRound;
-    const shouldStartNewRound = !current || current.status === "paused";
+    const shouldStartNewRound = !current || current.status === "stopped";
     const totalRoundCount = shouldStartNewRound
         ? input.state.totalRoundCount + 1
         : input.state.totalRoundCount;
@@ -185,25 +203,25 @@ function applyPromptSubmitted(input) {
         ? {
             id: input.roundId,
             sequence: totalRoundCount,
-            status: "active",
+            status: "running",
             activeRole: input.role,
             startedAt: input.timestamp,
-            lastPromptSubmittedAt: input.timestamp,
-            runningSince: input.timestamp,
+            lastTurnStartedAt: input.timestamp,
+            activeTurnStartedAt: input.timestamp,
             ccActiveMs: 0,
-            promptSubmitCount: 1,
-            stopCount: 0,
+            turnCount: 1,
+            completedTurnCount: 0,
             roles: [input.role]
         }
         : {
             ...current,
-            status: "active",
+            status: "running",
             activeRole: input.role,
-            lastPromptSubmittedAt: input.timestamp,
+            lastTurnStartedAt: input.timestamp,
             settleDeadlineAt: undefined,
-            pausedAt: undefined,
-            runningSince: current.runningSince ?? input.timestamp,
-            promptSubmitCount: current.promptSubmitCount + 1,
+            stoppedAt: undefined,
+            activeTurnStartedAt: current.activeTurnStartedAt ?? input.timestamp,
+            turnCount: current.turnCount + 1,
             roles: appendUniqueRole(current.roles, input.role)
         };
     return {
@@ -211,63 +229,63 @@ function applyPromptSubmitted(input) {
         taskSlug: input.taskSlug,
         currentRound: nextRound,
         totalRoundCount,
-        totalPromptSubmitCount: input.state.totalPromptSubmitCount + 1,
-        totalStopCount: input.state.totalStopCount,
+        totalTurnCount: input.state.totalTurnCount + 1,
+        totalCompletedTurnCount: input.state.totalCompletedTurnCount,
         totalCcActiveMs: input.state.totalCcActiveMs,
         updatedAt: input.timestamp
     };
 }
 function applyStop(input) {
     const current = input.state.currentRound;
-    if (!current || current.status === "paused") {
+    if (!current || current.status === "stopped" || !current.activeTurnStartedAt) {
         return {
             ...input.state,
             taskSlug: input.taskSlug,
             updatedAt: input.timestamp
         };
     }
-    const activeDurationMs = current.runningSince
-        ? getDurationMs(current.runningSince, input.timestamp)
+    const activeDurationMs = current.activeTurnStartedAt
+        ? getDurationMs(current.activeTurnStartedAt, input.timestamp)
         : 0;
     const nextRound = {
         ...current,
-        status: "settling",
+        status: "running",
         activeRole: input.role,
-        lastStopAt: input.timestamp,
+        lastTurnEndedAt: input.timestamp,
         settleDeadlineAt: addMilliseconds(input.timestamp, input.settleMs),
-        runningSince: undefined,
+        activeTurnStartedAt: undefined,
         ccActiveMs: current.ccActiveMs + activeDurationMs,
-        stopCount: current.stopCount + 1,
+        completedTurnCount: current.completedTurnCount + 1,
         roles: appendUniqueRole(current.roles, input.role)
     };
     return {
         ...input.state,
         taskSlug: input.taskSlug,
         currentRound: nextRound,
-        totalStopCount: input.state.totalStopCount + 1,
+        totalCompletedTurnCount: input.state.totalCompletedTurnCount + 1,
         totalCcActiveMs: input.state.totalCcActiveMs + activeDurationMs,
         updatedAt: input.timestamp
     };
 }
-function toTaskRoundState(state, updatedAt) {
+function toSessionRoundState(state, updatedAt) {
     const current = state.currentRound;
     if (!current) {
         return {
             taskSlug: state.taskSlug,
-            status: "idle",
-            promptSubmitCount: 0,
-            stopCount: 0,
+            status: "stopped",
+            turnCount: 0,
+            completedTurnCount: 0,
             totalRoundCount: state.totalRoundCount,
-            totalPromptSubmitCount: state.totalPromptSubmitCount,
-            totalStopCount: state.totalStopCount,
+            totalTurnCount: state.totalTurnCount,
+            totalCompletedTurnCount: state.totalCompletedTurnCount,
             totalCcActiveMs: state.totalCcActiveMs,
             currentRoundCcActiveMs: 0,
             roles: [],
             updatedAt
         };
     }
-    const activeDurationMs = current.runningSince
-        ? getDurationMs(current.runningSince, updatedAt)
+    const activeDurationMs = current.activeTurnStartedAt
+        ? getDurationMs(current.activeTurnStartedAt, updatedAt)
         : 0;
     const currentRoundCcActiveMs = current.ccActiveMs + activeDurationMs;
     return {
@@ -276,17 +294,17 @@ function toTaskRoundState(state, updatedAt) {
         roundId: current.id,
         activeRole: current.activeRole,
         startedAt: current.startedAt,
-        lastPromptSubmittedAt: current.lastPromptSubmittedAt,
-        lastStopAt: current.lastStopAt,
+        lastTurnStartedAt: current.lastTurnStartedAt,
+        lastTurnEndedAt: current.lastTurnEndedAt,
         settleDeadlineAt: current.settleDeadlineAt,
-        pausedAt: current.pausedAt,
-        runningSince: current.runningSince,
+        stoppedAt: current.stoppedAt,
+        activeTurnStartedAt: current.activeTurnStartedAt,
         roundSequence: current.sequence,
-        promptSubmitCount: current.promptSubmitCount,
-        stopCount: current.stopCount,
+        turnCount: current.turnCount,
+        completedTurnCount: current.completedTurnCount,
         totalRoundCount: state.totalRoundCount,
-        totalPromptSubmitCount: state.totalPromptSubmitCount,
-        totalStopCount: state.totalStopCount,
+        totalTurnCount: state.totalTurnCount,
+        totalCompletedTurnCount: state.totalCompletedTurnCount,
         totalCcActiveMs: state.totalCcActiveMs + activeDurationMs,
         currentRoundCcActiveMs,
         roles: current.roles,
@@ -294,14 +312,15 @@ function toTaskRoundState(state, updatedAt) {
     };
 }
 function normalizeRoundFile(input, taskSlug, updatedAt) {
+    const legacy = input;
     return {
         version: 1,
         taskSlug,
         currentRound: normalizeRound(input.currentRound),
-        lastPausedRound: normalizeRound(input.lastPausedRound),
+        lastStoppedRound: normalizeRound(input.lastStoppedRound ?? legacy.lastPausedRound),
         totalRoundCount: normalizeNumber(input.totalRoundCount),
-        totalPromptSubmitCount: normalizeNumber(input.totalPromptSubmitCount),
-        totalStopCount: normalizeNumber(input.totalStopCount),
+        totalTurnCount: normalizeNumber(input.totalTurnCount ?? legacy.totalPromptSubmitCount),
+        totalCompletedTurnCount: normalizeNumber(input.totalCompletedTurnCount ?? legacy.totalStopCount),
         totalCcActiveMs: normalizeNumber(input.totalCcActiveMs),
         updatedAt: typeof input.updatedAt === "string" ? input.updatedAt : updatedAt
     };
@@ -310,26 +329,53 @@ function normalizeRound(input) {
     if (!input || typeof input.id !== "string") {
         return undefined;
     }
-    if (input.status !== "active" && input.status !== "settling" && input.status !== "paused") {
+    const status = normalizeRoundStatus(input.status);
+    if (!status) {
         return undefined;
     }
+    const legacy = input;
     return {
         id: input.id,
         sequence: Number.isFinite(input.sequence) ? input.sequence : 1,
-        status: input.status,
+        status,
         activeRole: input.activeRole,
         startedAt: input.startedAt,
-        lastPromptSubmittedAt: input.lastPromptSubmittedAt,
-        lastStopAt: input.lastStopAt,
+        lastTurnStartedAt: typeof input.lastTurnStartedAt === "string"
+            ? input.lastTurnStartedAt
+            : typeof legacy.lastPromptSubmittedAt === "string"
+                ? legacy.lastPromptSubmittedAt
+                : undefined,
+        lastTurnEndedAt: typeof input.lastTurnEndedAt === "string"
+            ? input.lastTurnEndedAt
+            : typeof legacy.lastStopAt === "string"
+                ? legacy.lastStopAt
+                : undefined,
         settleDeadlineAt: input.settleDeadlineAt,
-        pausedAt: input.pausedAt,
-        runningSince: input.runningSince,
+        stoppedAt: typeof input.stoppedAt === "string"
+            ? input.stoppedAt
+            : typeof legacy.pausedAt === "string"
+                ? legacy.pausedAt
+                : undefined,
+        activeTurnStartedAt: typeof input.activeTurnStartedAt === "string"
+            ? input.activeTurnStartedAt
+            : typeof legacy.runningSince === "string"
+                ? legacy.runningSince
+                : undefined,
         ccActiveMs: Number.isFinite(input.ccActiveMs) ? input.ccActiveMs : 0,
-        promptSubmitCount: Number.isFinite(input.promptSubmitCount) ? input.promptSubmitCount : 0,
-        stopCount: Number.isFinite(input.stopCount) ? input.stopCount : 0,
+        turnCount: normalizeNumber(input.turnCount ?? legacy.promptSubmitCount),
+        completedTurnCount: normalizeNumber(input.completedTurnCount ?? legacy.stopCount),
         roles: Array.isArray(input.roles) ? input.roles : []
     };
 }
+function normalizeRoundStatus(value) {
+    if (value === "running" || value === "active" || value === "settling") {
+        return "running";
+    }
+    if (value === "stopped" || value === "paused") {
+        return "stopped";
+    }
+    return undefined;
+}
 function appendUniqueRole(roles, role) {
     return roles.includes(role) ? roles : [...roles, role];
 }
@@ -344,7 +390,7 @@ async function runSettleGuard(settleGuard, input) {
         return await settleGuard(input);
     }
     catch {
-        return { action: "pause" };
+        return { action: "stop" };
     }
 }
 function getDurationMs(start, end) {

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

@@ -78,7 +78,6 @@ export function createSessionService(deps) {
         };
         deps.registry.upsert(record);
         await persistTaskSession(deps.fs, taskRepoRoot, config.stateRoot, record);
-        await deps.taskService.updateTaskStatus(repoRoot, taskSlug, "running");
         return record;
     }
     return {
@@ -171,8 +170,8 @@ export function createSessionService(deps) {
                 ...current,
                 activityStatus: isStop ? "idle" : "running",
                 lastHookEventAt: timestamp,
-                lastStopAt: isStop ? timestamp : current.lastStopAt,
-                lastPromptSubmittedAt: isStop ? current.lastPromptSubmittedAt : timestamp,
+                lastTurnEndedAt: isStop ? timestamp : current.lastTurnEndedAt,
+                lastTurnStartedAt: isStop ? current.lastTurnStartedAt : timestamp,
                 updatedAt: timestamp
             };
             deps.registry.upsert(updated);
@@ -190,7 +189,7 @@ export function createSessionService(deps) {
             const updated = {
                 ...current,
                 activityStatus: "running",
-                lastPromptSubmittedAt: timestamp,
+                lastTurnStartedAt: timestamp,
                 lastHookEventAt: timestamp,
                 updatedAt: timestamp
             };
@@ -239,9 +238,16 @@ async function loadPersistedRoleRecord(fs, repoRoot, stateRoot, taskSlug, role)
     }
     const current = await fs.readJson(sessionPath);
     const record = current.roles[role]?.record;
+    const legacy = record;
     return record
         ? {
             ...record,
+            lastTurnStartedAt: record.lastTurnStartedAt ?? (typeof legacy?.lastPromptSubmittedAt === "string"
+                ? legacy.lastPromptSubmittedAt
+                : undefined),
+            lastTurnEndedAt: record.lastTurnEndedAt ?? (typeof legacy?.lastStopAt === "string"
+                ? legacy.lastStopAt
+                : undefined),
             permissionMode: normalizeClaudePermissionMode(record.permissionMode),
             model: normalizeClaudeModel(record.model)
         }

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

@@ -123,7 +123,7 @@ export function createTaskService(deps) {
             const entries = await deps.fs.readDir(tasksDir);
             const tasks = [];
             for (const entry of entries.filter((candidate) => candidate.endsWith(".json"))) {
-                tasks.push(await deps.fs.readJson(path.join(tasksDir, entry)));
+                tasks.push(normalizeTaskRecord(await deps.fs.readJson(path.join(tasksDir, entry))));
             }
             return tasks.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
         },
@@ -137,7 +137,7 @@ export function createTaskService(deps) {
                     statusCode: 404
                 });
             }
-            return deps.fs.readJson(taskPath);
+            return normalizeTaskRecord(await deps.fs.readJson(taskPath));
         },
         async saveTask(repoRoot, task) {
             await deps.fs.writeJsonAtomic(getTaskPath(deps.projectService.getProjectDataRoot(repoRoot), task.taskSlug), task);
@@ -212,13 +212,42 @@ async function findActiveInlineTask(fs, taskStoreRoot) {
     }
     const entries = await fs.readDir(tasksDir);
     for (const entry of entries.filter((candidate) => candidate.endsWith(".json"))) {
-        const task = await fs.readJson(path.join(tasksDir, entry));
+        const task = normalizeTaskRecord(await fs.readJson(path.join(tasksDir, entry)));
         if (!task.worktreePath && task.cleanupStatus !== "cleaned") {
             return task;
         }
     }
     return undefined;
 }
+function normalizeTaskRecord(input) {
+    return {
+        version: 1,
+        taskSlug: input.taskSlug ?? "",
+        title: input.title,
+        createdAt: input.createdAt ?? "",
+        updatedAt: input.updatedAt ?? input.createdAt ?? "",
+        repoRoot: input.repoRoot ?? "",
+        worktreePath: input.worktreePath,
+        branch: input.branch ?? "",
+        handoffDir: input.handoffDir ?? ".ai/vcm/handoffs",
+        status: normalizeTaskStatus(input.status),
+        specPath: input.specPath,
+        cleanupStatus: input.cleanupStatus,
+        cleanedAt: input.cleanedAt
+    };
+}
+function normalizeTaskStatus(value) {
+    if (value === "created" || value === "running" || value === "stopped") {
+        return value;
+    }
+    if (value === undefined || value === null) {
+        return "created";
+    }
+    if (value === "planning") {
+        return "created";
+    }
+    return "stopped";
+}
 function getTaskStatePaths(taskStoreRoot, taskRepoRoot, stateRoot, handoffRoot, taskSlug) {
     return [
         getTaskPath(taskStoreRoot, taskSlug),

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

@@ -780,6 +780,21 @@ export function createTranslationService(deps) {
                 publishFailures(sessionId);
             }
             return { failures: [] };
+        },
+        async translateGatewayOutput(input) {
+            const { settings, secrets } = await loadConfig();
+            const prompt = buildTranslationPrompt({
+                direction: "cc-output-to-user",
+                text: input.text,
+                settings
+            });
+            const result = await deps.provider.translate({
+                settings,
+                secrets,
+                systemPrompt: prompt.systemPrompt,
+                userPrompt: prompt.userPrompt
+            });
+            return result.text.trim();
         }
     };
     async function writeToCurrentRole(repoRoot, taskSlug, role, text) {

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

@@ -1,24 +1,28 @@
 export function renderArchitectHarnessRules() {
-    return `## VCM Architect Rules
+    return `
+## VCM Architect Rules
 
 ### Role Scope
 
 - Own technical analysis, architecture planning, module boundaries, file responsibilities, public contracts, verifiable behavior, phase boundaries, behavior/contract proof points, risks, and Replan triggers.
+- Own \`docs/known-issues.md\` promotion and durable issue updates.
+- Own architecture docs sync across \`docs/ARCHITECTURE.md\` and affected \`<module>/ARCHITECTURE.md\` files.
 - Do not implement production code.
 - Do not design complete test cases, coverage matrices, or final validation strategy; reviewer owns independent test design, test adequacy, and validation confidence.
 - Do not make product priority or approval decisions; route those questions back to project-manager.
-- Reply to project-manager with the \`vcm-route-message\` skill.
 
 ### Planning Inputs
 
-- Read \`CLAUDE.md\`, the role command, durable plans when present, relevant handoff artifacts, and affected project docs before planning.
-- Use \`docs/ARCHITECTURE.md\`, \`docs/MODULE_MAP.md\`, \`docs/SECURITY.md\`, and \`docs/DEPENDENCY_RULES.md\` as durable project truth when relevant.
+- 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/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.
 
 ### Architecture Plan
 
 - Write \`.ai/vcm/handoffs/architecture-plan.md\` before coder work starts.
-- The plan must cover changed files, file responsibilities, public interfaces or user-visible behavior, required behavior or contract proof points, docs impact, risks, and Replan triggers.
+- The plan must cover changed files, task-local file responsibilities, affected modules, public interfaces or user-visible behavior, required behavior or contract proof points, docs impact, risks, and Replan triggers.
+- For docs impact, state whether changes belong in \`docs/ARCHITECTURE.md\`, affected \`<module>/ARCHITECTURE.md\`, \`.ai/generated/public-surface.json\`, or no durable architecture doc.
 - Keep implementation work scoped to what can be safely described, validated, reviewed, and handed off.
 
 ### Phase Planning
@@ -39,10 +43,17 @@ export function renderArchitectHarnessRules() {
 ### Docs Sync
 
 - Perform docs sync only when project-manager requests it after reviewer completes.
-- Check whether final code changed durable project truth: architecture, module map, public contracts, security constraints, dependency rules, or durable plans.
-- Update affected durable docs when project truth changed; otherwise state which docs were checked and why they remain current.
-- Treat reviewer-reported docs gaps as inputs; resolve technical docs drift or report conflicts back to project-manager.
+- 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.
+- 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.
+- When module structure changes, require \`.ai/tools/generate-module-index --check\` or regeneration.
+- When crate-external public APIs change, require \`.ai/tools/generate-public-surface --check\` or regeneration.
 - Read \`.ai/vcm/handoffs/known-issues.md\` and promote confirmed unresolved issues to \`docs/known-issues.md\`.
 - Write \`.ai/vcm/handoffs/docs-sync-report.md\` with decision, evidence reviewed, architecture drift check, docs updated, docs left unchanged, remaining documentation risks, and handoff notes.
+
+### Background Jobs
+
+- Never background a Bash command: no \`run_in_background\`, \`nohup\`, \`setsid\`, \`disown\`, or trailing \`&\`.
+- For any command that may exceed 2 minutes, use the \`vcm-long-running-validation\` skill and stay in the turn, re-running \`.ai/tools/watch-job\` until it reports a terminal result.
 `;
 }