vibe-coding-master 0.3.27 → 0.3.29

package/docs/full-harness-baseline.md

@@ -1,259 +1,165 @@
 # Full Harness Baseline
 
-Last updated: 2026-06-12
+Last updated: 2026-06-21
 
-Status: Temporary working document.
+Status: Current implementation reference.
 
-This file tracks the current VCM 0.2 harness baseline as represented by
-`example/rust-layered`. It is not a broad inventory of the old
-`cc-best-practices.md` baseline.
+This file tracks the VCM fixed harness currently installed by
+`src/backend/services/harness-service.ts` and
+`src/backend/cli/install-vcm-harness.ts`.
 
-When the example stabilizes, migrate the durable decisions into
-`docs/vcm-cc-best-practices.md` and delete this file.
+## Principles
 
-## Current Principle
+VCM separates three file classes:
 
-VCM separates three kinds of files:
+- Harness-managed files: VCM installs, upgrades, repairs, and can overwrite
+  inside managed blocks or whole-file templates.
+- Project-owned durable docs: VCM may create starter docs, but project roles own
+  their content afterward.
+- Runtime state: VCM writes these during task execution and cleanup removes them
+  when the task is closed.
 
-- Harness-managed files: VCM owns, upgrades, repairs, and can uninstall these
-  through `.ai/vcm-harness-manifest.json`.
-- 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 deletes them during
-  task cleanup. Runtime files are not manifest entries.
+The current implementation no longer uses `.ai/vcm-harness-manifest.json`.
+Harness ownership is defined by the deterministic installer and by managed
+markers such as `<!-- VCM:BEGIN version=1 -->`.
 
-The manifest is a harness ownership and lifecycle record. It should include
-VCM-managed rules, agents, skills, settings merges, harness tools, generated
-context artifacts, PR template managed blocks, marker metadata, JSON ownership,
-lifecycle labels, runtime roots, and uninstall actions.
+## Fixed Harness Files
 
-The manifest should not list project-owned durable docs such as
-`docs/ARCHITECTURE.md`, `docs/TESTING.md`, `docs/known-issues.md`,
-`docs/plans/`, or module-level `ARCHITECTURE.md` files as managed entries. It
-should not list `.ai/vcm/**` runtime files as managed entries either.
-
-## Install And Bootstrap Flow
-
-VCM 0.2 uses a two-stage harness setup:
-
-1. Fixed install: VCM runs the deterministic fixed installer. This creates or
-   updates VCM-owned managed blocks, whole-file skills, role agents, settings
-   hooks, harness tools, generated-context directories, the PR template, and
-   `.ai/vcm-harness-manifest.json`.
-2. AI bootstrap: VCM starts a temporary Claude Code terminal in the repository
-   root and instructs it to use `vcm-harness-bootstrap`. This fills
-   project-owned content and generated artifacts.
-
-The fixed install does not copy example project content. It may create blank
-durable doc templates when missing, but project-specific facts are added only by
-bootstrap or by later role work.
-
-Bootstrap should produce or refresh:
+Managed-block files:
 
 ```text
-CLAUDE.md project context outside the VCM managed block
-docs/ARCHITECTURE.md
-<module>/ARCHITECTURE.md
-docs/TESTING.md
-.ai/generated/module-index.json
-.ai/generated/public-surface.json
+CLAUDE.md
+.gitignore
+.github/pull_request_template.md
+.claude/agents/project-manager.md
+.claude/agents/architect.md
+.claude/agents/coder.md
+.claude/agents/reviewer.md
+.claude/agents/gate-reviewer.md
+.ai/codex-translator/AGENTS.md
 ```
 
-Bootstrap runtime metadata is temporary:
+Whole-file or raw-file harness files:
 
 ```text
-.ai/vcm/bootstrap/session.json
-.ai/vcm/bootstrap/bootstrap.log
+.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
+.claude/skills/vcm-gate-review/SKILL.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
 ```
 
