npm - vibe-coding-master - Versions diffs - 0.0.14 → 0.0.16 - Mend

vibe-coding-master 0.0.14 → 0.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

package/README.md +32 -34
package/dist/backend/api/claude-hook-routes.js +3 -0
package/dist/backend/api/message-routes.js +8 -40
package/dist/backend/server.js +1 -23
package/dist/backend/services/artifact-service.js +27 -2
package/dist/backend/services/claude-hook-service.js +108 -49
package/dist/backend/services/harness-service.js +18 -1
package/dist/backend/services/message-service.js +307 -210
package/dist/backend/services/round-service.js +2 -2
package/dist/backend/services/session-service.js +25 -9
package/dist/backend/templates/handoff.js +3 -0
package/dist/backend/templates/harness/architect-agent.js +4 -3
package/dist/backend/templates/harness/claude-root.js +5 -4
package/dist/backend/templates/harness/coder-agent.js +4 -3
package/dist/backend/templates/harness/project-manager-agent.js +5 -5
package/dist/backend/templates/harness/reviewer-agent.js +4 -3
package/dist/backend/templates/message-envelope.js +7 -3
package/dist-frontend/assets/{index-DVhkEVnA.js → index-CvtyKEfS.js} +44 -44
package/dist-frontend/index.html +1 -1
package/docs/cc-best-practices.md +10 -9
package/docs/product-design.md +64 -35
package/docs/v1-architecture-design.md +31 -29
package/docs/v1-implementation-plan.md +71 -50
package/package.json +2 -3
package/scripts/verify-package.mjs +0 -3
package/dist/cli/vcmctl.js +0 -171

package/dist-frontend/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>VibeCodingMaster</title>
-    <script type="module" crossorigin src="/assets/index-DVhkEVnA.js"></script>
+    <script type="module" crossorigin src="/assets/index-CvtyKEfS.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-jEkUTnIY.css">
   </head>
   <body>

package/docs/cc-best-practices.md CHANGED Viewed

@@ -214,9 +214,10 @@ Role-specific behavior lives in `.claude/agents/`.
 - Do not let one coding session own architecture/plan decisions, implementation, final testing responsibility, and review.
 - Role outputs are exchanged through `.ai/vcm/handoffs/`, not through chat history.
 - Role messaging is turn-based. Keep at most one active message to the same target role.
-- After sending a role message, wait for that role to respond with `vcmctl reply` or `vcmctl result` before sending another message to the same role.
-- After any successful `vcmctl send`, `vcmctl reply`, or `vcmctl result`, end the current Claude Code turn. Treat the command as the final coordination action of that turn.
-- Do not run `vcmctl inbox`, poll files, start shell loops, or keep the turn open waiting for another role's answer.
+- Send role messages by writing or updating the fixed route file under `.ai/vcm/handoffs/messages/<from-role>-<to-role>.md`.
+- For a given target role, update the same route file instead of creating multiple fragmented messages.
+- After writing or updating a role message file, end the current Claude Code turn. Treat the file write as the final coordination action of that turn.
+- Do not poll message files, start shell loops, or keep the turn open waiting for another role's answer. VCM dispatches pending route files after Claude Code `Stop`.
 - Do not use Claude Code Task/Subagent for VCM role delegation; VCM owns the four long-running role sessions.
 - If new information appears while a role is still processing, update the handoff artifact or wait instead of sending fragmented follow-up messages.
 - When the required role route includes `architect`, coding must not start until the architecture and plan artifact exists.
@@ -565,7 +566,7 @@ Do not include:
 For large projects, the default execution model should be explicit role-based sessions, not dynamic role routing inside one generic Claude conversation.
