vibe-coding-master 0.0.5 → 0.0.7

package/docs/v1-implementation-plan.md

@@ -1,1949 +1,1128 @@
-# VibeCodingMaster V1 实施计划
+# V1 Implementation Plan And File Map
 
-版本：v0.2  
-日期：2026-05-29  
-状态：实施计划草案  
-依据：
+Last updated: 2026-05-30
 
-- `docs/product-design.md`
-- `docs/v1-architecture-design.md`
-- `docs/cc-best-practices.md`
+This document is the current implementation map for VCM V1. It replaces older plan text that referenced removed files or obsolete UI behavior.
 
-## 1. 实施目标
+## 1. Current Status
 
-V1 实现一个本地 GUI Session Cockpit，让用户可以在一个任务工作台中启动、切换、查看、输入和管理多个 Claude Code role sessions。
+V1 is implemented as a local GUI app with:
 
-V1 完成后，用户应能：
+- Fastify backend.
+- React frontend.
+- `node-pty` embedded terminals.
+- `xterm.js` terminal rendering.
+- Four Claude Code role sessions.
+- VCM harness installer.
+- API-driven message bus.
+- Translation panel based on Claude transcript JSONL tailing.
+- npm packaging with built `dist` and `dist-frontend` output.
 
-```text
-Open VibeCodingMaster
-  -> Select repo
-  -> New task
-  -> Start project-manager session
-  -> Start architect session
-  -> Switch between role sessions
-  -> Type directly into embedded Claude Code terminals
-  -> View role commands, logs, and handoff artifacts
-  -> Send role command to target session from GUI
-  -> Restart / stop role sessions
-```
+The implementation still has planned improvement space, but this file only describes code that exists now.
 
-V1 不再以手动 CLI 或手动终端控制为主路径。
+## 2. Package And Build
 
-V1 不实现：
+File:
 
-- 自动生成完整 Task Spec。
-- 自动识别 public contract / test contract。
-- 自动执行 validation commands。
-- 自动 Cross-Model Review。
-- 自动创建 PR。
-- SaaS 多用户协作。
-- 完整 Desktop 打包和自动更新。
-- 多 worktree 自动管理。
+- `package.json`
 
-## 2. 关键约束
+Current package facts:
 
-1. GUI 是用户主入口，CLI 只用于启动 dev server、调试和 smoke test。
-2. Claude Code role session 必须在 embedded terminal 中可见、可输入、可重启。
-3. Project Manager 不直接无限制控制其他 role sessions。
-4. Role command 必须先落盘到 `.ai/handoffs/<task-slug>/role-commands/<role>.md`。
-5. GUI 读取 role command，用户点击发送后，backend 只向目标 terminal 写入短指令。
-6. Backend 可以程序化写入和监听 embedded terminal，但 V1 只允许用户触发的 command dispatch，不自动确认权限，不自动串联驱动角色。
-7. Terminal output 只作为调试信息；长期事实源是 handoff artifacts。
-8. Raw terminal stream 必须持续写入 `.ai/handoffs/<task-slug>/logs/<role>.log`。
-9. V1 只做 artifact 存在性和标题完整性检查，不判断内容质量。
-10. 状态必须能从 backend session registry、terminal process state、repo artifacts、`.vcm` metadata 恢复。
-11. V1 不把每个 role 放到独立 worktree。同一任务默认共享当前 repo working directory。
-12. V1 默认遵守 single-writer rule，但主要通过流程提示、role status 和 review gate 实现，不做强制 sandbox。
+- package name: `vibe-coding-master`
+- current version: `0.0.6`
+- type: ESM
+- `bin.vcm`: `dist/main.js`
+- `bin.vcmctl`: `dist/cli/vcmctl.js`
+- published files: `dist`, `dist-frontend`, `docs`, `scripts`, `README.md`
 
-## 3. 技术选型
+Scripts:
 
-```text
-Language: TypeScript
-Runtime: Node.js LTS
-Frontend: React + Vite
-Terminal UI: xterm.js
-Backend: Fastify + ws
-Terminal runtime: node-pty
-Process execution: execa
-State storage: JSON files
-Test runner: Vitest + Playwright
-Module format: ESM / NodeNext
-```
+- `clean`: remove build output.
+- `fix:node-pty`: fix packaged `node-pty` spawn helper.
+- `postinstall`: run `fix:node-pty`.
+- `verify:package`: verify required package files.
+- `prepack`: run build and package verification.
+- `dev`: start backend plus Vite dev server.
+- `build`: clean, compile Node TypeScript, build frontend.
+- `start`: run built backend.
+- `typecheck`: TypeScript no-emit checks for browser and Node configs.
+- `test`: Vitest.
+- `e2e`: Playwright.
+
+Packaging guard:
+
+- `scripts/verify-package.mjs`
+
+It verifies required files, shebangs, packaged static path behavior, and frontend built assets.
 
-## 4. 目标目录结构
+## 3. Source Tree
 
 ```text
-VibeCodingMaster/
-  package.json
-  tsconfig.json
-  tsconfig.node.json
-  vite.config.ts
-  vitest.config.ts
-  playwright.config.ts
-  index.html
-  README.md
-  docs/
-    product-design.md
-    v1-architecture-design.md
-    v1-implementation-plan.md
-    cc-best-practices.md
-
-  src/
-    main.ts
-
-    shared/
-      constants.ts
-      types/
-        api.ts
-        artifact.ts
-        project.ts
-        role.ts
-        session.ts
-        task.ts
-        terminal.ts
-      validation/
-        artifact-check.ts
-        slug-check.ts
-
-    frontend/
-      app.tsx
-      main.tsx
-      styles.css
-      routes/
-        project-dashboard.tsx
-        task-workspace.tsx
-      components/
-        app-shell.tsx
-        event-log.tsx
-        repo-connect-form.tsx
-        role-session-tabs.tsx
-        session-console.tsx
-        session-toolbar.tsx
-        status-badge.tsx
-        task-nav.tsx
-      terminal/
-        terminal-client.ts
-        xterm-view.tsx
-      state/
-        api-client.ts
-        app-store.ts
-        session-store.ts
-
-    backend/
-      server.ts
-      api/
-        artifact-routes.ts
-        project-routes.ts
-        session-routes.ts
-        task-routes.ts
-      ws/
-        terminal-ws.ts
-      runtime/
-        node-pty-runtime.ts
-        session-registry.ts
-        terminal-runtime.ts
-      services/
-        artifact-service.ts
-        command-dispatcher.ts
-        project-service.ts
-        session-service.ts
-        status-service.ts
-        task-service.ts
-      adapters/
-        claude-adapter.ts
-        command-runner.ts
-        filesystem.ts
-        git-adapter.ts
-      templates/
-        handoff.ts
-        role-command.ts
-      validation/
-        environment-check.ts
-
-  tests/
-    unit/
-      shared/
-      backend/
-      frontend/
-    integration/
-      api/
-      runtime/
-    e2e/
-      task-workspace.spec.ts
+src/
+  main.ts
+  cli/
+    vcmctl.ts
+  shared/
+    constants.ts
+    types/
+    validation/
+  backend/
+    server.ts
+    adapters/
+    api/
+    runtime/
+    services/
+    templates/
+    ws/
+  frontend/
+    app.tsx
+    main.tsx
+    routes/
+    components/
+    state/
+    terminal/
+    styles.css
 ```
 
-## 5. Package 和配置文件
-
-### 5.1 `package.json`
-
-职责：
-
-- 声明本地开发命令。
-- 声明 build、test、typecheck、e2e 命令。
-- 保留 `vcm` binary 用于启动本地 GUI dev/prod server。
-
-计划字段：
-
-```json
-{
-  "type": "module",
-  "bin": {
-    "vcm": "./dist/main.js"
-  },
-  "scripts": {
-    "dev": "tsx src/main.ts --dev",
-    "build": "tsc -p tsconfig.node.json && vite build",
-    "start": "node dist/main.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.node.json --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "e2e": "playwright test"
-  },
-  "dependencies": {
-    "@fastify/static": "^7.0.0",
-    "@xterm/addon-fit": "^0.10.0",
-    "@xterm/addon-web-links": "^0.11.0",
-    "@xterm/xterm": "^5.5.0",
-    "execa": "^9.0.0",
-    "fastify": "^5.0.0",
-    "node-pty": "^1.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "ws": "^8.0.0",
-    "zod": "^3.0.0"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.0.0",
-    "@types/node": "^22.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "@types/ws": "^8.0.0",
-    "@vitejs/plugin-react": "^4.0.0",
-    "tsx": "^4.0.0",
-    "typescript": "^5.0.0",
-    "vite": "^6.0.0",
-    "vitest": "^2.0.0"
-  }
-}
-```
+Removed/obsolete files that must not be documented as active:
 
-### 5.2 `tsconfig.json`
-
-职责：
-
-- 类型检查前端和 shared 代码。
-- 使用 JSX。
-- 不输出文件。
-
-关键配置：
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "jsx": "react-jsx",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "types": ["vite/client"]
-  },
-  "include": ["src/frontend/**/*.ts", "src/frontend/**/*.tsx", "src/shared/**/*.ts"]
-}
-```
+- `src/shared/validation/translation-classifier.ts`
+- `src/frontend/state/translation-store.ts`
+- `src/frontend/components/translation-entry-row.tsx`
+- `src/frontend/state/task-store.ts`
 
-### 5.3 `tsconfig.node.json`
-
-职责：
-
-- 编译 backend、main 和 shared 代码到 `dist/`。
-- 使用 NodeNext ESM。
-
-关键配置：
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "rootDir": "src",
-    "outDir": "dist",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true
-  },
-  "include": ["src/main.ts", "src/backend/**/*.ts", "src/shared/**/*.ts"]
-}
-```
+## 4. Entry Points
 
-### 5.4 `vite.config.ts`
-
-职责：
-
-- 构建 React frontend。
-- 开发时代理 API 和 WebSocket 到 local backend。
-
-导出定义：
-
-```ts
-export default defineConfig({
-  plugins: [react()],
-  root: ".",
-  build: {
-    outDir: "dist-frontend"
-  },
-  server: {
-    port: 5173,
-    proxy: {
-      "/api": "http://localhost:4173",
-      "/ws": {
-        target: "ws://localhost:4173",
-        ws: true
-      }
-    }
-  }
-});
-```
+### `src/main.ts`
 
