vibe-coding-master 0.0.6 → 0.0.8

package/docs/v1-architecture-design.md

@@ -1,1431 +1,912 @@
-# VibeCodingMaster V1 架构设计方案
+# V1 Architecture Design
 
-版本：v0.2  
-日期：2026-05-29  
-状态：架构设计草案  
-依据：
+Last updated: 2026-05-31
 
-- `docs/product-design.md`
-- `docs/cc-best-practices.md`
+This document describes the architecture implemented by the current VCM codebase.
 
-## 1. V1 架构目标
+## 1. System Overview
 
-VibeCodingMaster V1 只解决一个核心问题：
+VCM is a local Node.js application with:
 
-> 做一个本地 GUI Session Cockpit，让用户可以在一个任务工作台中启动、切换、查看、输入和管理多个 Claude Code role sessions。
+- Fastify backend.
+- React frontend.
+- `node-pty` terminal runtime.
+- `xterm.js` terminal view.
+- Claude Code role processes.
+- API-driven message bus.
+- Claude transcript JSONL tailer for translation.
 
-V1 不再把 CLI 或手动终端管理作为主交互模式。CLI 可以保留为开发、调试和 smoke test 入口，但用户主流程必须在 GUI 中完成。
+Runtime shape:
 
-核心能力：
-
-- 启动本地 GUI 应用。
-- 连接或选择本地 Git repo。
-- 检查 Claude Code 是否可用。
-- 创建任务 workspace。
-- 为任务创建 `.ai/handoffs/<task-slug>/`、`role-commands/`、`logs/`。
-- 在 GUI 中展示 `project-manager / architect / coder / reviewer` role session tabs。
-- 用 embedded terminal 承载每个 Claude Code role session。
-- 支持用户在 GUI 内直接输入、确认权限、继续对话。
-- 将 terminal output 持续保存为 raw logs。
-- 在 GUI 中查看 role command 和 handoff artifacts。
-- 从 GUI 将 role command 发送到目标 role session。
-- 展示 session 状态、artifact 状态、任务状态和下一步建议。
-- 支持停止、重启、恢复单个 role session。
-
-V1 的成功标准不是“能不能用命令控制多个终端”，而是：
-
-> 用户是否可以不离开 GUI，就完成多 Claude Code sessions 的创建、切换、沟通、观察、日志保存和 handoff artifact 查看。
-
-## 2. V1 非目标
-
-V1 明确不做：
-
-- SaaS 多用户协作。
-- 企业权限和审计。
-- 完整 Desktop 打包和自动更新。
-- 产品层翻译管线。
-- 独立翻译模型调用。
-- 自动生成完整 Task Spec。
-- 自动 Preflight Review。
-- 自动 Cross-Model Code Review。
-- 自动识别 public contract / test contract。
-- 自动执行 validation commands。
-- 自动创建 PR。
-- Jira / Linear / GitHub 双向同步。
-- 云端 session 托管。
-- 多 repo / 多任务并行调度。
-- 多 worktree 自动管理。
-- 让用户手动管理底层 terminal process。
+```text
+browser
+  -> React GUI
+  -> HTTP API + WebSocket
+  -> Fastify backend
+  -> services
+  -> node-pty
+  -> claude --agent <role>
+```
 
-这些能力应在 V1 的 GUI session cockpit 稳定后作为 V2/V3 能力演进。
+The app is local-first. It writes project control state under `.ai/vcm/`, handoff artifacts under `.ai/handoffs/` inside the active task worktree, app settings under `~/.vcm/settings.json`, and reads Claude transcript files under `~/.claude/projects/`.
 
-## 3. 关键设计原则
+## 2. Processes And Ports
 
-### 3.1 GUI First
+Default ports:
 
-V1 的主入口是本地 GUI。用户应该通过页面完成：
+- backend / production GUI: `4173`
+- Vite dev GUI: `5173`
 
-- 选择 repo。
-- 创建任务。
-- 启动 role sessions。
-- 切换 `project-manager / architect / coder / reviewer`。
-- 直接在 session 面板中输入和查看输出。
-- 查看 role command、logs、handoff artifacts 和状态。
+Development:
 
-CLI 只用于：
+```text
+npm run dev
+  -> backend at http://127.0.0.1:4173
+  -> Vite dev server at http://127.0.0.1:5173
+```
 
-- 启动 dev server。
-- 调试 backend。
-- 导出状态。
-- 执行自动化 smoke test。
+Production / npm package:
 
-### 3.2 Terminal Runtime Is Internal
+```text
+vcm
+  -> backend serves dist-frontend at http://127.0.0.1:4173
+```
 
-Claude Code 本质上是交互式终端程序，V1 通过 embedded terminal 承载它。
+`src/main.ts` starts the backend and optionally starts Vite when `--dev` is passed.
 
-用户不需要理解：
+## 3. Frontend Architecture
 
-- pseudo-terminal。
-- process id。
-- terminal stream。
-- WebSocket message。
-- input/output bridge。
+Entry:
 
-产品界面表达的是任务、角色、会话、artifact、状态和验收。
+- `src/frontend/main.tsx`
+- `src/frontend/app.tsx`
 
-### 3.3 Controller-Mediated
+Main state lives in `App`:
 
-Project Manager session 不直接无限制控制其他 Claude Code sessions。
+- connected project
+- recent repository paths
+- harness status
+- task list
+- active task
+- active role
+- active workflow report
+- active messages
+- active orchestration state
+- task-local event list
 
-正确模型：
+Layout:
 
 ```text
-Project Manager session
-  -> writes role command artifact
-  -> GUI shows command artifact to user
-  -> user approves or sends from GUI
-  -> VibeCodingMaster backend writes short instruction to target role session
-  -> target role session executes
-  -> backend records raw log
-  -> handoff artifact becomes stable result
+AppShell
+  sidebar: ProjectDashboard
+  main: TaskWorkspace or EmptyWorkspace
 ```
 
-职责分离：
+### ProjectDashboard
 
-- PM 决定发什么 role command。
-- GUI 让用户看见、确认和发送。
-- Backend 把短指令写入正确 role session。
-- Role agent 执行命令并产出 artifact。
-- Handoff artifacts 是跨 session 的事实源。
+File:
 
-### 3.4 File Handoff First
+- `src/frontend/routes/project-dashboard.tsx`
 
-角色交接不依赖聊天记忆。所有关键结果必须进入：
+Responsibilities:
 
-```text
-.ai/handoffs/<task-slug>/
-```
+- Render collapsible sidebar sections.
+- Render repository connect form.
+- Render repository summary.
+- Render workflow panel.
+- Render settings section with Messages, Events, Auto orchestration.
+- Render harness status/actions.
+- Render task creation form with one task-name field, a checked non-optional worktree/branch indicator, and generated branch/path previews.
+- Render task list.
+- Render Messages and Events modals.
 
-Terminal output 是调试信息；长期事实源是 handoff artifacts。
+All sections default collapsed. `Repository Path` opens when there is no selected task.
 
-### 3.5 One Task, One Workspace
+### TaskWorkspace
 
-V1 默认：
+File:
 
-```text
-one task
-  -> one GUI task workspace
-  -> multiple role sessions
-  -> one handoff directory
-  -> one repo working directory
-```
+- `src/frontend/routes/task-workspace.tsx`
 
-V1 不为每个 role 创建独立 worktree。角色隔离由 role session、role prompt、permissions、handoff files 和流程顺序实现。
+Responsibilities:
 
-### 3.6 Single-Writer Rule
+- Fetch task status, messages, and orchestration state.
+- Poll those every three seconds.
+- Render compact header with task title, branch, immutable worktree path, role tabs, and Refresh.
+- Hold per-role permission mode selection.
+- Render one `SessionConsole` per role but only show the active role.
+- Emit workflow/messages/orchestration/events back to `App` so sidebar stays synchronized.
 