-The user-facing task should start with a `project-manager` role session. The project manager owns user communication, role command dispatch, severity classification, role routing, progress tracking, and process verification. It does not own architecture, coding, and independent review for the same non-trivial task.
+The user-facing task should start with a `project-manager` role session. The project manager owns user communication, route-file message preparation, severity classification, role routing, progress tracking, and process verification. It does not own architecture, coding, and independent review for the same non-trivial task.
 Do not make one generic Claude session own architecture, planning, coding, final testing, and review for non-trivial work. That blurs responsibility and makes acceptance weak.
@@ -719,7 +720,7 @@ Role responsibilities:
 ```text
 project-manager
-  owns user communication, task clarification, task specs, role routing, and role command dispatch
+  owns user communication, task clarification, task specs, role routing, and route-file message preparation
   turns user input into an engineering task when needed
   summarizes role outputs back to the user
   creates and verifies handoff artifacts
@@ -1365,9 +1366,9 @@ Do not rely on `CLAUDE.md` for constraints that can be automated.
 Recommended hooks:
 ```text
-UserPromptSubmit:
-  confirm that a VCM message actually entered the target Claude Code role session
-  switch the role activity state to running
+Stop:
+  notify VCM that a role turn ended
+  trigger VCM to scan .ai/vcm/handoffs/messages/ for pending route files
 PreToolUse:
   block protected files
@@ -2158,7 +2159,7 @@ Monthly review:
 If you can only enforce 16 rules, enforce these:
 1. User-facing tasks start with `claude --agent project-manager`; untagged sessions are not implicit project managers.
-2. The `project-manager` agent owns user communication, task clarification, and precise role command dispatch.
+2. The `project-manager` agent owns user communication, task clarification, and precise route-file message preparation.
 3. Complex tasks use explicit role sessions, handoff artifacts, and plan first; do not edit directly.
 4. One task uses one branch, one worktree, one handoff directory, and one PR by default.
 5. Role sessions for the same task work in the same task worktree sequentially; parallel write work uses separate task or sub-task worktrees.

package/docs/product-design.md CHANGED Viewed

@@ -243,14 +243,14 @@ The old `Dirty: yes/no` label is not used. The UI uses `Working tree: clean` or
 `Settings` contains:
 - `Theme` button, cycling through `System`, `Light`, and `Dark`.
-- `Round alert` button, on by default, controlling the completion prompt and sound.
+- `Round alert` button, on by default, controlling the completion prompt and soft two-note completion chime.
 - `Try alert` button, firing the same completion prompt and sound for local verification.
 - `Messages` button, opening a modal list of role messages.
 - `Events` button, opening a modal list of runtime UI events for the current task.
 The default theme mode is `System`, which follows the OS/browser color-scheme preference. The entire application chrome, sidebar, forms, modals, status badges, and workspace panels must support both light and dark rendering. Embedded terminals keep their terminal-native dark styling.
-When `Round alert` is on, VCM shows a compact in-app prompt and plays a short local sound after a full conversation round truly ends.
+When `Round alert` is on, VCM shows a compact in-app prompt and plays a short, soft, two-note local chime after a full conversation round truly ends.
 `Try alert` must work even when no conversation has just completed so the user can verify browser sound and notification behavior.
 There is no separate `Pause orchestration` or `Resume orchestration` control in the GUI. The current product model is one on/off toggle in the active role toolbar, immediately to the left of `Translate`.
@@ -320,13 +320,13 @@ VCM detects answer completion from VCM's hook-driven role activity state, not fr
 Backend role state:
-- `UserPromptSubmit`: role becomes `running`.
+- VCM terminal submit: role becomes `running`.
 - `Stop`: role becomes `idle` and records `lastStopAt`.
 - The role tab and Round alert use the same activity state source.
 Task-level round state:
-- If VCM role messages exist, the latest active `delivering`, `submitted`, `delivered`, or `staged` message defines the current target role.
+- If VCM role messages exist, the latest active `submitted` message defines the current target role.
 - A PM -> Coder -> PM chain completes only when the latest target role, PM, reaches hook `Stop`.
 - Queued or pending messages prevent completion because more role work is waiting.
 - If no VCM role message is involved, the latest direct role `Stop` can complete the round.
