vibe-coding-master 0.0.16 → 0.2.0

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

@@ -0,0 +1,379 @@
+# VCM 0.2 Implementation Plan
+
+Last updated: 2026-06-08
+
+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 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.
+
+## 2. Gateway Non-Goals
+
+VCM 0.2 gateway should not:
+
+- expose the full embedded terminal over Weixin
+- promise ordinary Weixin group chat support
+- store gateway credentials in the connected repository
+- let unauthenticated Weixin users control VCM
+- bypass existing backend task/session/orchestration services
+
+## 3. Gateway Shape
+
+```text
+Weixin mobile DM
+  -> Tencent iLink Bot API
+  -> VCM gateway channel: weixin-ilink
+  -> Gateway command parser
+  -> Existing VCM backend services
+  -> Gateway reply / notification
+```
+
+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.
+
+Suggested backend files:
+
+```text
+src/backend/gateway/
+  gateway-service.ts
+  gateway-settings-service.ts
+  gateway-command-parser.ts
+  gateway-audit-log.ts
+  gateway-notifier.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/audit.jsonl
+```
+
+Gateway credentials must never be written to a connected repository, terminal
+log, `.ai/vcm/**`, or PR text.
+
+## 4. Gateway Command Surface
+
+Initial read-only commands:
+
+```text
+/status
+/tasks
+/task <id>
+/pending
+/help
+```
+
+Initial state-changing commands:
+
+```text
+/pm <text>
+/approve <id>
+/reject <id>
+/pause <task>
+/resume <task>
+```
+
+State-changing commands require:
+
+- authenticated allowed Weixin user
+- command parsing into a known action
+- confirmation when destructive or high-risk
+- audit logging with secrets redacted
+
+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.
+
+## 5. Gateway Security
+
+Treat gateway authorization and command parsing as high-risk code.
+
+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
+
+## 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
+
+## 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.md
+.claude/skills/vcm-final-acceptance.md
+.claude/skills/vcm-long-running-validation.md
+.claude/skills/vcm-harness-bootstrap.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
+~/.vcm/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