-同一个任务中，默认只有一个 write-capable role 在编辑代码。
+### SessionConsole
 
-推荐顺序：
+File:
 
-```text
-project-manager -> architect -> coder -> reviewer
-```
+- `src/frontend/components/session-console.tsx`
 
-允许并行：
+Responsibilities:
 
-- read-only review。
-- log analysis。
-- artifact inspection。
-- 用户查看多个 session。
+- Render role toolbar.
+- Render embedded terminal for running sessions.
+- Render empty/resume state for stopped sessions.
+- Toggle translation panel.
+- Split terminal and translation into two equal columns when translation is on.
 
-不允许：
+### TranslationPanel
 
-- `coder` 和 `reviewer` 同时大范围改代码。
-- PM 直接替代 coder 实现复杂功能。
-- reviewer 接管大范围实现。
+File:
 
-### 3.7 State Can Be Rebuilt
+- `src/frontend/components/translation-panel.tsx`
 
-V1 的状态必须能从四类来源恢复：
+Responsibilities:
 
-```text
-backend session registry
-terminal process state
-repo artifacts
-local VCM metadata
-```
+- Load translation settings and prompt previews.
+- Open translation WebSocket for the current terminal runtime session id.
+- Render dark translation output panel.
+- Render translation status: `ready`, `translating <elapsed>`, or `error`.
+- Render preserved tool output as dim one-line rows.
+- Render prose source while translating, then translated text after completion.
+- Render user composer.
+- Translate on `Enter`; newline on `Shift+Enter`.
+- Replace Chinese input with English draft after translation.
+- Send English draft to the active terminal.
+- Provide panel-level `Auto-send`, `Settings`, and `Clear`.
 
-不要把前端页面内存作为唯一状态源。
+## 4. Backend Architecture
 
-## 4. 技术栈选择
+Entry:
 
-### 4.1 主语言
+- `src/backend/server.ts`
 
-推荐：
+`createDefaultServerDeps()` wires:
 
-```text
-TypeScript + Node.js LTS
-```
+- filesystem adapter
+- command runner
+- git adapter
+- Claude adapter
+- app settings service
+- node-pty runtime
+- session registry
+- artifact service
+- harness service
+- project service
+- task service
+- session service
+- command dispatcher
+- status service
+- message service
+- translation service
 
-原因：
+Fastify registers:
 
-- 前后端共享类型。
-- 适合本地 GUI、WebSocket 和进程编排。
-- 易于调用 `git`、`claude`、文件系统和终端 runtime。
-- 与后续 Desktop shell、Web UI 和自动化能力兼容。
+- project routes
+- harness routes
+- task routes
+- session routes
+- artifact routes
+- message routes
+- translation routes
+- terminal WebSocket
+- translation WebSocket
 
-### 4.2 前端
+## 5. Repository Connection
 
-推荐：
+File:
 
-```text
-React + Vite
-```
-
-原因：
+- `src/backend/services/project-service.ts`
+- `src/backend/adapters/git-adapter.ts`
 
-- 适合构建本地单页工作台。
-- 与 xterm.js 集成成熟。
-- 本地开发体验快。
-- 后续可以被 Electron / Tauri / Desktop shell 包装。
-
-前端核心依赖：
+Connect flow:
 
 ```text
-@xterm/xterm
-@xterm/addon-fit
-@xterm/addon-web-links
+POST /api/projects/connect
+  -> resolve path
+  -> check path exists
+  -> check .git marker directly
+  -> create .ai/vcm/config.json
+  -> ensure .ai/vcm state dirs
+  -> read branch and dirty state
+  -> record recent repo path in ~/.vcm/settings.json
 ```
 
-### 4.3 后端
+Git repository detection:
 
-推荐：
-
-```text
-Node.js HTTP server + WebSocket
-```
+- `.git` directory with `HEAD` is accepted.
+- `.git` file with `gitdir:` pointer and target `HEAD` is accepted.
+- This supports normal repositories and worktrees.
 
-可选框架：
+Git metadata commands use:
 
 ```text
-Fastify 或 Express
-ws
+git -c safe.directory=<repoRoot> -c safe.directory=<realpath(repoRoot)> ...
 ```
 
-后端职责：
+VCM does not require global `safe.directory` configuration.
 
-- 提供 REST API。
-- 提供 terminal WebSocket。
-- 管理 pseudo-terminal lifecycle。
-- 读写 `.vcm` 和 `.ai/handoffs`。
-- 执行 git / claude 环境检查。
+## 6. Task Worktree Architecture
 
-### 4.4 Terminal Runtime
+Task-level worktree management is the current architecture for multi-task parallelism.
 
-V1 推荐：
+Rule:
 
 ```text
-node-pty
+one VCM task = one branch + one git worktree + one handoff directory + one role-session set
 ```
 
-用途：
-
-- 启动 `claude --agent <role>`，并按用户选择追加权限参数。
-- 承载交互式输入输出。
-- 支持 backend 程序化写入 input。
-- 支持 backend 程序化监听 output。
-- 支持 terminal resize。
-- 支持退出码和进程状态。
-- 配合 xterm.js 提供接近真实终端的 GUI 体验。
-
-V1 的 terminal runtime 固定为：
+Branch name:
 
 ```text
-TerminalRuntime implementation = node-pty
+feature/<taskSlug>
 ```
 
-后续持久性增强应优先改进 backend lifecycle、session registry、raw logs 和恢复体验。
-
-### 4.5 进程执行
-
-推荐：
+Worktree path:
 
 ```text
-execa
+<baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
 ```
 
-用途：
+VCM does not support switching a task to another branch or worktree after creation. If the user needs a different branch/worktree, they should create a new task.
 
-- 调用 `git`。
-- 调用 `claude --version`。
-- 执行 shell-safe command。
-- 不用于承载 Claude Code 交互式 session；交互式 session 由 `node-pty` 负责。
-
-### 4.6 本地状态存储
-
-V1 推荐 JSON 文件，而不是 SQLite。
-
-推荐路径：
+VCM does not create worktrees by role. All four role sessions for a task share the same task worktree:
 
 ```text
-.vcm/
-  config.json
-  tasks/
-    <task-slug>.json
-  sessions/
-    <task-slug>.json
-  app-state.json
+.ai/vcm/worktrees/<taskSlug>/
+  project-manager session cwd
+  architect session cwd
+  coder session cwd
+  reviewer session cwd
 ```
 
-原因：
+### 6.1 Base Repo vs Task Worktree
 
-- V1 是本地单用户。
-- 状态量小。
-- 易于检查和恢复。
-- 与 repo-local harness 理念一致。
+VCM distinguishes:
 
-后续加入多任务并发、后台 daemon 或复杂查询后，再迁移到 SQLite。
+- `baseRepoRoot`: repository the user connected.
+- `taskRepoRoot`: git worktree path for a specific task.
+- `branch`: `feature/<taskSlug>`.
+- `worktreePath`: same as `taskRepoRoot`.
 
-### 4.7 Markdown 处理
-
-V1 不需要复杂 Markdown AST。
-
-建议：
-
-- 写入模板用字符串模板。
-- artifact completeness 用标题存在性检查。
-- 前端预览用简单 Markdown renderer。
-- 后续再引入 Markdown parser。
-
-### 4.8 测试框架
-
-推荐：
+Project-level VCM control state stays under the base repo:
 
 ```text
-Vitest
-Playwright
+<baseRepoRoot>/.ai/vcm/config.json
+<baseRepoRoot>/.ai/vcm/tasks/<task>.json
+<baseRepoRoot>/.ai/vcm/sessions/<task>.json
+<baseRepoRoot>/.ai/vcm/messages/<task>.jsonl
+<baseRepoRoot>/.ai/vcm/orchestration/<task>.json
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/
 ```
 
