vibe-coding-master 0.0.12 → 0.0.14

package/docs/v1-architecture-design.md

@@ -69,7 +69,6 @@ Main state lives in `App`:
 - task list
 - active task
 - active role
-- active workflow report
 - active messages
 - active orchestration state
 - task-local event list
@@ -93,8 +92,7 @@ Responsibilities:
 - Render collapsible sidebar sections.
 - Render repository connect form.
 - Render repository summary.
-- Render workflow panel.
-- Render settings section with Theme, Messages, Events, Auto orchestration.
+- Render settings section with Theme, Round alert, Try alert, Messages, and Events.
 - Render harness status/actions.
 - Render task creation form with one task-name field, a `Create worktree and branch` checkbox selected by default, and generated branch/path previews when selected.
 - Render task list.
@@ -110,12 +108,15 @@ File:
 
 Responsibilities:
 
-- Fetch task status, messages, and orchestration state.
+- Fetch task status, messages, orchestration state, and round state.
 - Poll those every three seconds.
 - Render compact header with task title, branch, immutable worktree path, role tabs, Refresh, and red `Close Task`.
 - Hold per-role permission mode selection.
+- Hold task orchestration state and pass its on/off control to the active role console.
+- Detect newly submitted auto-orchestration messages from Claude Code `UserPromptSubmit` hooks and switch the active role tab to the target role.
+- Emit task round state to `App` so completion alerts can be deduplicated and displayed.
 - Render one `SessionConsole` per role but only show the active role.
-- Emit workflow/messages/orchestration/events back to `App` so sidebar stays synchronized.
+- Emit messages/orchestration/events back to `App` so sidebar stays synchronized.
 
 ### SessionConsole
 
@@ -125,6 +126,12 @@ File:
 
 Responsibilities:
 
+- Render role session controls and embedded terminal.
+- Render `Auto orchestration` immediately to the left of `Translate`, using the same compact toggle styling.
+- Render the translation split panel when `Translate` is enabled.
+
+Responsibilities:
+
 - Render role toolbar.
 - Render embedded terminal for running sessions.
 - Render empty/resume state for stopped sessions.
@@ -242,7 +249,7 @@ feature/<taskSlug>
 Worktree path:
 
 ```text
-<baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+<baseRepoRoot>/.claude/worktrees/<taskSlug>
 ```
 
 VCM does not support switching a task to another branch or worktree mode after creation. If the user needs a different branch/worktree choice, they should create a new task.
@@ -258,7 +265,7 @@ worktreePath: undefined
 VCM does not create worktrees by role. All four role sessions for a task share the same task worktree:
 
 ```text
-.ai/vcm/worktrees/<taskSlug>/
+.claude/worktrees/<taskSlug>/
   project-manager session cwd
   architect session cwd
   coder session cwd
@@ -274,11 +281,11 @@ VCM distinguishes:
 - `branch`: `feature/<taskSlug>`.
 - `worktreePath`: same as `taskRepoRoot`.
 
-Base repo state is only the task index and the container for nested task worktrees:
+Base repo state is the task index plus the Claude-compatible container for nested task worktrees:
 
 ```text
 <baseRepoRoot>/.ai/vcm/tasks/<task>.json
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/
+<baseRepoRoot>/.claude/worktrees/<task>/
 ```
 
 Project configuration is app-local and stored outside the repository:
@@ -291,11 +298,11 @@ Project configuration is app-local and stored outside the repository:
 Task runtime state, source changes, and handoff artifacts live in the task runtime repo. For worktree-backed tasks this is the nested task worktree:
 
 ```text
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/sessions/<task>.json
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/orchestration/<task>.json
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/translation/<task>/
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/handoffs/
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/sessions/<task>.json
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/orchestration/<task>.json
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/translation/<task>/
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/handoffs/
 ```
 
 For inline tasks, `taskRepoRoot` is the connected base repo, so these same runtime paths resolve under the connected repo's `.ai/vcm/`.
@@ -306,15 +313,15 @@ This split lets VCM list tasks from the base repo after worktrees are created, w
 
 ### 6.2 Git Ignore Requirement
 
-The base repository must ignore `.ai/vcm/`.
+The base repository must ignore `.ai/vcm/` and `.claude/worktrees/`.
 
 Reason:
 
-- `.ai/vcm/worktrees/<task>` is a nested git worktree.
-- Without `.ai/vcm/` in `.gitignore`, the base repo sees worktree files as untracked noise.
+- `.claude/worktrees/<task>` is a nested git worktree.
+- Without `.claude/worktrees/` 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.
 
-The VCM harness manages a `.gitignore` block that ignores `.ai/vcm/` before task worktree creation.
+The VCM harness manages a `.gitignore` block that ignores `.ai/vcm/` and `.claude/worktrees/` before task worktree creation.
 
 ### 6.3 Task Creation Flow
 
@@ -323,8 +330,9 @@ POST /api/tasks
   -> validate taskSlug
   -> assert .ai/vcm/ is ignored by Git
   -> if createWorktree is not false:
+       -> assert .claude/worktrees/ is ignored by Git
        -> compute branch feature/<taskSlug>
-       -> compute worktreePath <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+       -> compute worktreePath <baseRepoRoot>/.claude/worktrees/<taskSlug>
        -> assert branch does not already exist
        -> assert worktreePath does not already exist
        -> assert base repo has no uncommitted changes
@@ -347,7 +355,7 @@ POST /api/tasks/:taskSlug/cleanup
   -> list role sessions for the task
   -> stop each VCM-managed role session whose runtime status is running
   -> stop translation tailers and clear task translation cache
-  -> when worktreePath exists, verify it belongs under <baseRepoRoot>/.ai/vcm/worktrees/
+  -> when worktreePath exists, verify it belongs under <baseRepoRoot>/.claude/worktrees/
   -> when worktreePath exists, git worktree remove --force <worktreePath>
   -> when worktreePath exists, delete the task branch by default
   -> delete base task metadata
@@ -424,9 +432,9 @@ Artifact checks are simple V1 checks:
 - placeholder / incomplete
 - ok
 
-They are used for workflow readiness, not content quality judgment.
+They are used for missing/incomplete artifact warnings, not content quality judgment.
 
-## 8. Workflow Computation
+## 8. Task Status Report
 
 File:
 
@@ -438,21 +446,7 @@ Endpoint:
 GET /api/tasks/:taskSlug/status
 ```
 