@@ -424,31 +424,60 @@ Each task creates:
   review-report.md
   docs-sync-report.md
   messages/
-    <message-id>.md
+    project-manager-architect.md
+    project-manager-coder.md
+    project-manager-reviewer.md
+    architect-project-manager.md
+    coder-project-manager.md
+    reviewer-project-manager.md
+    <optional-peer-route>.md
 ```
 The product treats handoff files as task-local coordination facts. The terminal is useful for live interaction, but handoff files and message history are the source of truth during a task. They live under `.ai/vcm/`, are ignored by Git, and are removed by `Close Task`; final decisions that should survive must be copied into normal project docs, source, commit messages, or PR text.
-The main UI no longer has a dedicated artifact panel. Artifact APIs still exist for status checks, role command compatibility, and future UI work.
+The main UI no longer has a dedicated artifact panel. Artifact APIs still exist for status checks and future UI work.
 ## 12. Message Bus
-VCM messaging is API-driven.
+VCM messaging is file-driven and dispatched by VCM after Claude Code turn completion. Roles do not call a VCM CLI to send messages.
 ```text
 role terminal
-  -> vcmctl
-  -> VCM backend API
-  -> policy validation
-  -> durable message snapshots
-  -> target terminal write when allowed
+  -> writes/updates one route file under .ai/vcm/handoffs/messages/
+  -> ends the Claude Code turn
+  -> Claude Code Stop hook calls VCM backend directly
+  -> VCM scans pending route files
+  -> VCM validates, snapshots, and dispatches one allowed message per idle target role
 ```
-Allowed message routes:
+Route files:
-- `project-manager` to `architect` / `coder` / `reviewer`: `task`, `question`, `review-request`, `revise`, `cancel`
-- `architect` / `coder` / `reviewer` to `project-manager`: `result`, `question`, `blocked`, `finding`
-- `user` to `project-manager`: `user-request`
+- File name format is `<from-role>-<to-role>.md`.
+- Role names use VCM role slugs, for example `project-manager-coder.md`.
+- The file path determines `from` and `to`; frontmatter cannot override the route.
+- The file body is Markdown.
+- Optional YAML frontmatter may provide `type`, `severity`, `title`, or `related_artifact`.
+- Blank or whitespace-only files mean "no pending message".
+- Non-empty files mean "pending message waiting for VCM dispatch".
+The important product rule is one file per directed route. If role A decides several times during one turn that it needs to call role B, it must edit the same `A-B.md` file instead of creating multiple messages. This turns duplicate sends into a single latest pending instruction.
+Default route policy:
+- `project-manager` may send to `architect`, `coder`, and `reviewer`.
+- `architect`, `coder`, and `reviewer` may send to `project-manager`.
+- Peer routes such as `coder-reviewer.md` may exist for explicit task designs, but VCM still serializes delivery per target role.
+- `user` talks to `project-manager` through the normal active terminal or translation composer, not through a route file.
+Stop-triggered scan:
+- VCM injects Claude Code `UserPromptSubmit` and `Stop` hooks into `.claude/settings.json`.
+- The hooks do not call `vcmctl`; they POST directly to the local VCM backend.
+- When any role stops, VCM marks that role idle, then scans pending route files.
+- VCM scans the stopped role's outgoing files and also any pending files targeting newly idle roles, so messages that were blocked by a busy target can be delivered after that target stops.
+- VCM reads only stable, non-empty files and ignores blank files.
+- VCM delivers at most one message to a target role per scan.
+- If multiple pending files target the same idle role, VCM chooses deterministically by oldest modified time, then route name.
 Manual mode:
@@ -458,28 +487,28 @@ Manual mode:
 - `Mark All Done` marks open message records as `acknowledged` after the user manually handled stuck messages
 - user decides whether to copy or manually act on the message
 - VCM does not write to the target terminal or submit Enter
+- VCM does not clear the source route file until the user marks it done or VCM later dispatches it in auto mode
 Auto mode:
-- if target role is running, VCM writes a `[VCM MESSAGE]` envelope, submits Enter, and marks the message `delivering`
-- Claude Code `UserPromptSubmit` is the delivery acknowledgement; when the hook prompt contains the message id, VCM marks the message `submitted`
-- PM remains the routing hub
-- non-PM roles reply to PM
-- VCM enforces per-target-role turn-taking
-- each target role may have at most one active `delivering`, `submitted`, `delivered`, or `staged` message
-- extra messages to the same busy target role remain queued and are not written to the terminal
-- when the GUI sees a newly submitted auto message, it switches the active role tab to the target role
-- a role's `vcmctl reply` or `vcmctl result` acknowledges the active message and releases the next queued message for that role
-- `Mark All Done` is a manual recovery action for stuck orchestration. It marks `pending_approval`, `queued`, `staged`, `delivering`, `submitted`, `delivered`, and failed message states as `acknowledged` so the next queued work is not permanently blocked after the user manually copied or sent a message.
+- if the target role is idle and has no active `delivering` or `submitted` message, VCM writes a `[VCM MESSAGE]` envelope to that role's embedded terminal and submits Enter
+- terminal write success stores a durable message snapshot and marks the delivery `delivering`
+- Claude Code `UserPromptSubmit` confirms the accepted prompt, marks the message `submitted`, and clears the source route file if it still contains that same message
+- if the target role is not running, is busy, or terminal submission fails, VCM leaves the route file non-empty so it remains pending
+- when VCM dispatches a message, the GUI switches to the target role tab so the user can watch execution
+- the target role answers by writing its own route file back to the next role and then ending its turn
+- `Mark All Done` is a manual recovery action for stuck orchestration. It marks open message records as `acknowledged` and may clear route files only after the user confirms the pending file contents were manually handled.
 VCM Harness injects Claude Code hooks into `.claude/settings.json`:
-- `UserPromptSubmit`: sets the role tab activity to `running` and confirms submitted VCM messages
-- `Stop`: sets the role tab activity to `idle`
+- `UserPromptSubmit`: posts directly to the VCM backend, marks the role running, and confirms any matching VCM message from `delivering` to `submitted`
+- `Stop`: posts directly to the VCM backend, marks the role idle, and triggers pending route-file dispatch
+VCM uses `UserPromptSubmit` as the Claude Code acceptance signal. A successful PTY write only proves VCM delivered text to the embedded terminal; `UserPromptSubmit` proves Claude Code accepted the prompt.
-The injected role rules require asynchronous role messaging: after any successful `vcmctl send`, `vcmctl reply`, or `vcmctl result`, the role must end the current Claude Code turn and wait for VCM to deliver a later reply. Roles must not run `vcmctl inbox`, loop, poll, or wait inside the same turn for another role to answer, and they must not use Claude Code Task/Subagent for VCM role delegation.
+The injected role rules require asynchronous file messaging: after writing or updating a route file, the role must end the current Claude Code turn and wait for VCM to deliver a later reply. Roles must not poll files, start shell loops, or keep the turn open waiting for another role to answer, and they must not use Claude Code Task/Subagent for VCM role delegation.
-The backend still has `stage`, `approve`, `reject`, `paused`, and pause/resume API compatibility paths. The current GUI exposes only message copy plus manual/auto orchestration.
+There is no `vcmctl` in the target design. Hook entrypoints are direct HTTP from Claude Code hooks to the local VCM backend.
 ## 13. Translation
@@ -617,6 +646,7 @@ Task worktree local files:
 .claude/worktrees/<task>/.ai/vcm/orchestration/<task>.json
 .claude/worktrees/<task>/.ai/vcm/translation/<task>/
 .claude/worktrees/<task>/.ai/vcm/handoffs/
+.claude/worktrees/<task>/.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
 ```
 For tasks created without a worktree, the task runtime repo is the connected base repo, so the runtime state resolves under the base repo's `.ai/vcm/`. Because `.ai/vcm/handoffs/` has no task-name segment, VCM allows only one active inline task in a connected repo.