-### 5.5 `vitest.config.ts`
+Exports:
 
-职责：
+- `MainOptions`
+- `parseMainArgs(argv): MainOptions`
+- `main(argv): Promise<void>`
 
-- 运行 unit 和 integration tests。
-- 使用 node environment。
+Responsibilities:
 
-导出定义：
+- parse `--dev`, `--open`, `--host=`, `--port=`
+- start backend on port `4173` by default
+- start Vite on port `5173` in dev mode
+- serve `dist-frontend` through backend in production mode
+- close backend/Vite on `SIGINT`
 
-```ts
-export default defineConfig({
-  test: {
-    environment: "node",
-    include: ["tests/unit/**/*.test.ts", "tests/integration/**/*.test.ts"]
-  }
-});
-```
+### `src/cli/vcmctl.ts`
 
-### 5.6 `playwright.config.ts`
+CLI commands:
 
-职责：
+- `vcmctl send`
+- `vcmctl reply`
+- `vcmctl result`
+- `vcmctl inbox`
+- `vcmctl ready`
 
-- 运行 GUI smoke tests。
-- 启动 `npm run dev` 作为 webServer。
+Environment required in role sessions:
 
-导出定义：
+- `VCM_API_URL`
+- `VCM_TASK_SLUG`
+- `VCM_ROLE`
 
-```ts
-export default defineConfig({
-  testDir: "tests/e2e",
-  webServer: {
-    command: "npm run dev",
-    url: "http://localhost:5173",
-    reuseExistingServer: true
-  }
-});
-```
+Role sessions receive these env vars from `SessionService`.
 
-### 5.7 `src/main.ts`
+## 5. Shared Layer
 
-职责：
+### `src/shared/constants.ts`
 
-- 启动 local backend。
-- 在 dev 模式提示 Vite URL。
-- 在 prod 模式 serve frontend static assets。
+Exports:
 
-导出定义：
+- `DEFAULT_BACKEND_PORT`
+- `DEFAULT_FRONTEND_PORT`
+- `ROLE_DEFINITIONS`
+- `ROLE_NAMES`
+- `DISPATCHABLE_ROLES`
+- `isRoleName(value)`
+- `isDispatchableRole(value)`
+- `getRoleDefinition(role)`
 
-```ts
-export interface MainOptions {
-  dev?: boolean;
-  host?: string;
-  port?: number;
-  open?: boolean;
-}
+Roles:
 
-export function parseMainArgs(argv: string[]): MainOptions;
+- `project-manager`
+- `architect`
+- `coder`
+- `reviewer`
 
-export async function main(argv?: string[]): Promise<void>;
-```
+Dispatchable roles:
 
-## 6. Shared 类型层
-
-### 6.1 `src/shared/types/role.ts`
-
-职责：
-
-- 定义 V1 role 集合和状态。
-
-导出定义：
-
-```ts
-export type RoleName =
-  | "project-manager"
-  | "architect"
-  | "coder"
-  | "reviewer";
-
-export type DispatchableRole =
-  | "architect"
-  | "coder"
-  | "reviewer";
-
-export type RoleStatus =
-  | "not_started"
-  | "starting"
-  | "running"
-  | "waiting"
-  | "blocked"
-  | "done"
-  | "resumable"
-  | "crashed"
-  | "exited"
-  | "missing"
-  | "unknown";
-
-export interface RoleDefinition {
-  name: RoleName;
-  label: string;
-  commandAgent: string;
-  dispatchable: boolean;
-}
-```
+- `architect`
+- `coder`
+- `reviewer`
 
-### 6.2 `src/shared/constants.ts`
+### `src/shared/types/role.ts`
 
-职责：
+Defines:
 
-- 定义固定 role、artifact 文件名、默认端口。
+- `RoleName`
+- `DispatchableRole`
+- `RoleStatus`
+- `RoleDefinition`
 
-导出定义：
+### `src/shared/types/project.ts`
 
-```ts
-export const DEFAULT_BACKEND_PORT = 4173;
-export const DEFAULT_FRONTEND_PORT = 5173;
+Defines:
 
-export const ROLE_DEFINITIONS: readonly RoleDefinition[];
-export const ROLE_NAMES: readonly RoleName[];
-export const DISPATCHABLE_ROLES: readonly DispatchableRole[];
+- `ProjectConfig`
+- `ProjectSummary`
+- `ConnectProjectRequest`
 
-export function isRoleName(value: string): value is RoleName;
-export function isDispatchableRole(value: string): value is DispatchableRole;
-export function getRoleDefinition(role: RoleName): RoleDefinition;
-```
+Important fields:
 
-### 6.3 `src/shared/types/project.ts`
+- `handoffRoot`
+- `stateRoot`
+- `terminalBackend`
+- `claudeCommand`
+- `isDirty`
 
-职责：
+### `src/shared/types/task.ts`
 
-- 定义 repo 连接和项目配置。
+Defines:
 
-导出定义：
+- `TaskStatus`
+- `TaskRecord`
+- `CreateTaskRequest`
 
-```ts
-export interface ProjectConfig {
-  version: 1;
-  repoRoot: string;
-  defaultRoles: RoleName[];
-  handoffRoot: string;
-  stateRoot: string;
-  terminalBackend: "node-pty";
-  claudeCommand: string;
-}
+Current UI sends only `taskSlug`, although the API type still permits optional `title` and `specPath`.
 
-export interface ProjectSummary {
-  repoRoot: string;
-  branch: string;
-  isDirty: boolean;
-  config: ProjectConfig;
-  warnings: string[];
-}
+### `src/shared/types/session.ts`
 
-export interface ConnectProjectRequest {
-  repoPath: string;
-}
-```
+Defines:
 
-### 6.4 `src/shared/types/task.ts`
-
-职责：
-
-- 定义 task metadata。
-
-导出定义：
-
-```ts
-export type TaskStatus =
-  | "created"
-  | "planning"
-  | "running"
-  | "blocked"
-  | "stopped"
-  | "done";
-
-export interface TaskRecord {
-  version: 1;
-  taskSlug: string;
-  title?: string;
-  createdAt: string;
-  updatedAt: string;
-  repoRoot: string;
-  branch: string;
-  handoffDir: string;
-  status: TaskStatus;
-  specPath?: string;
-}
-
-export interface CreateTaskRequest {
-  taskSlug: string;
-  title?: string;
-  specPath?: string;
-}
-```
+- `ClaudePermissionMode`
+- `RoleSessionRecord`
+- `TaskSessionRecord`
+- `RoleSessionPointer`
+- `StartRoleSessionRequest`
 
-### 6.5 `src/shared/types/session.ts`
-
-职责：
-
-- 定义 role session metadata 和 task session summary。
-
-导出定义：
-
-```ts
-export type ClaudePermissionMode =
-  | "default"
-  | "bypassPermissions"
-  | "dangerously-skip-permissions";
-
-export interface RoleSessionRecord {
-  id: string;
-  claudeSessionId: string;
-  taskSlug: string;
-  role: RoleName;
-  status: RoleStatus;
-  command: string;
-  permissionMode: ClaudePermissionMode;
-  cwd: string;
-  terminalBackend: "node-pty";
-  pid?: number;
-  logPath: string;
-  roleCommandPath?: string;
-  handoffArtifactPath?: string;
-  startedAt?: string;
-  updatedAt: string;
-  lastOutputAt?: string;
-  exitCode?: number | null;
-}
-
-export interface TaskSessionRecord {
-  version: 1;
-  taskSlug: string;
-  updatedAt: string;
-  roles: Record<RoleName, RoleSessionPointer>;
-}
-
-export interface RoleSessionPointer {
-  id: string | null;
-  claudeSessionId?: string;
-  status: RoleStatus;
-  record?: RoleSessionRecord;
-}
-
-export interface StartRoleSessionRequest {
-  cols?: number;
-  rows?: number;
-  permissionMode?: ClaudePermissionMode;
-}
-```
+`RoleSessionRecord` includes `claudeSessionId` and `transcriptPath`, which are required for resume and translation transcript lookup.
 
-### 6.6 `src/shared/types/terminal.ts`
+### `src/shared/types/message.ts`
 
-职责：
+Defines:
 
-- 定义 WebSocket terminal 消息和事件。
+- `VcmMessageActor`
+- `VcmMessageType`
+- `VcmMessageStatus`
+- `VcmOrchestrationMode`
+- `VcmRoleMessage`
+- `VcmOrchestrationState`
+- `SendRoleMessageRequest`
+- `SendRoleMessageResult`
 
-导出定义：
+The state type includes `paused` for backend/API compatibility. The current GUI only exposes manual/auto.
 
-```ts
-export type ClientTerminalMessage =
-  | { type: "input"; data: string }
-  | { type: "resize"; cols: number; rows: number };
+### `src/shared/types/translation.ts`
 
-export type ServerTerminalMessage =
-  | { type: "output"; data: string }
-  | { type: "status"; status: RoleStatus }
-  | { type: "exit"; exitCode: number | null }
-  | { type: "error"; message: string };
+Defines:
 
-export interface TerminalEvent {
-  id: string;
-  sessionId: string;
-  taskSlug: string;
-  role: RoleName;
-  type: "input" | "output" | "status" | "exit" | "error" | "dispatch";
-  timestamp: string;
-  data?: string;
-  status?: RoleStatus;
-  exitCode?: number | null;
-}
-```
+- `TranslationProviderType`
+- `TranslationDirection`
+- `TranslationInputMode`
+- `TranslationPromptKey`
+- `TRANSLATION_PROMPT_KEYS`
+- `TranslationSourceKind`
+- `TranslationStatus`
+- `TranslationSettings`
+- `TranslationSecretSettings`
+- `TranslationEntry`
+- `TranslateUserInputRequest`
+- `TranslateUserInputResult`
+- `SendTranslatedInputRequest`
+- `TranslationProviderTestResult`
+- `TranslationPromptPreview`
+- `TranslationWsMessage`
 