-The workflow has five steps:
-
-```text
-architecture-plan -> implementation -> review -> docs-sync -> final-acceptance
-```
-
-Step readiness:
-
-- 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.
-
-The report is displayed in the sidebar `Workflow` section.
+The status report returns the task record, role sessions, artifact checks, and warnings. VCM no longer computes or renders a Workflow panel; role sequencing is guided by the injected Claude rules and PM-mediated messages.
 
 ## 9. Session Runtime
 
@@ -581,21 +575,69 @@ Manual mode:
 send -> pending_approval or queued -> Messages modal -> Copy/manual action
 ```
 
-The current GUI shows sequence, timestamp, status, body preview, path, and a `Copy` button. It does not expose Open Role, Stage, or Reject buttons. The backend still exposes stage/approve/reject routes; `Stage` writes `Read and handle VCM message <id> at <bodyPath>` without appending Enter.
+The current GUI shows sequence, timestamp, status, body preview, path, `Copy`, and `Mark All Done`. It does not expose Open Role, Stage, or Reject buttons. The backend still exposes stage/approve/reject routes; `Stage` writes `Read and handle VCM message <id> at <bodyPath>` without appending Enter.
 
 Auto mode:
 
 ```text
-send -> delivered
+send -> delivering when target has no active message
+UserPromptSubmit hook containing message id -> submitted
+send -> queued when target is already handling an active delivering/submitted/staged message
+target role reply/result -> acknowledge active message -> deliver next queued message for that role
 ```
 
-The backend pastes a `[VCM MESSAGE]` envelope into the target terminal, then sends Enter as a separate terminal input event.
+The backend pastes a `[VCM MESSAGE]` envelope into the target terminal, then sends Enter as a separate terminal input event. That terminal write is only `delivering`. Delivery is confirmed by the target Claude Code `UserPromptSubmit` hook, which includes the submitted prompt and message id. Delivery is serialized per target role. VCM does not infer Claude Code readiness from PTY silence; it treats `vcmctl reply` and `vcmctl result` from that role as the workflow-complete signal for that message.
+
+VCM Harness owns Claude Code hook injection through `.claude/settings.json`. V1 injects only `UserPromptSubmit` and `Stop`. `UserPromptSubmit` switches the role activity badge to `running` and confirms submitted messages. `Stop` switches the role activity badge to `idle`. VCM does not use Claude Code Subagent hooks for role delegation.
+
+`Mark All Done` is a manual recovery action for stuck orchestration. It appends `acknowledged` snapshots for open messages, including `pending_approval`, `queued`, `staged`, `delivering`, `submitted`, `delivered`, and failed message states. It is intended for the case where the user manually copied or delivered stuck messages and wants auto orchestration to continue.
+
+The message service also serializes message mutations per task inside the VCM process so concurrent API calls cannot bypass the per-role in-flight check.
 
 The backend still exposes pause/resume orchestration API routes and stores `paused` for compatibility. The current GUI only toggles `mode` between `manual` and `auto`.
 
 Messages and orchestration snapshots are task runtime state under `taskRepoRoot/.ai/vcm`. Message body markdown also lives in the task worktree handoff directory.
 
-## 12. Role Command Compatibility
+## 12. Round Completion Architecture
+
+Files:
+
+- `src/backend/services/round-service.ts`
+- `src/backend/api/round-routes.ts`
+- `src/shared/types/round.ts`
+
+API:
+
+```text
+GET /api/tasks/:taskSlug/round
+```
+
+The round service reads hook-driven role activity from `RoleSessionRecord`. It does not use transcript tailing as the source of truth for round completion.
+
+- `unknown`
+- `idle`
+- `answering`
+
+Mapping:
+
+- `UserPromptSubmit` updates the session to `activityStatus: "running"` and the round role state to `answering`
+- `Stop` updates the session to `activityStatus: "idle"`, records `lastStopAt`, and the round role state becomes `idle`
+
+Task-level completion:
+
+- If a message is currently `delivering`, `submitted`, `delivered`, or `staged`, the latest such message defines the round target.
+- In a PM -> role -> PM chain, completion follows the newest active message, so the round completes after PM emits hook `Stop` for the final response.
+- Queued or pending messages prevent completion.
+- If no VCM message is in the round, the latest direct role `Stop` can still produce a completion state.
+
+Frontend behavior:
+
+- `TaskWorkspace` polls the round endpoint with the other task state.
+- `App` stores the sidebar `Round alert` preference in `~/.vcm/settings.json`.
+- `Try alert` is frontend-only and calls the same round completion notice/sound path without persisting any setting.
+- `App` deduplicates `completionId`, then shows a small `Round complete` prompt and plays a short Web Audio tone when alerts are enabled.
+
+## 13. Role Command Compatibility
 
 Files:
 
@@ -625,7 +667,7 @@ The dispatcher:
 
 This is a compatibility path. The preferred V1 coordination path is `vcmctl` message bus.
 
-## 13. Harness Service
+## 14. Harness Service
 
 File:
 
@@ -636,6 +678,7 @@ Harness files:
 ```text
 CLAUDE.md
 .gitignore
