vibe-coding-master 0.3.26 → 0.3.28

package/docs/product-design.md

@@ -1,6 +1,6 @@
 # VibeCodingMaster Product Design
 
-Last updated: 2026-06-13
+Last updated: 2026-06-21
 
 This document describes the current product direction and implemented V1 behavior for VCM.
 
@@ -44,7 +44,7 @@ This `Session` term is only for VCM statistics. It must not be confused with a C
 VCM V1 must make multi-session Claude Code work visible and recoverable:
 
 - Connect a local Git repository.
-- Create a named task with its own branch and task-level worktree by default.
+- Create a named task with its own branch and task-level worktree.
 - Start, stop, restart, and resume one Claude Code session per role.
 - Keep role terminals embedded in one GUI.
 - Preserve task state, session state, handoff files, and message history.
@@ -82,43 +82,40 @@ project-manager
   -> project-manager final acceptance, commit, and PR
 ```
 
-### 4.1 Codex Review Gates
+### 4.1 Gate Review Gates
 
-For complex tasks, VCM supports optional Codex Review Gates as an independent
-cross-model review layer. Claude Code remains the role execution engine, but
-Codex reviews three high-value handoff points:
+For complex tasks, VCM supports optional Gate Review Gates through an
+independent `gate-reviewer` Claude Code role. The reviewer uses a
+project-scoped long-lived session, but every gate prompt names the current task
+and task worktree so task evidence stays explicit.
 
 ```text
 architect architecture plan
-  -> Codex reviews plan quality before coder starts
+  -> Gate Reviewer checks plan quality before coder starts
 
 reviewer review-report
-  -> Codex reviews validation adequacy before final acceptance
+  -> Gate Reviewer checks validation adequacy before final acceptance
 
 final task diff
-  -> Codex reviews code and PR readiness before PR preparation
+  -> Gate Reviewer checks code and PR readiness before PR preparation
 ```
 
 Each gate returns `approve` or `request_changes`. PM triggers gates through the
-`vcm-codex-review-gate` skill at the three workflow points; VCM owns the Codex
-Review sidebar toggles, gate state, Codex CLI / adapter execution, and PM
-callback after review completes. Codex writes reports under
-`.ai/vcm/codex-reviews/`. All three gate toggles default to off.
-When any gate is on, or when a Codex Reviewer session already exists, the task
-workspace shows `Codex Reviewer` as a fifth terminal role with Codex model and
-effort selection. VCM sends gate prompts into this long-lived terminal session
-so the review can be challenged or clarified afterward; the role remains
-outside PM routing and Claude Code auto orchestration. Codex Reviewer
-`UserPromptSubmit` and `Stop` hooks post back to VCM from
-`.ai/codex/.codex/hooks.json`, so the fifth role participates in session and
-Round state while a gate is running.
+`vcm-gate-review` skill at the three workflow points; VCM owns the sidebar
+toggles, gate state, Gate Reviewer session, report polling, and PM callback.
+Reports are task-scoped under `.ai/vcm/gate-reviews/`. All three gate toggles
+default to off.
+
+When any gate is on, or when a Gate Reviewer session already exists, the task
+workspace shows `Gate Reviewer` as a fifth terminal role. VCM sends a short gate
+prompt into that session and manually marks the role/Round running until the
+assigned report is valid. The role remains outside PM routing and normal
+auto-orchestration.
 Architecture-plan findings return to architect, validation-adequacy findings
 return to reviewer, and final-diff findings go to architect first for
-assessment. Codex reviewer role configuration lives under `.ai/codex/`,
-including `.ai/codex/AGENTS.md` and `.ai/codex/config.toml`, so VCM does not
-require a root-level `AGENTS.md`.
+assessment. Gate Reviewer role rules live in `.claude/agents/gate-reviewer.md`.
 
-The detailed design lives in `docs/codex-review-gates.md`.
+The detailed design lives in `docs/gate-review-gates.md`.
 
 ### 4.2 Task Worktree Model
 
@@ -277,6 +274,9 @@ Sections:
 - `Repository Path`
 - `Connected Repository`
 - `Settings`
+- `Translation`
+- `Gate Review Gates`
+- `Gateway`
 - `VCM Harness`
 - `New Task`
 - `Tasks`
@@ -330,6 +330,24 @@ Safari may still require the user to manually set `Safari > Website Settings > A
 
 There is no separate `Pause orchestration` or `Resume orchestration` control in the GUI. The current product model is one on/off toggle in the role console toolbar.
 