-### 6.7 `src/shared/types/artifact.ts`
-
-职责：
-
-- 定义 handoff artifact paths 和 schema check。
-
-导出定义：
-
-```ts
-export type ArtifactKind =
-  | "architecture-plan"
-  | "implementation-log"
-  | "validation-log"
-  | "review-report";
-
-export interface HandoffPaths {
-  handoffDir: string;
-  roleCommandsDir: string;
-  logsDir: string;
-  roleCommandPaths: Record<DispatchableRole, string>;
-  roleLogPaths: Record<RoleName, string>;
-  architecturePlanPath: string;
-  implementationLogPath: string;
-  validationLogPath: string;
-  reviewReportPath: string;
-}
-
-export interface ArtifactCheckResult {
-  kind: ArtifactKind;
-  path: string;
-  exists: boolean;
-  isEmpty: boolean;
-  missingHeadings: string[];
-  status: "missing" | "empty" | "incomplete" | "ok";
-}
-
-export interface ArtifactSummary {
-  paths: HandoffPaths;
-  checks: ArtifactCheckResult[];
-}
-```
+Prompt keys:
 
-### 6.8 `src/shared/types/api.ts`
+- `zh-to-en`
+- `zh-to-en-with-context`
+- `en-to-zh`
 
-职责：
+Source kinds:
 
-- 定义统一 API response。
+- `prose`
+- `tool-output`
 
-导出定义：
+Statuses:
 
-```ts
-export interface ApiSuccess<T> {
-  ok: true;
-  data: T;
-}
+- `queued`
+- `translating`
+- `translated`
+- `failed`
+- `preserved`
 
-export interface ApiFailure {
-  ok: false;
-  error: {
-    code: string;
-    message: string;
-    hint?: string;
-  };
-}
+### `src/shared/types/api.ts`
 
-export type ApiResponse<T> = ApiSuccess<T> | ApiFailure;
-```
+Defines:
 
-## 7. Shared Validation
+- `ApiErrorResponse`
+- `TaskStatusReport`
+- `TaskWorkflowStepId`
+- `TaskWorkflowStepStatus`
+- `TaskWorkflowStep`
+- `TaskWorkflowReport`
+- `DispatchRoleCommandResult`
+- `BootstrapState`
 
-### 7.1 `src/shared/validation/slug-check.ts`
+### `src/shared/types/artifact.ts`
 
-导出定义：
+Defines:
 
-```ts
-export interface SlugValidationResult {
-  valid: boolean;
-  reason?: string;
-  suggestion?: string;
-}
+- `ArtifactKind`
+- `HandoffPaths`
+- `ArtifactCheckResult`
+- `ArtifactSummary`
 
-export function isValidTaskSlug(value: string): boolean;
-export function validateTaskSlug(value: string): SlugValidationResult;
-export function assertValidTaskSlug(value: string): string;
-export function suggestTaskSlug(value: string): string;
-```
+Artifact kinds:
 
-### 7.2 `src/shared/validation/artifact-check.ts`
+- `architecture-plan`
+- `implementation-log`
+- `validation-log`
+- `review-report`
+- `docs-sync-report`
 
-导出定义：
+### `src/shared/types/harness.ts`
 
-```ts
-export const REQUIRED_ARCHITECTURE_PLAN_HEADINGS: readonly string[];
-export const REQUIRED_IMPLEMENTATION_LOG_HEADINGS: readonly string[];
-export const REQUIRED_REVIEW_REPORT_HEADINGS: readonly string[];
+Defines:
 
-export function getRequiredHeadings(kind: ArtifactKind): readonly string[];
-export function parseMarkdownHeadings(content: string): string[];
-export function findMissingHeadings(content: string, required: readonly string[]): string[];
-export function checkMarkdownArtifact(kind: ArtifactKind, path: string, content: string | null): ArtifactCheckResult;
-export function checkValidationLogArtifact(path: string, content: string | null): ArtifactCheckResult;
-```
+- `HarnessFileKind`
+- `HarnessFileAction`
+- `HarnessFileStatus`
+- `HarnessPlannedChange`
+- `HarnessStatusReport`
+- `HarnessApplyResult`
 
-## 8. Backend Adapter 层
+### `src/shared/types/terminal.ts`
 
-### 8.1 `src/backend/adapters/command-runner.ts`
+Defines:
 
-职责：
+- `ClientTerminalMessage`
+- `ServerTerminalMessage`
+- `TerminalEvent`
 
-- 封装 `execa`。
-- 供 git / claude check 使用。
+### `src/shared/validation/slug-check.ts`
 
-导出定义：
+Exports:
 
-```ts
-export interface RunCommandOptions {
-  cwd?: string;
-  reject?: boolean;
-  env?: NodeJS.ProcessEnv;
-}
+- `validateTaskSlug(taskSlug)`
+- `assertValidTaskSlug(taskSlug)`
 
-export interface RunCommandResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
+Current rule:
 
-export interface CommandRunner {
-  run(command: string, args: string[], options?: RunCommandOptions): Promise<RunCommandResult>;
-}
+- lowercase slug-style task names
+- safe for local paths and URLs
 
-export function createDefaultCommandRunner(): CommandRunner;
-export function normalizeCommandError(error: unknown): RunCommandResult;
-```
+### `src/shared/validation/artifact-check.ts`
 
-### 8.2 `src/backend/adapters/filesystem.ts`
+Exports:
 
-职责：
+- `checkMarkdownArtifact(kind, path, content)`
 
-- 封装文件读写、JSON 读写、目录创建。
+Current checks are title/placeholder oriented and do not judge semantic quality.
 
-导出定义：
+### `src/shared/validation/language-detect.ts`
 
-```ts
-export interface FileSystemAdapter {
-  pathExists(path: string): Promise<boolean>;
-  ensureDir(path: string): Promise<void>;
-  readText(path: string): Promise<string>;
-  writeText(path: string, content: string): Promise<void>;
-  appendText(path: string, content: string): Promise<void>;
-  readJson<T>(path: string): Promise<T>;
-  writeJsonAtomic<T>(path: string, value: T): Promise<void>;
-  ensureFile(path: string, content: string, options?: EnsureFileOptions): Promise<boolean>;
-}
+Exports:
 
-export interface EnsureFileOptions {
-  overwrite?: boolean;
-}
+- `cjkRatio(value)`
+- `isProbablyCjk(value, threshold)`
+- `shouldSkipForTargetLanguage(value, targetLanguage)`
 
-export function createNodeFileSystemAdapter(): FileSystemAdapter;
-export function resolveRepoPath(repoRoot: string, repoRelativePath: string): string;
-export function toRepoRelativePath(repoRoot: string, absolutePath: string): string;
-```
+These helpers remain available, but current Claude-output translation no longer uses a classifier to skip assistant prose.
 
-### 8.3 `src/backend/adapters/git-adapter.ts`
+## 6. Backend Adapters
 
-职责：
+### `src/backend/adapters/filesystem.ts`
 
-- 检查 Git repo 和 branch 状态。
+Exports:
 
-导出定义：
+- `FileSystemAdapter`
+- `EnsureFileOptions`
+- `createNodeFileSystemAdapter()`
+- `resolveRepoPath(repoRoot, repoRelativePath)`
+- `toRepoRelativePath(repoRoot, absolutePath)`
 
-```ts
-export interface GitAdapter {
-  isGitRepo(cwd: string): Promise<boolean>;
-  getRepoRoot(cwd: string): Promise<string>;
-  getCurrentBranch(repoRoot: string): Promise<string>;
-  isDirty(repoRoot: string): Promise<boolean>;
-  getDiffSummary(repoRoot: string): Promise<string>;
-}
+Used by all services that touch repo/app files.
 
-export function createGitAdapter(runner: CommandRunner): GitAdapter;
-```
+### `src/backend/adapters/command-runner.ts`
 
-### 8.4 `src/backend/adapters/claude-adapter.ts`
+Exports:
 
-职责：
+- `CommandResult`
+- `CommandRunner`
+- `CommandRunnerOptions`
+- `createCommandRunner()`
 
-- 检查 Claude Code 是否安装。
-- 生成 role session 启动命令。
+Used by Git and Claude adapters.
 
-导出定义：
+### `src/backend/adapters/git-adapter.ts`
 
-```ts
-export interface ClaudeAdapter {
-  isAvailable(command?: string): Promise<boolean>;
-  getVersion(command?: string): Promise<string>;
-  buildRoleStartCommand(
-    role: RoleName,
-    command?: string,
-    permissionMode?: ClaudePermissionMode
-  ): { command: string; args: string[]; display: string };
-}
+Exports:
 
-export function createClaudeAdapter(runner: CommandRunner): ClaudeAdapter;
-```
+- `GitRepoCheck`
+- `GitAdapter`
+- `createGitAdapter(runner)`
 
-## 9. Backend Runtime 层
-
-### 9.1 `src/backend/runtime/terminal-runtime.ts`
-
-职责：
-
-- 定义 terminal runtime 抽象。
-- 让上层业务不依赖 node-pty 细节。
-
-导出定义：
-
-```ts
-export interface CreateTerminalSessionInput {
-  taskSlug: string;
-  role: RoleName;
-  command: string;
-  args: string[];
-  cwd: string;
-  env?: NodeJS.ProcessEnv;
-  cols?: number;
-  rows?: number;
-  logPath: string;
-}
-
-export interface TerminalSession {
-  id: string;
-  taskSlug: string;
-  role: RoleName;
-  status: RoleStatus;
-  pid?: number;
-  startedAt: string;
-  lastOutputAt?: string;
-  exitCode?: number | null;
-}
-
-export type TerminalEventListener = (event: TerminalEvent) => void;
-export type Unsubscribe = () => void;
-
-export interface TerminalRuntime {
-  createSession(input: CreateTerminalSessionInput): Promise<TerminalSession>;
-  getSession(sessionId: string): TerminalSession | undefined;
-  getSessionByRole(taskSlug: string, role: RoleName): TerminalSession | undefined;
-  listSessions(taskSlug?: string): TerminalSession[];
-  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;
-}
-```
+Important behavior:
 