-测试重点：
-
-- slug/path 生成。
-- artifact schema 检查。
-- session status 推断。
-- REST API。
-- WebSocket terminal bridge。
-- role command dispatch。
-- GUI task workspace smoke test。
-
-## 5. 进程架构
-
-V1 采用本地 Web GUI + 本地 Node backend。
+Task source changes and handoff artifacts live in the task worktree:
 
 ```text
-User
-  -> Browser / Desktop shell
-      -> React Task Workspace
-      -> xterm.js Role Session Console
-      -> WebSocket terminal bridge
-      -> REST API
-          -> Local Node backend
-              -> GitAdapter
-              -> ClaudeAdapter
-              -> FileSystemAdapter
-              -> ArtifactService
-              -> TaskService
-              -> SessionRegistry
-              -> TerminalRuntimeManager
-                  -> node-pty
-                      -> claude --agent project-manager
-                      -> claude --agent architect
-                      -> claude --agent coder
-                      -> claude --agent reviewer
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/handoffs/<task>/
 ```
 
-Backend 是长生命周期本地进程。前端刷新后，应该能重新连接 backend 并恢复可见状态。
+This central base-state model lets VCM list and manage multiple tasks while each task's code changes happen in a separate worktree.
 
-## 6. GUI 结构
+### 6.2 Git Ignore Requirement
 
-### 6.1 Project Dashboard
+The base repository must ignore `.ai/vcm/`.
 
-职责：
+Reason:
 
-- 显示已连接 repo。
-- 显示 active tasks。
-- 显示每个任务的 severity、required role route、session health。
-- 显示 blocked tasks、recent validation failures、known issues、harness health。
-- 提供进入 Task Workspace 的入口。
+- `.ai/vcm/worktrees/<task>` is a nested git worktree.
+- Without `.ai/vcm/` in `.gitignore`, the base repo sees worktree files as untracked noise.
+- `.ai/vcm` also contains local task/session/message metadata that should not be committed by default.
 
-### 6.2 Task Workspace
+The VCM harness manages a `.gitignore` block that ignores `.ai/vcm/` before task worktree creation.
 
-V1 的主界面。
-
-推荐布局：
+### 6.3 Task Creation Flow
 
 ```text
-┌──────────────────────────────────────────────────────────────────────────────┐
-│ Header: repo / branch / task / severity / route / overall status            │
-├───────────────┬──────────────────────────────────────────────────────────────┤
-│ Task Nav      │ Role Sessions                                                │
-│               │ tabs: PM | Architect | Coder | Reviewer                      │
-│ Session State │ embedded terminal                                             │
-│ Known Issues  │ session ops                                                   │
-│               │ input handled by terminal                                     │
-├───────────────┴──────────────────────────────────────────────────────────────┤
-│ Event Log: PM wrote architect.md | Coder waiting for approval                │
-└──────────────────────────────────────────────────────────────────────────────┘
+POST /api/tasks
+  -> validate taskSlug
+  -> compute branch feature/<taskSlug>
+  -> compute worktreePath <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+  -> assert branch does not already exist
+  -> assert worktreePath does not already exist
+  -> assert .ai/vcm/ is ignored by Git
+  -> assert base repo has no uncommitted changes
+  -> git worktree add -b feature/<taskSlug> <worktreePath> <baseRef>
+  -> create handoff structure in taskRepoRoot
+  -> write central task metadata under baseRepoRoot/.ai/vcm/tasks/<task>.json
 ```
 
-### 6.3 Session Console
+The default `baseRef` is the connected repo's current `HEAD`.
 
-每个 role session 对应一个 console。
+### 6.4 Task Cleanup Flow
 
-能力：
+```text
+POST /api/tasks/:taskSlug/cleanup
+  -> require no running role sessions
+  -> load task metadata
+  -> verify worktree path belongs under <baseRepoRoot>/.ai/vcm/worktrees/
+  -> check worktree status
+  -> refuse cleanup when uncommitted work exists unless force is explicitly requested
+  -> git worktree remove <worktreePath>
+  -> delete central task/session/message/orchestration metadata
+```
 
-- 展示 role name。
-- 展示 command，例如 `claude --agent architect`。
-- 展示 xterm.js terminal viewport。
-- 支持输入、复制、选择文本、resize。
-- 展示状态：not started / starting / running / waiting / blocked / done / crashed。
-- 支持 start / stop / restart。
-- 显示 raw log path。
+Branch deletion is intentionally separate:
 
-### 6.4 Handoff Files
+- Keep `feature/<taskSlug>` by default.
+- Allow branch deletion only with explicit confirmation.
+- Prefer allowing deletion only when the branch has been merged, or when the user force-confirms.
 
-V1 不在主界面展示独立 artifact inspector。handoff artifacts 和 role commands 仍保存在任务目录中，作为 session 之间的文件级事实源；GUI 的主工作区优先展示 embedded terminal。
+## 7. Task And Artifact Model
 
-### 6.5 Event Log
+File:
 
-展示产品级事件，不展示完整 terminal stream。
+- `src/backend/services/task-service.ts`
+- `src/backend/services/artifact-service.ts`
+- `src/shared/types/task.ts`
+- `src/shared/types/artifact.ts`
 
-示例：
+Task state:
 
 ```text
-PM session started
-PM wrote architect.md
-User sent architect command
-Architect wrote architecture-plan.md
-Coder waiting for permission
-Reviewer missing validation evidence
+<baseRepoRoot>/.ai/vcm/tasks/<task>.json
 ```
 
-## 7. Terminal Runtime
+Each task stores:
 
-### 7.1 Role Session 启动命令
+- `taskSlug`
+- optional `title`
+- timestamps
+- `baseRepoRoot`
+- `worktreePath`
+- `repoRoot` / `taskRepoRoot`
+- branch, always `feature/<taskSlug>` for VCM-created tasks
+- handoff directory
+- status
+- optional spec path
 
-每个 role session 启动对应 Claude Code：
+Task creation:
 
-```bash
-claude --agent project-manager
-claude --agent architect
-claude --agent coder
-claude --agent reviewer
+```text
+POST /api/tasks
+  -> validate slug
+  -> create branch and worktree
+  -> create handoff directories
+  -> create artifact templates
+  -> write base .ai/vcm/tasks/<task>.json
 ```
 
-### 7.2 TerminalRuntime 接口
-
-V1 后端应抽象 terminal runtime，避免把 node-pty 写死到上层业务。
+Handoff directory:
 
-```ts
-interface TerminalRuntime {
-  createSession(input: CreateTerminalSessionInput): Promise<TerminalSession>;
-  getSession(sessionId: string): TerminalSession | undefined;
-  listSessions(taskSlug?: string): TerminalSessionSummary[];
-  write(sessionId: string, data: string): void;
-  resize(sessionId: string, cols: number, rows: number): void;
-  stop(sessionId: string): Promise<void>;
-  restart(sessionId: string): Promise<TerminalSession>;
-  subscribe(sessionId: string, listener: TerminalEventListener): Unsubscribe;
-}
+```text
+<taskRepoRoot>/.ai/handoffs/<task>/
+  role-commands/
+    architect.md
+    coder.md
+    reviewer.md
+  logs/
+    project-manager.log
+    architect.log
+    coder.log
+    reviewer.log
+  architecture-plan.md
+  implementation-log.md
+  validation-log.md
+  review-report.md
+  docs-sync-report.md
+  messages/
 ```
 
-### 7.3 node-pty 实现
-
-`NodePtyTerminalRuntime` 负责：
-
-- spawn `claude`。
-- 设置 cwd 为 repo root。
-- 设置 env。
-- 捕获 stdout/stderr stream。
-- 将 stream 推送给 WebSocket subscribers。
-- 将 stream append 到 role log。
-- 监听 exit code。
-- 更新 session status。
-- 支持 resize。
+Artifact checks are simple V1 checks:
 
