vibe-coding-master 0.0.14 → 0.0.16

package/docs/v1-implementation-plan.md

@@ -28,10 +28,9 @@ File:
 Current package facts:
 
 - package name: `vibe-coding-master`
-- current version: `0.0.10`
+- current version: `0.0.14`
 - type: ESM
 - `bin.vcm`: `dist/main.js`
-- `bin.vcmctl`: `dist/cli/vcmctl.js`
 - published files: `dist`, `dist-frontend`, `docs`, `scripts`, `README.md`
 
 Scripts:
@@ -59,8 +58,6 @@ It verifies required files, shebangs, packaged static path behavior, and fronten
 ```text
 src/
   main.ts
-  cli/
-    vcmctl.ts
   shared/
     constants.ts
     types/
@@ -108,23 +105,24 @@ Responsibilities:
 - serve `dist-frontend` through backend in production mode
 - close backend/Vite on `SIGINT`
 
-### `src/cli/vcmctl.ts`
+### Removed CLI Surface
 
-CLI commands:
+The target design removes `vcmctl` completely. Role sessions must not call a VCM CLI to send messages or hook events.
 
-- `vcmctl send`
-- `vcmctl reply`
-- `vcmctl result`
-- `vcmctl inbox`
-- `vcmctl ready`
+Remove:
 
-Environment required in role sessions:
+- `src/cli/vcmctl.ts`
+- `bin.vcmctl` from `package.json`
+- packaged `dist/cli/vcmctl.js`
+- `VCM_CTL_COMMAND` session environment
+- harness rules that mention `vcmctl`
+
+Role sessions still receive enough environment for direct hook POSTs and backend-aware terminal delivery:
 
 - `VCM_API_URL`
 - `VCM_TASK_SLUG`
 - `VCM_ROLE`
-
-Role sessions receive these env vars from `SessionService`.
+- `VCM_SESSION_ID`
 
 ## 5. Shared Layer
 
@@ -239,10 +237,10 @@ Defines:
 - `VcmOrchestrationMode`
 - `VcmRoleMessage`
 - `VcmOrchestrationState`
-- `SendRoleMessageRequest`
-- `SendRoleMessageResult`
+- `VcmRouteFile`
+- `VcmRouteFileDispatchResult`
 
-The state type includes `paused` for backend/API compatibility. The current GUI only exposes manual/auto.
+The state type should only expose the current manual/auto mode. Remove compatibility-only paused state when deleting `vcmctl`.
 
 ### `src/shared/types/round.ts`
 
@@ -679,41 +677,62 @@ In task-worktree mode:
 Exports:
 
 - `MessageService`
-- input interfaces
+- `ScanPendingRouteFilesInput`
+- `DispatchPendingRouteFileInput`
+- `RouteFileRecord`
 - `createMessageService(deps)`
 
 Responsibilities:
 
 - list messages
-- send messages
-- confirm submitted messages from Claude Code `UserPromptSubmit` hooks
+- scan route-file outboxes after Claude Code `Stop`
+- snapshot pending route-file messages
 - mark all open messages done for manual recovery
-- stage/approve/reject messages
 - get/update orchestration state
 - enforce message policy
 - enforce per-target-role in-flight delivery
-- queue extra messages for a busy target role
-- acknowledge a role's active message when that role sends `vcmctl reply` or `vcmctl result`
-- deliver the next queued message for that role after acknowledgement
+- leave non-empty route files pending when a target role is busy, unavailable, or terminal submission fails
+- deliver the next pending route file when a target role becomes idle
 - persist message snapshots
-- write message body markdown
-- write staged or delivering messages to target terminal
+- archive dispatched route-file bodies before clearing source files
+- submit route-file messages to the target terminal
 
 In task-worktree mode:
 
 - message snapshots live under `task.worktreePath/.ai/vcm/messages`
 - orchestration state lives under `task.worktreePath/.ai/vcm/orchestration`
-- message body files live under `task.worktreePath/.ai/vcm/handoffs/messages`
+- pending route files live under `task.worktreePath/.ai/vcm/handoffs/messages`
 - terminal delivery uses the runtime session for the role, whose cwd is the task worktree
 - message mutations are serialized per task inside the VCM process to avoid concurrent API calls bypassing the in-flight check
 
-Auto-delivery state:
-
-- `send` writes the envelope and Enter, then stores `delivering`
-- `UserPromptSubmit` hook with the same message id stores `submitted`
-- `delivering`, `submitted`, `delivered`, and `staged` all count as active for per-role turn-taking
-- target-role `vcmctl reply` / `vcmctl result` acknowledges the active message and releases the next queued message
-- `markAllDone` appends `acknowledged` snapshots for open messages so the user can recover after manually copying or sending stuck queued work
+Route-file protocol:
+
+- route file name is `<from-role>-<to-role>.md`
+- the filename is the authoritative route; frontmatter cannot override `from` or `to`
+- blank or whitespace-only files are ignored
+- non-empty files are pending
+- each directed route has exactly one pending file, so repeated sends by the same role to the same target become edits to the same file
+- VCM scans after every `Stop` hook
+- VCM scans the stopped role's outgoing files and pending files targeting newly idle roles
+- VCM delivers at most one route file per target role per scan
+- if several files target the same idle role, choose oldest modified time, then route name
+- successful terminal write snapshots the body as `delivering`
+- `UserPromptSubmit` confirms Claude Code accepted the prompt, stores `submitted`, then clears the source route file if it still contains that same message
+- failed, blocked, manual, or unavailable delivery leaves the source route file unchanged
+- `markAllDone` appends `acknowledged` snapshots and may clear pending route files only after user confirmation
+
+Required service functions:
+
+- `listMessages(taskSlug): Promise<VcmRoleMessage[]>`
+- `listPendingRouteFiles(repoRoot, taskSlug): Promise<RouteFileRecord[]>`
+- `scanAndDispatchPendingRouteFiles(input: { repoRoot: string; taskSlug: string; stoppedRole: RoleName }): Promise<void>`
+- `readRouteFile(path): Promise<RouteFileRecord | null>`
+- `dispatchPendingRouteFile(record): Promise<VcmRouteFileDispatchResult>`
+- `appendMessageSnapshot(message): Promise<void>`
+- `clearRouteFile(path): Promise<void>`
+- `markAllDone(taskSlug, options): Promise<MarkAllMessagesDoneResult>`
+
+`dispatchPendingRouteFile` must snapshot before clearing. Clearing means truncating the route file to an empty string, not deleting it.
 
 ### `src/backend/services/claude-hook-service.ts`
 
@@ -724,11 +743,12 @@ Exports:
 
 Responsibilities:
 
-- accept Claude Code hook events from `vcmctl hook-event`
-- support only `UserPromptSubmit` and `Stop` in V1
+- accept Claude Code `UserPromptSubmit` and `Stop` hook events directly over HTTP
 - map hook events to the current VCM project, task, role, and persisted Claude session id
 - update `RoleSessionRecord.activityStatus`: `UserPromptSubmit -> running`, `Stop -> idle`
-- call `MessageService.confirmPromptSubmitted` when a `UserPromptSubmit` prompt contains a VCM message id
+- call `MessageService.confirmPromptSubmitted` when `UserPromptSubmit` includes a VCM message envelope
+- call `MessageService.scanAndDispatchPendingRouteFiles` after recording the stop event
+- never require `vcmctl hook-event`
 
 ### `src/backend/services/command-dispatcher.ts`
 
@@ -739,7 +759,7 @@ Exports:
 - `CommandDispatcherDeps`
 - `createCommandDispatcher(deps)`
 
-Compatibility role-command dispatch only. Preferred orchestration is `MessageService` plus `vcmctl`.
+Obsolete role-command dispatch path. Remove this as part of the route-file messaging migration; preferred orchestration is `MessageService` scanning `.ai/vcm/handoffs/messages/<from-role>-<to-role>.md` after `Stop`.
 
 ### `src/backend/services/harness-service.ts`
 
@@ -871,9 +891,8 @@ Responsibilities:
 - map `activityStatus: "running"` to role state `answering`
 - map `activityStatus: "idle"` plus `lastStopAt` to role state `idle`
 - evaluate task-level round completion from messages plus role states
-- wait for the latest active delivering/submitted/delivered/staged target role in PM -> role -> PM chains
+- wait for the latest active delivering/submitted target role in PM -> role -> PM chains
 - ignore completion while queued or pending messages exist
-- keep `stopSession` and `stopTask` as no-op lifecycle compatibility hooks
 
 ## 9. Backend API
 
@@ -897,9 +916,9 @@ Registers HTTP routes and the terminal WebSocket.
 - `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, task status, and Close Task cleanup endpoint; Close Task stops running role sessions before translation/task cleanup
