vibe-coding-master 0.4.19 → 0.4.20

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

@@ -1,23 +1,20 @@
 import { randomUUID } from "node:crypto";
 import path from "node:path";
-import { CORE_VCM_ROLE_NAMES, isDispatchableRole } from "../../shared/constants.js";
+import { VCM_ROLE_NAMES, isDispatchableRole } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { claudeTranscriptPath } from "./claude-transcript-service.js";
 import { readHarnessRevisionState } from "./harness-revision.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
-const GATE_REVIEWER_ROLE = "gate-reviewer";
 const TRANSLATOR_ROLE = "translator";
 const HARNESS_ENGINEER_ROLE = "harness-engineer";
 const TRANSLATION_DIR = ".ai/vcm/translations";
 const TRANSLATOR_SESSION_PATH = ".ai/vcm/translations/session.json";
 const HARNESS_ENGINEER_DIR = ".ai/vcm/harness-engineer";
 const HARNESS_ENGINEER_SESSION_PATH = ".ai/vcm/harness-engineer/session.json";
-const GATE_REVIEWER_SESSION_PATH = ".ai/vcm/gate-reviewer/session.json";
 const PROJECT_TRANSLATOR_SCOPE = "__project__";
 const PROJECT_HARNESS_ENGINEER_SCOPE = "__project_harness_engineer__";