@@ -632,7 +662,6 @@ External Claude transcripts:
 Published npm packages must include built output:
 - `dist/main.js`
-- `dist/cli/vcmctl.js`
 - backend route/service/template output in `dist/`
 - frontend static assets in `dist-frontend/`
 - `README.md`
@@ -658,10 +687,10 @@ VCM V1 is successful when:
 - Switching roles never loses the embedded terminal.
 - Restart creates a fresh Claude session; Resume reconnects to the persisted one.
 - Permission modes are reflected in the Claude command.
-- PM can route messages through `vcmctl`.
-- Manual orchestration lets the user inspect and stage messages without auto-submitting Enter.
-- Auto orchestration can deliver PM-approved work to running target roles.
-- Auto orchestration switches to the target role tab when a new message is confirmed by `UserPromptSubmit`.
+- Roles can route messages by writing fixed route files under `.ai/vcm/handoffs/messages/`.
+- Manual orchestration lets the user inspect pending route-file messages without auto-submitting Enter.
+- Auto orchestration can deliver pending route-file messages to idle running target roles.
+- Auto orchestration switches to the target role tab when VCM submits a route-file message.
 - Round completion detection waits for the final role in a chained conversation and can alert with prompt plus sound.
 - Translation settings save to `~/.vcm/settings.json`.
 - Translation reads Claude transcript JSONL reliably after start, resume, and restart.