-### 7.4 WebSocket Terminal Bridge
+- missing
+- placeholder / incomplete
+- ok
 
-WebSocket 负责前后端双向通信。
+They are used for workflow readiness, not content quality judgment.
 
-推荐消息：
-
-```json
-{ "type": "input", "sessionId": "session_123", "data": "hello\n" }
-{ "type": "resize", "sessionId": "session_123", "cols": 120, "rows": 32 }
-{ "type": "output", "sessionId": "session_123", "data": "..." }
-{ "type": "status", "sessionId": "session_123", "status": "running" }
-{ "type": "exit", "sessionId": "session_123", "exitCode": 0 }
-```
+## 8. Workflow Computation
 
-### 7.5 Role Command Dispatch
+File:
 
-长 role command 不直接粘贴进 terminal。V1 应先写入文件，再向目标 session 发送短指令。
+- `src/backend/services/status-service.ts`
 
-任务身份以 VCM `taskSlug` 为准。Project Manager 必须只写入当前 task 的 canonical handoff directory：
+Endpoint:
 
 ```text
-.ai/handoffs/<task-slug>/role-commands/<role>.md
+GET /api/tasks/:taskSlug/status
 ```
 
-如果 task slug 不符合用户意图，Project Manager 必须要求用户创建或选择正确的 VCM task，不能自行创建 `.ai/handoffs/<other-task>/` 来绕过当前 task。
-
-示例：
-
-```text
-Please read and execute the role command at: .ai/handoffs/<task-slug>/role-commands/architect.md
-```
-
-发送流程：
+The workflow has five steps:
 
 ```text
-GUI Send Command button
-  -> POST /api/tasks/:taskSlug/sessions/:role/dispatch
-  -> backend checks role command file exists, non-empty, and not placeholder/draft
-  -> backend writes short instruction to terminal runtime
-  -> backend records dispatch event
+architecture-plan -> implementation -> review -> docs-sync -> final-acceptance
 ```
 
-### 7.6 Programmatic I/O Boundary
+Step readiness:
 
-通过 `node-pty`，backend 技术上可以对 Claude Code session 做两类程序化操作：
+- Architecture is ready until `architecture-plan.md` is ok.
+- Implementation is blocked until architecture is ok.
+- Review is blocked until `implementation-log.md` and `validation-log.md` are ok.
+- Docs Sync is blocked until `review-report.md` is ok.
+- PM Final is blocked until `docs-sync-report.md` is ok.
 
-```text
-write input:
-  runtime.write(sessionId, "Please read ...\r")
+The report is displayed in the sidebar `Workflow` section.
 
-read output:
-  runtime.subscribe(sessionId, listener)
-```
+## 9. Session Runtime
 
-V1 允许：
+Files:
 
-- 用户点击 Send Command 后，backend 写入短指令。
-- 用户在 GUI terminal 中输入后，backend 转发输入。
-- 用户在 Start / Restart 前选择 Claude Code 权限模式。
-- backend 监听 output，写入 raw log。
-- backend 根据进程退出、输出活动和用户操作更新轻量状态。
-- backend 在 GUI 中提示 waiting / crashed / exited 等状态。
+- `src/backend/services/session-service.ts`
+- `src/backend/adapters/claude-adapter.ts`
+- `src/backend/runtime/node-pty-runtime.ts`
+- `src/backend/runtime/session-registry.ts`
 
-V1 不允许：
+Session service owns role session lifecycle:
 
-- 自动确认 Claude Code 权限提示。
-- PM 写完 command 后自动发送给下一个 role。
-- Architect 完成后自动触发 Coder。
-- Coder 完成后自动触发 Reviewer。
-- 根据 terminal output 自动执行高风险下一步。
+- start
+- resume
+- restart
+- stop
+- list
+- get
 
-更高级的自动编排必须进入后续版本，并带有人类 approval gate、审计日志和明确 stop conditions。
+Runtime session id and Claude session id are different:
 
-### 7.7 Claude Code Permission Modes
+- runtime session id identifies the local `node-pty` process in VCM.
+- Claude session id identifies the Claude Code conversation for resume/transcript lookup.
 
-V1 在 Task Workspace 的每个 role session 控制区提供三档权限模式：
+Start:
 
 ```text
-默认
-  -> claude --agent <role>
-
-bypassPermissions
-  -> claude --agent <role> --permission-mode bypassPermissions
-
---dangerously-skip-permissions
-  -> claude --agent <role> --dangerously-skip-permissions
+claude --agent <role> --session-id <uuid>
 ```
 
-规则：
-
-- 权限模式是用户显式选择，不由 Project Manager 或 backend 自动切换。
-- 权限模式只影响 Start / Restart 创建的新 Claude Code 进程。
-- `RoleSessionRecord.permissionMode` 必须记录实际启动模式。
-- GUI 显示实际 command，方便用户确认当前 session 的权限状态。
-
-## 8. Repo Artifacts
-
-V1 需要创建和维护：
+Resume:
 
 ```text
-.ai/
-  handoffs/
-    <task-slug>/
-      role-commands/
-        architect.md
-        coder.md
-        reviewer.md
-      logs/
-        project-manager.log
-        architect.log
-        coder.log
-        reviewer.log
-      architecture-plan.md
-      implementation-log.md
-      validation-log.md
-      review-report.md
-
-.vcm/
-  config.json
-  tasks/
-    <task-slug>.json
-  sessions/
-    <task-slug>.json
-  app-state.json
+claude --agent <role> --resume <uuid>
 ```
 
-V1 可以不自动创建 `.ai/task-specs/`，但如果 Project Manager 已经生成 task spec，应在 task metadata 中记录路径。
-
-## 9. 模块划分
-
-推荐代码结构：
+Permission flags:
 
 ```text
-src/
-  main.ts
-
-  frontend/
-    app.tsx
-    routes/
-      project-dashboard.tsx
-      task-workspace.tsx
-    components/
-      app-shell.tsx
-      task-nav.tsx
-      role-session-tabs.tsx
-      session-console.tsx
-      event-log.tsx
-      status-badge.tsx
-    terminal/
-      xterm-view.tsx
-      terminal-client.ts
-    state/
-      api-client.ts
-      task-store.ts
-      session-store.ts
-
-  backend/
-    server.ts
-    api/
-      project-routes.ts
-      task-routes.ts
-      session-routes.ts
-      artifact-routes.ts
-    ws/
-      terminal-ws.ts
-    runtime/
-      terminal-runtime.ts
-      node-pty-runtime.ts
-      session-registry.ts
-    services/
-      project-service.ts
-      task-service.ts
-      session-service.ts
-      artifact-service.ts
-      command-dispatcher.ts
-      status-service.ts
-    adapters/
-      git-adapter.ts
-      claude-adapter.ts
-      filesystem.ts
-      command-runner.ts
-    validation/
-      environment-check.ts
-      artifact-check.ts
-      slug-check.ts
-    templates/
-      handoff.ts
-      role-command.ts
-    types/
-      project.ts
-      task.ts
-      session.ts
-      role.ts
-      artifact.ts
-      terminal.ts
-      api.ts
-
-tests/
-  unit/
-  integration/
-  e2e/
+--permission-mode bypassPermissions
+--dangerously-skip-permissions
 ```
 
-### 9.1 Frontend App
-
-职责：
+Session persistence:
 
-- 渲染 GUI。
-- 调用 REST API。
-- 连接 terminal WebSocket。
-- 管理 active task 和 active role tab state。
-
-### 9.2 SessionConsole
-
-职责：
+```text
+<baseRepoRoot>/.ai/vcm/sessions/<task>.json
+```
 