-### 9.2 `src/backend/runtime/node-pty-runtime.ts`
+- checks `.git` directly
+- accepts normal `.git` directories
+- accepts `.git` pointer files
+- passes per-command `safe.directory`
 
-职责：
+### `src/backend/adapters/claude-adapter.ts`
 
-- 实现 `TerminalRuntime`。
-- 使用 node-pty 承载 Claude Code 交互式 session。
-- 将 output 写入 logs 并推送给 subscribers。
+Exports:
 
-导出定义：
+- `ClaudeAdapter`
+- `createClaudeAdapter(runner)`
 
-```ts
-export interface NodePtyRuntimeDeps {
-  fs: FileSystemAdapter;
-  now?: () => string;
-  id?: () => string;
-}
+Builds role commands:
 
-export function createNodePtyTerminalRuntime(deps: NodePtyRuntimeDeps): TerminalRuntime;
+```text
+claude --agent <role> --session-id <uuid>
+claude --agent <role> --resume <uuid>
 ```
 
-实现规则：
+Adds permission flags for `bypassPermissions` and `dangerously-skip-permissions`.
 
-- `createSession` 使用 `pty.spawn(command, args, { cwd, env, cols, rows })`。
-- 监听 `onData`：
-  - append 到 log。
-  - emit `TerminalEvent`。
-  - 更新 `lastOutputAt`。
-- 监听 `onExit`：
-  - 更新 `status` 为 `exited` 或 `crashed`。
-  - emit `exit` event。
-- `write` 写入 pty。
-- `resize` 调用 pty resize。
-- `stop` kill pty 并更新状态。
+### `src/backend/adapters/translation-provider.ts`
 
-### 9.3 Programmatic I/O Boundary
+Exports:
 
-V1 的 backend 允许程序化读写 embedded terminal：
+- `TranslationProviderRequest`
+- `TranslationProviderResult`
+- `TranslationProvider`
+- `TranslationProviderError`
+- `createOpenAiCompatibleTranslationProvider(fetchImpl)`
+- `buildChatCompletionsUrl(baseUrl)`
+- `parseOpenAiUsage(raw)`
 
-- `runtime.write(sessionId, data)`：向指定 role session 写入 terminal input。
-- `runtime.subscribe(sessionId, listener)`：监听 terminal output、status、exit 和 error event。
-- `terminal-ws`：把用户在 GUI terminal 中输入的内容转发给 runtime。
-- `command-dispatcher`：在用户点击 Send Command 后，向目标 session 写入短指令。
+Implements OpenAI-compatible chat completions.
 
-V1 允许的自动化边界：
+## 7. Backend Runtime
 
-- 用户在 GUI terminal 里的输入可以原样转发。
-- 用户点击 Send Command 后，backend 可以写入 `Please read and execute the role command at: <path>`。
-- Backend 可以监听 output 并写入 raw log。
-- Backend 可以根据 output/exit event 更新轻量状态和 GUI 提示。
+### `src/backend/runtime/terminal-runtime.ts`
 
-V1 明确不做：
+Defines the runtime interface:
 
-- 不自动确认 Claude Code permission prompt。
-- 不由 Project Manager 自动向 Architect/Coder/Reviewer 连续下发命令。
-- 不由 Architect 输出自动触发 Coder。
-- 不由 Coder 输出自动触发 Reviewer。
-- 不根据 terminal output 自动执行高风险下一步。
+- `CreateTerminalSessionInput`
+- `TerminalSession`
+- `TerminalEventListener`
+- `Unsubscribe`
+- `SubscribeTerminalOptions`
+- `TerminalRuntime`
 
-### 9.4 `src/backend/runtime/session-registry.ts`
+### `src/backend/runtime/node-pty-runtime.ts`
 
-职责：
+Exports:
 
-- 保存 backend 内存中的 live sessions。
-- 将 runtime state 转为 GUI 可展示状态。
+- `NodePtyRuntimeDeps`
+- `createNodePtyTerminalRuntime(deps)`
+- `buildPtyEnvironment(baseEnv, inputEnv)`
 
-导出定义：
+Responsibilities:
 
-```ts
-export interface SessionRegistry {
-  upsert(session: RoleSessionRecord): void;
-  get(sessionId: string): RoleSessionRecord | undefined;
-  getByRole(taskSlug: string, role: RoleName): RoleSessionRecord | undefined;
-  list(taskSlug?: string): RoleSessionRecord[];
-  updateStatus(sessionId: string, status: RoleStatus, patch?: Partial<RoleSessionRecord>): void;
-  remove(sessionId: string): void;
-}
+- spawn Claude Code with `node-pty`
+- append raw output to role log file
+- emit terminal output/input/exit events
+- replay logs on subscribe
+- handle writes, resize, stop
+- set color-friendly terminal env vars
 
-export function createSessionRegistry(): SessionRegistry;
-```
+### `src/backend/runtime/session-registry.ts`
 
-## 10. Backend Service 层
+Exports:
 
-### 10.1 `src/backend/services/project-service.ts`
+- `SessionRegistry`
+- `createSessionRegistry()`
 
-职责：
+In-memory index for live/persisted role records by runtime session id and role.
 
-- 连接 repo。
-- 创建 `.vcm/config.json`。
-- 检查 Claude Code、branch、dirty state。
+## 8. Backend Services
 
-导出定义：
+### `src/backend/services/project-service.ts`
 
-```ts
-export interface ProjectService {
-  connectProject(input: ConnectProjectInput): Promise<ProjectSummary>;
-  getCurrentProject(): Promise<ProjectSummary | null>;
-  loadConfig(repoRoot: string): Promise<ProjectConfig>;
-  saveConfig(config: ProjectConfig, force?: boolean): Promise<void>;
-  getConfigPath(repoRoot: string): string;
-}
+Exports:
 
-export interface ProjectServiceDeps {
-  fs: FileSystemAdapter;
-  git: GitAdapter;
-  claude: ClaudeAdapter;
-}
+- `ProjectService`
+- `ProjectServiceDeps`
+- `createProjectService(deps)`
+- `buildDefaultProjectConfig(repoRoot)`
 
-export function createProjectService(deps: ProjectServiceDeps): ProjectService;
-export function buildDefaultProjectConfig(repoRoot: string): ProjectConfig;
-```
+Responsibilities:
 
-### 10.2 `src/backend/services/task-service.ts`
+- connect repo
+- store current project in process memory
+- record recent repo paths in app settings
+- create `.vcm/config.json`
+- ensure base state directories
 
-职责：
+### `src/backend/services/task-service.ts`
 
-- 创建任务 metadata。
-- 创建 handoff structure。
-- 读取任务列表和单个任务。
+Exports:
 
-导出定义：
+- `TaskService`
+- `TaskServiceDeps`
+- `createTaskService(deps)`
 
-```ts
-export interface TaskService {
-  createTask(repoRoot: string, input: CreateTaskRequest): Promise<TaskRecord>;
-  listTasks(repoRoot: string): Promise<TaskRecord[]>;
-  loadTask(repoRoot: string, taskSlug: string): Promise<TaskRecord>;
-  saveTask(repoRoot: string, task: TaskRecord): Promise<void>;
-  updateTaskStatus(repoRoot: string, taskSlug: string, status: TaskStatus): Promise<TaskRecord>;
-}
+Responsibilities:
 
-export interface TaskServiceDeps {
-  fs: FileSystemAdapter;
-  git: GitAdapter;
-  artifactService: ArtifactService;
-  projectService: Pick<ProjectService, "loadConfig">;
-}
+- create task
+- list tasks
+- load task
+- save task
+- update task status
 
-export function createTaskService(deps: TaskServiceDeps): TaskService;
+Task files:
+
+```text
+.vcm/tasks/<task>.json
 ```
 
