vibe-coding-master 0.0.16 → 0.2.0

package/docs/full-harness-baseline.md

@@ -0,0 +1,254 @@
+# Full Harness Baseline
+
+Last updated: 2026-06-08
+
+Status: Temporary working document.
+
+This file tracks the current VCM 0.2 harness baseline as represented by
+`example/rust-layered`. It is not a broad inventory of the old
+`cc-best-practices.md` baseline.
+
+When the example stabilizes, migrate the durable decisions into
+`docs/vcm-cc-best-practices.md` and delete this file.
+
+## Current Principle
+
+VCM separates three kinds of files:
+
+- Harness-managed files: VCM owns, upgrades, repairs, and can uninstall these
+  through `.ai/vcm-harness-manifest.json`.
+- Project-owned durable docs: VCM bootstrap may create or initialize these, but
+  they become project truth and are not VCM-owned harness.
+- Runtime state: VCM writes these during task execution and deletes them during
+  task cleanup. Runtime files are not manifest entries.
+
+The manifest is a harness ownership and lifecycle record. It should include
+VCM-managed rules, agents, skills, settings merges, harness tools, generated
+context artifacts, PR template managed blocks, marker metadata, JSON ownership,
+lifecycle labels, runtime roots, and uninstall actions.
+
+The manifest should not list project-owned durable docs such as
+`docs/ARCHITECTURE.md`, `docs/TESTING.md`, `docs/known-issues.md`,
+`docs/plans/`, or module-level `ARCHITECTURE.md` files as managed entries. It
+should not list `.ai/vcm/**` runtime files as managed entries either.
+
+## Install And Bootstrap Flow
+
+VCM 0.2 uses a two-stage harness setup:
+
+1. Fixed install: VCM runs the deterministic fixed installer. This creates or
+   updates VCM-owned managed blocks, whole-file skills, role agents, settings
+   hooks, harness tools, generated-context directories, the PR template, and
+   `.ai/vcm-harness-manifest.json`.
+2. AI bootstrap: VCM starts a temporary Claude Code terminal in the repository
+   root and instructs it to use `vcm-harness-bootstrap`. This fills
+   project-owned content and generated artifacts.
+
+The fixed install does not copy example project content. It may create blank
+durable doc templates when missing, but project-specific facts are added only by
+bootstrap or by later role work.
+
+Bootstrap should produce or refresh:
+
+```text
+CLAUDE.md project context outside the VCM managed block
+docs/ARCHITECTURE.md
+<module>/ARCHITECTURE.md
+docs/TESTING.md
+.ai/generated/module-index.json
+.ai/generated/public-surface.json
+```
+
+Bootstrap runtime metadata is temporary:
+
+```text
+.ai/vcm/bootstrap/session.json
+.ai/vcm/bootstrap/bootstrap.log
+```
+
+These files are runtime state, not manifest entries. They can be deleted after
+the generated artifacts and durable docs are complete.
+
+## Current Manifest Entries
+
+These entries match the current `example/rust-layered/.ai/vcm-harness-manifest.json`.
+
+| Area | Path | Ownership | Lifecycle | Notes |
+| --- | --- | --- | --- | --- |
+| Manifest | `.ai/vcm-harness-manifest.json` | whole-file | Long-term | VCM harness ownership record. |
+| Root rules | `CLAUDE.md` | managed-block | Long-term | VCM HTML marker block only; project context outside the block is project-owned. |
+| Ignore rules | `.gitignore` | managed-block | Long-term | VCM hash-comment marker block. The example comments `.ai/vcm/` so readers can inspect runtime artifacts. |
+| Claude settings | `.claude/settings.json` | json-merge | Long-term | VCM owns hook entries matching VCM command markers. |
+| Agent directory | `.claude/agents/` | VCM-created directory | Long-term | Contains the four core VCM role agents. |
+| Core agent | `.claude/agents/project-manager.md` | managed-block | Long-term | Project-manager role rules. |
+| Core agent | `.claude/agents/architect.md` | managed-block | Long-term | Architect role rules. |
+| Core agent | `.claude/agents/coder.md` | managed-block | Long-term | Coder role rules. |
+| Core agent | `.claude/agents/reviewer.md` | managed-block | Long-term | Reviewer role rules. |
+| Skill directory | `.claude/skills/` | VCM-created directory | Conditional long-term | Keep while repo-local VCM skills are installed. |
+| Skill | `.claude/skills/vcm-route-message.md` | whole-file | Conditional long-term | Route-file authoring protocol. |
+| Skill | `.claude/skills/vcm-final-acceptance.md` | whole-file | Conditional long-term | PM final evidence audit. |
+| Skill | `.claude/skills/vcm-long-running-validation.md` | whole-file | Conditional long-term | Role-independent long-running command protocol. |
+| Skill | `.claude/skills/vcm-harness-bootstrap.md` | whole-file | Conditional long-term | AI-assisted project understanding procedure. |
+| Harness tool directory | `.ai/tools/` | VCM-created directory | Long-term | Repo-local harness tools. |
+| Generated-context tool | `.ai/tools/generate-module-index` | whole-file | Long-term | Generates `.ai/generated/module-index.json`. |
+| Generated-context tool | `.ai/tools/generate-public-surface` | whole-file | Long-term | Generates `.ai/generated/public-surface.json`. |
+| Runtime tool | `.ai/tools/run-long-check` | whole-file | Conditional long-term | Starts file-backed long-running command jobs. |
+| Runtime tool | `.ai/tools/watch-job` | whole-file | Conditional long-term | Bounded watcher for long-running command jobs. |
+| Generated context directory | `.ai/generated/` | VCM-created directory | Long-term | Derived context artifacts. |
+| Generated context | `.ai/generated/module-index.json` | derived artifact | Derived | Regenerated by `generate-module-index`; do not hand-edit as source truth. |
+| Generated context | `.ai/generated/public-surface.json` | derived artifact | Derived | Regenerated by `generate-public-surface`; do not hand-edit as source truth. |
+| PR template | `.github/pull_request_template.md` | managed-block | Long-term | VCM PR checklist block. |
+
+Runtime roots recorded by the manifest:
+
+```text
+.ai/vcm/
+.claude/worktrees/
+```
+
+These roots are cleanup targets, not managed entries.
+
+## Project-Owned Bootstrap Outputs
+
+The current example includes project-owned durable docs created or initialized
+during harness bootstrap. They are important for the workflow, but they are not
+VCM-owned harness and should not appear as manifest entries.
+
+| Area | Path | Owner | Lifecycle | Notes |
+| --- | --- | --- | --- | --- |
+| Project context | `CLAUDE.md` content outside VCM block | Project | Long-term | Rust-layered project facts and constraints. |
+| Project architecture | `docs/ARCHITECTURE.md` | Architect | Long-term | Project-level module overview, responsibilities, relationships, dependency direction, and links to module docs. |
+| Module architecture | `<module>/ARCHITECTURE.md` | Architect | Long-term | Module-level boundaries, behavior, important public surface explanations, and risks. |
+| Testing docs | `docs/TESTING.md` | Reviewer | Long-term | Validation levels, Rust commands, generated-context freshness checks, and testing gaps. |
+| Known issues | `docs/known-issues.md` | Architect | Rolling durable doc | Confirmed unresolved issues and accepted limitations. Remove fixed, rejected, or obsolete entries. |
+| Durable plans | `docs/plans/` | Project | Conditional long-term | Durable plans only when a large task needs them. Completed routine plans should be deleted after durable facts are promoted. |
+
+Current `example/rust-layered` does not use these old separate docs:
+
+```text
+docs/MODULE_MAP.md
+docs/SECURITY.md
+docs/DEPENDENCY_RULES.md
+docs/AI_WORKFLOW.md
+```
+
+## Runtime State
+
+Runtime state is created while VCM manages a task. It is task-local and should be
+deleted during task cleanup after useful facts are promoted to code, tests,
+durable docs, PR text, or commit history.
+
+| Area | Path | Lifecycle | Notes |
+| --- | --- | --- | --- |
+| Worktrees | `.claude/worktrees/<task-slug>/` | Runtime cleanup | One task worktree shared by all roles. |
+| Handoff root | `.ai/vcm/handoffs/` | Runtime cleanup | Role artifacts and route files for the active task. |
+| Route messages | `.ai/vcm/handoffs/messages/<from-role>-<to-role>.md` | Runtime cleanup | Pending route files written by `vcm-route-message`. |
+| Handoff logs | `.ai/vcm/handoffs/logs/` | Runtime cleanup | Debug/recovery logs, not durable project truth. |
+| Architecture plan | `.ai/vcm/handoffs/architecture-plan.md` | Task-temporary | Architect handoff for one executable task. |
+| Review report | `.ai/vcm/handoffs/review-report.md` | Task-temporary | Reviewer handoff for one executable task. |
+| Docs sync report | `.ai/vcm/handoffs/docs-sync-report.md` | Task-temporary | Architect docs-sync handoff for one executable task. |
+| Final acceptance | `.ai/vcm/handoffs/final-acceptance.md` | Task-temporary | PM final evidence-audit handoff for one executable task. |
+| Task known issues | `.ai/vcm/handoffs/known-issues.md` | Task-temporary | Promote unresolved durable findings to `docs/known-issues.md`, then delete. |
+| Long-running jobs | `.ai/vcm/jobs/<job-id>/` | Runtime cleanup | Status and logs from `run-long-check` / `watch-job`. |
+| Bootstrap session | `.ai/vcm/bootstrap/session.json` | Runtime cleanup | Last harness-bootstrap terminal metadata. |
+| Bootstrap log | `.ai/vcm/bootstrap/bootstrap.log` | Runtime cleanup | Terminal log for the harness-bootstrap session. |
+| App-local task records | `~/.vcm/projects/<project-id>/tasks/<task-slug>.json` | Runtime cleanup | VCM UI/lifecycle subtask records outside the connected repo. |
+
+Runtime state under `.ai/vcm/**` is excluded from manifest entries. The manifest
+records `.ai/vcm/` only as a runtime root.
+
+## Current Skills
+
+The current example installs these skills:
+
+- `vcm-route-message`: route-file write protocol.
+- `vcm-final-acceptance`: final PM evidence audit.
+- `vcm-long-running-validation`: role-independent long-running command protocol.
+- `vcm-harness-bootstrap`: one-time or occasional project-understanding, generated-context refresh, and durable-doc bootstrap procedure.
+
+The current example does not install a separate `vcm-docs-sync` skill. Docs sync
+is expressed in the architect role rules and writes
+`.ai/vcm/handoffs/docs-sync-report.md`.
+
+## Current Tools
+
+The current example keeps only four `.ai/tools/` files:
+
+```text
+.ai/tools/generate-module-index
+.ai/tools/generate-public-surface
+.ai/tools/run-long-check
+.ai/tools/watch-job
+```
+
+The generated-context tools currently support Rust projects only. The fixed
+installer may install them as the default Rust baseline, but non-Rust projects
+need project-specific generators before `.ai/generated/*` can be trusted.
+
+The current example intentionally does not install these old validation or
+discovery wrappers:
+
+```text
+.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/check-generated-artifacts
+.ai/tools/find-owner
+.ai/tools/find-callers
+.ai/tools/find-tests
+```
+
+Rust unit tests and integration tests are run with native Cargo commands chosen
+by the responsible role. The harness does not need a fixed wrapper for every
+validation level.
+
+## Generated Context
+
+The current example has two generated artifacts:
+
+```text
+.ai/generated/module-index.json
+.ai/generated/public-surface.json
+```
+
+Current support is Rust-only:
+
+- `generate-module-index` reads Cargo workspace structure, auto-detects a
+  direct child `cargoRoot` when the project root has no `Cargo.toml`, and
+  filters workspace member paths that do not contain a crate.
+- `generate-public-surface` indexes crate-external Rust `pub fn`,
+  `pub struct`, `pub enum`, and `pub trait` items, using `pub use` only to
+  resolve re-exported high-value API entries.
+
+There is no `test-map.json`. Test files are discoverable through
+`module-index.json` and Rust's normal Cargo test layout.
+
+Generated artifacts are derived context, not durable project truth. They must be
+regenerated by their tools after relevant source, manifest, module, or public API
+changes.
+
+## Not Part Of The Current Example
+
+The following items are intentionally not part of the current `rust-layered`
+baseline:
+
+```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
+```
+
+Do not reintroduce these into the example baseline unless there is a specific,
+current VCM requirement.

