vibe-coding-master 0.4.42 → 0.5.1

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

@@ -1,408 +0,0 @@
-# VCM 0.2 Implementation Plan
-
-Last updated: 2026-06-10
-
-> Archived historical plan. This document records the 0.2 design context and is
-> not the current implementation reference. For current behavior, use
-> `README.md`, `docs/gateway-design.md`, and `docs/full-harness-baseline.md`.
-
-VCM 0.2 has two product tracks:
-
-- Mobile gateway through Tencent iLink Bot API / Weixin DM.
-- Full harness initialization based on the current `example/rust-layered`
-  baseline.
-
-This document is an implementation plan, not a target-repository harness file.
-
-## 1. Mobile Gateway Goal
-
-VCM 0.2 should let one mobile Weixin DM bind to one desktop VCM instance,
-manage the basic task lifecycle, 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.
-- The bound phone can pull the selected connected base repo through VCM's
-  fast-forward-only connected repository pull path.
-- The bound phone can create a worktree-backed task and ask VCM to initialize it
-  through the saved launch template.
-- The bound phone can close a completed task through VCM's Close Task cleanup
-  path after explicit confirmation.
-- 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 embedded terminal over Weixin
-- support group chat
-- support multiple mobile users
-- store gateway credentials in the connected repository
-- send directly to non-PM roles
-- run shell commands from gateway messages
-- provide approve/reject gates, arbitrary role-specific start/stop controls, or
-  shell execution in the MVP
-- bypass existing backend task/session/orchestration services
-
-## 3. Gateway Shape
-
-```text
-Weixin mobile DM
-  -> Tencent iLink Bot API getupdates
-  -> VCM gateway channel: weixin-ilink
-  -> bound identity check
-  -> command parser or PM message bridge
-  -> existing VCM backend services
-  -> Tencent iLink sendmessage
-```
-
-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.
-
-Implemented 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
-  channels/
-    weixin-ilink-channel.ts
-
-src/backend/api/gateway-routes.ts
-```
-
-Gateway settings and secrets must live in app-local state:
-
-```text
-<vcmDataDir>/gateway/settings.json
-<vcmDataDir>/gateway/audit.jsonl
-```
-
-Gateway credentials must never be written to a connected repository, terminal
-log, `.ai/vcm/**`, or PR text.
-
-## 4. Gateway Command Surface
-
-MVP commands:
-
-```text
-/help
-/status
-/projects
-/use-project <index-or-path>
-/pull-current
-/tasks
-/use-task <index-or-task-slug>
-/create-task <task-slug> [title]
-/close-task
-/close-task confirm <task-slug>
-/translate on
-/translate off
-```
-
-Plain text that does not start with `/` is treated as a PM message for the
-current task.
-
-## 5. Gateway Feasibility
-
-The local reference implementation
-`/Users/sheldon/Documents/New project 3/weixin-ilink-gateway-test` proves the
-needed Tencent iLink primitives:
-
-- 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`.
-
-VCM already has the other required primitives:
-
-- 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 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 run `/pull-current` to update the connected base repo
-- the bound phone can run `/create-task <task-slug> [title]` to create a task
-  and start four role sessions through the saved launch template
-- 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
-- the bound phone can close a completed task through `/close-task` and exact
-  slug confirmation
-- restart does not replay already handled iLink messages or PM replies
-- credentials and audit logs stay outside connected repos
-
-## 7. Full Harness Goal
-
-Full harness initialization should create the current `example/rust-layered`
-baseline, not the older broad `cc-best-practices.md` inventory.
-
-The goal is a practical VCM harness:
-
-- four core role agents
-- concise root `CLAUDE.md` VCM block
-- repo-local VCM skills
-- manifest-managed harness ownership
-- generated context tools
-- generated context artifacts
-- long-running command helper scripts
-- project-owned durable docs created or initialized by bootstrap
-- runtime state kept temporary and cleanable
-
-## 8. Current Target Harness Shape
-
-Fixed installer files:
-
-```text
-CLAUDE.md
-.gitignore
-.claude/settings.json
-.claude/agents/project-manager.md
-.claude/agents/architect.md
-.claude/agents/coder.md
-.claude/agents/reviewer.md
-.claude/skills/vcm-route-message/SKILL.md
-.claude/skills/vcm-final-acceptance/SKILL.md
-.claude/skills/vcm-long-running-validation/SKILL.md
-.claude/skills/vcm-harness-bootstrap/SKILL.md
-.ai/vcm-harness-manifest.json
-.ai/tools/generate-module-index
-.ai/tools/generate-public-surface
-.ai/tools/run-long-check
-.ai/tools/watch-job
-.github/pull_request_template.md
-```
-
-Derived bootstrap artifacts:
-
-```text
-.ai/generated/module-index.json
-.ai/generated/public-surface.json
-```
-
-Generated context is Rust-only for VCM 0.2. The fixed installer installs the
-Rust `generate-module-index` and `generate-public-surface` tools, but it does
-not generate trusted context by itself and does not promise generated-context
-support for non-Rust projects.
-
-Project-owned bootstrap outputs:
-
-```text
-docs/ARCHITECTURE.md
-<module>/ARCHITECTURE.md
-docs/TESTING.md
-docs/known-issues.md
-docs/plans/
-```
-
-Runtime roots:
-
-```text
-.ai/vcm/
-.claude/worktrees/
-```
-
-Explicitly not part of the current target:
-
-```text
-.claude/commands/
-.claude/agents/optional/
-.ai/task-specs/
-.ai/vcm/tasks/
-.ai/vcm/handoffs/role-commands/
-docs/plans/active/
-docs/plans/completed/
-docs/MODULE_MAP.md
-docs/SECURITY.md
-docs/DEPENDENCY_RULES.md
-docs/AI_WORKFLOW.md
-.ai/generated/test-map.json
-.ai/tools/check-fast
-.ai/tools/check-changed
-.ai/tools/check-module
-.ai/tools/check-boundaries
-.ai/tools/check-agent-rules
-.ai/tools/check-docs-freshness
-.ai/tools/find-owner
-.ai/tools/find-callers
-.ai/tools/find-tests
-```
-
-## 9. Harness Manifest
-
-Full harness initialization writes:
-
-```text
-.ai/vcm-harness-manifest.json
-```
-
-The manifest records harness ownership only. It should include:
-
-- VCM-managed files and directories
-- marker type and marker boundaries
-- JSON merge ownership
-- VCM agents and skills
-- harness tools
-- derived generated artifacts
-- runtime roots
-- lifecycle labels
-- uninstall actions
-
-It should not include:
-
-- project-owned durable docs
-- module-level `ARCHITECTURE.md`
-- `.ai/vcm/**` runtime files
-- `.claude/worktrees/**`
-- `.gitkeep`
-
-## 10. AI-Assisted Bootstrap
-
-The deterministic installer owns:
-
-- managed block writes
-- `.claude/settings.json` merge
-- manifest creation and migration
-- skill and agent file installation
-- tool file installation
-- generated directory creation
-- uninstall behavior
-
-The `vcm-harness-bootstrap` skill owns AI-assisted project understanding. It may
-draft or refresh:
-
-- `CLAUDE.md` project context outside the VCM managed block
-- `docs/ARCHITECTURE.md`
-- module-level `ARCHITECTURE.md`
-- `docs/TESTING.md`
-- `docs/known-issues.md`
-- `.ai/generated/module-index.json`
-- `.ai/generated/public-surface.json`
-
-It must not edit product source, product tests, package manifests, lockfiles,
-deployment config, or secrets. It must not create new validation wrapper tools
-during bootstrap.
-
-VCM UI startup flow:
-
-1. User connects a repository.
-2. User runs fixed harness install/update from the VCM Harness panel.
-3. Backend runs `scripts/install-vcm-harness.mjs <repo-root>` and records the
-   deterministic result in the UI.
-4. Backend recomputes bootstrap checks: fixed harness, `CLAUDE.md` project
-   context, generated context, project architecture doc, module architecture
-   docs, and testing doc.
-5. User starts harness bootstrap from the UI when fixed harness is ready.
-6. Backend starts one temporary Claude Code terminal in the repository root,
-   without a role agent, and sends a prompt requiring use of the
-   `vcm-harness-bootstrap` skill.
-7. Backend passes bootstrap environment variables:
-   `VCM_TASK_REPO_ROOT`, `VCM_HARNESS_BOOTSTRAP=1`, `VCM_SESSION_ID`, and
-   `VCM_API_URL`.
-8. Bootstrap terminal output is shown in the VCM UI. Session metadata is stored
-   in `.ai/vcm/bootstrap/session.json`; terminal output is logged to
-   `.ai/vcm/bootstrap/bootstrap.log`.
-9. User refreshes harness status after the bootstrap session finishes. The
-   bootstrap is complete only when all checks are `ok`.
-
-The bootstrap terminal is deliberately visible and resumable. If the terminal
-process disappears before the files are complete, VCM should report the previous
-session as resumable and allow the user to start bootstrap again or finish the
-remaining files manually.
-
-## 11. Runtime Cleanup
-
-Runtime files under `.ai/vcm/**` are not manifest entries. They are deleted
-during task cleanup after useful facts are promoted.
-
-Task records live outside connected repos:
-
-```text
-<vcmDataDir>/projects/<project-id>/tasks/<task-slug>.json
-```
-
-Routine completed task plans should not be archived under
-`docs/plans/completed/`. Durable facts should move into durable docs, code,
-tests, PR text, or commit history; temporary task files should be deleted.
-
-## 12. Harness Implementation Phases
-
-Phase 1: Deterministic skeleton
-
-- install/update managed VCM blocks
-- install four role agents
-- install four VCM skills
-- install `.ai/tools/` scripts
-- create `.ai/generated/`
-- create `.ai/vcm-harness-manifest.json`
-- create/update `.github/pull_request_template.md`
-- do not write project-specific generated context or durable doc content
-
-Phase 2: Rust generated context
-
-- implement or refine `generate-module-index`
-- implement or refine `generate-public-surface`
-- generate `.ai/generated/module-index.json`
-- generate `.ai/generated/public-surface.json`
-- support `--check` freshness mode
-- treat non-Rust generated context as unsupported until project-specific
-  generators are added
-
-Phase 3: AI-assisted project docs
-
-- use `vcm-harness-bootstrap`
-- create or refresh project-owned durable docs
-- mark unknowns and needs-human-confirmation
-
-Phase 4: Cleanup and acceptance
-
-- keep temporary docs deleted and durable docs updated
-- verify generated context freshness when relevant
-- report any deterministic VCM upgrade needs as implementation follow-up
-
-## 13. Full Harness Acceptance
-
-Full harness initialization is acceptable when:
-
-- manifest records only harness-managed entries
-- project durable docs are not manifest entries
-- `.ai/vcm/**` runtime files are not manifest entries
-- generated context has real generator tools
-- no fixed `check-*` wrapper is installed by default
-- no `test-map.json` is installed by default
-- no `.claude/commands/`, optional agents, role-commands, or repo-local task
-  records are installed by default
-- `example/rust-layered` and generated templates agree on the same baseline