-These files are runtime state, not manifest entries. They can be deleted after
-the generated artifacts and durable docs are complete.
-
-## Current Manifest Entries
-
-These entries match the current `example/rust-layered/.ai/vcm-harness-manifest.json`.
-
-| Area | Path | Ownership | Lifecycle | Notes |
-| --- | --- | --- | --- | --- |
-| Manifest | `.ai/vcm-harness-manifest.json` | whole-file | Long-term | VCM harness ownership record. |
-| Root rules | `CLAUDE.md` | managed-block | Long-term | VCM HTML marker block only; project context outside the block is project-owned. |
-| Ignore rules | `.gitignore` | managed-block | Long-term | VCM hash-comment marker block. The example comments `.ai/vcm/` so readers can inspect runtime artifacts. |
-| Claude settings | `.claude/settings.json` | json-merge | Long-term | VCM owns hook entries matching VCM command markers. |
-| Agent directory | `.claude/agents/` | VCM-created directory | Long-term | Contains the four core VCM role agents. |
-| Core agent | `.claude/agents/project-manager.md` | managed-block | Long-term | Project-manager role rules. |
-| Core agent | `.claude/agents/architect.md` | managed-block | Long-term | Architect role rules: plan document, Scaffold Manifest, code scaffolding, Debug Mode, docs sync. |
-| Core agent | `.claude/agents/coder.md` | managed-block | Long-term | Coder role rules: scaffold implementation, coding standards, baseline unit checks. |
-| Core agent | `.claude/agents/reviewer.md` | managed-block | Long-term | Reviewer role rules: independent validation, TESTING.md strategy, integration/E2E case lists. |
-| Skill directory | `.claude/skills/` | VCM-created directory | Conditional long-term | Keep while repo-local VCM skills are installed. |
-| Skill directory | `.claude/skills/vcm-route-message/` | VCM-created directory | Conditional long-term | Claude Code registration directory for the route-message skill. |
-| Skill directory | `.claude/skills/vcm-final-acceptance/` | VCM-created directory | Conditional long-term | Claude Code registration directory for the final-acceptance skill. |
-| Skill directory | `.claude/skills/vcm-long-running-validation/` | VCM-created directory | Conditional long-term | Claude Code registration directory for the long-running-validation skill. |
-| Skill directory | `.claude/skills/vcm-harness-bootstrap/` | VCM-created directory | Conditional long-term | Claude Code registration directory for the harness-bootstrap skill. |
-| Skill | `.claude/skills/vcm-route-message/SKILL.md` | whole-file | Conditional long-term | Route-file authoring protocol. |
-| Skill | `.claude/skills/vcm-final-acceptance/SKILL.md` | whole-file | Conditional long-term | PM final evidence audit. |
-| Skill | `.claude/skills/vcm-long-running-validation/SKILL.md` | whole-file | Conditional long-term | Role-independent long-running command protocol: worker-enforced 60 minute ceiling, supervision lease, windowed foreground watching. |
-| Skill | `.claude/skills/vcm-harness-bootstrap/SKILL.md` | whole-file | Conditional long-term | AI-assisted project understanding procedure. |
-| Harness tool directory | `.ai/tools/` | VCM-created directory | Long-term | Repo-local harness tools. |
-| Generated-context tool | `.ai/tools/generate-module-index` | whole-file | Long-term | Generates `.ai/generated/module-index.json`. |
-| Generated-context tool | `.ai/tools/generate-public-surface` | whole-file | Long-term | Generates `.ai/generated/public-surface.json`. |
-| Runtime tool | `.ai/tools/run-long-check` | whole-file | Conditional long-term | Starts the only VCM-allowed file-backed validation job; its worker enforces the job ceiling (max 60m) and a supervision lease, and refuses concurrent jobs. |
-| Runtime tool | `.ai/tools/watch-job` | whole-file | Conditional long-term | Foreground watcher and lease renewer; watches in windows up to 8 minutes and exits 125 while the job still runs instead of killing it. |
-| Runtime tool | `.ai/tools/vcm-bash-guard` | whole-file | Conditional long-term | PreToolUse hook guard; denies `run_in_background`, `nohup`, `setsid`, `disown`, and `&` background Bash in VCM role sessions. |
-| Generated context directory | `.ai/generated/` | VCM-created directory | Long-term | Derived context artifacts. |
-| Generated context | `.ai/generated/module-index.json` | derived artifact | Derived | Regenerated by `generate-module-index`; do not hand-edit as source truth. |
-| Generated context | `.ai/generated/public-surface.json` | derived artifact | Derived | Regenerated by `generate-public-surface`; do not hand-edit as source truth. |
-| PR template | `.github/pull_request_template.md` | managed-block | Long-term | VCM PR checklist block. |
-
-Runtime roots recorded by the manifest:
+Durable doc templates created only when missing:
 
 ```text
-.ai/vcm/
-.claude/worktrees/
+docs/ARCHITECTURE.md
+docs/TESTING.md
+docs/known-issues.md
 ```
 