package/docs/product-design.md

@@ -1,6 +1,6 @@
 # VibeCodingMaster Product Design
 
-Last updated: 2026-05-31
+Last updated: 2026-06-02
 
 This document describes the current product direction and implemented V1 behavior for VCM.
 
@@ -163,7 +163,7 @@ The architect owns:
 - module boundaries
 - file responsibilities
 - public contracts
-- test contracts
+- verifiable behavior and behavior/contract proof points
 - Replan triggers
 - post-review docs sync and architecture drift checks
 
@@ -179,12 +179,10 @@ The coder owns:
 - implementation within the approved plan
 - direct unit/contract/regression tests
 - validation evidence
-- implementation log
 
 Outputs:
 
-- `.ai/vcm/handoffs/implementation-log.md`
-- `.ai/vcm/handoffs/validation-log.md`
+- `.ai/vcm/handoffs/known-issues.md`
 
 ### Reviewer
 
@@ -199,6 +197,7 @@ The reviewer owns:
 Output:
 
 - `.ai/vcm/handoffs/review-report.md`
+- `.ai/vcm/handoffs/known-issues.md`
 
 ## 6. Information Architecture
 
@@ -253,7 +252,7 @@ The default theme mode is `System`, which follows the OS/browser color-scheme pr
 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`.
+There is no separate `Pause orchestration` or `Resume orchestration` control in the GUI. The current product model is one on/off toggle in the role console toolbar.
 
 `VCM Harness` shows whether VCM managed blocks are installed/up to date in the project rules files and `.gitignore`.
 
@@ -274,9 +273,13 @@ The worktree/branch path is the recommended VCM task model, but the user may cle
 The task workspace header is one compact row:
 
 ```text