-- 渲染 xterm.js。
-- 连接指定 role session 的 WebSocket stream。
-- 将用户输入写回 backend。
-- 处理 resize。
-- 显示 start / stop / restart 操作。
+The persisted record includes:
 
-### 9.3 EventLog
+- runtime session id
+- Claude session id
+- transcript path
+- role
+- status
+- command display
+- permission mode
+- cwd
+- pid
+- raw log path
+- role command path
+- handoff artifact path
 
-职责：
+If a runtime process is gone but the role has a Claude session id, `getRoleSession` returns a recoverable `resumable` status.
 
-- 展示任务级运行事件。
-- 保持短日志形态，不占用 terminal 主视野。
+In task-worktree mode, `cwd` must be the immutable task worktree path. Role sessions must not start in the base repo when a task worktree exists.
 
-### 9.4 Backend Server
+## 10. Terminal Runtime
 
-职责：
+File:
 
-- 提供 REST API。
-- 提供 WebSocket endpoint。
-- 管理 backend service lifecycle。
-- Serve frontend static assets。
+- `src/backend/runtime/node-pty-runtime.ts`
 
-### 9.5 TerminalRuntimeManager
+The runtime:
 
-职责：
+- spawns `node-pty`
+- sets `TERM=xterm-256color`
+- sets color-friendly env vars
+- appends raw PTY output to `<taskRepoRoot>/.ai/handoffs/<task>/logs/<role>.log`
+- emits terminal output/input/exit events to WebSocket subscribers
+- replays the log on terminal WebSocket subscribe
 
-- 管理 role session 生命周期。
-- 启动 Claude Code pty。
-- 转发 terminal input/output。
-- 保存 raw logs。
-- 维护 runtime status。
+Terminal WebSocket:
 
-### 9.6 SessionRegistry
+```text
+GET /ws/terminal/:sessionId
+```
 
-职责：
+Client messages:
 
-- 保存当前 backend 进程中的 live sessions。
-- 对比 `.vcm/sessions/<task-slug>.json`。
-- 支持页面刷新后的 session 查询。
-- 标记 crashed / exited / missing。
+- input
+- resize
 
-### 9.7 ArtifactService
+Server messages:
 
-职责：
+- output
+- exit
+- error
 
-- 创建 handoff directory。
-- 创建 `role-commands/` 和 `logs/`。
-- 创建 artifact 模板。
-- 检查 artifact 是否存在。
-- 检查 artifact 是否包含关键标题。
-- 保存 role command。
-- 追加 raw terminal logs。
+## 11. Message Bus
 
-### 9.8 CommandDispatcher
+Files:
 
-职责：
+- `src/backend/services/message-service.ts`
+- `src/backend/templates/message-envelope.ts`
+- `src/cli/vcmctl.ts`
 
-- 读取 `role-commands/<role>.md`。
-- 校验目标 role session 是否 running。
-- 将短指令写入目标 terminal session。
-- 记录 dispatch event。
+State:
 
-原则：
+```text
+.ai/vcm/messages/<task>.jsonl
+.ai/vcm/orchestration/<task>.json
+.ai/handoffs/<task>/messages/<message-id>.md
+```
 
-- 不发送未落盘的长 prompt。
-- 每次 dispatch 都必须有 role command artifact。
-- 高风险 command 后续可增加用户确认 gate。
+Policy:
 
-## 10. API 设计
+- User can only send `user-request` to `project-manager`.
+- PM can send `task`, `question`, `review-request`, `revise`, `cancel` to non-PM roles.
+- Non-PM roles can send `result`, `question`, `blocked`, `finding` to PM.
 
-### 10.1 Project API
+Manual mode:
 
 ```text
-GET  /api/health
-POST /api/projects/connect
-GET  /api/projects/current
-GET  /api/projects/harness
+send -> pending_approval -> Stage -> staged
 ```
 
-`POST /api/projects/connect`：
+`Stage` writes:
 
-```json
-{
-  "repoPath": "/path/to/repo"
-}
+```text
+Read and handle VCM message <id> at <bodyPath>
 ```
 
-### 10.2 Task API
+It does not append Enter.
+
+Auto mode:
 
 ```text
-GET  /api/tasks
-POST /api/tasks
-GET  /api/tasks/:taskSlug
-GET  /api/tasks/:taskSlug/status
+send -> delivered
 ```
 
-`POST /api/tasks`：
+The backend writes a `[VCM MESSAGE]` envelope to the target terminal and appends Enter.
 
-```json
-{
-  "taskSlug": "fix-refund-coupon",
-  "title": "Fix refund coupon behavior",
-  "specPath": ".ai/task-specs/fix-refund-coupon.md"
-}
-```
+The backend still exposes pause/resume orchestration API routes and stores `paused` for compatibility. The current GUI only toggles `mode` between `manual` and `auto`.
 
-### 10.3 Session API
+Messages and orchestration snapshots are central project state under `baseRepoRoot/.ai/vcm`. Message body markdown lives in the task worktree handoff directory.
 
-```text
-GET    /api/tasks/:taskSlug/sessions
-POST   /api/tasks/:taskSlug/sessions/:role/start
-POST   /api/tasks/:taskSlug/sessions/:role/stop
-POST   /api/tasks/:taskSlug/sessions/:role/resume
-POST   /api/tasks/:taskSlug/sessions/:role/restart
-POST   /api/tasks/:taskSlug/sessions/:role/resize
-POST   /api/tasks/:taskSlug/sessions/:role/dispatch
-```
+## 12. Role Command Compatibility
 
-### 10.4 Artifact API
+Files:
 
-```text
-GET /api/tasks/:taskSlug/artifacts
-GET /api/tasks/:taskSlug/artifacts/:artifactName
-GET /api/tasks/:taskSlug/role-commands/:role
-PUT /api/tasks/:taskSlug/role-commands/:role
-GET /api/tasks/:taskSlug/logs/:role
-```
+- `src/backend/services/command-dispatcher.ts`
+- `src/backend/api/session-routes.ts`
+- `src/backend/api/artifact-routes.ts`
 
-### 10.5 Terminal WebSocket
+Compatibility endpoint:
 
 ```text
