vibe-coding-master 0.0.17 → 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.
+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`.
 
@@ -279,6 +278,8 @@ The task workspace header is one compact row:
 
 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.
@@ -420,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/
@@ -509,7 +509,7 @@ VCM Harness injects Claude Code hooks into `.claude/settings.json`:
 
 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.