-TASK WORKSPACE  <task>  <branch>  <worktree>   [Project Manager] [Architect] [Coder] [Reviewer] [Refresh]
+<task>  [Project Manager] [Architect] [Coder] [Reviewer]  [Translate] [Close Task]
 ```
 
+The header does not show `TASK WORKSPACE`, branch, or worktree path. Task branch/worktree details remain task metadata, but they are not first-row chrome.
+
+The task workspace does not show a manual `Refresh` button. Task status, role status, messages, orchestration state, and round completion state refresh automatically. The only remaining `Refresh` control is inside the sidebar `VCM Harness` section, where it rechecks managed project files.
+
 Role tabs show the session status for each role.
 
 The main task workspace only renders the active role console. Messages and Events are opened from the sidebar.
@@ -292,7 +295,6 @@ Controls:
 - `Resume`.
 - `Restart`.
 - `Stop`.
-- `Translate` toggle.
 
 Permission modes:
 
@@ -316,7 +318,7 @@ The split should stay close to 50/50 width. Both panes expand vertically to fill
 
 ## 8. Round Completion Detection
 
-VCM detects answer completion from VCM's hook-driven role activity state, not from terminal silence.
+VCM detects answer completion from VCM's hook-driven role activity state, not from terminal silence or message history.
 
 Backend role state:
 
@@ -326,10 +328,10 @@ Backend role state:
 
 Task-level round state:
 
-- 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.
+- The latest role with a real hook `Stop` is the completion source when no role is still running.
+- A PM -> Coder -> PM chain completes only when the final role, PM, reaches hook `Stop`.
+- Pending route files prevent completion because more role work is waiting, but message history does not define completion.
+- If no VCM role message is involved, the latest direct role `Stop` can still complete the round.
 
 The frontend polls this task-level round state. It deduplicates `completionId`, then shows the prompt and plays the sound only once per completed round.
 
@@ -419,8 +421,7 @@ Each task creates:
     coder.log
     reviewer.log
   architecture-plan.md
-  implementation-log.md
-  validation-log.md
+  known-issues.md
   review-report.md
   docs-sync-report.md
   messages/
@@ -481,32 +482,34 @@ Stop-triggered scan:
 
 Manual mode:
 
-- message status becomes `pending_approval` when the target role is running
+- role route files stay non-empty as pending handoffs
 - user opens `Messages`
-- message rows show sequence, timestamp, status, body preview, path, and `Copy`
-- `Mark All Done` marks open message records as `acknowledged` after the user manually handled stuck messages
+- message rows show newest delivered history first with stable increasing sequence, timestamp, body preview, path, and `Copy`
+- `Mark All Done` clears pending route files after the user manually handled stuck handoff content
+- `Delete All` removes message history without touching pending route files
 - 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 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 running and hook-idle, VCM writes a `[VCM MESSAGE]` envelope to that role's embedded terminal and submits Enter
+- before writing to the terminal, VCM stores `dispatchingAt` and waits briefly so the GUI can switch to the target role tab first
+- terminal write success stores a durable delivered message snapshot
+- Claude Code `UserPromptSubmit` confirms the accepted prompt, stores `acceptedAt`, 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
+- when VCM records `dispatchingAt`, the GUI switches to the target role tab so the user can watch the terminal receive and execute the message
 - 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.
+- `Mark All Done` is a manual recovery action for stuck orchestration. It clears 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`: posts directly to the VCM backend, marks the role running, and confirms any matching VCM message from `delivering` to `submitted`
+- `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
 
 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 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 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 should use `.claude/skills/vcm-route-message.md` to author route files. Roles must not poll files, start shell loops, keep the turn open waiting for another role to answer, paste directly into another role terminal, or use Claude Code Task/Subagent for VCM role delegation.
 
 There is no `vcmctl` in the target design. Hook entrypoints are direct HTTP from Claude Code hooks to the local VCM backend.
 
@@ -540,7 +543,7 @@ Prompt slots:
 - `zh-to-en-with-context`
 - `en-to-zh`
 
-The settings modal shows all three prompt slots as direct editors. `Reset prompts` restores every prompt to its built-in default. The modal does not include separate enable/output/input-mode switches; opening the role toolbar `Translate` panel is the translation on/off control, and the panel-level `Auto-send` toggle controls whether translated user input is submitted automatically.
+The settings modal shows all three prompt slots as direct editors. `Reset prompts` restores every prompt to its built-in default. The modal does not include separate enable/output/input-mode switches; opening the task header `Translate` panel is the translation on/off control, and the panel-level `Auto-send` toggle controls whether translated user input is submitted automatically.
 
 ### Claude Output Translation
 
@@ -606,7 +609,7 @@ Translation panel `Auto-send` is separate from task `Auto orchestration`:
 - `Auto-send` on: translate and send if there is no translation warning.
 - `Auto-send` off: translate to English draft and wait for user send.
 
-Task `Auto orchestration` is an adjacent toolbar button to the left of `Translate` and uses the same compact selected/unselected button styling.
+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
 
@@ -690,7 +693,7 @@ VCM V1 is successful when:
 - 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.
+- Auto orchestration switches to the target role tab when VCM records `dispatchingAt`, before VCM submits the 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.