+`Translation` contains:
+
+- `Conversation translation`
+- `Auto-send`
+- `Language`
+- `Reply scope`
+- `File translation`
+- `Bootstrap`
+- `Update memory`
+- `Session status`
+- `Open Session`
+
+`Gate Review Gates` contains three independent switches:
+
+- `Architecture plan`
+- `Validation adequacy`
+- `Final diff`
+
 `VCM Harness` shows whether VCM managed blocks are installed/up to date in the project rules files and `.gitignore`.
 
 `New Task` contains:
@@ -345,14 +363,16 @@ There is no optional title input in the current UI.
 The task workspace header is one compact row:
 
 ```text
-<task>  [Project Manager] [Architect] [Coder] [Reviewer]  [Translate] [Close Task]
+<task>  [Project Manager] [Architect] [Coder] [Reviewer] [Gate Reviewer?]  [Auto orchestration] [Close Task]
 ```
 
 The header does not show `TASK WORKSPACE`, branch, or worktree path. Task branch/worktree details remain task metadata, but they are not first-row chrome.
 
 The task workspace does not show a manual `Refresh` button. Task status, role status, messages, orchestration state, and flow pause state refresh automatically. The only remaining `Refresh` control is inside the sidebar `VCM Harness` section, where it rechecks managed project files.
 
-Role tabs show the session status for each role.
+Role tabs show the session status for each visible role. `Gate Reviewer` appears
+only when a Gate Review switch is enabled or a Gate Reviewer session already
+exists.
 
 The main task workspace only renders the active role console. Messages and Events are opened from the sidebar.
 
@@ -389,7 +409,7 @@ The split should stay close to 50/50 width. Both panes expand vertically to fill
 
 ## 8. Flow Pause Detection
 
-VCM detects flow pauses from role hook events, not from terminal silence, message history, or pending route files. Claude Code roles report through `.claude/settings.json`; Codex Reviewer reports through `.ai/codex/.codex/hooks.json`.
+VCM detects flow pauses from role hook events, not from terminal silence, message history, or pending route files. Claude Code roles report through `.claude/settings.json`; VCM directly records Gate Reviewer turns while a gate prompt is active.
 
 Backend role state:
 
@@ -397,7 +417,7 @@ Backend role state:
 - `Stop`: role becomes `idle` and records `lastTurnEndedAt`.
 - `PostCompact`: refreshes role session metadata and records `lastCompactAt` without changing `running`/`idle`.
 - `StopFailure`: first checks completion evidence. If the role already wrote an outgoing route file, VCM marks the role idle and dispatches normally. If not, VCM sends a recovery prompt to the same role without marking it idle.
-- The role tab and flow pause state both react to Claude Code and Codex Reviewer hook events.
+- The role tab and flow pause state react to Claude Code hook events plus VCM-recorded Gate Reviewer gate turns.
 
 Task-level Round state:
 
@@ -587,18 +607,13 @@ VCM Harness injects Claude Code hooks into `.claude/settings.json`:
 
 VCM uses `UserPromptSubmit` as the Claude Code acceptance signal. A successful PTY write only proves VCM delivered text to the embedded terminal; `UserPromptSubmit` proves Claude Code accepted the prompt.
 
-VCM Harness also injects Codex Reviewer hooks into `.ai/codex/.codex/hooks.json`:
-
-- `UserPromptSubmit`: posts directly to `/api/hooks/codex-reviewer`, marks the fifth role running, and starts or continues the shared Round state
-- `Stop`: posts directly to `/api/hooks/codex-reviewer/stop`, marks the fifth role idle, and lets the Round settle normally
-
-Codex Reviewer hooks do not dispatch route files. PM receives Codex review completion through the Codex Review Gate callback managed by VCM.
+Gate Reviewer does not dispatch route files. PM receives Gate Review completion through the Gate Review callback managed by VCM.
 
 The injected role rules require asynchronous file messaging: after writing or updating a route file, the role must end the current Claude Code turn and wait for VCM to deliver a later reply. Roles should use `.claude/skills/vcm-route-message/SKILL.md` to author route files. Roles must not poll files, start shell loops, keep the turn open waiting for another role to answer, paste directly into another role terminal, or use Claude Code Task/Subagent for VCM role delegation.
 
 Roles must not run background Bash; a `PreToolUse` hook (`.ai/tools/vcm-bash-guard`) denies `run_in_background`, `nohup`, `setsid`, `disown`, and trailing `&`. The only sanctioned long-running mechanism is `.ai/tools/run-long-check` plus `.ai/tools/watch-job` through `vcm-long-running-validation`: the detached job worker enforces the 60 minute ceiling and a supervision lease that kills unwatched jobs, `watch-job` renews the lease in foreground windows of up to 8 minutes (exit `125` means call it again in the same turn), and the VCM backend blocks a role's turn-end while one of its validation jobs is still running.
 