-### 10.3 `src/backend/services/artifact-service.ts`
-
-职责：
-
-- 创建 handoff 目录结构。
-- 创建 artifact 模板。
-- 读写 role command。
-- 检查 artifact 状态。
-- 追加 raw logs。
-
-导出定义：
-
-```ts
-export interface ArtifactService {
-  getHandoffPaths(repoRoot: string, handoffDir: string): HandoffPaths;
-  ensureHandoffStructure(input: EnsureHandoffStructureInput): Promise<HandoffPaths>;
-  createArtifactTemplates(input: CreateArtifactTemplatesInput): Promise<string[]>;
-  listArtifacts(input: ListArtifactsInput): Promise<ArtifactSummary>;
-  readArtifact(input: ReadArtifactInput): Promise<string>;
-  readRoleCommand(input: ReadRoleCommandInput): Promise<string>;
-  saveRoleCommand(input: SaveRoleCommandInput): Promise<void>;
-  appendRoleLog(input: AppendRoleLogInput): Promise<void>;
-}
-
-export interface EnsureHandoffStructureInput {
-  repoRoot: string;
-  taskSlug: string;
-  handoffDir: string;
-}
-
-export interface CreateArtifactTemplatesInput {
-  repoRoot: string;
-  taskSlug: string;
-  handoffDir: string;
-  overwrite?: boolean;
-}
-
-export interface ListArtifactsInput {
-  repoRoot: string;
-  taskSlug: string;
-  handoffDir: string;
-}
-
-export interface ReadArtifactInput {
-  repoRoot: string;
-  path: string;
-}
-
-export interface ReadRoleCommandInput {
-  repoRoot: string;
-  handoffDir: string;
-  role: DispatchableRole;
-}
-
-export interface SaveRoleCommandInput {
-  repoRoot: string;
-  handoffDir: string;
-  role: DispatchableRole;
-  content: string;
-}
-
-export interface AppendRoleLogInput {
-  repoRoot: string;
-  handoffDir: string;
-  role: RoleName;
-  content: string;
-}
-
-export function createArtifactService(fs: FileSystemAdapter): ArtifactService;
+### `src/backend/services/artifact-service.ts`
+
+Exports:
+
+- `ArtifactService`
+- input interfaces for handoff, artifacts, role commands, logs
+- `createArtifactService(fs)`
+
+Responsibilities:
+
+- compute handoff paths
+- create handoff directory structure
+- create artifact templates
+- list artifact checks
+- read artifacts
+- read/save role commands
+- append role logs
+
+Primary role command path:
+
+```text
+.ai/handoffs/<task>/role-commands/<role>.md
 ```
 
-### 10.4 `src/backend/services/session-service.ts`
-
-职责：
-
-- 启动、停止、重启 role session。
-- 同步 runtime、registry 和 `.vcm/sessions` metadata。
-- 首次启动生成 `claudeSessionId`，并使用 `claude --agent <role> --session-id <uuid>`。
-- 异常中断或 backend 重启后，从 `.vcm/sessions/<task-slug>.json` 恢复 role metadata。
-- Resume 使用 `claude --agent <role> --resume <claudeSessionId>` 创建新的 embedded terminal。
-- Restart 优先复用已有 `claudeSessionId`，避免丢失长任务上下文。
-
-导出定义：
-
-```ts
-export interface SessionService {
-  listSessions(repoRoot: string, taskSlug: string): Promise<RoleSessionRecord[]>;
-  startRoleSession(input: StartRoleSessionInput): Promise<RoleSessionRecord>;
-  resumeRoleSession(input: StartRoleSessionInput): Promise<RoleSessionRecord>;
-  stopRoleSession(input: StopRoleSessionInput): Promise<RoleSessionRecord>;
-  restartRoleSession(input: RestartRoleSessionInput): Promise<RoleSessionRecord>;
-  getRoleSession(repoRoot: string, taskSlug: string, role: RoleName): Promise<RoleSessionRecord | null>;
-}
-
-export interface StartRoleSessionInput {
-  repoRoot: string;
-  taskSlug: string;
-  role: RoleName;
-  cols?: number;
-  rows?: number;
-  permissionMode?: ClaudePermissionMode;
-}
-
-export interface StopRoleSessionInput {
-  repoRoot: string;
-  taskSlug: string;
-  role: RoleName;
-}
-
-export interface RestartRoleSessionInput extends StopRoleSessionInput {
-  cols?: number;
-  rows?: number;
-}
-
-export interface SessionServiceDeps {
-  claude: ClaudeAdapter;
-  runtime: TerminalRuntime;
-  registry: SessionRegistry;
-  taskService: TaskService;
-  artifactService: ArtifactService;
-  projectService: Pick<ProjectService, "loadConfig">;
-}
-
-export function createSessionService(deps: SessionServiceDeps): SessionService;
+Legacy fallback:
+
+```text
+.ai/handoffs/<task>/role-commands/<role>-command.md
 ```
 
-### 10.5 `src/backend/services/command-dispatcher.ts`
+### `src/backend/services/status-service.ts`
 
-职责：
+Exports:
 
-- 从 role command artifact 读取命令。
-- 将短指令写入目标 role terminal。
-- 记录 dispatch event。
+- `StatusService`
+- `StatusServiceDeps`
+- `createStatusService(deps)`
 
-导出定义：
+Responsibilities:
 
-```ts
-export interface CommandDispatcher {
-  dispatchRoleCommand(input: DispatchRoleCommandInput): Promise<DispatchRoleCommandResult>;
-}
+- assemble `TaskStatusReport`
+- list sessions
+- list artifact checks
+- compute workflow report
 
-export interface DispatchRoleCommandInput {
-  repoRoot: string;
-  taskSlug: string;
-  role: DispatchableRole;
-}
+### `src/backend/services/session-service.ts`
 
-export interface DispatchRoleCommandResult {
-  taskSlug: string;
-  role: DispatchableRole;
-  commandPath: string;
-  instruction: string;
-  dispatchedAt: string;
-}
+Exports:
 
-export interface CommandDispatcherDeps {
-  runtime: TerminalRuntime;
-  sessionService: SessionService;
-  taskService: TaskService;
-  artifactService: ArtifactService;
-}
+- `SessionService`
+- `SessionServiceDeps`
+- `createSessionService(deps)`
 
-export function createCommandDispatcher(deps: CommandDispatcherDeps): CommandDispatcher;
-```
+Responsibilities:
 
-实现规则：
+- start role session
+- resume role session
+- restart role session
+- stop role session
+- get role session
+- list role sessions
 
-- role command 文件缺失时失败。
-- role command 文件为空时失败。
-- role command 文件仍是模板或包含 `TBD` / `status: draft` 时失败。
-- role command 必须使用当前 VCM task 的 canonical path：`.ai/handoffs/<task-slug>/role-commands/<role>.md`。
-- Project Manager 启动时，backend 必须向 session 注入 task context，明确 `taskSlug`、`handoffDir` 和三个 role command 路径。
-- 目标 role session 未运行时失败并提示启动 session。
-- `instruction` 必须是短文本：
-- 只有用户通过 GUI 点击 Send Command 时才调用 dispatch。
-- dispatch 不解析 Claude Code 输出，不自动重试，不自动确认权限。
-- dispatch 成功后只记录 event，不继续触发下一个 role。
+Persistence:
 
 ```text
-Please read and execute the role command at: <path>
+.vcm/sessions/<task>.json
 ```
 
-### 10.6 `src/backend/services/status-service.ts`
+Environment passed to Claude Code:
 
-职责：
+- `VCM_API_URL`
+- `VCM_CTL_COMMAND`
+- `VCM_TASK_SLUG`
+- `VCM_ROLE`
 
-- 汇总 task、sessions、artifacts、events。
+### `src/backend/services/message-service.ts`
 
-导出定义：
+Exports:
 
-```ts
-export interface TaskStatusReport {
-  task: TaskRecord;
-  sessions: RoleSessionRecord[];
-  artifacts: ArtifactSummary;
-  warnings: string[];
-}
+- `MessageService`
+- input interfaces
+- `createMessageService(deps)`
 
-export interface StatusService {
-  getTaskStatus(repoRoot: string, taskSlug: string): Promise<TaskStatusReport>;
-}
+Responsibilities:
 
-export interface StatusServiceDeps {
-  taskService: TaskService;
-  sessionService: SessionService;
-  artifactService: ArtifactService;
-}
+- list messages
+- send messages
+- stage/approve/reject messages
+- get/update orchestration state
+- enforce message policy
+- persist message snapshots
+- write message body markdown
+- write staged or delivered messages to target terminal
 
-export function createStatusService(deps: StatusServiceDeps): StatusService;
-```
+### `src/backend/services/command-dispatcher.ts`
 
-## 11. Backend API 层
+Exports:
 
-### 11.1 `src/backend/server.ts`
+- `CommandDispatcher`
+- `DispatchRoleCommandInput`
+- `CommandDispatcherDeps`
+- `createCommandDispatcher(deps)`
 
-职责：
+Compatibility role-command dispatch only. Preferred orchestration is `MessageService` plus `vcmctl`.
 
-- 创建 Fastify server。
-- 注册 API routes。
-- 注册 WebSocket terminal bridge。
-- Serve frontend assets。
+### `src/backend/services/harness-service.ts`
 
-导出定义：
+Exports:
 
-```ts
-export interface CreateServerOptions {
-  host?: string;
-  port?: number;
-  staticDir?: string;
-  dev?: boolean;
-}
+- `HarnessService`
+- `HarnessServiceDeps`
+- `VCM_HARNESS_VERSION`
+- `createHarnessService(deps)`
 
-export interface ServerDeps {
-  projectService: ProjectService;
-  taskService: TaskService;
-  sessionService: SessionService;
-  artifactService: ArtifactService;
-  commandDispatcher: CommandDispatcher;
-  statusService: StatusService;
-  runtime: TerminalRuntime;
-}
+Responsibilities:
 
-export function createServer(deps: ServerDeps, options?: CreateServerOptions): Promise<FastifyInstance>;
-export async function startServer(options?: CreateServerOptions): Promise<{ url: string; close(): Promise<void> }>;
-```
+- inspect harness files
+- plan create/insert/update/ok
+- apply VCM managed blocks
+- preserve user content outside managed blocks
+
+### `src/backend/services/app-settings-service.ts`
 
-### 11.2 `src/backend/api/project-routes.ts`
+Exports:
 
-Routes：
+- `StoredTranslationConfig`
+- `AppSettingsFile`
+- `AppSettingsService`
+- `AppSettingsServiceDeps`
+- `createAppSettingsService(deps)`
+
+Storage:
 
 ```text
-GET  /api/health
-POST /api/projects/connect
-GET  /api/projects/current
-GET  /api/projects/harness
+~/.vcm/settings.json
 ```
 
-导出定义：
-
-```ts
-export function registerProjectRoutes(app: FastifyInstance, deps: ProjectRouteDeps): void;
+Also migrates legacy:
 
-export interface ProjectRouteDeps {
-  projectService: ProjectService;
-}
+```text
+~/.vibe-coding-master/settings.json
+~/.vibe-coding-master/translation.json
 ```
 
-### 11.3 `src/backend/api/task-routes.ts`
+### `src/backend/services/translation-prompts.ts`
 
-Routes：
+Exports:
 
-```text
-GET  /api/tasks
-POST /api/tasks
-GET  /api/tasks/:taskSlug
-GET  /api/tasks/:taskSlug/status
-```
+- `TranslationPromptInput`
+- `BuiltTranslationPrompt`
+- `buildTranslationPrompt(input)`
+- `getTranslationPromptKey(input)`
+- `getBaseTranslationPrompt(key, settings)`
+- `resolveTranslationSystemPrompt(key, settings)`
+- `getTranslationPromptPreviews(settings)`
 
-导出定义：
+Owns default prompts and user overrides.
 
-```ts
-export function registerTaskRoutes(app: FastifyInstance, deps: TaskRouteDeps): void;
+### `src/backend/services/translation-queue.ts`
 