package/docs/v1-architecture-design.md CHANGED Viewed

@@ -113,7 +113,7 @@ Responsibilities:
 - 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.
+- Detect newly submitted auto-orchestration messages from VCM dispatch 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 messages/orchestration/events back to `App` so sidebar stays synchronized.
@@ -553,50 +553,56 @@ Files:
 - `src/backend/services/message-service.ts`
 - `src/backend/templates/message-envelope.ts`
-- `src/cli/vcmctl.ts`
 State:
 ```text
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
 <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
-<taskRepoRoot>/.ai/vcm/handoffs/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
 ```
 Policy:
-- 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.
+- Roles never call a VCM CLI to send messages.
+- A role writes or updates exactly one route file for each directed target role.
+- File name format is `<from-role>-<to-role>.md`; the filename is the authoritative route.
+- Blank route files are not pending.
+- Non-empty route files are pending and are dispatched only by VCM.
+- Optional YAML frontmatter may provide message type and metadata, but cannot override the route.
+- PM-to-role and role-to-PM routes are the default policy. Peer route files are supported only when the task design explicitly allows them.
 Manual mode:
 ```text
-send -> pending_approval or queued -> Messages modal -> Copy/manual action
+role writes route file -> Stop hook -> VCM records pending snapshot -> Messages modal -> Copy/manual action
 ```
-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.
+The current GUI shows sequence, timestamp, status, route file path, body preview, `Copy`, and `Mark All Done`. VCM leaves the route file non-empty until the user confirms the pending content was handled or auto mode later dispatches it.
 Auto mode:
 ```text
-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
+role writes route file
+Stop hook -> VCM scans pending route files
+target idle and running -> VCM writes envelope + Enter -> delivering
+UserPromptSubmit hook -> VCM confirms accepted prompt -> submitted
+submitted -> VCM clears source route file if it still contains the same message
+target busy/unavailable/failure -> source route file remains non-empty
+target Stop hook -> VCM scans again and may deliver next pending route file
 ```