-- `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, Mark All Done recovery, and orchestration
+- `src/backend/api/session-routes.ts`: session lifecycle
+- `src/backend/api/artifact-routes.ts`: artifact and log reads/writes
+- `src/backend/api/message-routes.ts`: message history, pending route files, Mark All Done recovery, and orchestration
 - `src/backend/api/claude-hook-routes.ts`: Claude Code `UserPromptSubmit` and `Stop` hook receiver
 - `src/backend/api/round-routes.ts`: task round completion state
 - `src/backend/api/translation-routes.ts`: settings, prompt previews, provider test, start/poll, input/send, clear/retry
@@ -977,6 +996,7 @@ It calls:
 - artifact endpoints
 - message endpoints
 - orchestration endpoints
+- route-file inspection endpoints for the Messages modal
 - round completion endpoint
 - translation endpoints
 
@@ -1100,7 +1120,7 @@ Exports:
 - `getMessageCounts(messages)`
 - `MessageTimeline(props)`
 
-Used inside the Messages modal. Current UI rows show sequence, timestamp, route, type, status, body preview, body path, and a `Copy` button. The modal header includes `Mark All Done` for manual recovery from stuck queued/in-flight messages. Stage/approve/reject backend APIs remain compatibility paths, but those buttons are not displayed in the current modal.
+Used inside the Messages modal. Current UI rows show sequence, timestamp, route, type, status, body preview, source route file path, and a `Copy` button. The modal header includes `Mark All Done` for manual recovery from stuck queued/in-flight messages. Stage/approve/reject backend APIs should be removed with the route-file migration.
 
 ### `src/frontend/components/event-log.tsx`
 
@@ -1147,7 +1167,7 @@ Exports:
 
 Renders permission select and session lifecycle buttons.
 
-There is no visible primary `Send Command` button in the current toolbar. Role-command dispatch remains backend compatibility.
+There is no visible primary `Send Command` button in the current toolbar. Role-command dispatch should be removed with the route-file migration.
 
 ### `src/frontend/components/translation-panel.tsx`
 
@@ -1212,7 +1232,7 @@ Sidebar:
 - `Repository Path` default open only when no task is selected
 - `Settings` includes `Theme`, `Round alert`, `Try alert`, `Messages`, and `Events`
 - `Theme` cycles through `System`, `Light`, and `Dark`; `System` follows the browser/OS color-scheme preference
-- `Round alert` is on by default and controls the in-app completion prompt plus short sound
+- `Round alert` is on by default and controls the in-app completion prompt plus a soft two-note completion chime
 - `Try alert` calls the same prompt/sound path without waiting for a real completed round
 
 Task workspace:
@@ -1224,8 +1244,8 @@ Task workspace:
 
 Round completion:
 
-- task state follows the latest active delivering/submitted/delivered/staged message target role
-- role activity uses `UserPromptSubmit -> running` and `Stop -> idle`
+- task state follows the latest active delivering/submitted message target role
+- role activity uses Claude Code `UserPromptSubmit` -> `running` and Claude Code `Stop` -> `idle`; VCM terminal submit also optimistically marks the target role `running`
 - PM -> role -> PM chains complete after PM's final hook `Stop`, not after the intermediate role's `Stop`
 - queued or pending messages keep the round active
 - frontend dedupes `completionId` before showing a prompt or playing sound
@@ -1271,7 +1291,7 @@ Messages:
 
 ```text
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
-<taskRepoRoot>/.ai/vcm/handoffs/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
 ```
 
 Orchestration:
@@ -1330,7 +1350,7 @@ For frontend layout changes, also verify manually:
 - Messages modal opens from sidebar Settings
 - Events modal opens from sidebar Settings
 - Auto orchestration toggles on/off from the role toolbar
-- Auto orchestration switches to the target role tab when a new message is confirmed by `UserPromptSubmit`
+- Auto orchestration switches to the target role tab when VCM submits a route-file message
 - Round alert can be toggled from sidebar Settings and fires once after a chained round truly completes
 - `Enter` in translation composer translates/sends
 - `Shift+Enter` inserts newline
@@ -1350,6 +1370,7 @@ Do not reintroduce these into V1 docs or UI unless the product direction changes
 - optional title input in New Task
 - `Dirty: yes/no` sidebar label
 - role command dispatch as the primary orchestration path
+- `vcmctl` as an active CLI or agent-facing message path
 - per-role worktrees
 - switching a task to another branch/worktree after creation
 - a separate `Create task worktree` button outside task creation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [
@@ -11,8 +11,7 @@
     "README.md"
   ],
   "bin": {
-    "vcm": "dist/main.js",
-    "vcmctl": "dist/cli/vcmctl.js"
+    "vcm": "dist/main.js"
   },
   "engines": {
     "node": "^20.0.0 || >=22.0.0"

package/scripts/verify-package.mjs

@@ -7,7 +7,6 @@ const requiredFiles = [
   "package.json",
   "scripts/fix-node-pty-spawn-helper.mjs",
   "dist/main.js",
-  "dist/cli/vcmctl.js",
   "dist/backend/server.js",
   "dist/backend/api/harness-routes.js",
   "dist/backend/runtime/node-pty-runtime.js",
@@ -40,14 +39,12 @@ async function main() {
   const pkg = JSON.parse(await readText("package.json"));
   assertArrayIncludes(pkg.files, requiredFileEntries, "package.json files");
   assertEqual(pkg.bin?.vcm, "dist/main.js", "package.json bin.vcm");
-  assertEqual(pkg.bin?.vcmctl, "dist/cli/vcmctl.js", "package.json bin.vcmctl");
 
   for (const file of requiredFiles) {
     await assertFile(file);
   }
 
   await assertStartsWith("dist/main.js", "#!/usr/bin/env node", "vcm bin shebang");
-  await assertStartsWith("dist/cli/vcmctl.js", "#!/usr/bin/env node", "vcmctl bin shebang");
 
   const server = await readText("dist/backend/server.js");
   assertIncludes(server, 'path.join(getAppRoot(), "dist-frontend")', "packaged static dir must resolve from app root");

package/dist/cli/vcmctl.js

@@ -1,171 +0,0 @@
-#!/usr/bin/env node
-import fs from "node:fs/promises";
-async function main(argv = process.argv.slice(2)) {
-    const [command, ...rest] = argv;
-    if (!command || command === "--help" || command === "-h") {
-        printHelp();
-        return;
-    }
-    if (command === "send") {
-        const options = parseOptions(rest);
-        await sendMessage({
-            fromRole: getEnvRole(),
-            toRole: requireOption(options.to, "--to"),
-            type: options.type ?? "task",
-            body: await resolveBody(options),
-            artifactRefs: options.artifactRefs
-        });
-        return;
-    }
-    if (command === "reply" || command === "result") {
-        const options = parseOptions(rest);
-        await sendMessage({
-            fromRole: getEnvRole(),
-            toRole: "project-manager",
-            type: command === "result" ? "result" : options.type ?? "question",
-            body: await resolveBody(options),
-            artifactRefs: options.artifactRefs
-        });
-        return;
-    }
-    if (command === "inbox") {
-        const response = await fetchJson(`${getApiUrl()}/api/tasks/${encodeURIComponent(getTaskSlug())}/messages`);
-        console.log(JSON.stringify(response, null, 2));
-        return;
-    }
-    if (command === "hook-event") {
-        await sendHookEvent(await readStdinJson());
-        return;
-    }
-    if (command === "ready") {
-        console.log("ready: VCM readiness signaling is planned for a later phase.");
-        return;
-    }
-    throw new Error(`Unknown vcmctl command: ${command}`);
-}
-async function sendMessage(input) {
-    const result = await fetchJson(`${getApiUrl()}/api/tasks/${encodeURIComponent(getTaskSlug())}/messages`, {
-        method: "POST",
-        body: JSON.stringify(input),
-        headers: {
-            "content-type": "application/json"
-        }
-    });
-    console.log(JSON.stringify(result, null, 2));
-}
-async function sendHookEvent(event) {
-    const input = {
-        taskSlug: getTaskSlug(),
-        role: getEnvRole(),
-        event
-    };
-    await fetchJson(`${getApiUrl()}/api/hooks/claude-code`, {
-        method: "POST",
-        body: JSON.stringify(input),
-        headers: {
-            "content-type": "application/json"
-        }
-    });
-}
-async function readStdinJson() {
-    const chunks = [];
-    for await (const chunk of process.stdin) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-    }
-    const raw = Buffer.concat(chunks).toString("utf8").trim();
-    if (!raw) {
-        return {};
-    }
-    return JSON.parse(raw);
-}
-function parseOptions(args) {
-    const options = {
-        artifactRefs: []
-    };
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        if (arg === "--to") {
-            options.to = requireValue(args, index += 1);
-        }
-        else if (arg === "--type") {
-            options.type = requireValue(args, index += 1);
-        }
-        else if (arg === "--body") {
-            options.body = requireValue(args, index += 1);
-        }
-        else if (arg === "--body-file") {
-            options.bodyFile = requireValue(args, index += 1);
-        }
-        else if (arg === "--artifact") {
-            options.artifactRefs.push(requireValue(args, index += 1));
-        }
-        else {
-            throw new Error(`Unknown option: ${arg}`);
-        }
-    }
-    return options;
-}
-async function resolveBody(options) {
-    if (options.bodyFile) {
-        return fs.readFile(options.bodyFile, "utf8");
-    }
-    if (options.body) {
-        return options.body;
-    }
-    throw new Error("Message body is required. Use --body or --body-file.");
-}
-function requireValue(args, index) {
-    const value = args[index];
-    if (!value) {
-        throw new Error("Missing option value.");
-    }
-    return value;
-}
-function requireOption(value, name) {
-    if (!value) {
-        throw new Error(`Missing required option: ${name}`);
-    }
-    return value;
-}
-async function fetchJson(url, init = {}) {
-    const response = await fetch(url, init);
-    if (!response.ok) {
-        const payload = await response.json().catch(() => null);
-        const message = payload?.error?.hint
-            ? `${payload.error.message} ${payload.error.hint}`
-            : payload?.error?.message ?? `Request failed: ${response.status}`;
-        throw new Error(message);
-    }
-    return response.json();
-}
-function getApiUrl() {
-    return process.env.VCM_API_URL ?? "http://127.0.0.1:4173";
-}
-function getTaskSlug() {
-    return requireEnv("VCM_TASK_SLUG");
-}
-function getEnvRole() {
-    return requireEnv("VCM_ROLE");
-}
-function requireEnv(name) {
-    const value = process.env[name];
-    if (!value) {
-        throw new Error(`${name} is not set.`);
-    }
-    return value;
-}
-function printHelp() {
-    console.log(`vcmctl
-
-Usage:
-  vcmctl send --to coder --type task --body-file /tmp/message.md
-  vcmctl reply --type blocked --body "Need clarification."
-  vcmctl result --body-file /tmp/result.md --artifact .ai/vcm/handoffs/implementation-log.md
-  vcmctl inbox
-  vcmctl hook-event < hook-payload.json
-`);
-}
-main().catch((error) => {
-    console.error(error.message);
-    process.exit(1);
-});