-There is no `vcmctl` in the target design. Hook entrypoints are direct HTTP from Claude Code and Codex Reviewer hooks to the local VCM backend.
+There is no `vcmctl` in the target design. Hook entrypoints are direct HTTP from Claude Code hooks to the local VCM backend.
 
 ## 13. Translation
 
@@ -711,7 +726,11 @@ Translation panel `Auto-send` is separate from task `Auto orchestration`:
 - `Auto-send` on: translate and send if there is no translation warning.
 - `Auto-send` off: translate to English draft and wait for user send.
 
-Task `Auto orchestration` is a compact selected/unselected button in the role console toolbar. New tasks default to auto orchestration. `Translate` is a global task header toggle next to `Close Task`; it opens/closes the translation split for all role consoles, so switching roles keeps the same translation setting.
+Task `Auto orchestration` is a compact selected/unselected button in the task
+workspace header next to `Close Task`. New tasks default to auto orchestration.
+Conversation translation is controlled by the sidebar `Translation` group; when
+enabled, each running core VCM role console shows the translation split, so
+switching roles keeps the same global translation setting.
 
 ## 14. Mobile Gateway
 
@@ -777,7 +796,6 @@ and audit logs live under `vcmDataDir`. VCM resolves `vcmDataDir` from
 Repository-level VCM state:
 
 ```text
-.ai/vcm/tasks/<task>.json
 .claude/worktrees/<task>/
 ```
 
@@ -797,10 +815,20 @@ Task worktree local files:
 .claude/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
 .claude/worktrees/<task>/.ai/vcm/orchestration/<task>.json
 .claude/worktrees/<task>/.ai/vcm/translation/<task>/
+.claude/worktrees/<task>/.ai/vcm/gate-reviews/
 .claude/worktrees/<task>/.ai/vcm/handoffs/
 .claude/worktrees/<task>/.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
 ```
 
+Project-scoped local files:
+
+```text
+.ai/vcm/gate-reviewer/session.json
+.ai/vcm/translations/
+.ai/vcm/bootstrap/session.json
+.ai/vcm/bootstrap/bootstrap.log
+```
+
 External Claude transcripts:
 
 ```text

package/docs/v0.2-implementation-plan.md

@@ -2,6 +2,10 @@
 
 Last updated: 2026-06-10
 
+> Archived historical plan. This document records the 0.2 design context and is
+> not the current implementation reference. For current behavior, use
+> `README.md`, `docs/gateway-design.md`, and `docs/full-harness-baseline.md`.
+
 VCM 0.2 has two product tracks:
 
 - Mobile gateway through Tencent iLink Bot API / Weixin DM.

package/docs/vcm-cc-best-practices.md

@@ -1,13 +1,14 @@
 # VCM Claude Code Best Practices
 
-Last updated: 2026-06-08
+Last updated: 2026-06-21
 
 This is the current VCM-specific Claude Code / AI coding best-practices guide.
 It is based on the latest `example/rust-layered` harness baseline.
 
 Do not install this document into target repositories. Target repositories should
-receive a concise root `CLAUDE.md` VCM block, four role agents, repo-local VCM
-skills, harness tools, and project-owned durable docs.
+receive a concise root `CLAUDE.md` VCM block, role agents, repo-local VCM
+skills, harness tools, Codex Translator harness files, and project-owned
+durable docs.
 
 `docs/cc-best-practices.md` is archived as the old generic baseline. Current VCM
 implementation should use this document and `docs/full-harness-baseline.md`.
@@ -17,7 +18,7 @@ implementation should use this document and `docs/full-harness-baseline.md`.
 VCM separates three concerns:
 
 - Harness-managed files: VCM owns, upgrades, repairs, audits, and can uninstall
-  these through `.ai/vcm-harness-manifest.json`.
+  these through deterministic installer definitions and managed markers.
 - Project-owned durable docs: VCM bootstrap may create or initialize these, but
   they become project truth and are not VCM-owned harness.
 - Runtime state: VCM writes these during task execution and cleans them up after
@@ -41,13 +42,19 @@ CLAUDE.md
 .claude/agents/architect.md
 .claude/agents/coder.md
 .claude/agents/reviewer.md