-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.
+The backend pastes a `[VCM MESSAGE]` envelope into the target terminal, then sends Enter as a separate terminal input event. A successful terminal write creates a `delivering` snapshot. Claude Code `UserPromptSubmit` is the acceptance confirmation that moves the message to `submitted`. VCM snapshots the message body before clearing the source route file so the message history remains auditable. Delivery is serialized per target role; VCM never sends two pending route files into the same target role during one scan.
-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.
+VCM Harness owns Claude Code hook injection through `.claude/settings.json`. The target design injects `UserPromptSubmit` and `Stop`. Hooks post directly to a local VCM backend endpoint and do not use `vcmctl`. `UserPromptSubmit` confirms accepted prompts and switches the role activity badge to `running`; `Stop` switches the role activity badge to `idle` and triggers a pending route-file scan. VCM also marks a role `running` immediately after it submits user input or a VCM message to that embedded terminal. 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.
+`Mark All Done` is a manual recovery action for stuck orchestration. It appends `acknowledged` snapshots for open messages and, after user confirmation, clears pending route files that the user already handled manually.
 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`.
+The backend should not keep compatibility-only message command paths after this migration. Removing `vcmctl` is part of the target simplification.
-Messages and orchestration snapshots are task runtime state under `taskRepoRoot/.ai/vcm`. Message body markdown also lives in the task worktree handoff directory.
+Messages and orchestration snapshots are task runtime state under `taskRepoRoot/.ai/vcm`. Pending route files live in the task worktree handoff directory and are cleared after successful VCM submission.
 ## 12. Round Completion Architecture
@@ -620,12 +626,12 @@ The round service reads hook-driven role activity from `RoleSessionRecord`. It d
 Mapping:
-- `UserPromptSubmit` updates the session to `activityStatus: "running"` and the round role state to `answering`
+- VCM terminal submit 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.
+- If a message is currently `delivering` or `submitted`, 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.
@@ -635,7 +641,7 @@ 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.
+- `App` deduplicates `completionId`, then shows a small `Round complete` prompt and plays a short two-note Web Audio chime when alerts are enabled.
 ## 13. Role Command Compatibility
@@ -665,7 +671,7 @@ The dispatcher:
 4. Resolves primary command path `role-commands/<role>.md`, with legacy fallback `<role>-command.md`.
 5. Pastes `Please read and execute the role command at: <path>` to the target terminal, then sends Enter as a separate terminal input event.
-This is a compatibility path. The preferred V1 coordination path is `vcmctl` message bus.
+This is an obsolete compatibility path and should be removed when route-file messaging lands. The preferred V1 coordination path is VCM-dispatched route files under `.ai/vcm/handoffs/messages/`.
 ## 14. Harness Service
@@ -702,7 +708,7 @@ Managed block:
 # 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`.
+`.claude/settings.json` is JSON-merged by the harness. VCM preserves existing settings and adds `UserPromptSubmit` and `Stop` hooks that post directly to the local VCM backend using the session-provided VCM API URL, task slug, role, and Claude session id. The hooks must not call `vcmctl`.
 The service:
@@ -883,21 +889,18 @@ Messages:
 ```text
 GET  /api/tasks/:taskSlug/messages
-POST /api/tasks/:taskSlug/messages
+GET  /api/tasks/:taskSlug/messages/pending-route-files
+POST /api/tasks/:taskSlug/messages/scan
 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
 GET  /api/tasks/:taskSlug/orchestration
 PUT  /api/tasks/:taskSlug/orchestration
-POST /api/tasks/:taskSlug/orchestration/pause
-POST /api/tasks/:taskSlug/orchestration/resume
 ```
 Claude Code hooks:
 ```text
 POST /api/hooks/claude-code
+POST /api/hooks/claude-code/stop
 ```
 Round:
@@ -972,7 +975,6 @@ Fastify error handler returns:
 Bins:
 - `vcm` -> `dist/main.js`
-- `vcmctl` -> `dist/cli/vcmctl.js`
 Important scripts: