vibe-coding-master 0.2.4 → 0.2.6

package/docs/product-design.md

@@ -1,6 +1,6 @@
 # VibeCodingMaster Product Design
 
-Last updated: 2026-06-09
+Last updated: 2026-06-10
 
 This document describes the current product direction and implemented V1 behavior for VCM.
 
@@ -217,7 +217,7 @@ All sidebar groups are collapsible and default to collapsed. When no task is sel
 Sections:
 
 - `Repository Path`
-- `Repository`
+- `Connected Repository`
 - `Settings`
 - `VCM Harness`
 - `New Task`
@@ -233,13 +233,29 @@ Repository Path
 [ Recent v                  ] [ Connect ]
 ```
 
-`Repository` shows:
+`Connected Repository` shows the connected base repository, not the active task
+worktree:
 
-- path
-- branch
-- working tree state
+- base repo path
+- current branch
+- upstream branch when configured
+- ahead/behind status relative to upstream
+- current commit hash
+- base repo working tree state
+- last checked time
+- a `Pull` button
 
-The old `Dirty: yes/no` label is not used. The UI uses `Working tree: clean` or `Working tree: uncommitted changes`.
+Opening this section refreshes the connected repository status through
+`GET /api/projects/current`. VCM does not poll this state at high frequency.
+
+The `Pull` button runs `git pull --ff-only` only against the connected base
+repository. It is disabled when the base repository has uncommitted changes,
+when the branch has no upstream, or when the active task is an inline task using
+the base repository directly. VCM does not stash, merge, or mutate task
+worktrees from this button.
+
+The old `Dirty: yes/no` label is not used. The UI uses `Working tree: clean` or
+`Working tree: uncommitted changes`.
 
 `Settings` contains:
 
@@ -251,7 +267,7 @@ The old `Dirty: yes/no` label is not used. The UI uses `Working tree: clean` or
 
 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 `Flow pause alert` is on, VCM plays a short, soft, two-note local chime after a role flow stops advancing. If the flow lasted less than 10 minutes, the chime plays 3 times, 1.4 seconds apart, and stops. If the flow lasted 10 minutes or longer, VCM shows an in-app alert dialog and repeats the chime until the user confirms the dialog. The alert sound must reuse one browser audio context after user activation instead of creating a fresh context for each repeat, because Safari can block repeated timer-driven playback when every repeat looks like a new autoplay attempt.
+When `Flow pause alert` is on, VCM plays a short, soft, two-note local chime after a role flow stops advancing. If the flow lasted less than 2 minutes, the chime plays 3 times, 1.4 seconds apart, and stops. If the flow lasted 2 minutes or longer, VCM shows an in-app alert dialog and repeats the chime until the user confirms the dialog. The alert sound must reuse one browser audio context after user activation instead of creating a fresh context for each repeat, because Safari can block repeated timer-driven playback when every repeat looks like a new autoplay attempt.
 `Try alert` must work even when no flow has just paused so the user can verify browser sound and notification behavior.
 Safari may still require the user to manually set `Safari > Website Settings > Auto-Play > Allow All Auto-Play`; Chrome is the recommended browser for reliable repeated alert sound.
 
@@ -335,10 +351,11 @@ Task-level round state:
 - `Stop` moves the round into a 10 second settling window.
 - A new `UserPromptSubmit` inside the window continues the same round.
 - If no new prompt is accepted before the deadline, the round becomes `paused`.
-- The normal pause transition is timer-driven from the `Stop` event. Round-state reads also settle expired deadlines as a recovery fallback after restarts, sleep, or missed timers.
+- The pause transition is timer-driven from the `Stop` event. Round-state reads do not end a round.
+- Before pausing, VCM checks `.ai/vcm/handoffs/messages`; if a pending route message exists and can be delivered, VCM retries delivery and extends the settling window instead of alerting.
 - The same round state stores total round count, prompt-submit count, stop count, and Claude Code active runtime. Active runtime is measured only between `UserPromptSubmit` and `Stop`, not during the settling window.
 
-The frontend polls this task-level round state and deduplicates each paused round so the same paused state does not alert on every poll. Flow duration is measured from the first `UserPromptSubmit` to `pausedAt`, falling back to the last `Stop` when needed. Pauses under 10 minutes trigger the weak 3-chime reminder at 1.4 second intervals. Pauses at or above 10 minutes trigger the strong alert dialog and repeating sound until confirmation.
+The frontend polls this task-level round state and deduplicates each paused round so the same paused state does not alert on every poll. Flow duration is measured from the first `UserPromptSubmit` to `pausedAt`, falling back to the last `Stop` when needed. Pauses under 2 minutes trigger the weak 3-chime reminder at 1.4 second intervals. Pauses at or above 2 minutes trigger the strong alert dialog and repeating sound until confirmation.
 
 ## 9. Session Lifecycle
 
@@ -478,7 +495,7 @@ Default route policy:
 
 Stop-triggered scan:
 
-- VCM injects Claude Code `UserPromptSubmit` and `Stop` hooks into `.claude/settings.json`.
+- VCM injects Claude Code `UserPromptSubmit`, `Stop`, and `PermissionRequest` 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.
@@ -512,6 +529,7 @@ VCM Harness injects Claude Code hooks into `.claude/settings.json`:
 
 - `UserPromptSubmit`: posts directly to the VCM backend, marks the role running, and confirms any matching VCM message by recording `acceptedAt`
 - `Stop`: posts directly to the VCM backend, marks the role idle, and triggers pending route-file dispatch
+- `PermissionRequest`: posts directly to the VCM backend and prints the backend response to stdout so Claude Code can consume an allow decision when the local VCM setting is enabled
 
 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.
 
@@ -633,7 +651,32 @@ Translation panel `Auto-send` is separate from task `Auto orchestration`:
 
 Task `Auto orchestration` is a compact selected/unselected button in the role console toolbar. `Translate` is a global task header toggle next to `Close Task`; it opens/closes the translation split for all role consoles, so switching roles keeps the same translation setting.
 
-## 14. Local State
+## 14. Mobile Gateway
+
+VCM Gateway is a mobile Weixin DM bridge to the local desktop VCM instance.
+
+Gateway product rules:
+
+- DM only; group chat is not supported.
+- One mobile Weixin DM identity binds to one desktop VCM instance.
+- Binding is not tied to one project or one task.
+- The bound phone can select among the projects and tasks available to the
+  desktop VCM instance.
+- Plain mobile text is sent only to the current task's `project-manager`.
+- Gateway never sends directly to `architect`, `coder`, or `reviewer`.
+- Gateway can push PM assistant replies to Weixin whenever gateway is enabled,
+  even if that PM turn was started from desktop VCM.
+- When gateway translation is enabled, mobile Chinese input is translated to
+  English before PM receives it, and PM English replies are translated to
+  Chinese before Weixin receives them.
+- The PM prompt does not include the original Chinese text.
+- There is no multi-user allowlist. The security model is one bound DM identity.
+
+The first channel is Tencent iLink Bot API / Weixin DM. VCM uses QR login,
+`getupdates` long polling, and `sendmessage` text replies. Gateway details and
+implementation plan live in `docs/gateway-design.md`.
+
+## 15. Local State
 
 App-level settings:
 
@@ -644,9 +687,21 @@ App-level settings:
 Stored app-level settings include:
 
 - UI theme mode: `system`, `light`, or `dark`
+- flow pause alert preference
+- Claude Code permission request handling preference
 - translation provider settings and API key
 - recent repository paths
 
+Gateway state and audit logs:
+
+```text
+~/.vcm/gateway/settings.json
+~/.vcm/gateway/audit.jsonl
+```
+
+Gateway credentials, iLink tokens, DM binding identity, cursors, context tokens,
+and audit logs must stay outside connected repositories.
+
 Repository-level VCM state:
 
 ```text
@@ -682,7 +737,7 @@ External Claude transcripts:
 ~/.claude/projects/<project-hash>/<claude-session-id>.jsonl
 ```
 
-## 15. Packaging Expectations
+## 16. Packaging Expectations
 
 Published npm packages must include built output:
 
@@ -701,7 +756,7 @@ npm run build && npm run verify:package
 
 This protects against publishing raw TypeScript bin files or missing frontend assets.
 
-## 16. Success Criteria
+## 17. Success Criteria
 
 VCM V1 is successful when:
 
@@ -712,6 +767,7 @@ 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.
+- Sidebar settings include Claude Code permission request handling with `off` and `allow all`; `off` is the default.
 - 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.
@@ -719,6 +775,8 @@ VCM V1 is successful when:
 - 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.
+- Gateway can bind one Weixin DM identity to the desktop VCM instance, send
+  translated plain text to PM, and push translated PM replies back to Weixin.
 - Terminal and translation panel have equal, stable reading space.
 - Harness install/update preserves user content outside VCM managed blocks.
 - Completed tasks can cleanly remove their worktree and VCM task metadata without affecting other tasks.

package/docs/v0.2-implementation-plan.md

@@ -12,65 +12,80 @@ This document is an implementation plan, not a target-repository harness file.
 
 ## 1. Mobile Gateway Goal
 
-VCM 0.2 should let the user monitor and lightly control VCM from mobile Weixin
-direct messages.
-
-The gateway is a mobile command surface, not a remote terminal. It should help
-the user:
-
-- check current task status
-- see pending role messages or blockers
-- approve or reject confirmation-gated actions
-- send a short PM prompt
-- receive high-value notifications
-
-The first channel is Tencent iLink Bot API / Weixin DM.
+VCM 0.2 should let one mobile Weixin DM bind to one desktop VCM instance and
+talk to the current task's `project-manager` role.
+
+The detailed gateway product design and implementation plan lives in
+`docs/gateway-design.md`.
+
+Current decisions:
+
+- Support Weixin DM only. Group chat is not supported.
+- Bind one mobile Weixin DM identity to one desktop VCM instance.
+- Binding is not project-specific and not task-specific.
+- The bound phone can select among the projects and tasks available to the
+  desktop VCM instance.
+- Plain mobile text is sent only to the current task's `project-manager`.
+- Gateway never sends directly to `architect`, `coder`, or `reviewer`.
+- PM replies may be pushed to Weixin whenever gateway is enabled, even when the
+  PM turn was started from the desktop UI.
+- When translation is enabled, mobile Chinese input is translated to English
+  before PM sees it, and PM English replies are translated to Chinese before
+  Weixin sees them.
+- The prompt sent to PM does not include the original Chinese text.
+- There is no multi-user allowlist. The security model is one bound DM identity.
 
 ## 2. Gateway Non-Goals
 
 VCM 0.2 gateway should not:
 
-- expose the full embedded terminal over Weixin
-- promise ordinary Weixin group chat support
+- expose the embedded terminal over Weixin
+- support group chat
+- support multiple mobile users
 - store gateway credentials in the connected repository
-- let unauthenticated Weixin users control VCM
+- send directly to non-PM roles
+- run shell commands from gateway messages
+- provide approve/reject/start/stop workflow controls in the MVP
 - bypass existing backend task/session/orchestration services
 
 ## 3. Gateway Shape
 
 ```text
 Weixin mobile DM