-WS /ws/tasks/:taskSlug/sessions/:role
+POST /api/tasks/:taskSlug/sessions/:role/dispatch
 ```
 
-Client -> server：
+Dispatchable roles:
 
-```json
-{ "type": "input", "data": "..." }
-{ "type": "resize", "cols": 120, "rows": 32 }
-```
+- `architect`
+- `coder`
+- `reviewer`
 
-Server -> client：
+The dispatcher:
 
-```json
-{ "type": "output", "data": "..." }
-{ "type": "status", "status": "running" }
-{ "type": "exit", "exitCode": 0 }
-{ "type": "error", "message": "Claude Code is not available" }
-```
+1. Loads the task.
+2. Reads the role command artifact.
+3. Rejects missing, empty, or placeholder role commands.
+4. Resolves primary command path `role-commands/<role>.md`, with legacy fallback `<role>-command.md`.
+5. Writes `Please read and execute the role command at: <path>` to the target terminal and submits Enter.
 
-## 11. 数据模型
+This is a compatibility path. The preferred V1 coordination path is `vcmctl` message bus.
 
-### 11.1 ProjectConfig
-
-```json
-{
-  "version": 1,
-  "repoRoot": "/path/to/repo",
-  "defaultRoles": ["project-manager", "architect", "coder", "reviewer"],
-  "handoffRoot": ".ai/handoffs",
-  "stateRoot": ".vcm",
-  "terminalBackend": "node-pty",
-  "claudeCommand": "claude"
-}
-```
+## 13. Harness Service
 
-### 11.2 TaskRecord
+File:
 
-```json
-{
-  "version": 1,
-  "taskSlug": "fix-refund-coupon",
-  "title": "Fix refund coupon behavior",
-  "createdAt": "2026-05-29T00:00:00+08:00",
-  "updatedAt": "2026-05-29T00:00:00+08:00",
-  "repoRoot": "/path/to/repo",
-  "branch": "feature/refund-coupon",
-  "handoffDir": ".ai/handoffs/fix-refund-coupon",
-  "status": "created",
-  "specPath": ".ai/task-specs/fix-refund-coupon.md"
-}
-```
+- `src/backend/services/harness-service.ts`
 
-### 11.3 RoleSessionRecord
+Harness files:
 
-```json
-{
-  "id": "session_architect_123",
-  "claudeSessionId": "00000000-0000-4000-8000-000000000001",
-  "taskSlug": "fix-refund-coupon",
-  "role": "architect",
-  "status": "running",
-  "command": "claude --agent architect --permission-mode bypassPermissions",
-  "permissionMode": "bypassPermissions",
-  "cwd": "/path/to/repo",
-  "terminalBackend": "node-pty",
-  "pid": 12345,
-  "logPath": ".ai/handoffs/fix-refund-coupon/logs/architect.log",
-  "roleCommandPath": ".ai/handoffs/fix-refund-coupon/role-commands/architect.md",
-  "handoffArtifactPath": ".ai/handoffs/fix-refund-coupon/architecture-plan.md",
-  "startedAt": "2026-05-29T00:00:00+08:00",
-  "lastOutputAt": "2026-05-29T00:03:14+08:00",
-  "exitCode": null
-}
+```text
+CLAUDE.md
+.gitignore
+.claude/agents/project-manager.md
+.claude/agents/architect.md
+.claude/agents/coder.md
+.claude/agents/reviewer.md
 ```
 
-### 11.4 TaskSessionRecord
+Managed block:
 
-```json
-{
-  "version": 1,
-  "taskSlug": "fix-refund-coupon",
-  "updatedAt": "2026-05-29T00:03:14+08:00",
-  "roles": {
-    "project-manager": {
-      "id": "session_pm_123",
-      "status": "running"
-    },
-    "architect": {
-      "id": "session_architect_123",
-      "claudeSessionId": "00000000-0000-4000-8000-000000000001",
-      "status": "running",
-      "record": "{...RoleSessionRecord}"
-    },
-    "coder": {
-      "id": null,
-      "status": "not_started"
-    },
-    "reviewer": {
-      "id": null,
-      "status": "not_started"
-    }
-  }
-}
+```md
+<!-- VCM:BEGIN version=1 -->
+...
+<!-- VCM:END -->
 ```
 
-### 11.5 RoleStatus
+`.gitignore` uses the same VCM managed-block concept with hash comments:
 
-V1 状态枚举：
-
-```text
-not_started
-starting
-running
-waiting
-blocked
-done
-resumable
-crashed
-exited
-missing
-unknown
+```gitignore
+# VCM:BEGIN version=1
+.ai/vcm/
+.vcm/
+# VCM:END
 ```
 
-V1 很难可靠判断 Claude Code 内部语义状态，因此：
+The service:
 
-- `not_started` 来自 metadata。
-- `running` 来自 live pty。
-- `exited/crashed` 来自 process exit。
-- `missing` 来自 metadata 存在但 live process 不存在。
-- `resumable` 来自 metadata 中存在 `claudeSessionId`，但当前没有 live pty。
-- `waiting/blocked/done` 可以先由用户或 role output marker 显式标记。
-- 自动推断只能作为 best-effort。
+- checks whether files exist
+- checks whether a managed block exists
+- compares the managed block with the current template
+- plans `create`, `insert`, `update`, or `ok`
+- applies only the planned managed-block change
 
-### 11.6 TerminalEvent
+It must not overwrite user content outside the VCM block.
 
-```json
-{
-  "id": "evt_123",
-  "sessionId": "session_architect_123",
-  "taskSlug": "fix-refund-coupon",
-  "role": "architect",
-  "type": "output",
-  "timestamp": "2026-05-29T00:03:14+08:00",
-  "data": "..."
-}
-```
+## 14. Translation Architecture
 
-## 12. 核心工作流
+Files:
 
-### 12.1 启动应用
+- `src/backend/services/translation-service.ts`
+- `src/backend/services/translation-queue.ts`
+- `src/backend/services/translation-prompts.ts`
+- `src/backend/services/claude-transcript-service.ts`
+- `src/backend/adapters/translation-provider.ts`
+- `src/backend/ws/translation-ws.ts`
+- `src/backend/api/translation-routes.ts`
+- `src/frontend/components/translation-panel.tsx`
+- `src/frontend/components/translation-settings-modal.tsx`
 
-```text
-vcm dev 或桌面入口
-  -> start local Node backend
-  -> serve React frontend
-  -> open browser / desktop shell
-  -> show Project Dashboard
-```
+### Settings
 
-### 12.2 连接 repo
+Settings service:
 
-```text
-User selects repo path
-  -> POST /api/projects/connect
-  -> check git repo
-  -> check claude --version
-  -> create .vcm/config.json
-  -> create .ai/handoffs/
-  -> show branch and dirty warning
-```
+- `src/backend/services/app-settings-service.ts`
 
-### 12.3 创建任务 workspace
+Storage:
 
 ```text
-User clicks New Task
-  -> enter task slug / title
-  -> POST /api/tasks
-  -> create .ai/handoffs/<task-slug>/
-  -> create role-commands/
-  -> create logs/
-  -> create artifact templates
-  -> create .vcm/tasks/<task-slug>.json
-  -> open Task Workspace
+~/.vcm/settings.json
 ```
 
-### 12.4 启动 role session
+Stored data:
 
-```text
-User clicks Start project-manager
-  -> POST /api/tasks/<task-slug>/sessions/project-manager/start
-  -> NodePtyTerminalRuntime spawns claude --agent project-manager
-  -> backend writes RoleSessionRecord
-  -> frontend opens WebSocket
-  -> xterm.js renders output
-```
+- translation settings
+- translation secrets
+- recent repository paths, max 5
 
-### 12.5 用户切换和沟通
+Legacy migration:
 
-```text
-User clicks Architect tab
-  -> frontend switches active role
-  -> if session exists, subscribe to WebSocket
-  -> if session not started, show Start button
-  -> user types directly into terminal
-```
+- `~/.vibe-coding-master/settings.json`
+- `~/.vibe-coding-master/translation.json`
+
+### Provider
 
-### 12.6 下发 role command
+Provider type:
 
 ```text
-PM writes architect.md
-  -> User can inspect the command file in the task directory when needed
-  -> User clicks Send Command in the target role toolbar
-  -> backend validates command file
-  -> backend writes short instruction to architect pty
-  -> backend records dispatch event
+openai-compatible
 ```
 
-### 12.7 查看 artifacts
+It uses chat completions and builds the URL from `baseUrl`.
 
-```text
-V1 main GUI does not render artifact status.
-Handoff files remain available in the task directory and backend services.
-```
+Prompt keys:
 
-### 12.8 重启 role session
+- `zh-to-en`
+- `zh-to-en-with-context`
+- `en-to-zh`
 
-```text
-User clicks Restart coder
-  -> backend stops existing coder pty if any
-  -> preserves logs and artifacts
-  -> starts new claude --agent coder
-  -> updates session record
-  -> frontend reconnects WebSocket
-```
+### Claude Output Path
 
-## 13. Artifact Schema Checks
+Output translation reads Claude transcript JSONL, not terminal raw output.
 
-V1 不判断内容质量，但必须检查关键 artifact 是否存在且包含必要标题。
+Resolution order:
 
