vibe-coding-master 0.2.13 → 0.3.1

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

@@ -4,6 +4,7 @@ import path from "node:path";
 import { promisify } from "node:util";
 import { renderArchitectHarnessRules } from "../templates/harness/architect-agent.js";
 import { renderCoderHarnessRules } from "../templates/harness/coder-agent.js";
+import { renderCodexAgentsHarnessRules, renderCodexArchitecturePlanPrompt, renderCodexCliConfigHarnessRules, renderCodexConfigHarnessRules, renderCodexFinalDiffPrompt, renderCodexHooksHarnessRules, renderCodexReviewResultSchema, renderCodexValidationAdequacyPrompt, renderRequestCodexReviewTool, renderVcmCodexReviewGateSkillRules } from "../templates/harness/codex-review.js";
 import { renderRootClaudeHarnessRules } from "../templates/harness/claude-root.js";
 import { renderGitignoreHarnessRules } from "../templates/harness/gitignore.js";
 import { renderProjectManagerHarnessRules } from "../templates/harness/project-manager-agent.js";
@@ -88,6 +89,76 @@ const HARNESS_FILES = [
         ownership: "whole-file",
         renderRules: renderVcmLongRunningValidationSkillRules
     },
+    {
+        kind: "skill-vcm-codex-review-gate",
+        path: ".claude/skills/vcm-codex-review-gate/SKILL.md",
+        title: "VCM Codex Review Gate Skill",
+        frontmatter: renderSkillFrontmatter("vcm-codex-review-gate", "Use when project-manager reaches a Codex Review Gate or receives a VCM Codex Review callback."),
+        ownership: "whole-file",
+        renderRules: renderVcmCodexReviewGateSkillRules
+    },
+    {
+        kind: "codex-agents",
+        path: ".ai/codex/AGENTS.md",
+        title: "VCM Codex Reviewer",
+        renderRules: renderCodexAgentsHarnessRules
+    },
+    {
+        kind: "codex-config",
+        path: ".ai/codex/config.toml",
+        title: "VCM Codex Config",
+        ownership: "raw-file",
+        renderRules: renderCodexConfigHarnessRules
+    },
+    {
+        kind: "codex-cli-config",
+        path: ".ai/codex/.codex/config.toml",
+        title: "VCM Codex CLI Config",
+        ownership: "raw-file",
+        renderRules: renderCodexCliConfigHarnessRules
+    },
+    {
+        kind: "codex-hooks",
+        path: ".ai/codex/.codex/hooks.json",
+        title: "VCM Codex Hooks",
+        ownership: "raw-file",
+        renderRules: renderCodexHooksHarnessRules
+    },
+    {
+        kind: "codex-prompt-architecture-plan",
+        path: ".ai/codex/prompts/architecture-plan-gate.md",
+        title: "Codex Architecture Plan Gate Prompt",
+        ownership: "raw-file",
+        renderRules: renderCodexArchitecturePlanPrompt
+    },
+    {
+        kind: "codex-prompt-validation-adequacy",
+        path: ".ai/codex/prompts/validation-adequacy-gate.md",
+        title: "Codex Validation Adequacy Gate Prompt",
+        ownership: "raw-file",
+        renderRules: renderCodexValidationAdequacyPrompt
+    },
+    {
+        kind: "codex-prompt-final-diff",
+        path: ".ai/codex/prompts/final-diff-gate.md",
+        title: "Codex Final Diff Gate Prompt",
+        ownership: "raw-file",
+        renderRules: renderCodexFinalDiffPrompt
+    },
+    {
+        kind: "codex-review-schema",
+        path: ".ai/codex/schemas/codex-review-result.schema.json",
+        title: "Codex Review Result Schema",
+        ownership: "raw-file",
+        renderRules: renderCodexReviewResultSchema
+    },
+    {
+        kind: "tool-request-codex-review",
+        path: ".ai/tools/request-codex-review",
+        title: "Request Codex Review Tool",
+        ownership: "raw-file",
+        renderRules: renderRequestCodexReviewTool
+    },
     {
         kind: "agent-project-manager",
         path: ".claude/agents/project-manager.md",
@@ -232,13 +303,13 @@ async function analyzeHarnessFiles(fs, repoRoot) {
 }
 async function analyzeHarnessFile(fs, repoRoot, definition) {
     const absolutePath = resolveHarnessPath(repoRoot, definition.path);
-    const expectedContent = definition.ownership === "whole-file"
+    const expectedContent = definition.ownership === "whole-file" || definition.ownership === "raw-file"
         ? renderWholeHarnessFile(definition)
         : undefined;
-    const expectedBlock = definition.ownership === "whole-file"
+    const expectedBlock = definition.ownership === "whole-file" || definition.ownership === "raw-file"
         ? undefined
         : renderManagedBlock(definition, definition.renderRules());
-    const managedBlockPattern = definition.ownership === "whole-file"
+    const managedBlockPattern = definition.ownership === "whole-file" || definition.ownership === "raw-file"
         ? undefined
         : getManagedBlockPattern(definition);
     const exists = await fs.pathExists(absolutePath);
@@ -336,8 +407,21 @@ function renderHarnessStatus(analyses) {
     const plannedChanges = analyses
         .map((analysis) => analysis.plannedChange)
         .filter((change) => Boolean(change));
+    // Derive `initialized`: the VCM harness is considered installed when at least one
+    // VCM-exclusive marker is present (per analysis):
+    //   - status.hasManagedBlock === true (a managed block already lives in the file), OR
+    //   - definition.ownership is "whole-file" | "raw-file" AND status.exists === true
+    //     (a VCM-owned file lives at a VCM-exclusive path).
+    // A pre-existing claude-settings (default "managed-block" ownership, no managed block)
+    // or a non-VCM CLAUDE.md/.gitignore (action "insert", hasManagedBlock === false) is
+    // intentionally NOT counted as initialized.
+    const initialized = analyses.some((analysis) => analysis.status.hasManagedBlock ||
+        ((analysis.definition.ownership === "whole-file" ||
+            analysis.definition.ownership === "raw-file") &&
+            analysis.status.exists));
     return {
         version: VCM_HARNESS_VERSION,
+        initialized,
         files,
         needsApply: plannedChanges.length > 0,
         plannedChanges,
@@ -365,6 +449,9 @@ function renderNewHarnessFile(definition, block) {
     return `${frontmatter}# ${definition.title}\n\n${block}\n`;
 }
 function renderWholeHarnessFile(definition) {
+    if (definition.ownership === "raw-file") {
+        return ensureTrailingNewline(definition.renderRules().trimEnd());
+    }
     return ensureTrailingNewline(renderNewHarnessFile(definition, definition.renderRules().trimEnd()));
 }
 async function analyzeClaudeSettingsFile(fs, repoRoot) {

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

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { ROLE_NAMES, isRoleName } from "../../shared/constants.js";
+import { VCM_ROLE_NAMES, isVcmRoleName } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
@@ -282,8 +282,8 @@ async function listRouteFiles(fs, input) {
     return routeFiles;
 }
 function parseRouteFileName(fileName) {
-    for (const fromRole of ROLE_NAMES) {
-        for (const toRole of ROLE_NAMES) {
+    for (const fromRole of VCM_ROLE_NAMES) {
+        for (const toRole of VCM_ROLE_NAMES) {
             if (fromRole === toRole) {
                 continue;
             }
@@ -371,14 +371,14 @@ function selectDispatchCandidates(routeFiles, stoppedRole) {
     });
 }
 function validateMessagePolicy(fromRole, toRole, type) {
-    if (!ROLE_NAMES.includes(toRole)) {
+    if (!VCM_ROLE_NAMES.includes(toRole)) {
         throw new VcmError({
             code: "MESSAGE_TARGET_UNKNOWN",
             message: `Unknown target role: ${toRole}`,
             statusCode: 400
         });
     }
-    if (!isRoleName(String(fromRole))) {
+    if (!isVcmRoleName(String(fromRole))) {
         throw new VcmError({
             code: "MESSAGE_SENDER_UNKNOWN",
             message: `Unknown sender role: ${fromRole}`,
@@ -424,7 +424,8 @@ function getMessageDeliveryTime(message) {
     return message.deliveredAt ?? message.createdAt;
 }
 async function clearRouteFileIfStillMatchesMessage(fs, input, message) {
-    if (!message.routePath || !isRoleName(String(message.fromRole))) {
+    const fromRole = message.fromRole;
+    if (!message.routePath || !isVcmRoleName(fromRole)) {
         return;
     }
     const absolutePath = resolveRepoPath(input.taskRepoRoot ?? input.repoRoot, message.routePath);
@@ -432,7 +433,7 @@ async function clearRouteFileIfStillMatchesMessage(fs, input, message) {
         return;
     }
     const routeContent = await fs.readText(absolutePath);
-    const parsed = parseRouteFileContent(routeContent, message.fromRole, message.toRole);
+    const parsed = parseRouteFileContent(routeContent, fromRole, message.toRole);
     if (parsed.body.trim() === message.body.trim() &&
         parsed.type === message.type &&
         arraysEqual(parsed.artifactRefs, message.artifactRefs)) {

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

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { ROLE_NAMES } from "../../shared/constants.js";
+import { VCM_ROLE_NAMES } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 const DEFAULT_HANDOFF_ROOT = ".ai/vcm/handoffs";
 const DEFAULT_STATE_ROOT = ".ai/vcm";
@@ -182,7 +182,7 @@ export function buildDefaultProjectConfig(repoRoot) {
     return {
         version: 1,
         repoRoot,
-        defaultRoles: [...ROLE_NAMES],
+        defaultRoles: [...VCM_ROLE_NAMES],
         handoffRoot: DEFAULT_HANDOFF_ROOT,
         stateRoot: DEFAULT_STATE_ROOT,
         terminalBackend: "node-pty",

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

@@ -134,6 +134,32 @@ export function createRoundService(deps) {
         }, delayMs);
         settleTimers.set(getRoundStatePath(input), timer);
     }
+    async function recordRoleTurnEvent(input) {
+        return withTaskLock(input, async () => {
+            const timestamp = now();
+            const settled = await settleIfNeeded(input, await load(input), timestamp);
+            const current = settled.currentRound;
+            const shouldStartNewRound = input.eventName === "UserPromptSubmit" && (!current || current.status === "stopped");
+            const next = applyRoundHookEvent({
+                state: settled,
+                taskSlug: input.taskSlug,
+                role: input.role,
+                eventName: input.eventName,
+                timestamp,
+                roundId: shouldStartNewRound ? id() : current?.id ?? "",
+                settleMs
+            });
+            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 toSessionRoundState(next, timestamp);
+        });
+    }
     async function withTaskLock(input, run) {
         const key = getRoundStatePath(input);
         const previous = taskLocks.get(key) ?? Promise.resolve();
@@ -155,31 +181,9 @@ export function createRoundService(deps) {
                 return toSessionRoundState(await load(input), timestamp);
             });
         },
-        async recordClaudeHookEvent(input) {
-            return withTaskLock(input, async () => {
-                const timestamp = now();
-                const settled = await settleIfNeeded(input, await load(input), timestamp);
-                const current = settled.currentRound;
-                const shouldStartNewRound = input.eventName === "UserPromptSubmit" && (!current || current.status === "stopped");
-                const next = applyRoundHookEvent({
-                    state: settled,
-                    taskSlug: input.taskSlug,
-                    role: input.role,
-                    eventName: input.eventName,
-                    timestamp,
-                    roundId: shouldStartNewRound ? id() : current?.id ?? "",
-                    settleMs
-                });
-                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 toSessionRoundState(next, timestamp);
-            });
+        recordRoleTurnEvent,
+        recordClaudeHookEvent(input) {
+            return recordRoleTurnEvent(input);
         },
         stopSession() { },
         stopTask(taskSlug) {

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

@@ -5,6 +5,10 @@ import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { claudeTranscriptPath } from "./claude-transcript-service.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
+const CODEX_REVIEWER_ROLE = "codex-reviewer";
+const CODEX_DIR = ".ai/codex";
+const CODEX_REVIEW_DIR = ".ai/vcm/codex-reviews";
+const CODEX_CONFIG_PATH = ".ai/codex/config.toml";
 export function createSessionService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
     async function launchRoleSession(repoRoot, taskSlug, role, input, launchMode) {
@@ -17,29 +21,38 @@ export function createSessionService(deps) {
         const taskRepoRoot = getTaskRuntimeRepoRoot(task);
         const paths = deps.artifactService.getHandoffPaths(taskRepoRoot, task.handoffDir);
         const persisted = await loadPersistedRoleRecord(deps.fs, taskRepoRoot, config.stateRoot, taskSlug, role);
+        const isCodexReviewer = role === CODEX_REVIEWER_ROLE;
         const permissionMode = normalizeClaudePermissionMode(input.permissionMode ?? persisted?.permissionMode);
-        const model = normalizeClaudeModel(input.model ?? persisted?.model);
+        const model = isCodexReviewer
+            ? normalizeCodexModel(input.model ?? persisted?.model)
+            : normalizeClaudeModel(input.model ?? persisted?.model);
+        const effort = normalizeSessionEffort(input.effort ?? persisted?.effort);
         const claudeSessionId = launchMode === "resume"
             ? persisted?.claudeSessionId
             : randomUUID();
         if (!claudeSessionId) {
             throw new VcmError({
                 code: "CLAUDE_SESSION_MISSING",
-                message: `${role} does not have a Claude session id to resume.`,
+                message: `${role} does not have a session id to resume.`,
                 statusCode: 409,
                 hint: "Start the role once before using Resume."
             });
         }
         const transcriptPath = launchMode === "resume" && persisted?.transcriptPath
             ? persisted.transcriptPath
-            : claudeTranscriptPath(taskRepoRoot, claudeSessionId);
-        const startCommand = deps.claude.buildRoleStartCommand(role, config.claudeCommand, permissionMode, claudeSessionId, launchMode === "resume", model);
+            : isCodexReviewer ? undefined : claudeTranscriptPath(taskRepoRoot, claudeSessionId);
+        const startCommand = isCodexReviewer
+            ? await buildCodexReviewerStartCommand(deps.fs, taskRepoRoot, launchMode, model, effort)
+            : {
+                ...deps.claude.buildRoleStartCommand(role, config.claudeCommand, permissionMode, claudeSessionId, launchMode === "resume", model, effort),
+                cwd: taskRepoRoot
+            };
         const runtimeSession = await deps.runtime.createSession({
             taskSlug,
             role,
             command: startCommand.command,
             args: startCommand.args,
-            cwd: taskRepoRoot,
+            cwd: startCommand.cwd,
             env: {
                 VCM_API_URL: deps.apiUrl,
                 VCM_TASK_REPO_ROOT: taskRepoRoot,
@@ -63,7 +76,8 @@ export function createSessionService(deps) {
             command: startCommand.display,
             permissionMode,
             model,
-            cwd: taskRepoRoot,
+            effort,
+            cwd: startCommand.cwd,
             terminalBackend: "node-pty",
             pid: runtimeSession.pid,
             logPath: paths.roleLogPaths[role],
@@ -159,15 +173,18 @@ export function createSessionService(deps) {
             }
             return sessions;
         },
-        async recordClaudeHookEvent(repoRoot, input) {
+        async recordRoleHookEvent(repoRoot, input) {
             const current = await this.getRoleSession(repoRoot, input.taskSlug, input.role);
-            if (!current || !matchesClaudeHookSession(current, input)) {
+            if (!current || (!input.allowSessionMismatch && !matchesRoleHookSession(current, input))) {
                 return undefined;
             }
             const timestamp = now();
             const isStop = input.eventName === "Stop";
             const updated = {
                 ...current,
+                claudeSessionId: input.sessionId ?? current.claudeSessionId,
+                transcriptPath: input.transcriptPath ?? current.transcriptPath,
+                cwd: input.cwd ?? current.cwd,
                 activityStatus: isStop ? "idle" : "running",
                 lastHookEventAt: timestamp,
                 lastTurnEndedAt: isStop ? timestamp : current.lastTurnEndedAt,
@@ -180,6 +197,16 @@ export function createSessionService(deps) {
             await persistTaskSession(deps.fs, getTaskRuntimeRepoRoot(task), config.stateRoot, updated);
             return updated;
         },
+        recordClaudeHookEvent(repoRoot, input) {
+            return this.recordRoleHookEvent(repoRoot, {
+                taskSlug: input.taskSlug,
+                role: input.role,
+                eventName: input.eventName,
+                sessionId: input.claudeSessionId,
+                transcriptPath: input.transcriptPath,
+                cwd: input.cwd
+            });
+        },
         async markRoleActivityRunning(repoRoot, taskSlug, role) {
             const current = await this.getRoleSession(repoRoot, taskSlug, role);
             if (!current) {
@@ -201,14 +228,67 @@ export function createSessionService(deps) {
         }
     };
 }
-function matchesClaudeHookSession(record, input) {
-    if (input.claudeSessionId && record.claudeSessionId === input.claudeSessionId) {
+async function buildCodexReviewerStartCommand(fs, taskRepoRoot, launchMode, selectedModel, selectedEffort) {
+    const codexDir = resolveRepoPath(taskRepoRoot, CODEX_DIR);
+    const reviewDir = resolveRepoPath(taskRepoRoot, CODEX_REVIEW_DIR);
+    if (!(await fs.pathExists(codexDir))) {
+        throw new VcmError({
+            code: "CODEX_REVIEW_CONFIG_MISSING",
+            message: `${CODEX_DIR} does not exist.`,
+            statusCode: 409,
+            hint: "Apply the VCM harness before starting Codex Reviewer."
+        });
+    }
+    await fs.ensureDir(reviewDir);
+    const config = await loadCodexSessionConfig(fs, taskRepoRoot);
+    const model = selectedModel === "default"
+        ? config.model
+        : selectedModel;
+    const modelReasoningEffort = selectedEffort === "default"
+        ? config.modelReasoningEffort
+        : selectedEffort;
+    const args = launchMode === "resume"
+        ? ["resume", "--last"]
+        : [];
+    args.push("--cd", codexDir, "--add-dir", reviewDir, "--sandbox", "workspace-write", "--ask-for-approval", "never", "--dangerously-bypass-hook-trust");
+    if (model && model !== "default") {
+        args.push("--model", model);
+    }
+    if (modelReasoningEffort && modelReasoningEffort !== "default") {
+        args.push("--config", `model_reasoning_effort="${modelReasoningEffort}"`);
+    }
+    return {
+        command: config.command,
+        args,
+        cwd: taskRepoRoot,
+        display: [config.command, ...args].map(formatDisplayArg).join(" ")
+    };
+}
+async function loadCodexSessionConfig(fs, taskRepoRoot) {
+    const configPath = resolveRepoPath(taskRepoRoot, CODEX_CONFIG_PATH);
+    if (!(await fs.pathExists(configPath))) {
+        return {
+            command: "codex",
+            model: "gpt-5.5",
+            modelReasoningEffort: "xhigh"
+        };
+    }
+    const content = await fs.readText(configPath);
+    const reviewSection = extractTomlSection(content, "vcm.codex_review");
+    return {
+        command: parseTomlString(reviewSection, "command") ?? "codex",
+        model: parseTomlString(content, "model") ?? "gpt-5.5",
+        modelReasoningEffort: parseTomlString(content, "model_reasoning_effort") ?? "xhigh"
+    };
+}
+function matchesRoleHookSession(record, input) {
+    if (input.sessionId && record.claudeSessionId === input.sessionId) {
         return true;
     }
     if (input.transcriptPath && record.transcriptPath === input.transcriptPath) {
         return true;
     }
-    if (!input.claudeSessionId && !input.transcriptPath) {
+    if (!input.sessionId && !input.transcriptPath) {
         return true;
     }
     return false;
@@ -249,7 +329,10 @@ async function loadPersistedRoleRecord(fs, repoRoot, stateRoot, taskSlug, role)
                 ? legacy.lastStopAt
                 : undefined),
             permissionMode: normalizeClaudePermissionMode(record.permissionMode),
-            model: normalizeClaudeModel(record.model)
+            model: record.role === CODEX_REVIEWER_ROLE
+                ? normalizeCodexModel(record.model)
+                : normalizeClaudeModel(record.model),
+            effort: normalizeSessionEffort(record.effort)
         }
         : undefined;
 }
@@ -311,3 +394,49 @@ function normalizeClaudeModel(value) {
     }
     return "default";
 }
+function normalizeCodexModel(value) {
+    if (value === "default" || value === "gpt-5.5") {
+        return value;
+    }
+    return "gpt-5.5";
+}
+function normalizeSessionEffort(value) {
+    if (value === "low"
+        || value === "medium"
+        || value === "high"
+        || value === "xhigh"
+        || value === "max") {
+        return value;
+    }
+    return "default";
+}
+function extractTomlSection(content, sectionName) {
+    const lines = content.split(/\r?\n/);
+    const header = `[${sectionName}]`;
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start < 0) {
+        return "";
+    }
+    const section = [];
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (/^\s*\[[^\]]+\]\s*$/.test(line)) {
+            break;
+        }
+        section.push(line);
+    }
+    return section.join("\n");
+}
+function parseTomlString(content, key) {
+    const pattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=\\s*"([^"]*)"\\s*$`, "m");
+    return pattern.exec(content)?.[1];
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function formatDisplayArg(value) {
+    if (/^[A-Za-z0-9_./:=@+-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

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

@@ -204,6 +204,7 @@ async function ensureTaskRuntimeStateDirs(fs, taskRepoRoot, stateRoot) {
     await fs.ensureDir(path.join(taskRepoRoot, stateRoot, "messages"));
     await fs.ensureDir(path.join(taskRepoRoot, stateRoot, "orchestration"));
     await fs.ensureDir(path.join(taskRepoRoot, stateRoot, "translation"));
+    await fs.ensureDir(path.join(taskRepoRoot, stateRoot, "codex-reviews"));
 }
 async function findActiveInlineTask(fs, taskStoreRoot) {
     const tasksDir = path.join(taskStoreRoot, "tasks");
@@ -255,6 +256,7 @@ function getTaskStatePaths(taskStoreRoot, taskRepoRoot, stateRoot, handoffRoot,
         path.join(taskRepoRoot, stateRoot, "messages", `${taskSlug}.jsonl`),
         path.join(taskRepoRoot, stateRoot, "orchestration", `${taskSlug}.json`),
         path.join(taskRepoRoot, stateRoot, "translation", taskSlug),
+        path.join(taskRepoRoot, stateRoot, "codex-reviews"),
         path.join(taskRepoRoot, handoffRoot)
     ];
 }

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

@@ -5,6 +5,7 @@ export function renderRootClaudeHarnessRules() {
 - Read module-local \`CLAUDE.md\` before editing a subdirectory if one exists.
 - Use \`vcm-route-message\` whenever a VCM role hands off work, asks another role a question, reports a result, reports a blocker, or raises a finding. Follow its write-then-stop rule.
 - Use \`vcm-long-running-validation\` for long-running validation. Follow the background job limits below.
+- Project-manager uses \`vcm-codex-review-gate\` at enabled Codex Review Gate trigger points and on VCM Codex review callbacks.
 
 ## VCM Background Jobs
 
@@ -31,6 +32,7 @@ export function renderRootClaudeHarnessRules() {
 - Test-only or validation-only work may use: \`project-manager -> reviewer -> project-manager final acceptance\`.
 - If a docs/test/validation-only task reveals required code, architecture, public contract, dependency, durable-doc, or test-strategy changes, route back through the full code-change flow.
 - Keep role outputs under \`.ai/vcm/handoffs/\`.
+- Codex Review Gate reports live under \`.ai/vcm/codex-reviews/\` and are VCM-managed task evidence.
 - Runtime task records and handoffs under \`.ai/vcm/\` are temporary. Durable facts must move into code, tests, PR text, commit history, or long-term docs.
 - Record current-task unresolved findings in \`.ai/vcm/handoffs/known-issues.md\`.