-  -> Tencent iLink Bot API
+  -> Tencent iLink Bot API getupdates
   -> VCM gateway channel: weixin-ilink
-  -> Gateway command parser
-  -> Existing VCM backend services
-  -> Gateway reply / notification
+  -> bound identity check
+  -> command parser or PM message bridge
+  -> existing VCM backend services
+  -> Tencent iLink sendmessage
 ```
 
-The iLink channel should be outbound-first from the VCM process. It should
-long-poll iLink for direct messages and send replies through the iLink send API.
-This avoids requiring a public callback URL for the first gateway version.
+The iLink channel is outbound-first from the VCM process. It long-polls iLink
+for direct messages and sends replies through the iLink send API. This avoids a
+public callback URL for the first gateway version.
 
 Suggested backend files:
 
 ```text
+src/shared/types/gateway.ts
+
 src/backend/gateway/
   gateway-service.ts
   gateway-settings-service.ts
   gateway-command-parser.ts
-  gateway-audit-log.ts
+  gateway-pm-bridge.ts
   gateway-notifier.ts
+  gateway-audit-log.ts
   channels/
     weixin-ilink-channel.ts
 
 src/backend/api/gateway-routes.ts
-src/shared/types/gateway.ts
 ```
 
 Gateway settings and secrets must live in app-local state:
 
 ```text