-These roots are cleanup targets, not managed entries.
-
-## Project-Owned Bootstrap Outputs
-
-The current example includes project-owned durable docs created or initialized
-during harness bootstrap. They are important for the workflow, but they are not
-VCM-owned harness and should not appear as manifest entries.
-
-| Area | Path | Owner | Lifecycle | Notes |
-| --- | --- | --- | --- | --- |
-| Project context | `CLAUDE.md` content outside VCM block | Project | Long-term | Rust-layered project facts and constraints. |
-| Project architecture | `docs/ARCHITECTURE.md` | Architect | Long-term | Project-level module overview, responsibilities, relationships, dependency direction, and links to module docs. |
-| Module architecture | `<module>/ARCHITECTURE.md` | Architect | Long-term | Module-level boundaries, behavior, important public surface explanations, and risks. |
-| Testing docs | `docs/TESTING.md` | Reviewer | Long-term | Validation levels, commands, selection rules, final-validation cleanup, integration/E2E case definitions, generated-context freshness checks, and testing gaps. |
-| Known issues | `docs/known-issues.md` | Architect | Rolling durable doc | Confirmed unresolved issues and accepted limitations. Remove fixed, rejected, or obsolete entries. |
-| Durable plans | `docs/plans/` | Project | Conditional long-term | Durable plans only when a large task needs them. Completed routine plans should be deleted after durable facts are promoted. |
-
-Current `example/rust-layered` does not use these old separate docs:
+Directory roots created by the installer:
 
 ```text
-docs/MODULE_MAP.md
-docs/SECURITY.md
-docs/DEPENDENCY_RULES.md
-docs/AI_WORKFLOW.md
+.claude/agents/
+.claude/skills/
+.claude/skills/vcm-final-acceptance/
+.claude/skills/vcm-harness-bootstrap/
+.claude/skills/vcm-long-running-validation/
+.claude/skills/vcm-route-message/
+.claude/skills/vcm-gate-review/
+.ai/codex-translator/
+.ai/codex-translator/.codex/
+.ai/vcm/translations/
+.ai/vcm/gate-reviews/
+.ai/tools/
+.ai/generated/
 ```
 
-## Runtime State
-
-Runtime state is created while VCM manages a task. It is task-local and should be
-deleted during task cleanup after useful facts are promoted to code, tests,
-durable docs, PR text, or commit history.
-
-| Area | Path | Lifecycle | Notes |
-| --- | --- | --- | --- |
-| Worktrees | `.claude/worktrees/<task-slug>/` | Runtime cleanup | One task worktree shared by all roles. |
-| Handoff root | `.ai/vcm/handoffs/` | Runtime cleanup | Role artifacts and route files for the active task. |
-| Route messages | `.ai/vcm/handoffs/messages/<from-role>-<to-role>.md` | Runtime cleanup | Pending route files written by `vcm-route-message`. |
-| Architecture plan | `.ai/vcm/handoffs/architecture-plan.md` | Task-temporary | Architect handoff for one executable task. |
-| Review report | `.ai/vcm/handoffs/review-report.md` | Task-temporary | Reviewer handoff for one executable task. |
-| Docs sync report | `.ai/vcm/handoffs/docs-sync-report.md` | Task-temporary | Architect docs-sync handoff for one executable task. |
-| Final acceptance | `.ai/vcm/handoffs/final-acceptance.md` | Task-temporary | PM final evidence-audit handoff for one executable task. |
-| Task known issues | `.ai/vcm/handoffs/known-issues.md` | Task-temporary | Promote unresolved durable findings to `docs/known-issues.md`, then delete. |
-| Long-running jobs | `.ai/vcm/jobs/<job-id>/` | Runtime cleanup | Status and logs from `run-long-check` / `watch-job`. |
-| Bootstrap session | `.ai/vcm/bootstrap/session.json` | Runtime cleanup | Last harness-bootstrap terminal metadata. |
-| Bootstrap log | `.ai/vcm/bootstrap/bootstrap.log` | Runtime cleanup | Terminal log for the harness-bootstrap session. |
-| App-local task records | `<vcmDataDir>/projects/<project-id>/tasks/<task-slug>.json` | Runtime cleanup | VCM UI/lifecycle subtask records outside the connected repo. |
-
-Runtime state under `.ai/vcm/**` is excluded from manifest entries. The manifest
-records `.ai/vcm/` only as a runtime root.
-
-## Current Skills
-
-The current example installs these skills:
+## Installed Skills
 
 - `vcm-route-message`: route-file write protocol.