-const PROJECT_GATE_REVIEWER_SCOPE = "__project_gate_reviewer__";
 export function createSessionService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
     async function readCurrentHarnessRevision(repoRoot) {
@@ -112,101 +109,6 @@ export function createSessionService(deps) {
         await persistRoleSessionRecord(deps.fs, repoRoot, taskRepoRoot, config.stateRoot, record);
         return withHarnessRevisionView(repoRoot, record);
     }
-    async function launchProjectGateReviewerSession(repoRoot, input, launchMode, activeTaskSlug) {
-        const live = toRoleSessionRecordView(getRegisteredProjectGateReviewerSession(deps.registry, deps.runtime), deps.runtime);
-        if (live && live.status === "running") {
-            return withHarnessRevisionView(repoRoot, await bindProjectGateReviewerSession(repoRoot, live, activeTaskSlug));
-        }
-        const config = await deps.projectService.loadConfig(repoRoot);
-        const persisted = await loadPersistedProjectGateReviewerSession(deps.fs, repoRoot);
-        const permissionMode = normalizeClaudePermissionMode(input.permissionMode ?? persisted?.permissionMode);
-        const model = normalizeClaudeModel(input.model ?? persisted?.model);
-        const effort = normalizeClaudeEffort(input.effort ?? persisted?.effort);
-        const claudeSessionId = launchMode === "resume"
-            ? persisted?.claudeSessionId
-            : randomUUID();
-        if (!claudeSessionId) {
-            throw new VcmError({
-                code: "GATE_REVIEWER_SESSION_MISSING",
-                message: "Gate Reviewer does not have a session id to resume.",
-                statusCode: 409,
-                hint: "Start Gate Reviewer once before using Resume."
-            });
-        }
-        const transcriptPath = launchMode === "resume" && persisted?.transcriptPath
-            ? persisted.transcriptPath
-            : claudeTranscriptPath(repoRoot, claudeSessionId);
-        const activeTask = activeTaskSlug
-            ? await deps.taskService.loadTask(repoRoot, activeTaskSlug)
-            : undefined;
-        const activeTaskRepoRoot = activeTask ? getTaskRuntimeRepoRoot(activeTask) : undefined;
-        const startCommand = {
-            ...deps.claude.buildRoleStartCommand(GATE_REVIEWER_ROLE, config.claudeCommand, permissionMode, claudeSessionId, launchMode === "resume", model, effort),
-            cwd: repoRoot
-        };
-        const runtimeSession = await deps.runtime.createSession({
-            taskSlug: PROJECT_GATE_REVIEWER_SCOPE,
-            role: GATE_REVIEWER_ROLE,
-            command: startCommand.command,
-            args: startCommand.args,
-            cwd: startCommand.cwd,
-            env: {
-                VCM_API_URL: deps.apiUrl,
-                VCM_BASE_REPO_ROOT: repoRoot,
-                VCM_TASK_REPO_ROOT: activeTaskRepoRoot ?? repoRoot,
-                VCM_TASK_SLUG: activeTaskSlug ?? PROJECT_GATE_REVIEWER_SCOPE,
-                VCM_ROLE: GATE_REVIEWER_ROLE,
-                VCM_SESSION_ID: claudeSessionId
-            },
-            cols: input.cols,
-            rows: input.rows
-        });
-        const timestamp = now();
-        const harnessRevision = await readCurrentHarnessRevision(repoRoot);
-        const record = {
-            id: runtimeSession.id,
-            claudeSessionId,
-            transcriptPath,
-            taskSlug: PROJECT_GATE_REVIEWER_SCOPE,
-            role: GATE_REVIEWER_ROLE,
-            status: runtimeSession.status,
-            activityStatus: "idle",
-            command: startCommand.display,
-            permissionMode,
-            model,
-            effort,
-            cwd: startCommand.cwd,
-            terminalBackend: "node-pty",
-            pid: runtimeSession.pid,
-            startedAt: runtimeSession.startedAt,
-            updatedAt: timestamp,
-            lastOutputAt: runtimeSession.lastOutputAt,
-            activeTaskSlug,
-            activeTaskRepoRoot,
-            harnessRevision,
-            exitCode: runtimeSession.exitCode
-        };
-        deps.registry.upsert(record);
-        await persistProjectGateReviewerSession(deps.fs, repoRoot, record);
-        return withHarnessRevisionView(repoRoot, record);
-    }
-    async function bindProjectGateReviewerSession(repoRoot, record, activeTaskSlug) {
-        if (!activeTaskSlug) {
-            return record;
-        }
-        const task = await deps.taskService.loadTask(repoRoot, activeTaskSlug);
-        const activeTaskRepoRoot = getTaskRuntimeRepoRoot(task);
-        const updated = {
-            ...record,
-            taskSlug: PROJECT_GATE_REVIEWER_SCOPE,
-            activeTaskSlug,
-            activeTaskRepoRoot,
-            updatedAt: now()
-        };
-        deps.registry.upsert(updated);
-        await persistProjectGateReviewerSession(deps.fs, repoRoot, updated);
-        return updated;
-    }
     async function launchProjectTranslatorSession(repoRoot, input, launchMode) {
         const taskContext = await resolveProjectToolTaskContext(repoRoot, input, "Translator");
         const live = toRoleSessionRecordView(getRegisteredProjectTranslatorSession(deps.registry, deps.runtime), deps.runtime);
@@ -379,8 +281,7 @@ export function createSessionService(deps) {
     }
     async function migrateRunningProjectToolSessionCwd(repoRoot, session, targetCwd) {
         if (session.role !== TRANSLATOR_ROLE
-            && session.role !== HARNESS_ENGINEER_ROLE
-            && session.role !== GATE_REVIEWER_ROLE) {
+            && session.role !== HARNESS_ENGINEER_ROLE) {
             return session;
         }
         if (samePath(session.cwd, targetCwd)) {
@@ -407,9 +308,7 @@ export function createSessionService(deps) {
     async function resumeProjectToolSessionAtCwd(repoRoot, session, targetCwd) {
         const live = toRoleSessionRecordView(session.role === TRANSLATOR_ROLE
             ? getRegisteredProjectTranslatorSession(deps.registry, deps.runtime)
-            : session.role === HARNESS_ENGINEER_ROLE
-                ? getRegisteredProjectHarnessEngineerSession(deps.registry, deps.runtime)
-                : getRegisteredProjectGateReviewerSession(deps.registry, deps.runtime), deps.runtime);
+            : getRegisteredProjectHarnessEngineerSession(deps.registry, deps.runtime), deps.runtime);
         if (live?.status === "running") {
             return migrateRunningProjectToolSessionCwd(repoRoot, live, targetCwd);
         }
@@ -460,10 +359,6 @@ export function createSessionService(deps) {
         return migrateRunningProjectToolSessionCwd(repoRoot, resumed, targetCwd);
     }
     async function persistProjectScopedToolSession(repoRoot, session) {
-        if (session.role === GATE_REVIEWER_ROLE) {
-            await persistProjectGateReviewerSession(deps.fs, repoRoot, session);
-            return;
-        }
         if (session.role === TRANSLATOR_ROLE) {
             await persistTranslatorSession(deps.fs, repoRoot, session);
             return;
@@ -498,13 +393,6 @@ export function createSessionService(deps) {
         return withHarnessRevisionView(repoRoot, updated);
     }
     async function persistNotifiedHarnessSession(repoRoot, session) {
-        if (session.role === GATE_REVIEWER_ROLE) {
-            await persistProjectGateReviewerSession(deps.fs, repoRoot, {
-                ...session,
-                taskSlug: PROJECT_GATE_REVIEWER_SCOPE
-            });
-            return;
-        }
         if (session.role === TRANSLATOR_ROLE) {
             await persistTranslatorSession(deps.fs, repoRoot, {
                 ...session,
@@ -524,68 +412,6 @@ export function createSessionService(deps) {
         await persistRoleSessionRecord(deps.fs, repoRoot, getTaskRuntimeRepoRoot(task), config.stateRoot, session);
     }
     return {
-        startProjectGateReviewerSession(repoRoot, input = {}) {
-            return launchProjectGateReviewerSession(repoRoot, input, "fresh");
-        },
-        resumeProjectGateReviewerSession(repoRoot, input = {}) {
-            return launchProjectGateReviewerSession(repoRoot, input, "resume");
-        },
-        async stopProjectGateReviewerSession(repoRoot) {
-            const existing = await this.getProjectGateReviewerSession(repoRoot);
-            if (!existing) {
-                throw new VcmError({
-                    code: "SESSION_MISSING",
-                    message: "Gate Reviewer session has not been started.",
-                    statusCode: 404
-                });
-            }
-            if (deps.runtime.getSession(existing.id)) {
-                await deps.runtime.stop(existing.id);
-            }
-            const updated = {
-                ...existing,
-                taskSlug: PROJECT_GATE_REVIEWER_SCOPE,
-                status: "exited",
-                activityStatus: "idle",
-                updatedAt: now()
-            };
-            deps.registry.upsert(updated);
-            await persistProjectGateReviewerSession(deps.fs, repoRoot, updated);
-            return updated;
-        },
-        async restartProjectGateReviewerSession(repoRoot, input = {}) {
-            const existing = await this.getProjectGateReviewerSession(repoRoot);
-            if (!existing) {
-                return launchProjectGateReviewerSession(repoRoot, input, "fresh");
-            }
-            if (deps.runtime.getSession(existing.id)) {
-                await deps.runtime.stop(existing.id);
-            }
-            deps.registry.remove(existing.id);
-            return launchProjectGateReviewerSession(repoRoot, input, "fresh");
-        },
-        async getProjectGateReviewerSession(repoRoot) {
-            const record = getRegisteredProjectGateReviewerSession(deps.registry, deps.runtime)
-                ?? await loadPersistedProjectGateReviewerSession(deps.fs, repoRoot);
-            const view = toRoleSessionRecordView(record, deps.runtime);
-            return view ? withHarnessRevisionView(repoRoot, view) : undefined;
-        },
-        async ensureProjectGateReviewerSession(repoRoot, input = {}) {
-            const existing = await this.getProjectGateReviewerSession(repoRoot);
-            if (existing?.status === "running") {
-                return existing;
-            }
-            if (existing?.claudeSessionId) {
-                return this.resumeProjectGateReviewerSession(repoRoot, {
-                    permissionMode: input.permissionMode ?? existing.permissionMode,
-                    model: input.model ?? existing.model,
-                    effort: input.effort ?? existing.effort,
-                    cols: input.cols,
-                    rows: input.rows
-                });
-            }
-            return this.startProjectGateReviewerSession(repoRoot, input);
-        },
         startProjectTranslatorSession(repoRoot, input = {}) {
             return launchProjectTranslatorSession(repoRoot, input, "fresh");
         },
@@ -835,10 +661,6 @@ export function createSessionService(deps) {
             return notifyHarnessUpdatedForSession(repoRoot, current);
         },
         startRoleSession(repoRoot, taskSlug, role, input = {}) {
-            if (role === GATE_REVIEWER_ROLE) {
-                return launchProjectGateReviewerSession(repoRoot, input, "fresh", taskSlug)
-                    .then((session) => scopeProjectRoleSession(session, taskSlug));
-            }
             if (role === TRANSLATOR_ROLE) {
                 return this.startProjectTranslatorSession(repoRoot, { ...input, taskSlug });
             }
@@ -848,10 +670,6 @@ export function createSessionService(deps) {
             return launchRoleSession(repoRoot, taskSlug, role, input, "fresh");
         },
         resumeRoleSession(repoRoot, taskSlug, role, input = {}) {
-            if (role === GATE_REVIEWER_ROLE) {
-                return launchProjectGateReviewerSession(repoRoot, input, "resume", taskSlug)
-                    .then((session) => scopeProjectRoleSession(session, taskSlug));
-            }
             if (role === TRANSLATOR_ROLE) {
                 return this.resumeProjectTranslatorSession(repoRoot, { ...input, taskSlug });
             }
@@ -861,9 +679,6 @@ export function createSessionService(deps) {
             return launchRoleSession(repoRoot, taskSlug, role, input, "resume");
         },
         async stopRoleSession(repoRoot, taskSlug, role) {
-            if (role === GATE_REVIEWER_ROLE) {
-                return scopeProjectRoleSession(await this.stopProjectGateReviewerSession(repoRoot), taskSlug);
-            }
             if (role === TRANSLATOR_ROLE) {
                 void taskSlug;
                 return this.stopProjectTranslatorSession(repoRoot);
@@ -896,16 +711,6 @@ export function createSessionService(deps) {
             return updated;
         },
         async restartRoleSession(repoRoot, taskSlug, role, input = {}) {
-            if (role === GATE_REVIEWER_ROLE) {
-                const existing = await this.getProjectGateReviewerSession(repoRoot);
-                if (existing && deps.runtime.getSession(existing.id)) {
-                    await deps.runtime.stop(existing.id);
-                }
-                if (existing) {
-                    deps.registry.remove(existing.id);
-                }
-                return scopeProjectRoleSession(await launchProjectGateReviewerSession(repoRoot, input, "fresh", taskSlug), taskSlug);
-            }
             if (role === TRANSLATOR_ROLE) {
                 return this.restartProjectTranslatorSession(repoRoot, { ...input, taskSlug });
             }
@@ -923,14 +728,6 @@ export function createSessionService(deps) {
             return launchRoleSession(repoRoot, taskSlug, role, input, "fresh");
         },
         async getRoleSession(repoRoot, taskSlug, role) {
-            if (role === GATE_REVIEWER_ROLE) {
-                const session = await this.getProjectGateReviewerSession(repoRoot);
-                if (!session) {
-                    return undefined;
-                }
-                const scoped = scopeProjectRoleSession(await bindProjectGateReviewerSession(repoRoot, session, taskSlug), taskSlug);
-                return scoped ? withHarnessRevisionView(repoRoot, scoped) : undefined;
-            }
             if (role === TRANSLATOR_ROLE) {
                 void taskSlug;
                 return this.getProjectTranslatorSession(repoRoot);
@@ -956,7 +753,7 @@ export function createSessionService(deps) {
             const task = await deps.taskService.loadTask(repoRoot, taskSlug);
             const taskRepoRoot = getTaskRuntimeRepoRoot(task);
             const persistedTaskSession = await loadPersistedTaskSessionRecord(deps.fs, taskRepoRoot, config.stateRoot, taskSlug);
-            for (const role of CORE_VCM_ROLE_NAMES) {
+            for (const role of VCM_ROLE_NAMES) {
                 const record = deps.registry.getByRole(taskSlug, role)
                     ?? normalizePersistedRoleRecord(persistedTaskSession?.roles[role]?.record);
                 const session = toRoleSessionRecordView(record, deps.runtime);
@@ -964,10 +761,6 @@ export function createSessionService(deps) {
                     sessions.push(session);
                 }
             }
-            const gateReviewerSession = scopeProjectRoleSession(await this.getProjectGateReviewerSession(repoRoot), taskSlug);
-            if (gateReviewerSession) {
-                sessions.push(gateReviewerSession);
-            }
             return Promise.all(sessions.map((session) => withHarnessRevisionView(repoRoot, session)));
         },
         async notifyRoleHarnessUpdated(repoRoot, taskSlug, role) {
@@ -982,31 +775,6 @@ export function createSessionService(deps) {
             return notifyHarnessUpdatedForSession(repoRoot, current);
         },
         async recordRoleHookEvent(repoRoot, input) {
-            if (input.role === GATE_REVIEWER_ROLE) {
-                const current = await this.getProjectGateReviewerSession(repoRoot);
-                if (!current || (!input.allowSessionMismatch && !matchesRoleHookSession(current, input))) {
-                    return undefined;
-                }
-                const timestamp = now();
-                const isTurnEnd = isTurnEndHook(input.eventName);
-                const isCompact = isCompactHook(input.eventName);
-                const updated = {
-                    ...current,
-                    taskSlug: PROJECT_GATE_REVIEWER_SCOPE,
-                    claudeSessionId: input.sessionId ?? current.claudeSessionId,
-                    transcriptPath: input.transcriptPath ?? current.transcriptPath,
-                    cwd: input.cwd ?? current.cwd,
-                    activityStatus: isTurnEnd ? "idle" : isCompact ? current.activityStatus : "running",
-                    lastHookEventAt: timestamp,
-                    lastTurnEndedAt: isTurnEnd ? timestamp : current.lastTurnEndedAt,
-                    lastTurnStartedAt: isTurnEnd || isCompact ? current.lastTurnStartedAt : timestamp,
-                    lastCompactAt: isCompact ? timestamp : current.lastCompactAt,
-                    updatedAt: timestamp
-                };
-                deps.registry.upsert(updated);
-                await persistProjectGateReviewerSession(deps.fs, repoRoot, updated);
-                return scopeProjectRoleSession(updated, input.taskSlug);
-            }
             if (input.role === TRANSLATOR_ROLE) {
                 void input.taskSlug;
                 return this.recordProjectTranslatorHookEvent(repoRoot, {
@@ -1073,15 +841,6 @@ export function createSessionService(deps) {
                 lastHookEventAt: timestamp,
                 updatedAt: timestamp
             };
-            if (role === GATE_REVIEWER_ROLE) {
-                const persisted = {
-                    ...updated,
-                    taskSlug: PROJECT_GATE_REVIEWER_SCOPE
-                };
-                deps.registry.upsert(persisted);
-                await persistProjectGateReviewerSession(deps.fs, repoRoot, persisted);
-                return updated;
-            }
             deps.registry.upsert(updated);
             const config = await deps.projectService.loadConfig(repoRoot);
             const task = await deps.taskService.loadTask(repoRoot, taskSlug);
@@ -1100,15 +859,6 @@ export function createSessionService(deps) {
                 lastTurnEndedAt: timestamp,
                 updatedAt: timestamp
             };
-            if (role === GATE_REVIEWER_ROLE) {
-                const persisted = {
-                    ...updated,
-                    taskSlug: PROJECT_GATE_REVIEWER_SCOPE
-                };
-                deps.registry.upsert(persisted);
-                await persistProjectGateReviewerSession(deps.fs, repoRoot, persisted);
-                return updated;
-            }
             deps.registry.upsert(updated);
             const config = await deps.projectService.loadConfig(repoRoot);
             const task = await deps.taskService.loadTask(repoRoot, taskSlug);
@@ -1188,7 +938,7 @@ function getHandoffArtifactPath(paths, role) {
     return undefined;
 }
 function getRegisteredRoleSession(registry, runtime, taskSlug, role) {
-    if (role !== TRANSLATOR_ROLE && role !== GATE_REVIEWER_ROLE && role !== HARNESS_ENGINEER_ROLE) {
+    if (role !== TRANSLATOR_ROLE && role !== HARNESS_ENGINEER_ROLE) {
         return registry.getByRole(taskSlug, role);
     }
     const candidates = registry.list().filter((session) => session.role === role);
@@ -1198,11 +948,6 @@ function getRegisteredRoleSession(registry, runtime, taskSlug, role) {
         ?? candidates.sort(compareSessionUpdatedAtDesc)[0];
     return scopeProjectRoleSession(scoped, taskSlug);
 }
-function getRegisteredProjectGateReviewerSession(registry, runtime) {
-    const candidates = registry.list().filter((session) => session.role === GATE_REVIEWER_ROLE);
-    const live = candidates.find((session) => runtime.getSession(session.id)?.status === "running");
-    return live ?? candidates.sort(compareSessionUpdatedAtDesc)[0];
-}
 function getRegisteredProjectTranslatorSession(registry, runtime) {
     const candidates = registry.list().filter((session) => session.role === TRANSLATOR_ROLE);
     const live = candidates.find((session) => runtime.getSession(session.id)?.status === "running");
@@ -1217,7 +962,7 @@ function compareSessionUpdatedAtDesc(left, right) {
     return (right.updatedAt ?? "").localeCompare(left.updatedAt ?? "");
 }
 function scopeProjectRoleSession(record, taskSlug) {
-    if (!record || (record.role !== TRANSLATOR_ROLE && record.role !== GATE_REVIEWER_ROLE && record.role !== HARNESS_ENGINEER_ROLE)) {
+    if (!record || (record.role !== TRANSLATOR_ROLE && record.role !== HARNESS_ENGINEER_ROLE)) {
         return record;
     }
     return {
@@ -1226,10 +971,6 @@ function scopeProjectRoleSession(record, taskSlug) {
     };
 }
 async function loadPersistedRoleRecordForRole(fs, baseRepoRoot, taskRepoRoot, stateRoot, taskSlug, role) {
-    if (role === GATE_REVIEWER_ROLE) {
-        void taskSlug;
-        return loadPersistedProjectGateReviewerSession(fs, baseRepoRoot);
-    }
     if (role === TRANSLATOR_ROLE) {
         void taskSlug;
         return loadPersistedTranslatorSession(fs, baseRepoRoot);
@@ -1240,21 +981,6 @@ async function loadPersistedRoleRecordForRole(fs, baseRepoRoot, taskRepoRoot, st
     }
     return loadPersistedRoleRecord(fs, taskRepoRoot, stateRoot, taskSlug, role);
 }
-async function loadPersistedProjectGateReviewerSession(fs, repoRoot) {
-    const sessionPath = resolveRepoPath(repoRoot, GATE_REVIEWER_SESSION_PATH);
-    if (!(await fs.pathExists(sessionPath))) {
-        return undefined;
-    }
-    const payload = await fs.readJson(sessionPath);
-    const record = normalizePersistedRoleRecord(isProjectRoleSessionFile(payload) ? payload.record : payload);
-    if (!record) {
-        return undefined;
-    }
-    return {
-        ...record,
-        taskSlug: PROJECT_GATE_REVIEWER_SCOPE
-    };
-}
 async function loadPersistedTranslatorSession(fs, repoRoot) {
     const sessionPath = resolveRepoPath(repoRoot, TRANSLATOR_SESSION_PATH);
     if (!(await fs.pathExists(sessionPath))) {
@@ -1314,12 +1040,6 @@ function normalizePersistedRoleRecord(record) {
         : undefined;
 }
 function normalizeProjectScopedRecordForPersistence(record) {
-    if (record.role === GATE_REVIEWER_ROLE) {
-        return {
-            ...record,
-            taskSlug: PROJECT_GATE_REVIEWER_SCOPE
-        };
-    }
     if (record.role === TRANSLATOR_ROLE) {
         return {
             ...record,
@@ -1373,10 +1093,6 @@ async function persistTaskSession(fs, repoRoot, stateRoot, session) {
     });
 }
 async function persistRoleSessionRecord(fs, baseRepoRoot, taskRepoRoot, stateRoot, session) {
-    if (session.role === GATE_REVIEWER_ROLE) {
-        await persistProjectGateReviewerSession(fs, baseRepoRoot, session);
-        return;
-    }
     if (session.role === TRANSLATOR_ROLE) {
         await persistTranslatorSession(fs, baseRepoRoot, session);
         return;
@@ -1387,17 +1103,6 @@ async function persistRoleSessionRecord(fs, baseRepoRoot, taskRepoRoot, stateRoo
     }
     await persistTaskSession(fs, taskRepoRoot, stateRoot, session);
 }
-async function persistProjectGateReviewerSession(fs, repoRoot, session) {
-    await fs.writeJsonAtomic(resolveRepoPath(repoRoot, GATE_REVIEWER_SESSION_PATH), {
-        version: 1,
-        role: session.role,
-        updatedAt: session.updatedAt,
-        record: {
-            ...session,
-            taskSlug: PROJECT_GATE_REVIEWER_SCOPE
-        }
-    });
-}
 async function persistTranslatorSession(fs, repoRoot, session) {
     await fs.writeJsonAtomic(resolveRepoPath(repoRoot, TRANSLATOR_SESSION_PATH), {
         version: 1,

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

@@ -8,6 +8,7 @@ export function renderArchitectHarnessRules() {
 - Define every changed or created file's purpose, logic boundary, collaboration points, and non-private callable surface.
 - Own \`docs/known-issues.md\` promotion and durable issue updates.
 - Own architecture docs sync across \`docs/ARCHITECTURE.md\` and affected \`<module>/ARCHITECTURE.md\` files.
+- Own post-task module architecture doc maintenance for every module touched by the final diff.
 - 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.
@@ -31,7 +32,7 @@ export function renderArchitectHarnessRules() {
 - Give each Scaffold Manifest row a stable ID such as \`SCF-001\`; use that ID in any related \`VCM:CODE\` marker so coder can report completion by ID.
 - Put task context, phase notes, handoff instructions, temporary rationale, and coder guidance in the \`Scaffold Manifest\`, not in source-code comments.
 - Cover architecture docs impact, known 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.
+- For docs impact, list every touched module and state whether its \`<module>/ARCHITECTURE.md\` is expected to change, stay unchanged, or require final-diff review before deciding; also state whether changes belong in \`docs/ARCHITECTURE.md\`, \`.ai/generated/public-surface.json\`, or no durable architecture doc.
 
 #### Code Scaffolding
 
@@ -49,6 +50,11 @@ export function renderArchitectHarnessRules() {
 ### Phase Planning
 
 - Do not create phases for small, single-scope changes; use phases only when the task spans multiple modules, public contracts, migrations, high-risk integrations, or more work than one reliable coder handoff should carry.
+- For complex tasks, first provide an overall solution outline and recommended phases, but keep detailed implementation planning limited to the current phase.
+- Treat \`.ai/vcm/handoffs/architecture-plan.md\` as the executable plan for the current phase, not an accumulating history of all phases.
+- When moving to a new phase, rewrite \`architecture-plan.md\` for that phase: remove previous phase detailed scope, Scaffold Manifest rows, \`VCM:CODE\` guidance, and completed phase instructions.
+- Keep only the minimum overall roadmap and prior-phase context needed to understand the current phase.
+- Durable decisions discovered in previous phases must be promoted to durable docs when needed, not preserved as old task detail inside \`architecture-plan.md\`.
 - Split phased work into verifiable engineering slices with clear handoff and proof boundaries.
 - Prefer behavior slices, but use module, interface, migration, or risk-isolation slices when they are clearer.
 - Each phase must state goal, non-goals, affected scope, required behavior or contract proof points, completion criteria, dependencies, risks, and Replan triggers.
@@ -76,13 +82,41 @@ export function renderArchitectHarnessRules() {
 ### Docs Sync
 
 - Perform docs sync only when project-manager requests it after reviewer completes.
+
+#### Architecture Docs Sync
+
+- Architecture docs describe the current durable system architecture, not task history, implementation chronology, changelog, investigation notes, validation logs, or handoff content.
+- Do not add phase/task/RP labels unless they are durable product, protocol, or spec identifiers that future maintainers must understand.
+- Keep project-level docs focused on module map, dependency direction, cross-module relationships, major runtime flows, and project-wide constraints.
+- Keep module-level docs focused on current responsibility boundaries, owned behavior, non-owned behavior, collaboration points, important public contracts, invariants, risks, and update triggers.
+- Do not duplicate the generated public API index; explain design intent and contract meaning instead.
 - 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.
+- During docs sync, inspect every module touched by the final diff.
+- For each touched module, update its \`<module>/ARCHITECTURE.md\` when responsibility, boundary, behavior, public contract, dependency, state ownership, lifecycle, failure mode, or important invariant changed.
+- 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.
 - 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.
-- 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.
+
+#### 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.
+- Promote only unresolved durable issues or accepted limitations that can affect future architecture, implementation, validation, operation, or release decisions.
+- Remove fully resolved issues from \`docs/known-issues.md\`; git history preserves resolved details.
+- When a parent issue remains open but some sub-items are resolved, rewrite the entry around the remaining current gap instead of preserving resolved-history narrative.
+- Keep one KI entry focused on one owning problem. Split unrelated residuals instead of grouping them under a phase, review, or implementation session.
+- Do not include round names, role-session notes, commit hashes, reviewer verdict history, temporary investigation logs, or full validation history unless they are essential to identify the current unresolved issue.
+- Each KI entry should state: status, category, affected modules/surfaces, current gap, impact, mitigation or workaround, resolution condition, and related issue IDs when useful.
+- Distinguish product/protocol issues from dev-environment, test-infra, harness, or VCM-tooling issues. Do not mix them in one KI entry.
+- Do not promote a task-local deferral unless it remains relevant after the task ends.
+- Read \`.ai/vcm/handoffs/known-issues.md\`; 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.
+
+#### Docs Sync Report
+
+- Write \`.ai/vcm/handoffs/docs-sync-report.md\` with decision, evidence reviewed, architecture drift check, docs updated, docs left unchanged, promoted/updated/removed/not-promoted known issues, remaining documentation risks, and handoff notes.
 
 ### Background Jobs
 

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

@@ -12,9 +12,13 @@ export function renderCoderHarnessRules() {
 - Implement the architect-defined scaffold exactly; do not change file responsibilities, callable-surface signatures, or architect-defined contract intent unless the architecture plan explicitly allows it.
 - Implement every \`VCM:CODE\` placeholder, track completion by Scaffold Manifest ID when present, and remove all \`VCM:CODE\` markers before handoff.
 - Do not fake completion: no hardcoded success, disabled logic, swallowed errors, test-only shortcuts, or silent fallback that hides failure.
+- Implement behavior from the approved architecture, existing domain model, real inputs, and project runtime flow; do not derive logic from visible test fixtures, fixed sample values, snapshot text, or special branches that only satisfy known tests.
 - Keep the diff inside approved scope: no unrelated rewrites, drive-by refactors, renamed symbols, moved files, or formatting churn.
 - Preserve existing behavior unless the architecture plan explicitly changes it; keep existing call sites and shared code paths working.
-- Maintain code documentation: preserve durable architect-written contract comments, do not copy Scaffold Manifest task context into source comments, add comments only for non-obvious durable logic, remove stale/debug/TODO/task-process comments, and keep code and comments consistent.
+- Maintain code documentation: preserve durable architect-written contract comments, keep comments consistent with changed behavior, and update affected durable comments when logic changes.
+- Do not copy Scaffold Manifest task context, phase notes, handoff instructions, temporary rationale, or coder guidance into source comments.
+- Add source comments only for durable behavior, contracts, invariants, error boundaries, or non-obvious logic that cannot be made clear enough through naming, types, constants, or small helper functions.
+- Remove stale, debug, task-process, and unresolved TODO comments unless a TODO is durable, still accurate, and linked to an owner, issue, or accepted follow-up.
 
 ### General Coding Standards
 
@@ -38,6 +42,7 @@ export function renderCoderHarnessRules() {
 
 - Make only the implementation changes needed for the approved scope.
 - Do not weaken, delete, or skip tests to make validation pass.
+- When changing tests, keep assertions tied to the approved behavior contract; do not relax expectations, remove meaningful coverage, or rewrite tests merely to match the current implementation.
 - Record confirmed out-of-scope issues found during implementation in \`.ai/vcm/handoffs/known-issues.md\`.
 
 ### Handoff

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

@@ -36,6 +36,37 @@ You are not part of the task workflow round state.
 - Do not edit production source code as part of harness maintenance.
 - VCM does not create Harness Engineer commits after your turn.
 
+## Task Harness Retrospective
+
+After a task is completed, you may be asked to perform a task harness
+retrospective.
+
+Your goal is to find evidence-backed harness problems exposed by the completed
+task's actual workflow and deliverables. Do not review whether the business
+feature itself is good enough; review whether the VCM harness helped the task
+complete correctly.
+
+Inspect the active task worktree as needed. Useful evidence may include
+handoffs, route messages, commits, commit diffs, durable docs, generated
+context, validation reports, Gate Review reports, final acceptance artifacts,
+and user corrections during the task.
+
+For each finding, decide whether it is:
+
+- a reusable harness problem that should be fixed
+- a VCM fixed-template or product problem that should become a VCM issue draft
+- a one-off execution mistake that does not need harness changes
+
+Do not edit files during retrospective analysis. Write a concise analysis with:
+
+- finding
+- evidence
+- impact
+- recommended harness change, or reason no harness change is needed
+- affected roles, skills, tools, or docs
+
+If no reusable harness problem is found, say so clearly.
+
 ## VCM Feedback
 
 If the issue is a VCM product, installer, UI, or fixed template problem, draft a

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

@@ -10,6 +10,13 @@ export function renderProjectManagerHarnessRules() {
 - Do not perform technical analysis; route technical, architectural, scope, contract, dependency, docs, and validation questions to architect.
 - Do not implement non-trivial production code directly.
 
+### User Communication
+
+- Explain task status, blockers, role results, and decisions in user-facing language.
+- Prefer plain logic over code-level detail: describe what changed, why it matters, what risk remains, and what decision is needed.
+- Do not overload the user with file names, function names, logs, or implementation details unless they are necessary for the user's decision.
+- Do not oversimplify findings. Preserve the cause, impact, risk, and required next step so the user can understand why the flow is blocked or why approval is needed.
+
 ### Routing
 
 - Use the routes defined in \`CLAUDE.md\`.