-~/.vcm/settings.json
+~/.vcm/gateway/settings.json
 ~/.vcm/gateway/audit.jsonl
 ```
 
@@ -79,62 +94,57 @@ log, `.ai/vcm/**`, or PR text.
 
 ## 4. Gateway Command Surface
 
-Initial read-only commands:
+MVP commands:
 
 ```text
+/help
 /status
+/projects
+/use-project <index-or-path>
 /tasks
-/task <id>
-/pending
-/help
-```
-
-Initial state-changing commands:
-
-```text
-/pm <text>
-/approve <id>
-/reject <id>
-/pause <task>
-/resume <task>
+/use-task <index-or-task-slug>
+/translate on
+/translate off
 ```
 
-State-changing commands require:
+Plain text that does not start with `/` is treated as a PM message for the
+current task.
 
-- authenticated allowed Weixin user
-- command parsing into a known action
-- confirmation when destructive or high-risk
-- audit logging with secrets redacted
+## 5. Gateway Feasibility
 
-The gateway should call existing backend services instead of writing task files
-directly. `/pm <text>` should use the same safe submit semantics used by VCM's
-controlled session input path.
+The local reference implementation
+`/Users/sheldon/Documents/New project 3/weixin-ilink-gateway-test` proves the
+needed Tencent iLink primitives:
 
-## 5. Gateway Security
+- QR login through `ilink/bot/get_bot_qrcode`.
+- QR status polling through `ilink/bot/get_qrcode_status`.
+- Long-poll receive through `ilink/bot/getupdates`.
+- Text DM send through `ilink/bot/sendmessage`.
+- Token, cursor, and context-token persistence outside repositories.
+- Session-expiration handling through iLink error code `-14`.
 
-Treat gateway authorization and command parsing as high-risk code.
+VCM already has the other required primitives:
 
-Rules:
-
-- allowlist Weixin users
-- reject unknown users
-- deduplicate inbound iLink message ids
-- rate-limit command handling
-- redact secrets in logs
-- confirmation-gate destructive actions
-- never expose raw terminal write APIs to gateway commands
+- controlled terminal submission through backend PTY services
+- Claude Code `UserPromptSubmit` / `Stop` hooks
+- Claude transcript parsing
+- translation provider integration
+- project/task/session services
 
 ## 6. Gateway Acceptance
 
-Gateway is acceptable when:
-
-- an allowed Weixin user can DM `/status` and receive current VCM status
-- an unauthorized user is rejected and audited
-- `/tasks` and `/pending` return useful summaries
-- `/pm <text>` reaches PM through a controlled backend path
-- restart does not replay already handled iLink messages
-- credentials stay outside connected repos
-- state-changing commands are audited
+Gateway MVP is acceptable when:
+
+- desktop VCM can enable/disable gateway
+- desktop VCM can QR-bind one Weixin DM identity
+- the bound phone can DM `/status` and receive current VCM status
+- the bound phone can list and select current project/task context
+- the bound phone can send Chinese plain text to current task PM
+- PM receives only the translated English prompt, without original Chinese
+- gateway pushes PM assistant replies to Weixin whenever enabled
+- PM replies are translated to Chinese when gateway translation is enabled
+- restart does not replay already handled iLink messages or PM replies
+- credentials and audit logs stay outside connected repos
 
 ## 7. Full Harness Goal
 

package/docs/vcm-cc-best-practices.md

@@ -412,10 +412,24 @@ gateway-submitted prompts, and command authorization.
 VCM 0.2 gateway should expose a conservative mobile command surface through
 Tencent iLink Bot API / Weixin DM.
 
+Gateway product rules:
+
+- support Weixin DM only, not group chat
+- bind one mobile Weixin DM identity to one desktop VCM instance
+- do not bind gateway to a single project or task
+- let the bound phone select among the projects and tasks available to that VCM
+  instance
+- send ordinary mobile text only to the current task's `project-manager`
+- do not send gateway messages directly to architect, coder, or reviewer
+- when translation is enabled, send only translated English to PM and translated
+  Chinese back to Weixin
+- do not include the original Chinese text in PM prompts
+- use one bound DM identity; do not maintain a multi-user allowlist
+
 Gateway settings and secrets live in app-local state:
 
 ```text
-~/.vcm/settings.json
+~/.vcm/gateway/settings.json
 ```
 
 Gateway audit logs live outside connected repositories:
@@ -428,9 +442,9 @@ Rules:
 
 - do not expose the full embedded terminal over Weixin
 - do not store gateway credentials in connected repositories
-- authenticate and authorize allowed Weixin users
-- confirmation-gate state-changing or destructive commands
-- audit state-changing commands
+- reject or ignore messages outside the bound DM identity
+- keep the MVP PM-only and avoid approve/reject/start/stop workflow commands
+- audit gateway state changes and message handling with secrets redacted
 - treat gateway authorization and command parsing as high-risk code
 
 ## 16. Minimum VCM Rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [

package/scripts/install-vcm-harness.mjs

@@ -11,6 +11,7 @@ const MANIFEST_PATH = ".ai/vcm-harness-manifest.json";
 const HTML_BLOCK_PATTERN = /<!-- VCM:BEGIN(?:\s+version=\d+)? -->[\s\S]*?<!-- VCM:END -->/m;
 const HASH_BLOCK_PATTERN = /# VCM:BEGIN(?:\s+version=\d+)?\n[\s\S]*?# VCM:END/m;
 const VCM_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,event}));});'"'"' | curl -fsS --max-time 2 -X POST "\${VCM_API_URL}/api/hooks/claude-code" -H "content-type: application/json" --data-binary @- >/dev/null || true'`;
+const VCM_PERMISSION_REQUEST_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,event}));});'"'"' | curl -fsS --max-time 5 -X POST "\${VCM_API_URL}/api/hooks/claude-code/permission-request" -H "content-type: application/json" --data-binary @- || true'`;
 
 const AGENT_FRONTMATTER = {
   "project-manager": {
@@ -1480,14 +1481,14 @@ function mergeVcmHooks(settings) {
     }
   }
 
-  for (const eventName of ["UserPromptSubmit", "Stop"]) {
+  for (const eventName of ["UserPromptSubmit", "Stop", "PermissionRequest"]) {
     hooks[eventName] = [
       ...(Array.isArray(hooks[eventName]) ? hooks[eventName] : []),
       {
         hooks: [
           {
             type: "command",
-            command: VCM_HOOK_COMMAND,
+            command: eventName === "PermissionRequest" ? VCM_PERMISSION_REQUEST_HOOK_COMMAND : VCM_HOOK_COMMAND,
             timeout: 5
           }
         ]