+.claude/agents/gate-reviewer.md
 .claude/skills/vcm-route-message/SKILL.md
 .claude/skills/vcm-final-acceptance/SKILL.md
 .claude/skills/vcm-long-running-validation/SKILL.md
 .claude/skills/vcm-harness-bootstrap/SKILL.md
-.ai/vcm-harness-manifest.json
+.claude/skills/vcm-gate-review/SKILL.md
+.ai/codex-translator/AGENTS.md
+.ai/codex-translator/config.toml
+.ai/codex-translator/.codex/config.toml
+.ai/codex-translator/.codex/hooks.json
 .ai/tools/generate-module-index
 .ai/tools/generate-public-surface
+.ai/tools/request-gate-review
 .ai/tools/run-long-check
 .ai/tools/watch-job
 .ai/tools/vcm-bash-guard
@@ -61,9 +68,8 @@ Derived bootstrap artifacts:
 .ai/generated/public-surface.json
 ```
 
-The generated artifacts are tracked in the manifest as derived artifacts so VCM
-can clean or refresh them, but they are produced by generator tools during
-bootstrap or later maintenance work. They are not hand-authored fixed templates.
+The generated artifacts are produced by generator tools during bootstrap or
+later maintenance work. They are not hand-authored fixed templates.
 
 Runtime roots:
 
@@ -80,6 +86,7 @@ Not part of the current baseline:
 .ai/task-specs/
 .ai/vcm/tasks/
 .ai/vcm/handoffs/role-commands/
+.ai/vcm-harness-manifest.json
 docs/plans/active/
 docs/plans/completed/
 docs/MODULE_MAP.md
@@ -100,35 +107,31 @@ docs/AI_WORKFLOW.md
 
 Do not reintroduce these unless there is a current VCM requirement.
 
-## 3. Harness Manifest
+## 3. Harness Ownership
 
-`.ai/vcm-harness-manifest.json` is a VCM harness ownership and lifecycle record.
-It is not a project-document index.
+VCM harness ownership is defined by the installer code and by managed markers.
+The current implementation does not use `.ai/vcm-harness-manifest.json`.
 
-It should record:
+VCM-owned managed blocks use markers such as:
 
-- VCM-managed files and directories
-- managed-block marker type and boundaries
-- JSON merge ownership, especially `.claude/settings.json` hooks
-- VCM agent and skill files
-- harness tools under `.ai/tools/`
-- generated context artifacts under `.ai/generated/`
-- PR template managed blocks
-- lifecycle labels
-- runtime roots
-- uninstall actions
+```md
+<!-- VCM:BEGIN version=1 -->
+...
+<!-- VCM:END -->
+```
 
-It should not record:
+For `.gitignore`, VCM uses:
 
-- project-owned durable docs such as `docs/ARCHITECTURE.md`,
-  `docs/TESTING.md`, `docs/known-issues.md`, `docs/plans/`, or module-level
-  `ARCHITECTURE.md`
-- `.ai/vcm/**` runtime files
-- `.claude/worktrees/**` task worktrees
-- placeholder `.gitkeep` files
+```gitignore
+# VCM:BEGIN version=1
+...
+# VCM:END
+```
 
-VCM uninstall should remove only VCM-owned managed blocks or unchanged VCM-owned
-whole files. User-authored project docs must not be deleted by harness uninstall.
+Whole-file and raw-file harness files are owned by VCM only when their paths are
+listed by the fixed installer. VCM uninstall should remove only VCM-owned
+managed blocks or unchanged VCM-owned whole files. User-authored project docs
+must not be deleted by harness uninstall.
 
 ## 4. Project-Owned Durable Docs
 
@@ -169,6 +172,7 @@ Current runtime files and directories:
 .ai/vcm/handoffs/docs-sync-report.md
 .ai/vcm/handoffs/final-acceptance.md
 .ai/vcm/handoffs/known-issues.md
+.ai/vcm/gate-reviews/
 .ai/vcm/jobs/<job-id>/
 .ai/vcm/bootstrap/session.json
 .ai/vcm/bootstrap/bootstrap.log
@@ -417,7 +421,7 @@ an invisible background task:
 
 The UI should expose both stages: fixed install status and bootstrap completion
 status. A failed or disconnected bootstrap terminal should be restartable
-without treating project-owned durable docs as VCM-owned manifest entries.
+without treating project-owned durable docs as VCM-owned harness files.
 
 ## 12. Final Acceptance
 
@@ -444,7 +448,6 @@ Temporary files should be deleted after the task:
 - route messages
 - handoff artifacts
 - job logs and status files
-- raw terminal logs
 - app-local task records
 - routine completed plans
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [

package/scripts/verify-package.mjs

@@ -16,10 +16,10 @@ const requiredFiles = [
   "dist/main.js",
   "dist/backend/server.js",
   "dist/backend/api/harness-routes.js",
-  "dist/backend/api/codex-review-routes.js",
+  "dist/backend/api/gate-review-routes.js",
   "dist/backend/runtime/node-pty-runtime.js",
   "dist/backend/ws/terminal-ws.js",
-  "dist/backend/services/codex-review-service.js",
+  "dist/backend/services/gate-review-service.js",
   "dist/backend/services/harness-service.js",
   "dist/backend/services/session-service.js",
   "dist/backend/services/project-service.js",
@@ -29,9 +29,9 @@ const requiredFiles = [
   "dist/backend/templates/harness/architect-agent.js",
   "dist/backend/templates/harness/coder-agent.js",
   "dist/backend/templates/harness/reviewer-agent.js",
-  "dist/backend/templates/harness/codex-review.js",
+  "dist/backend/templates/harness/gate-review.js",
   "dist/shared/constants.js",
-  "dist/shared/types/codex-review.js",
+  "dist/shared/types/gate-review.js",
   "dist/shared/types/harness.js",
   "dist/shared/validation/slug-check.js",
   "dist/shared/validation/artifact-check.js",

package/dist/backend/api/codex-review-routes.js

@@ -1,58 +0,0 @@
-import { VcmError } from "../errors.js";
-import { isCodexReviewGate } from "../services/codex-review-service.js";
-export function registerCodexReviewRoutes(app, deps) {
-    app.get("/api/tasks/:taskSlug/codex-review", async (request) => {
-        const project = await requireCurrentProject(deps.projectService);
-        return deps.codexReviewService.getState(project.repoRoot, request.params.taskSlug);
-    });
-    app.put("/api/tasks/:taskSlug/codex-review/settings", async (request) => {
-        const project = await requireCurrentProject(deps.projectService);
-        return deps.codexReviewService.updateSettings(project.repoRoot, request.params.taskSlug, request.body);
-    });
-    app.post("/api/tasks/:taskSlug/codex-review/:gate/request", async (request) => {
-        const project = await requireCurrentProject(deps.projectService);
-        const gate = parseGate(request.params.gate);
-        return deps.codexReviewService.requestReviewGate(project.repoRoot, request.params.taskSlug, gate);
-    });
-    app.post("/api/tasks/:taskSlug/codex-review/:gate/retry", async (request) => {
-        const project = await requireCurrentProject(deps.projectService);
-        const gate = parseGate(request.params.gate);
-        return deps.codexReviewService.retryReviewGate(project.repoRoot, request.params.taskSlug, gate);
-    });
-    app.post("/api/tasks/:taskSlug/codex-review/:gate/skip", async (request) => {
-        const project = await requireCurrentProject(deps.projectService);
-        const gate = parseGate(request.params.gate);
-        return deps.codexReviewService.skipReviewGate(project.repoRoot, request.params.taskSlug, gate, request.body);
-    });
-    app.post("/api/tasks/:taskSlug/codex-review/:gate/override", async (request) => {
-        const project = await requireCurrentProject(deps.projectService);
-        const gate = parseGate(request.params.gate);
-        return deps.codexReviewService.overrideReviewGate(project.repoRoot, request.params.taskSlug, gate, request.body);
-    });
-    app.get("/api/tasks/:taskSlug/codex-review/:gate/report", async (request) => {
-        const project = await requireCurrentProject(deps.projectService);
-        const gate = parseGate(request.params.gate);
-        return deps.codexReviewService.readReport(project.repoRoot, request.params.taskSlug, gate);
-    });
-}
-function parseGate(gate) {
-    if (!isCodexReviewGate(gate)) {
-        throw new VcmError({
-            code: "UNKNOWN_CODEX_REVIEW_GATE",
-            message: `Unknown Codex review gate: ${gate}`,
-            statusCode: 400
-        });
-    }
-    return gate;
-}
-async function requireCurrentProject(projectService) {
-    const project = await projectService.getCurrentProject();
-    if (!project) {
-        throw new VcmError({
-            code: "PROJECT_NOT_CONNECTED",
-            message: "Connect a repository first.",
-            statusCode: 409
-        });
-    }
-    return project;
-}