-- `vcm-final-acceptance`: final PM evidence audit.
-- `vcm-long-running-validation`: role-independent long-running command protocol with a worker-enforced 60 minute ceiling, supervision lease, and windowed foreground watching.
-- `vcm-harness-bootstrap`: one-time or occasional project-understanding, generated-context refresh, and durable-doc bootstrap procedure.
-
-The current example does not install a separate `vcm-docs-sync` skill. Docs sync
-is expressed in the architect role rules and writes
-`.ai/vcm/handoffs/docs-sync-report.md`.
+- `vcm-final-acceptance`: PM final evidence audit.
+- `vcm-long-running-validation`: foreground supervision protocol for long jobs.
+- `vcm-harness-bootstrap`: AI-assisted project understanding and generated
+  context refresh.
+- `vcm-gate-review`: PM protocol for requesting Gate Review and handling VCM
+  callbacks.
 
-## Current Tools
-
-The current example keeps only five `.ai/tools/` files:
+## Installed Tools
 
 ```text
 .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
 ```
 
-The generated-context tools currently support Rust projects only. The fixed
-installer may install them as the default Rust baseline, but non-Rust projects
-need project-specific generators before `.ai/generated/*` can be trusted.
+`generate-module-index` and `generate-public-surface` currently target Rust
+projects. Non-Rust repositories can still install the fixed harness, but
+generated context should be treated as unsupported until project-specific
+generators exist.
+
+## Runtime State
 
-The current example intentionally does not install these old validation or
-discovery wrappers:
+Task runtime state lives in the task worktree:
 
 ```text
-.ai/tools/check-fast
-.ai/tools/check-changed
-.ai/tools/check-module
-.ai/tools/check-boundaries
-.ai/tools/check-agent-rules
-.ai/tools/check-docs-freshness
-.ai/tools/check-generated-artifacts
-.ai/tools/find-owner
-.ai/tools/find-callers
-.ai/tools/find-tests
+<taskRepoRoot>/.ai/vcm/sessions/<task>.json
+<taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
+<taskRepoRoot>/.ai/vcm/orchestration/<task>.json
+<taskRepoRoot>/.ai/vcm/translation/<task>/
+<taskRepoRoot>/.ai/vcm/handoffs/
+<taskRepoRoot>/.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
+<taskRepoRoot>/.ai/vcm/handoffs/architecture-plan.md
+<taskRepoRoot>/.ai/vcm/handoffs/known-issues.md
+<taskRepoRoot>/.ai/vcm/handoffs/review-report.md
+<taskRepoRoot>/.ai/vcm/handoffs/docs-sync-report.md
+<taskRepoRoot>/.ai/vcm/handoffs/final-acceptance.md
+<taskRepoRoot>/.ai/vcm/jobs/<job-id>/
+<taskRepoRoot>/.ai/vcm/gate-reviews/
 ```
 
-Rust unit tests and integration tests are run with native Cargo commands chosen
-by the responsible role. The harness does not need a fixed wrapper for every
-validation level.
-
-## Generated Context
-
-The current example has two generated artifacts:
+Project-scoped runtime state lives in the base repository:
 
 ```text
-.ai/generated/module-index.json
-.ai/generated/public-surface.json
+<baseRepoRoot>/.ai/vcm/gate-reviewer/session.json
+<baseRepoRoot>/.ai/vcm/translations/
+<baseRepoRoot>/.ai/vcm/bootstrap/session.json
+<baseRepoRoot>/.ai/vcm/bootstrap/bootstrap.log
 ```
 
-Current support is Rust-only:
-
-- `generate-module-index` reads Cargo workspace structure, auto-detects a
-  direct child `cargoRoot` when the project root has no `Cargo.toml`, and
-  filters workspace member paths that do not contain a crate.
-- `generate-public-surface` indexes crate-external Rust `pub fn`,
-  `pub struct`, `pub enum`, and `pub trait` items, using `pub use` only to
-  resolve re-exported high-value API entries.
-
-There is no `test-map.json`. Test files are discoverable through
-`module-index.json` and Rust's normal Cargo test layout.
+App-local state lives under `vcmDataDir`:
 