-export interface TaskRouteDeps {
-  projectService: ProjectService;
-  taskService: TaskService;
-  statusService: StatusService;
-}
-```
+Exports:
 
-### 11.4 `src/backend/api/session-routes.ts`
+- `SerialTranslationQueue`
+- `TranslationQueueRegistry`
+- `createSerialTranslationQueue()`
+- `createTranslationQueueRegistry()`
 
-Routes：
+Ensures translations for one session run serially.
 
-```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/dispatch
-```
+### `src/backend/services/claude-transcript-service.ts`
 
-导出定义：
+Exports:
 
-```ts
-export function registerSessionRoutes(app: FastifyInstance, deps: SessionRouteDeps): void;
+- transcript event types
+- `ClaudeTranscriptService`
+- `TranscriptTail`
+- `createClaudeTranscriptService()`
+- `resolveExistingClaudeTranscriptPath(session)`
+- `findClaudeTranscriptPathBySessionId(claudeSessionId)`
+- `claudeProjectsRoot()`
+- `projectHash(projectDir)`
+- `projectsTranscriptDir(projectDir)`
+- `claudeTranscriptPath(projectDir, claudeSessionId)`
+- `parseAssistantContent(line)`
 
-export interface SessionRouteDeps {
-  projectService: ProjectService;
-  sessionService: SessionService;
-  commandDispatcher: CommandDispatcher;
-}
-```
+Responsibilities:
 
-### 11.5 `src/backend/api/artifact-routes.ts`
+- tail Claude JSONL transcript files
+- resolve transcript path after start/resume/restart
+- parse assistant messages, tool uses, tool results, questions, todos, and agent calls
 
-Routes：
+### `src/backend/services/translation-service.ts`
 
-```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
-```
+Exports:
 
-导出定义：
+- `TranslationService`
+- `TranslateUserInputServiceInput`
+- `SendTranslatedInputServiceInput`
+- `TranslationEventListener`
+- `TranslationServiceDeps`
+- `createTranslationService(deps)`
+- `formatTerminalSubmit(text)`
 
-```ts
-export function registerArtifactRoutes(app: FastifyInstance, deps: ArtifactRouteDeps): void;
+Responsibilities:
 
-export interface ArtifactRouteDeps {
-  projectService: ProjectService;
-  taskService: TaskService;
-  artifactService: ArtifactService;
-}
-```
+- load/update translation settings
+- expose prompt previews
+- test provider
+- translate user input
+- send English text to active terminal
+- subscribe to session translation events
+- clear session entries
+- retry failed output translation
+- subscribe to Claude transcript service
+- translate prose output and preserve tool output
 
-### 11.6 `src/backend/ws/terminal-ws.ts`
+## 9. Backend API
 
-职责：
+### `src/backend/server.ts`
 
-- 处理 `/ws/tasks/:taskSlug/sessions/:role`。
-- 将 runtime events 推送给前端。
-- 将前端 input/resize 写回 runtime。
+Exports:
 
-导出定义：
+- `CreateServerOptions`
+- `ServerDeps`
+- `createServer(deps, options)`
+- `startServer(options)`
+- `CreateDefaultServerDepsOptions`
+- `createDefaultServerDeps(options)`
+- `getDefaultStaticDir()`
 
-```ts
-export interface TerminalWsDeps {
-  projectService: ProjectService;
-  sessionService: SessionService;
-  runtime: TerminalRuntime;
-}
+Registers all routes and WebSockets.
 
-export function registerTerminalWebSocket(server: FastifyInstance, deps: TerminalWsDeps): void;
+### Route files
 
-export function parseClientTerminalMessage(raw: string): ClientTerminalMessage;
-export function serializeServerTerminalMessage(message: ServerTerminalMessage): string;
-```
+- `src/backend/api/project-routes.ts`: health, recent paths, connect/current project
+- `src/backend/api/harness-routes.ts`: harness status/apply
+- `src/backend/api/task-routes.ts`: tasks and task status
+- `src/backend/api/session-routes.ts`: session lifecycle and dispatch compatibility endpoint
+- `src/backend/api/artifact-routes.ts`: artifact, role command, and log reads/writes
+- `src/backend/api/message-routes.ts`: messages and orchestration
+- `src/backend/api/translation-routes.ts`: settings, prompt previews, provider test, input/send, clear/retry
 
-## 12. Frontend 层
+### WebSocket files
 
-### 12.1 `src/frontend/main.tsx`
+- `src/backend/ws/terminal-ws.ts`
+- `src/backend/ws/translation-ws.ts`
 
-职责：
+Terminal WebSocket forwards PTY output/input/resize.
 
-- 挂载 React app。
+Translation WebSocket subscribes to translation entries/status for a runtime session id.
 
-导出定义：
+## 10. Backend Templates
 
-```ts
-export function bootstrap(): void;
-```
+### `src/backend/templates/handoff.ts`
 
-### 12.2 `src/frontend/app.tsx`
+Exports:
 
-职责：
+- `renderArchitecturePlanTemplate(taskSlug)`
+- `renderImplementationLogTemplate(taskSlug)`
+- `renderValidationLogTemplate(taskSlug)`
+- `renderReviewReportTemplate(taskSlug)`
+- `renderDocsSyncReportTemplate(taskSlug)`
 
-- 应用顶层路由和布局。
+### `src/backend/templates/role-command.ts`
 
-导出定义：
+Exports:
 
-```tsx
-export function App(): JSX.Element;
-```
+- `renderRoleCommandTemplate(taskSlug, role)`
 
-### 12.3 `src/frontend/state/api-client.ts`
-
-职责：
-
-- 封装 REST API。
-
-导出定义：
-
-```ts
-export interface ApiClient {
-  connectProject(input: ConnectProjectRequest): Promise<ProjectSummary>;
-  getCurrentProject(): Promise<ProjectSummary | null>;
-  listTasks(): Promise<TaskRecord[]>;
-  createTask(input: CreateTaskRequest): Promise<TaskRecord>;
-  getTask(taskSlug: string): Promise<TaskRecord>;
-  getTaskStatus(taskSlug: string): Promise<TaskStatusReport>;
-  listSessions(taskSlug: string): Promise<RoleSessionRecord[]>;
-  startRoleSession(taskSlug: string, role: RoleName, input?: StartRoleSessionRequest): Promise<RoleSessionRecord>;
-  stopRoleSession(taskSlug: string, role: RoleName): Promise<RoleSessionRecord>;
-  restartRoleSession(taskSlug: string, role: RoleName, input?: StartRoleSessionRequest): Promise<RoleSessionRecord>;
-  dispatchRoleCommand(taskSlug: string, role: DispatchableRole): Promise<DispatchRoleCommandResult>;
-  listArtifacts(taskSlug: string): Promise<ArtifactSummary>;
-  readRoleCommand(taskSlug: string, role: DispatchableRole): Promise<string>;
-  saveRoleCommand(taskSlug: string, role: DispatchableRole, content: string): Promise<void>;
-  readLog(taskSlug: string, role: RoleName): Promise<string>;
-}
-
-export function createApiClient(baseUrl?: string): ApiClient;
-```
+### `src/backend/templates/message-envelope.ts`
 
-### 12.4 `src/frontend/terminal/terminal-client.ts`
+Exports:
 
-职责：
+- `renderMessageEnvelope(message)`
+- `renderManualStagePrompt(message)`
 
-- 封装 terminal WebSocket。
+Manual stage prompt does not submit Enter.
 
-导出定义：
+Auto delivery envelope is submitted with Enter.
 
-```ts
-export interface TerminalClient {
-  connect(): void;
-  disconnect(): void;
-  sendInput(data: string): void;
-  resize(cols: number, rows: number): void;
-  onMessage(listener: (message: ServerTerminalMessage) => void): Unsubscribe;
-}
+### Harness templates
 
-export function createTerminalClient(input: CreateTerminalClientInput): TerminalClient;
+- `src/backend/templates/harness/claude-root.ts`
+- `src/backend/templates/harness/project-manager-agent.ts`
+- `src/backend/templates/harness/architect-agent.ts`
+- `src/backend/templates/harness/coder-agent.ts`
+- `src/backend/templates/harness/reviewer-agent.ts`
 
-export interface CreateTerminalClientInput {
-  taskSlug: string;
-  role: RoleName;
-  baseUrl?: string;
-}
-```
+Each exports one render function for VCM managed rules.
 
-### 12.5 `src/frontend/terminal/xterm-view.tsx`
+## 11. Frontend State And API Client
 
-职责：
+### `src/frontend/state/api-client.ts`
 
-- 渲染 xterm.js。
-- 连接 TerminalClient。
-- 处理 fit、resize、input、output。
+Central browser API wrapper.
 
-导出定义：
+It calls:
 
-```tsx
-export interface XtermViewProps {
-  taskSlug: string;
-  role: RoleName;
-  active: boolean;
-}
+- project endpoints
+- harness endpoints
+- task endpoints
+- session endpoints
+- artifact endpoints
+- message endpoints
+- orchestration endpoints
+- translation endpoints
 
-export function XtermView(props: XtermViewProps): JSX.Element;
-```
+### `src/frontend/state/app-store.ts`
 
-### 12.6 `src/frontend/components/session-console.tsx`
+Exports:
 
-职责：
+- `AppStateSnapshot`
+- `selectActiveTask(tasks, activeTaskSlug)`
 
-- 展示单个 role session。
-- 在 Start / Restart 上方提供三档权限模式选择。
-- 未启动时显示 Start。
-- 已启动时显示 terminal。
+### `src/frontend/state/session-store.ts`
 
-导出定义：
+Exports:
 
-```tsx
-export interface SessionConsoleProps {
-  taskSlug: string;
-  role: RoleName;
-  session?: RoleSessionRecord;
-  active: boolean;
-  permissionMode: ClaudePermissionMode;
-  onPermissionModeChange(mode: ClaudePermissionMode): void;
-  onStart(role: RoleName): Promise<void>;
-  onResume(role: RoleName): Promise<void>;
-  onStop(role: RoleName): Promise<void>;
-  onRestart(role: RoleName): Promise<void>;
-}
+- `getSessionForRole(sessions, role)`
 