-### 13.1 architecture-plan.md
+1. persisted `RoleSessionRecord.transcriptPath`
+2. `claudeTranscriptPath(session.cwd, session.claudeSessionId)`
+3. scan `~/.claude/projects/*/<sessionId>.jsonl` and choose newest mtime
 
-最低标题：
+Tailer:
 
-```text
-Architecture Summary
-Task Classification
-Required Role Route
-Modules / Files
-File Responsibilities
-Public Surface Contract
-Phases
-Validation Per Phase
-Risks
-Stop Conditions
-```
+- validates file exists
+- can replay history since session start minus a grace window
+- uses `fs.watch`
+- also polls every 500ms
+- parses only complete newline-delimited JSON records
 
-### 13.2 implementation-log.md
+Parsed transcript events:
 
-最低标题：
+- `text`
+- `thinking`
+- `question`
+- `todo`
+- `agent`
+- `tool_use`
+- `tool_result`
 
-```text
-Summary
-Files Changed
-Public Surface Changed
-Tests Added / Updated
-Validation Run
-Deviations From Architecture Plan
-Follow-ups
-```
+Translation service behavior:
 
-### 13.3 validation-log.md
+- ignores thinking
+- translates text/question/todo/agent as prose
+- preserves tool_use/tool_result as tool-output
+- queues translation per runtime session id
+- emits WebSocket `translation-entry`
+- emits WebSocket `translation-status`
 
-最低要求：
+### User Input Path
 
 ```text
-至少存在一个 validation entry，或明确说明 not run + reason。
+textarea -> POST translation/input -> provider -> English draft in the same textarea -> optional send
 ```
 
-### 13.4 review-report.md
-
-最低标题：
+Send path:
 
 ```text
-Summary
-Role / Handoff Compliance
-Scope Review
-Architecture Review
-Public Contract Review
-Test Review
-Validation Evidence
-Findings
-Decision
+POST translation/send -> runtime.write(session.id, englishText + "\r")
 ```
 
-## 14. 错误处理
+The backend strips trailing newlines before appending `\r`.
 
-### 14.1 Claude Code 不存在
+## 15. API Surface
 
-连接 repo 或启动 role session 前失败，并在 GUI 中提示：
+Project:
 
 ```text
-Claude Code command is not available.
-Install Claude Code or configure the claude command path.
+GET  /api/health
+GET  /api/projects/recent
+GET  /api/projects/current
+POST /api/projects/connect
 ```
 
-### 14.2 Repo 无效
-
-`POST /api/projects/connect` 必须检查 Git repo。
-
-失败时提示：
+Harness:
 
 ```text
-Selected path is not a Git repository.
+GET  /api/projects/harness
+POST /api/projects/harness/apply
 ```
 
-### 14.3 Role session 已存在
-
-默认不重复启动。
-
-GUI 显示：
-
-- Focus existing session。
-- Restart session。
-- Stop session。
-
-### 14.4 role command 缺失
-
-发送 command 必须失败：
+Tasks:
 
 ```text
-Missing .ai/handoffs/<task-slug>/role-commands/<role>.md
-Ask project-manager to produce the role command first.
+GET  /api/tasks
+POST /api/tasks
+GET  /api/tasks/:taskSlug
+GET  /api/tasks/:taskSlug/status
+POST /api/tasks/:taskSlug/cleanup
 ```
 
-### 14.5 role command 为空
+There is no task-level "switch worktree" API. Worktree selection happens only at task creation.
 
-发送 command 必须失败：
+Sessions:
 
 ```text
-Role command exists but is empty.
+GET  /api/tasks/:taskSlug/sessions
+POST /api/tasks/:taskSlug/sessions/:role/start
+POST /api/tasks/:taskSlug/sessions/:role/resume
+POST /api/tasks/:taskSlug/sessions/:role/restart
+POST /api/tasks/:taskSlug/sessions/:role/stop
+POST /api/tasks/:taskSlug/sessions/:role/dispatch
 ```
 
-### 14.6 artifact 缺失
-
-Backend artifact schema check 标记 missing，不自动补写真实内容。
-
-### 14.7 进程崩溃
-
-role session 进程异常退出时：
-
-- 状态标记为 `crashed`。
-- 保留 raw log。
-- 显示 exit code。
-- 提供 Restart。
-
-### 14.8 页面刷新
-
-页面刷新后：
-
-- 前端重新请求 task/session 状态。
-- 对 live session 重新建立 WebSocket。
-- 对 missing live process 显示 `missing` 或 `exited`。
-
-## 15. 安全和权限边界
-
-V1 不是 sandbox。它是本地 GUI session orchestrator。
-
-V1 必须明确提示：
-
-- Claude Code 在用户当前 repo 环境运行。
-- VCM 不拦截 Claude Code 的所有文件写入。
-- GUI 中的 terminal 是真实 Claude Code session。
-- 高风险任务仍需要 human approval。
-- 角色隔离依赖 `.claude/agents/*`、Claude Code permissions、用户 review 和 handoff artifacts。
-
-V1 推荐但不强制：
-
-- 项目提供 `.claude/agents/project-manager.md`。
-- 项目提供 `.claude/agents/architect.md`。
-- 项目提供 `.claude/agents/coder.md`。
-- 项目提供 `.claude/agents/reviewer.md`。
-- 项目配置 Claude Code permission hooks。
-
-V1 可以提供 Harness Health 检查这些文件是否存在，但不自动生成复杂 role agents。
-
-## 16. 后续演进接口
-
-V1 代码应预留这些抽象，但不完整实现：
-
-### 16.1 Review Adapter
-
-后续接入 Cross-Model Reviewer。
-
-### 16.2 Validation Runner
-
-后续自动运行 validation commands。
-
-### 16.3 Worktree Manager
-
-后续实现：
+Artifacts:
 
 ```text
-one task -> one branch -> one worktree
+GET /api/tasks/:taskSlug/artifacts
+GET /api/tasks/:taskSlug/artifacts/:artifactName
+GET /api/tasks/:taskSlug/role-commands/:role
+PUT /api/tasks/:taskSlug/role-commands/:role
+GET /api/tasks/:taskSlug/logs/:role
 ```
 