-Generated artifacts are derived context, not durable project truth. They must be
-regenerated by their tools after relevant source, manifest, module, or public API
-changes.
+```text
+<vcmDataDir>/settings.json
+<vcmDataDir>/projects/index.json
+<vcmDataDir>/projects/<project-id>/config.json
+<vcmDataDir>/projects/<project-id>/tasks/<task>.json
+<vcmDataDir>/gateway/
+```
 
-## Not Part Of The Current Example
+Ordinary VCM role sessions no longer persist raw terminal logs under
+`.ai/vcm/handoffs/logs/`. Claude transcript JSONL files under
+`~/.claude/projects/` remain the semantic source for output translation and
+session recovery.
 
-The following items are intentionally not part of the current `rust-layered`
-baseline:
+## Cleanup
 
-```text
-.claude/commands/
-.claude/agents/optional/
-.ai/task-specs/
-.ai/vcm/tasks/
-.ai/vcm/handoffs/role-commands/
-docs/plans/active/
-docs/plans/completed/
-docs/MODULE_MAP.md
-docs/SECURITY.md
-docs/DEPENDENCY_RULES.md
-docs/AI_WORKFLOW.md
-.ai/generated/test-map.json
-```
+Close Task removes the task-owned worktree, branch, app-local task record, and
+task-local runtime state. It stops task-scoped VCM role sessions for that task.
+It must not stop project-scoped Gate Reviewer or Codex Translator sessions.
 
-Do not reintroduce these into the example baseline unless there is a specific,
-current VCM requirement.
+Durable facts that should survive task cleanup must be promoted into code,
+tests, durable docs, PR text, commit history, or release notes before closing
+the task.

package/docs/gate-review-gates.md

@@ -3,8 +3,9 @@
 This document defines VCM Gate Review Gates.
 
 Gate Review is an optional quality layer for complex tasks. It uses a fifth
-role, `gate-reviewer`, powered by Claude Code. The role is independent from the
-normal PM -> architect -> coder -> reviewer workflow.
+VCM flow role, `gate-reviewer`, powered by Claude Code. The role uses the same
+hook, Round, terminal, and translation path as the normal VCM roles, but it
+does not participate in PM route-file dispatch.
 
 ## Gates
 
@@ -32,7 +33,8 @@ VCM owns:
 - starting/resuming the project-scoped Gate Reviewer Claude Code session
 - sending the gate prompt
 - waiting for the report
-- marking the Gate Reviewer turn in Round state
+- binding the project-scoped Gate Reviewer session to the current task for hook,
+  Round, and translation state
 - sending the callback to PM
 
 PM owns:
@@ -60,6 +62,11 @@ therefore name the current task and task worktree path explicitly. Prior
 session memory can help orientation, but only current worktree evidence can
 decide the gate.
 
+When a task uses Gate Reviewer, VCM records the active task binding on the
+project session. Hook events from the long-lived session are resolved through
+that binding so Round state and translation output are written to the current
+task.
+
 Gate reports remain task-scoped:
 
 ```text
@@ -122,9 +129,10 @@ PM reaches gate
   -> VCM checks global gate switch and task state
   -> VCM starts or resumes project Gate Reviewer session
   -> VCM sends short prompt with task/worktree/report paths
-  -> VCM marks Gate Reviewer running in current Round
+  -> VCM binds Gate Reviewer to the current task
   -> Gate Reviewer writes report
-  -> VCM validates report and marks Gate Reviewer idle
+  -> standard Claude hooks update Gate Reviewer activity/Round state
+  -> VCM validates report
   -> VCM callbacks PM
   -> PM continues or routes follow-up
 ```

package/docs/gateway-design.md

@@ -161,9 +161,8 @@ Task lifecycle commands:
 - `/create-task <task-slug> [title]` creates a task worktree,
   selects it as the mobile current task, applies the saved launch template, and
   starts the four role sessions (`project-manager`, `architect`, `coder`,
-  `reviewer`) through the same one-click-start path as the desktop UI. The saved
-  template controls permission mode, model, effort, auto orchestration, and
-  translation.
+  `reviewer`) using the saved desktop launch-template values. The saved template
+  controls permission mode, model, effort, and auto orchestration.
   If no template has been saved, VCM uses the default launch template.
 - `/close-task` starts a destructive confirmation flow for the current task.
   Gateway replies with the exact confirmation command.