+.claude/settings.json
 .claude/agents/project-manager.md
 .claude/agents/architect.md
 .claude/agents/coder.md
@@ -655,9 +698,12 @@ Managed block:
 ```gitignore
 # VCM:BEGIN version=1
 .ai/vcm/
+.claude/worktrees/
 # VCM:END
 ```
 
+`.claude/settings.json` is JSON-merged by the harness. VCM preserves existing settings and adds command hooks for `UserPromptSubmit` and `Stop` that call `vcmctl hook-event` through the session-provided `VCM_CTL_COMMAND`.
+
 The service:
 
 - checks whether files exist
@@ -668,7 +714,7 @@ The service:
 
 It must not overwrite user content outside the VCM block.
 
-## 14. Translation Architecture
+## 15. Translation Architecture
 
 Files:
 
@@ -782,7 +828,7 @@ POST translation/send -> bracketed paste English text -> short delay -> runtime.
 
 The backend strips trailing newlines before pasting and sends Enter separately. This avoids Claude Code TUI cases where a single large PTY write containing both text and `\r` fills the input line but does not submit it.
 
-## 15. API Surface
+## 16. API Surface
 
 Project:
 
@@ -838,6 +884,7 @@ Messages:
 ```text
 GET  /api/tasks/:taskSlug/messages
 POST /api/tasks/:taskSlug/messages
+POST /api/tasks/:taskSlug/messages/mark-all-done
 POST /api/tasks/:taskSlug/messages/:messageId/stage
 POST /api/tasks/:taskSlug/messages/:messageId/approve
 POST /api/tasks/:taskSlug/messages/:messageId/reject
@@ -847,6 +894,18 @@ POST /api/tasks/:taskSlug/orchestration/pause
 POST /api/tasks/:taskSlug/orchestration/resume
 ```
 
+Claude Code hooks:
+
+```text
+POST /api/hooks/claude-code
+```
+
+Round:
+
+```text
+GET  /api/tasks/:taskSlug/round
+```
+
 App settings:
 
 ```text
@@ -875,7 +934,7 @@ WebSockets:
 /ws/terminal/:sessionId
 ```
 
-## 16. Error Handling
+## 17. Error Handling
 
 File:
 
@@ -900,7 +959,7 @@ Fastify error handler returns:
 }
 ```
 
-## 17. Packaging Architecture
+## 18. Packaging Architecture
 
 `package.json` publishes built artifacts:
 
@@ -922,7 +981,7 @@ Important scripts:
 - `prepack`: build and package verification
 - `postinstall`: fixes `node-pty` spawn helper when needed
 
-## 18. Security And Safety Boundaries
+## 19. Security And Safety Boundaries
 
 Current boundaries:
 
@@ -936,13 +995,13 @@ Current boundaries:
 - 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.
 
-## 19. Known Implementation Boundaries
+## 20. Known Implementation Boundaries
 
 - 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 computed Workflow panel or hard 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.