-V1 只做当前 repo working directory orchestration。
-
-### 16.4 Session Persistence Hardening
-
-后续增强：
-
-- backend lifecycle 管理。
-- session registry 持久化。
-- raw log replay。
-- 页面刷新和 backend 重启后的状态恢复。
-- crashed / exited session 的恢复建议。
-
-### 16.5 Desktop Shell
-
-后续用 Electron 或 Tauri 包装本地 Web GUI。
-
-### 16.6 Permission / Hook Manager
-
-后续生成 role-specific Claude Code permission hooks。
-
-## 17. 实施顺序
-
-### Milestone 1: Local GUI Shell
-
-- TypeScript monorepo / app 初始化。
-- React + Vite frontend。
-- Node backend。
-- `vcm dev` 启动前后端。
-- Project Dashboard。
-- repo connect API。
-- environment check。
-
-### Milestone 2: Task Workspace and Artifacts
-
-- Task Workspace 页面。
-- `POST /api/tasks`。
-- handoff directory。
-- role command templates。
-- artifact templates。
-- artifact schema checks。
-
-### Milestone 3: Embedded Terminal Runtime
-
-- TerminalRuntime interface。
-- NodePtyTerminalRuntime。
-- WebSocket terminal bridge。
-- xterm.js SessionConsole。
-- start / stop / restart role session。
-- raw logs。
-
-### Milestone 4: Role Session Cockpit
-
-- role session tabs。
-- session status badges。
-- reconnect after page refresh。
-- event log。
-- session registry。
-- crash / exited handling。
-
-### Milestone 5: GUI Role Command Dispatch
-
-- role command viewer。
-- Send Command button。
-- backend dispatch API。
-- short instruction write to pty。
-- dispatch event recording。
-
-### Milestone 6: Acceptance Smoke
-
-- one repo。
-- one task。
-- start project-manager。
-- start architect。
-- send architect command。
-- verify output streams in GUI。
-- verify raw logs saved。
-- verify artifact status shown。
-- restart coder session。
-- stop all sessions。
-
-## 18. V1 验收标准
-
-V1 完成时，应能在一个真实 repo 中演示：
+Messages:
 
 ```text
-1. 打开 VibeCodingMaster GUI
-2. 选择本地 Git repo
-3. 创建 demo-task
-4. Task Workspace 打开成功
-5. project-manager session 在 embedded terminal 中启动
-6. architect session 在另一个 tab 中启动
-7. 用户可以在 GUI 中切换 PM / architect
-8. 用户可以直接在 terminal 中输入和确认 Claude Code 提示
-9. PM 产出 architect.md
-10. 用户需要时可在任务目录查看 architect.md
-11. 用户点击目标 role 的 Send Command
-12. architect session 收到短指令并执行
-13. architect raw output 写入 logs/architect.log
-14. backend artifact check 可识别 architecture-plan.md missing / incomplete / ok
-15. 用户可以 restart coder session
-16. 页面刷新后能恢复 task/session 状态
+GET  /api/tasks/:taskSlug/messages
+POST /api/tasks/:taskSlug/messages
+POST /api/tasks/:taskSlug/messages/:messageId/stage
+POST /api/tasks/:taskSlug/messages/:messageId/approve
+POST /api/tasks/:taskSlug/messages/:messageId/reject
+GET  /api/tasks/:taskSlug/orchestration
+PUT  /api/tasks/:taskSlug/orchestration
+POST /api/tasks/:taskSlug/orchestration/pause
+POST /api/tasks/:taskSlug/orchestration/resume
 ```
 
-成功指标：
-
-- GUI 启动成功。
-- repo 连接成功。
-- role session 创建成功。
-- terminal input/output 稳定。
-- raw logs 不丢。
-- artifact 状态可见。
-- role command dispatch 可控。
-- 页面刷新后可恢复状态。
-
-## 19. 主要风险和应对
-
-### 19.1 Claude Code 交互终端嵌入复杂
-
-应对：
+Translation:
 
-- 使用 xterm.js。
-- 使用 node-pty。
-- 保留 raw stream。
-- 支持 resize。
-- 支持权限确认和用户输入。
-
-### 19.2 Session 持久性不足
-
-应对：
-
-- backend 持有 session registry。
-- `.vcm/sessions` 保存每个 role 的完整 `RoleSessionRecord` 和 `claudeSessionId`。
-- 首次启动使用 `claude --agent <role> --session-id <uuid>`。
-- backend 重启或异常退出后，GUI 将旧 pty 标记为 `resumable`。
-- Resume 使用 `claude --agent <role> --resume <uuid>` 创建新的 embedded terminal。
-- raw logs 持续写入。
-- 页面刷新重新订阅。
-- 后续继续增强 backend lifecycle 和 raw log replay。
-
-### 19.3 Claude Code 状态不可结构化
+```text
+GET  /api/translation/settings
+PUT  /api/translation/settings
+GET  /api/translation/prompts
+POST /api/translation/test
+POST /api/tasks/:taskSlug/sessions/:role/translation/input
+POST /api/tasks/:taskSlug/sessions/:role/translation/send
+POST /api/translation/sessions/:sessionId/clear
+POST /api/translation/sessions/:sessionId/retry/:translationId
+```
 
-应对：
+WebSockets:
 
-- V1 不深度解析 Claude Code 输出。
-- 状态以 process state、用户显式标记、artifact state 为主。
-- 后续通过 structured reports 改进。
+```text
+/ws/terminal/:sessionId
+/ws/translation/:sessionId
+```
 
-### 19.4 PM 误控其他 session
+## 16. Error Handling
 
-应对：
+File:
 
-- PM 不直接操作 runtime。
-- dispatch 必须读取 role command artifact。
-- GUI 展示 command 并由用户发送。
-- backend 记录 dispatch event。
+- `src/backend/errors.ts`
 
-### 19.5 Handoff 空洞
+Backend services throw `VcmError` with:
 
-应对：
+- code
+- message
+- status code
+- optional hint
 
-- artifact schema check。
-- backend status 可报告 missing/incomplete/ok。
-- reviewer 后续检查 handoff compliance。
+Fastify error handler returns:
 
-### 19.6 用户在 main 分支上开发
+```json
+{
+  "error": {
+    "code": "CODE",
+    "message": "Human-readable message",
+    "hint": "Optional hint"
+  }
+}
+```
 
-应对：
+## 17. Packaging Architecture
 
-- repo connect 和 task create 时显示当前 branch。
-- 如果当前 branch 是 `main` 或 `master`，显示 warning。
-- V1 不强制创建 branch，但强烈建议用户切到 task branch。
+`package.json` publishes built artifacts:
 
-### 19.7 GUI 复杂度过高
+- `dist`
+- `dist-frontend`
+- `docs`
+- `scripts`
+- `README.md`
 
-应对：
+Bins:
 
-- V1 只做本地单用户。
-- V1 只做一个 repo 的核心路径。
-- V1 不做自动 review、validation runner、PR。
-- 优先完成 SessionConsole、role dispatch 和 session recovery。
+- `vcm` -> `dist/main.js`
+- `vcmctl` -> `dist/cli/vcmctl.js`
 
-## 20. 架构判断
+Important scripts:
 
-V1 的本质不是“自动写代码”，也不是“给终端包一层命令”。
+- `build`: clean, TypeScript build, Vite build
+- `verify:package`: verifies required dist files and frontend assets
+- `prepack`: build and package verification
+- `postinstall`: fixes `node-pty` spawn helper when needed
 
-V1 的本质是：
+## 18. Security And Safety Boundaries
 
-> 搭建一个可靠的本地 Claude Code 多角色 GUI 工作台，让多个 role sessions、handoff artifacts、logs 和状态在一个任务页面中变得可见、可切换、可沟通、可恢复。
+Current boundaries:
 
-第一版应该保持克制：
+- VCM runs local processes with the user's permissions.
+- VCM does not auto-confirm Claude Code permission prompts.
+- Relaxed Claude permission modes are user-selected per role launch.
+- Translation API key is local in `~/.vcm/settings.json`.
+- Translation output is UI/runtime state only unless a user or role copies it into a file.
+- `.ai/vcm` is local project control state and must be ignored by Git.
+- Task handoff artifacts live in the task worktree and users should decide whether those artifacts belong in task commits.
+- Task worktrees are created only during task creation; VCM does not expose branch/worktree switching APIs.
+- Sandbox isolation should come from a devContainer, Docker container, VM, or other user-controlled environment.
 
-```text
-少做智能判断
-多做状态可见
-少自动修改代码
-多沉淀 artifacts
-少解析终端语义
-多保留 raw logs
-少暴露终端编排细节
-多提供 GUI 操作入口
-```
+## 19. Known Implementation Boundaries
 
-只要 V1 能稳定做到 GUI task workspace、embedded Claude Code role sessions、terminal I/O、raw logs、role command dispatch 和 handoff artifact checks，后续 Task Spec Builder、Validation Runner、Cross-Model Review、Worktree Manager、Desktop Packaging 和 session persistence hardening 才有可靠地基。
+- No tmux backend.
+- No per-role worktree manager.
+- No branch switching for an existing task.
+- No main-page artifact inspector.
+- No raw PTY output translation.
+- No hard workflow gate enforcement.
+- No durable backend event log for the sidebar Events modal; current events are frontend runtime events for the active task.
+- No hosted multi-user collaboration.