@@ -248,7 +247,6 @@ Rules:
   -> select it as gateway current task
   -> load saved launch template from app preferences
   -> set orchestration from template
-  -> set gateway/desktop translation state from template
   -> start four role sessions with template permission/model/effort
   -> switch mobile current role to project-manager
   -> reply with task slug, branch, worktree, template summary, and session status
@@ -585,7 +583,7 @@ Service dependencies:
 - `SessionService`: PM session state, Claude session metadata, and role session
   start for launch-template initialization.
 - `AppSettingsService`: saved launch template with permission mode, model,
-  effort, auto orchestration, and translation defaults.
+  effort, auto orchestration, plus the global Gateway translation preference.
 - `MessageService` / orchestration state service: set the newly created task to
   template auto/manual orchestration mode.
 - `TerminalRuntime`: controlled PM terminal submission.
@@ -672,8 +670,8 @@ Validation:
   `POST /api/projects/current/pull` or the equivalent project service method.
 - Implement `/create-task <task-slug> [title]` by creating a task worktree
   task, selecting it as mobile current task, applying the saved launch template,
-  setting orchestration mode, setting translation state, and starting the four
-  role sessions.
+  setting orchestration mode, applying the global Gateway translation state, and
+  starting the four core role sessions.
 - Implement `/close-task` and `/close-task confirm <task-slug>` as a two-step
   destructive confirmation around the same Close Task cleanup path as desktop
   VCM.
@@ -779,7 +777,7 @@ Gateway MVP is complete when:
   through VCM's fast-forward-only pull path.
 - Bound phone can run `/create-task <task-slug> [title]` to create a task
   worktree, select it, apply the saved launch template, and start
-  the four role sessions.
+  the four core role sessions.
 - Bound phone can send Chinese plain text to current task PM.
 - PM receives only the translated English prompt, without original Chinese.
 - Gateway can push PM assistant replies to Weixin whenever enabled.

package/docs/product-design.md

@@ -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.
@@ -84,10 +84,11 @@ project-manager
 
 ### 4.1 Gate Review Gates
 
-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.
+For complex tasks, VCM supports optional Gate Review Gates through a
+`gate-reviewer` Claude Code role. Gate Reviewer is a VCM flow role with the same
+hook, Round, terminal, and translation behavior as the core roles. Its session
+is project-scoped and reusable across tasks, but each gate turn is bound to the
+current task and task worktree so task evidence stays explicit.
 
 ```text
 architect architecture plan
@@ -108,9 +109,9 @@ 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.
+prompt into that project session and binds the session to the current task for
+hooks, Round state, translation, and report polling. The role remains outside PM
+route-file dispatch.
 Architecture-plan findings return to architect, validation-adequacy findings
 return to reviewer, and final-diff findings go to architect first for
 assessment. Gate Reviewer role rules live in `.claude/agents/gate-reviewer.md`.
@@ -274,6 +275,9 @@ Sections:
 - `Repository Path`
 - `Connected Repository`
 - `Settings`
+- `Translation`
+- `Gate Review Gates`
+- `Gateway`
 - `VCM Harness`
 - `New Task`
 - `Tasks`
@@ -327,6 +331,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:
@@ -342,14 +364,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.
 
@@ -386,7 +410,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`; VCM directly records Gate Reviewer turns while a gate prompt is active.
+VCM detects flow pauses from role hook events, not from terminal silence, message history, or pending route files. Claude Code VCM flow roles report through `.claude/settings.json`; Gate Reviewer follows the same hook path while VCM separately validates the assigned gate report.
 
 Backend role state:
 
@@ -394,7 +418,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 react to Claude Code hook events plus VCM-recorded Gate Reviewer gate turns.
+- The role tab and flow pause state react to Claude Code hook events for all VCM flow roles, including Gate Reviewer.
 
 Task-level Round state:
 
@@ -703,7 +727,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
 
@@ -769,7 +797,6 @@ and audit logs live under `vcmDataDir`. VCM resolves `vcmDataDir` from
 Repository-level VCM state:
 
 ```text
-.ai/vcm/tasks/<task>.json
 .claude/worktrees/<task>/
 ```
 
@@ -789,10 +816,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.