-export function SessionConsole(props: SessionConsoleProps): JSX.Element;
-```
+## 12. Frontend Routes
 
-### 12.7 `src/frontend/components/role-session-tabs.tsx`
+### `src/frontend/app.tsx`
 
-职责：
+Exports:
 
-- 渲染 PM / Architect / Coder / Reviewer tabs。
-- 展示 status badge。
+- `App()`
 
-导出定义：
+Responsibilities:
 
-```tsx
-export interface RoleSessionTabsProps {
-  activeRole: RoleName;
-  sessions: RoleSessionRecord[];
-  onRoleChange(role: RoleName): void;
-}
+- own top-level app state
+- load current project and recent paths on startup
+- load tasks and harness status after connect
+- pass sidebar props to `ProjectDashboard`
+- pass task props to `TaskWorkspace`
+- keep active workflow/messages/orchestration/events synchronized by task
 
-export function RoleSessionTabs(props: RoleSessionTabsProps): JSX.Element;
-```
+### `src/frontend/routes/project-dashboard.tsx`
 
-### 12.8 `src/frontend/components/event-log.tsx`
+Exports:
 
-职责：
+- `ProjectDashboardProps`
+- `ProjectDashboard(props)`
 
-- 展示产品级事件摘要。
+Responsibilities:
 
-导出定义：
+- collapsible sidebar
+- repository connect form
+- repository summary
+- workflow panel
+- settings section
+- messages modal
+- events modal
+- harness panel
+- one-field task creation
+- task navigation
 
-```tsx
-export interface EventLogProps {
-  events: TerminalEvent[];
-}
+### `src/frontend/routes/task-workspace.tsx`
 
-export function EventLog(props: EventLogProps): JSX.Element;
-```
+Exports:
 
-### 12.9 `src/frontend/routes/project-dashboard.tsx`
+- `TaskWorkspaceProps`
+- `TaskWorkspace(props)`
 
-职责：
+Responsibilities:
 
-- 展示 repo 连接表单、任务列表和 harness health。
+- task header with role tabs and refresh
+- status/message/orchestration refresh
+- periodic polling
+- session lifecycle actions
+- per-role permission state
+- runtime event collection for sidebar Events modal
 
-导出定义：
+## 13. Frontend Components
 
-```tsx
-export function ProjectDashboard(): JSX.Element;
-```
+### `src/frontend/components/app-shell.tsx`
 
-### 12.10 `src/frontend/routes/task-workspace.tsx`
+Exports:
 
-职责：
+- `AppShellProps`
+- `AppShell({ sidebar, children })`
 
-- 任务运行时主界面。
-- 组合 TaskNav、RoleSessionTabs、SessionConsole、EventLog。
-- 不渲染独立 ArtifactPanel；handoff files 保留在任务目录中。
+Two-column page shell.
 
-导出定义：
+### `src/frontend/components/repo-connect-form.tsx`
 
-```tsx
-export interface TaskWorkspaceProps {
-  taskSlug: string;
-}
+Exports:
 
-export function TaskWorkspace(props: TaskWorkspaceProps): JSX.Element;
-```
+- `RepoConnectFormProps`
+- `RepoConnectForm(props)`
 
-## 13. Templates
+Layout:
 
-### 13.1 `src/backend/templates/handoff.ts`
+- path input row
+- recent select plus connect button row
 
-导出定义：
+### `src/frontend/components/harness-panel.tsx`
 
-```ts
-export function renderArchitecturePlanTemplate(taskSlug: string): string;
-export function renderImplementationLogTemplate(taskSlug: string): string;
-export function renderValidationLogTemplate(taskSlug: string): string;
-export function renderReviewReportTemplate(taskSlug: string): string;
-```
+Exports:
 
-### 13.2 `src/backend/templates/role-command.ts`
+- `HarnessPanelProps`
+- `HarnessPanel(props)`
 
-导出定义：
+Shows harness status and install/update action.
 
-```ts
-export function renderRoleCommandTemplate(taskSlug: string, role: DispatchableRole): string;
-export function renderDispatchInstruction(commandPath: string): string;
-```
+### `src/frontend/components/workflow-panel.tsx`
 
-`renderDispatchInstruction` 必须返回单行短指令：
+Exports:
 
-```text
-Please read and execute the role command at: <commandPath>
-```
+- `WorkflowPanelProps`
+- `WorkflowPanel({ workflow })`
 
-## 14. 核心调用链
+Renders the sidebar workflow steps.
 
-### 14.1 启动应用
+### `src/frontend/components/message-timeline.tsx`
 
-```text
-main
-  -> startServer
-  -> create services/adapters/runtime
-  -> register REST routes
-  -> register terminal WebSocket
-  -> serve frontend
-```
+Exports:
 
-### 14.2 连接 repo
+- `MessageTimelineProps`
+- `getMessageCounts(messages)`
+- `MessageTimeline(props)`
 
-```text
-ProjectDashboard
-  -> api.connectProject
-  -> POST /api/projects/connect
-  -> projectService.connectProject
-  -> git.getRepoRoot
-  -> git.getCurrentBranch
-  -> git.isDirty
-  -> claude.isAvailable
-  -> fs.writeJsonAtomic(.vcm/config.json)
-```
+Used inside the Messages modal. Can show stage/reject/open-role actions.
 
-### 14.3 创建任务
+### `src/frontend/components/event-log.tsx`
 
-```text
-ProjectDashboard / TaskWorkspace
-  -> api.createTask
-  -> POST /api/tasks
-  -> taskService.createTask
-  -> assertValidTaskSlug
-  -> artifactService.ensureHandoffStructure
-  -> artifactService.createArtifactTemplates
-  -> fs.writeJsonAtomic(.vcm/tasks/<task-slug>.json)
-```
+Exports:
 
-### 14.4 启动 role session
+- `EventLogProps`
+- `EventLog(props)`
 
-```text
-SessionConsole Start
-  -> api.startRoleSession
-  -> POST /api/tasks/:taskSlug/sessions/:role/start
-  -> sessionService.startRoleSession
-  -> claude.buildRoleStartCommand
-  -> runtime.createSession
-  -> node-pty spawn
-  -> registry.upsert
-  -> write session metadata
-```
+Used inside the Events modal.
 
-### 14.5 Terminal 输入输出
+### `src/frontend/components/task-nav.tsx`
 
-```text
-XtermView
-  -> TerminalClient WebSocket
-  -> input message
-  -> terminal-ws
-  -> runtime.write
-  -> node-pty
-  -> output event
-  -> append role log
-  -> WebSocket output message
-  -> xterm.write
-```
+Exports:
 
-### 14.6 下发 role command
+- `TaskNavProps`
+- `TaskNav(props)`
 
-```text
-Role toolbar Send Command
-  -> api.dispatchRoleCommand
-  -> POST /api/tasks/:taskSlug/sessions/:role/dispatch
-  -> commandDispatcher.dispatchRoleCommand
-  -> artifactService.readRoleCommand
-  -> sessionService.getRoleSession
-  -> runtime.write(short instruction)
-  -> registry event
-```
+Task list in sidebar.
 
-### 14.7 Handoff files
+### `src/frontend/components/role-session-tabs.tsx`
 
-V1 主界面不展示 artifact 状态。handoff files 和 role commands 仍由 backend templates / services 管理，供 Claude Code sessions 和 dispatch 流程使用。
+Exports:
 
-## 15. 测试计划
+- `RoleSessionTabsProps`
+- `RoleSessionTabs(props)`
 
-### 15.1 Unit Tests
+Header role tabs with status badges.
 
-`tests/unit/shared/slug-check.test.ts`
+### `src/frontend/components/session-console.tsx`
 
-- accepts valid task slugs。
-- rejects uppercase、underscore、space、path traversal。
-- suggests normalized slugs。
+Exports:
 
-`tests/unit/shared/artifact-check.test.ts`
+- `SessionConsoleProps`
+- `SessionConsole(props)`
 
-- parses headings。
-- detects missing headings。
-- validates handoff templates。
-- validates `validation-log` not-run reason。
+Role console and translation split.
 
-`tests/unit/backend/artifact-service.test.ts`
+### `src/frontend/components/session-toolbar.tsx`
 
-- creates handoff directory。
-- creates role command files。
-- does not overwrite existing files by default。
-- returns artifact summary statuses。
+Exports:
 
-`tests/unit/backend/command-dispatcher.test.ts`
+- `SessionToolbarProps`
+- `SessionToolbar(props)`
 
-- rejects missing command。
-- rejects empty command。
-- rejects not-started target session。
-- writes only short instruction to runtime。
+Renders permission select and session lifecycle buttons.
 
-`tests/unit/backend/session-registry.test.ts`
+There is no visible primary `Send Command` button in the current toolbar. Role-command dispatch remains backend compatibility.
 
-- upserts sessions。
-- finds by task + role。
-- updates status。
-- removes sessions。
+### `src/frontend/components/translation-panel.tsx`
 
-`tests/unit/frontend/api-client.test.ts`
+Exports:
 
-- unwraps successful API responses。
-- throws useful errors for API failures。
+- `TranslationPanelProps`
+- `TranslationPanel(props)`
 
-`tests/unit/frontend/terminal-client.test.ts`
+Renders output translations, settings actions, auto-send toggle, and composer.
 
-- serializes input and resize messages。
-- dispatches output/status/exit messages to listeners。
+Important current behavior:
 
-### 15.2 Integration Tests
+- panel-level status only
+- no per-entry status label
+- no `Original` buttons
+- tool output is preserved, dim, one-line
+- prose source is replaced by translated text after completion
+- no separate translated-English textarea
 
-`tests/integration/api/project-routes.test.ts`
+### `src/frontend/components/translation-settings-modal.tsx`
 
-- connects repo fixture。
-- writes `.vcm/config.json`。
-- returns branch and dirty warning。
+Exports:
 
-`tests/integration/api/task-routes.test.ts`
+- `TranslationSettingsModalProps`
+- `TranslationSettingsModal(props)`
 
-- creates task。
-- writes `.vcm/tasks/<task-slug>.json`。
-- creates handoff artifacts。
+Settings:
 
-`tests/integration/runtime/node-pty-runtime.test.ts`
+- enable translation
+- base URL
+- API key as text input
+- model
+- target language
+- input mode
+- context
+- translate output
+- translate user input
+- timeout
+- temperature
+- prompt slot overrides
+- provider test
 
-- starts a simple shell command fixture。
-- streams output。
-- writes log file。
-- handles exit。
+### `src/frontend/components/status-badge.tsx`
 
-`tests/integration/api/session-routes.test.ts`
+Exports:
 
-- starts role session with fake runtime。
-- stops role session。
-- restarts role session。
-- dispatches role command.
+- `StatusBadgeProps`
+- `StatusBadge(props)`
 
-### 15.3 E2E Tests
+### `src/frontend/terminal/xterm-view.tsx`
 
-`tests/e2e/task-workspace.spec.ts`
+Renders `xterm.js`, connects to terminal WebSocket, sends input and resize, and preserves terminal colors.
 
-- open GUI。
-- connect temp repo。
-- create task。
-- see Task Workspace。
-- start fake project-manager session。
-- see terminal output。
-- switch to architect tab。
-- see Start button。
-- verify the main workspace has no right-side artifact panel。
+### `src/frontend/terminal/terminal-client.ts`
 
-V1 e2e 可以使用 fake Claude command，避免真实消耗 Claude Code tokens。
+Terminal WebSocket client wrapper.
 
-### 15.4 Manual Smoke Test
+## 14. UI State Details
 
-在真实 repo 中执行：
+Sidebar:
 
-```text
-npm install
-npm run dev
-open http://localhost:5173
-Select repo
-Create demo-task
-Start project-manager
-Start architect
-Type in PM terminal
-Send architect command
-Verify logs/architect.log
-Verify artifact status
-Restart coder
-Refresh browser
-Verify session state recovers
-```
+- all groups default collapsed
+- `Repository Path` default open only when no task is selected
+- `Settings` includes `Messages`, `Events`, and `Auto orchestration`
 
-## 16. 实施里程碑
+Task workspace:
 
-### Milestone 1: Project Reshape and Local GUI Shell
+- role tabs in the first header row
+- workflow is not in main workspace
+- messages/events are not in main workspace
+- active role console fills available space
 
-文件：
+Translation:
 
-- `package.json`
-- `tsconfig.json`
-- `tsconfig.node.json`
-- `vite.config.ts`
-- `src/main.ts`
-- `src/backend/server.ts`
-- `src/frontend/main.tsx`
-- `src/frontend/app.tsx`
-- `src/frontend/routes/project-dashboard.tsx`
+- top role toolbar button label is `✅ Translate` when on and `× Translate` when off
+- translation panel `Auto-send` label is `✅ Auto-send` when on and `× Auto-send` when off
+- panel uses terminal-like dark styling
+- composer height is compact
+- `Enter` translates/sends, `Shift+Enter` inserts newline
 
-验收：
+## 15. Data Persistence Summary
 
-- `npm run dev` 启动 backend + frontend。
-- 浏览器打开 Project Dashboard。
-- `/api/health` 返回 ok。
+App settings:
 
-### Milestone 2: Shared Types, Validation, and Artifacts
+```text
+~/.vcm/settings.json
+```
 
-文件：
+Project config:
 
-- `src/shared/types/*.ts`
-- `src/shared/validation/*.ts`
-- `src/backend/templates/*.ts`
-- `src/backend/services/artifact-service.ts`
-- `src/backend/services/task-service.ts`
-- `src/backend/api/task-routes.ts`
+```text
+.vcm/config.json
+```
 
-验收：
+Task state:
 
-- GUI 可以创建 task。
-- `.ai/handoffs/<task-slug>/` 被创建。
-- Handoff artifacts 在任务目录中被创建。
+```text
+.vcm/tasks/<task>.json
+```
 
-### Milestone 3: Repo Connect and Project Service
+Session state:
 
-文件：
+```text
+.vcm/sessions/<task>.json
+```
 
-- `src/backend/adapters/*.ts`
-- `src/backend/services/project-service.ts`
-- `src/backend/validation/environment-check.ts`
-- `src/backend/api/project-routes.ts`
-- `src/frontend/components/repo-connect-form.tsx`
+Messages:
 
-验收：
+```text
+.vcm/messages/<task>.jsonl
+.ai/handoffs/<task>/messages/<message-id>.md
+```
 
-- GUI 可以选择/输入 repo path。
-- backend 检查 Git repo 和 Claude Code。
-- `.vcm/config.json` 被创建。
-- main/master 和 dirty state 显示 warning。
+Orchestration:
 
-### Milestone 4: Embedded Terminal Runtime
+```text
+.vcm/orchestration/<task>.json
+```
 
-文件：
+Handoff artifacts:
 
-- `src/backend/runtime/terminal-runtime.ts`
-- `src/backend/runtime/node-pty-runtime.ts`
-- `src/backend/runtime/session-registry.ts`
-- `src/backend/ws/terminal-ws.ts`
-- `src/frontend/terminal/terminal-client.ts`
-- `src/frontend/terminal/xterm-view.tsx`
-- `src/frontend/components/session-console.tsx`
-
-验收：
-
-- GUI 可以启动 fake role session。
-- xterm.js 显示 output。
-- 用户输入能写入 backend runtime。
-- output 写入 raw log。
-- resize 工作。
-
-### Milestone 5: Role Session Cockpit
-
-文件：
-
-- `src/backend/services/session-service.ts`
-- `src/backend/api/session-routes.ts`
-- `src/frontend/components/role-session-tabs.tsx`
-- `src/frontend/components/session-toolbar.tsx`
-- `src/frontend/components/status-badge.tsx`
-- `src/frontend/routes/task-workspace.tsx`
-- `src/frontend/state/session-store.ts`
-
-验收：
-
-- PM / Architect / Coder / Reviewer tabs 可切换。
-- 每个 role 可 start / stop / restart。
-- 状态 badge 正确显示。
-- 页面刷新后可重新加载 task/session 状态。
-
-### Milestone 6: GUI Role Command Dispatch
-
-文件：
-
-- `src/backend/services/command-dispatcher.ts`
-- `src/frontend/components/event-log.tsx`
-
-验收：
-
-- 用户点击目标 role toolbar 的 Send Command。
-- backend 写入短指令到 architect runtime。
-- dispatch event 出现在 Event Log。
-- 不发送未落盘长 prompt。
-
-### Milestone 7: Acceptance and Hardening
-
-内容：
-
-- unit tests。
-- integration tests。
-- e2e smoke。
-- README 更新。
-- GUI 错误态。
-- empty/missing/incomplete artifact 状态。
-- Claude Code 缺失提示。
-- process crashed 提示。
-
-验收：
-
-- `npm run typecheck` 通过。
-- `npm test` 通过。
-- `npm run build` 通过。
-- `npm run e2e` 通过或有明确 fake Claude 限制说明。
-
-## 17. 最终 V1 验收清单
-
-- [ ] GUI 可以启动。
-- [ ] 用户可以连接本地 Git repo。
-- [ ] GUI 显示 repo path、branch、dirty warning。
-- [ ] 用户可以创建 task workspace。
-- [ ] 系统创建 `.vcm/config.json`。
-- [ ] 系统创建 `.vcm/tasks/<task-slug>.json`。
-- [ ] 系统创建 `.ai/handoffs/<task-slug>/role-commands/`。
-- [ ] 系统创建 `.ai/handoffs/<task-slug>/logs/`。
-- [ ] 系统创建 architecture / implementation / validation / review artifact templates。
-- [ ] GUI 显示 PM / Architect / Coder / Reviewer tabs。
-- [ ] 用户可以启动 project-manager session。
-- [ ] 用户可以启动 architect session。
-- [ ] embedded terminal 可以显示 Claude Code output。
-- [ ] 用户可以直接在 embedded terminal 中输入。
-- [ ] terminal output 被保存到 role log。
-- [ ] 用户可以从 GUI 发送 role command 到目标 role session。
-- [ ] backend 只发送短指令，不粘贴完整长 prompt。
-- [ ] 用户可以 stop / restart role session。
-- [ ] 页面刷新后可以恢复 task/session 可见状态。
-- [ ] Claude Code 缺失时 GUI 有清晰提示。
-- [ ] 进程 crashed/exited 时 GUI 有清晰提示。
-
-## 18. 需要延后到 V2 的接口
-
-V1 文件中可以预留类型或接口，但不实现完整功能：
-
-- `ReviewAdapter`：后续接 Cross-Model Reviewer。
-- `ValidationRunner`：后续自动运行 validation commands。
-- `WorktreeManager`：后续实现 one task -> one branch -> one worktree。
-- `SessionPersistenceService`：后续增强 backend lifecycle、session registry 持久化、raw log replay 和恢复体验。
-- `DesktopShell`：后续用 Electron 或 Tauri 打包。
-- `PermissionHookManager`：后续生成 role-specific Claude Code permission hooks。
-
-V1 的判断标准是：
+```text
+.ai/handoffs/<task>/
+```
+
+Claude transcripts:
 
 ```text
-少做智能判断
-多做状态可见
-少自动修改代码
-多沉淀 artifacts
-少解析终端语义
-多保留 raw logs
-少暴露终端编排细节
-多提供 GUI 操作入口
+~/.claude/projects/<project-hash>/<claude-session-id>.jsonl
+```
+
+## 16. Validation Checklist
+
+Before release or publish:
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run verify:package
 ```
+
+For frontend layout changes, also verify manually:
+
+- connect repository
+- open task
+- role tabs stay in header
+- sidebar sections collapse/open correctly
+- embedded terminal remains visible after role switch
+- translation split is 50/50
+- Messages modal opens from sidebar Settings
+- Events modal opens from sidebar Settings
+- Auto orchestration toggles on/off
+- `Enter` in translation composer translates/sends
+- `Shift+Enter` inserts newline
+
+## 17. V1 Boundaries To Preserve
+
+Do not reintroduce these into V1 docs or UI unless the product direction changes:
+
+- tmux persistence backend
+- CLI-first task management as the main product mode
+- main workspace artifact panel
+- Pause/Resume orchestration buttons in GUI
+- raw PTY output translation
+- translation classifier that drops assistant prose
+- separate translated-English textarea
+- optional title input in New Task
+- `Dirty: yes/no` sidebar label
+- role command dispatch as the primary orchestration path