vibe-coding-master 0.4.41 → 0.5.0

package/docs/v0.4-harness-optimization-plan.md

@@ -1,664 +0,0 @@
-# VCM 0.4 Harness Optimization Plan
-
-Last updated: 2026-06-22
-
-This document defines the VCM 0.4 product plan.
-
-The original VCM 0.4 custom workflow engine plan has moved to
-`docs/v0.5-custom-workflow-plan.md`. VCM 0.4 will focus on the current fixed
-workflow, project harness quality, and visual harness configuration.
-
-## 1. Product Goal
-
-VCM 0.4 should make the existing VCM workflow easier to understand, tune, and
-improve without requiring a fully free custom workflow engine.
-
-The current workflow remains the default product shape:
-
-```text
-project-manager
-  -> architect
-  -> coder
-  -> reviewer
-  -> architect
-  -> project-manager
-```
-
-Optional project-level tool roles, such as Translator, stay outside the core
-chain unless VCM explicitly routes work to them. Gate Reviewer is an optional
-task-scoped VCM flow role.
-
-The target outcome:
-
-- users can inspect all VCM harness content from the UI
-- users can adjust role definitions, skills, and project harness settings safely
-- users can ask a dedicated Harness Engineer to improve project harness quality
-- every proposed harness change is shown as a diff before it is applied
-- VCM fixed managed blocks remain protected
-- VCM product or template problems can be reported upstream as GitHub issues
-- the current workflow becomes more reliable without adding arbitrary workflow
-  graph editing in 0.4
-
-## 2. Scope Decision
-
-VCM 0.4 is not the free custom workflow release.
-
-The previous custom workflow plan is still valuable, but it is too large for the
-next release because it requires a workflow engine, node model, branch
-conditions, artifact contracts, graph editing, workflow run state, and migration
-rules.
-
-VCM 0.4 should instead be:
-
-```text
-Harness Engineer + Harness Studio
-```
-
-This gives users direct control over the system they already use every day:
-roles, skills, managed blocks, project instructions, session defaults, and
-harness update flow.
-
-## 3. Non-Goals
-
-VCM 0.4 should not:
-
-- build a general workflow graph editor
-- replace the current fixed VCM role chain
-- allow arbitrary user-defined workflow nodes
-- allow AI to silently edit harness files
-- let any role overwrite VCM fixed managed blocks
-- make auxiliary roles part of the main task flow by default
-- submit external GitHub issues without explicit user confirmation
-- require users to understand Claude Code hook internals
-
-## 4. Core Concepts
-
-### 4.1 Fixed Harness
-
-Fixed harness content is VCM-owned template content installed into a project.
-It includes managed blocks in files such as:
-
-- `CLAUDE.md`
-- `.claude/agents/project-manager.md`
-- `.claude/agents/architect.md`
-- `.claude/agents/coder.md`
-- `.claude/agents/reviewer.md`
-- `.claude/agents/gate-reviewer.md`
-- `.claude/agents/translator.md`
-- `.claude/skills/*/SKILL.md`
-- `.ai/tools/*`
-- `.ai/vcm-harness-manifest.json`
-
-VCM fixed content is updated by VCM releases and the harness installer. It must
-remain deterministic and recoverable.
-
-### 4.2 Project Harness Customization
-
-Project harness customization is repository-specific guidance layered around
-VCM fixed content.
-
-Examples:
-
-- project coding rules
-- domain terminology
-- repository-specific testing commands
-- module boundaries
-- review preferences
-- role behavior tweaks
-- scaffold conventions
-- project-specific validation expectations
-
-Project harness customization is the primary editable surface for VCM 0.4.
-
-### 4.3 Harness Engineer
-
-`harness-engineer` is a project-scoped Claude Code tool role.
-
-It understands:
-
-- VCM fixed harness rules
-- project-specific harness content
-- role definitions
-- skills
-- project docs
-- harness manifest state
-- the boundary between VCM product defects and project harness defects
-
-It helps users improve the harness, but it is not part of the task workflow
-round state.
-
-## 5. Harness Engineer Role
-
-### 5.1 Role Identity
-
-Recommended role id:
-
-```text
-harness-engineer
-```
-
-Recommended display name:
-
-```text
-Harness Engineer
-```
-
-The role should be project-scoped, not task-scoped.
-
-Session behavior:
-
-- one long-lived session per project
-- default action is resume existing session
-- restart is available from the Harness Engineer session panel
-- closing a task does not stop this role
-- this role does not keep a VCM task round running
-- this role can be opened from Harness Studio
-
-### 5.2 Responsibilities
-
-Harness Engineer is responsible for:
-
-- reading current project harness files
-- understanding VCM fixed harness constraints
-- accepting user feedback about role behavior or harness quality
-- diagnosing whether a problem is project-specific or VCM-level
-- proposing harness changes as reviewable diffs
-- explaining the impact of proposed changes
-- identifying which active sessions may need restart or a reminder
-- helping the user keep harness content concise and consistent
-- drafting VCM GitHub issues for product or template problems
-
-### 5.3 Boundaries
-
-Harness Engineer must not:
-
-- silently apply changes
-- edit business source code as part of harness maintenance
-- overwrite VCM fixed managed blocks
-- submit GitHub issues without user confirmation
-- include private project code, logs, or secrets in an upstream issue
-- modify task workflow state
-- act as PM, Architect, Coder, Reviewer, Gate Reviewer, or Translator
-
-### 5.4 Allowed Files
-
-Harness Engineer may inspect:
-
-- `CLAUDE.md`
-- `.claude/agents/**`
-- `.claude/skills/**`
-- `.ai/tools/**`
-- `.ai/vcm-harness-manifest.json`
-- `.ai/generated/**`
-- project docs such as `docs/ARCHITECTURE.md` and `docs/TESTING.md`
-- VCM state relevant to harness status
-
-Harness Engineer may propose edits to:
-
-- project-editable harness sections
-- role files outside protected fixed managed blocks
-- project docs used by harness
-- project-specific skill guidance when allowed
-
-Harness Engineer may not directly edit VCM fixed managed blocks. If it finds a
-fixed block problem, it should create a VCM issue draft instead.
-
-## 6. Harness Studio UI
-
-VCM 0.4 should add a Harness Studio UI for inspecting and configuring harness
-content.
-
-### 6.1 Entry Point
-
-The existing VCM Harness sidebar group can become the entry point.
-
-Recommended actions:
-
-- Open Harness Studio
-- Refresh harness status
-- Apply fixed harness update
-- Run bootstrap
-- Review latest harness commit diff
-- Open Harness Engineer session
-
-### 6.2 Main Views
-
-Harness Studio should include:
-
-- Overview
-- Agents
-- Skills
-- Root Context
-- Project Docs
-- Tools
-- Harness Status
-- Proposed Changes
-- VCM Feedback
-
-### 6.3 Overview
-
-Overview should show:
-
-- fixed harness status
-- bootstrap status
-- modified harness files
-- outdated managed blocks
-- missing expected files
-- latest harness commit status
-- Harness Engineer session status
-- recent harness actions
-
-### 6.4 Agents
-
-Agents view should show:
-
-- Project Manager
-- Architect
-- Coder
-- Reviewer
-- Gate Reviewer
-- Translator
-- Harness Engineer
-
-For each agent:
-
-- file path
-- role type: core, optional flow role, or tool role
-- session scope: task or project
-- managed block status
-- editable project section
-- default model
-- default effort
-- permission mode
-- restart requirement after changes
-
-The UI should make role type visible:
-
-- core workflow role: participates in task flow
-- optional flow role: participates only when enabled
-- tool role: project utility, not part of task flow
-
-### 6.5 Skills
-
-Skills view should show installed VCM skills:
-
-- `vcm-route-message`
-- `vcm-final-acceptance`
-- `vcm-harness-bootstrap`
-- `vcm-long-running-validation`
-- `vcm-gate-review`
-
-For each skill:
-
-- file path
-- description
-- managed block status
-- whether it is current
-- related roles
-- editable project notes when supported
-
-### 6.6 Root Context
-
-Root Context view should show:
-
-- `CLAUDE.md`
-- VCM fixed managed block status
-- project-specific sections
-- warnings for duplicated or conflicting rules
-- active session refresh guidance
-
-### 6.7 Project Docs
-
-Project Docs view should show durable harness-relevant docs:
-
-- architecture docs
-- module docs
-- testing docs
-- public surface docs
-- module index
-- generated docs
-
-It should show whether docs are missing, stale, or incomplete.
-
-### 6.8 Tools
-
-Tools view should show:
-
-- `.ai/tools/run-long-check`
-- `.ai/tools/watch-job`
-- `.ai/tools/vcm-bash-guard`
-- `.ai/tools/request-gate-review`
-- generated doc tools
-
-For each tool:
-
-- path
-- executable status
-- managed status
-- purpose
-- related skill
-
-### 6.9 Proposed Changes
-
-All Harness Engineer changes must flow through Proposed Changes.
-
-The UI should show:
-
-- changed files
-- unified diff
-- generated summary
-- risk notes
-- affected roles
-- whether active sessions need restart or reminder
-- apply, discard, or revise actions
-
-No harness edit should be applied without user confirmation.
-
-### 6.10 VCM Feedback
-
-VCM Feedback view handles upstream VCM issues.
-
-When Harness Engineer finds a VCM-level product or fixed template issue, it
-should create an issue draft for:
-
-```text
-https://github.com/CodingForMoney/VibeCodingMaster
-```
-
-The user must review and confirm before VCM submits the issue.
-
-## 7. Change Review Model
-
-All modifications require reviewable diffs.
-
-Required flow:
-
-```text
-User feedback or harness diagnosis
-  -> Harness Engineer proposes changes
-  -> VCM stores a pending change set
-  -> UI shows diff and impact
-  -> User confirms
-  -> VCM applies the changes
-  -> VCM refreshes harness status
-  -> User may commit and rebase active task worktrees
-```
-
-Harness Engineer can explain, revise, or discard pending changes, but it cannot
-skip the review step.
-
-## 8. VCM Issue Feedback Flow
-
-Harness Engineer must classify issues before acting:
-
-```text
-Project harness issue
-  -> propose project harness diff
-
-VCM product or fixed template issue
-  -> draft GitHub issue for CodingForMoney/VibeCodingMaster
-```
-
-### 8.1 Issue Draft Requirements
-
-A VCM issue draft should include:
-
-- title
-- problem description
-- reproduction steps
-- expected behavior
-- actual behavior
-- VCM version
-- affected harness files or UI areas
-- impact
-- suggested fix if known
-- sanitized context only
-
-### 8.2 Privacy Rules
-
-Issue drafts must not include:
-
-- private source code
-- secrets
-- private file contents
-- full terminal logs
-- private repository names unless user confirms
-- user identity or environment details unless necessary
-
-Harness Engineer should summarize private context instead of copying it.
-
-### 8.3 Submission Rule
-
-VCM may submit the issue only after explicit user confirmation.
-
-Before submission, UI should show:
-
-- target repository
-- final issue title
-- final issue body
-- privacy warning
-- submit or cancel action
-
-## 9. Managed Block Policy
-
-VCM managed blocks remain protected.
-
-Managed blocks use markers such as:
-
-```text
-<!-- VCM:BEGIN version=1 -->
-...
-<!-- VCM:END -->
-```
-
-or:
-
-```text
-# VCM:BEGIN version=1
-...
-# VCM:END
-```
-
-Rules:
-
-- VCM installer owns fixed managed block content.
-- Harness Engineer must not directly rewrite fixed managed block content.
-- Project-specific customization should live outside fixed managed blocks.
-- If a fixed managed block is wrong, create a VCM issue draft.
-- If a managed block is stale, users should run fixed harness update.
-- If a managed block is user-modified, VCM should warn before replacing it.
-
-## 10. Session Refresh Policy
-
-Claude Code sessions do not automatically re-read every changed instruction file
-in a reliable, user-visible way.
-
-VCM tracks a project-level `harnessRevision`.
-
-Revision behavior:
-
-- fixed harness update increments the revision when it changes files
-- Harness Studio file saves increment the revision when content changes
-- each Claude Code role session records the revision it started or resumed with
-- session views compare the recorded revision with the current project revision
-- stale sessions are shown as `outdated`
-
-VCM offers:
-
-- `Notify role`: send a compact update message into the running session, asking
-  the role to re-read `CLAUDE.md`, its agent definition, and relevant skills
-- `Restart`: start a fresh Claude Code process when role definition, hook, or
-  core harness changes are significant
-- `Resume`: for stopped sessions, reload through the normal Claude Code startup
-  path
-
-Harness Engineer should include session impact in every proposed change.
-
-## 11. Storage
-
-Recommended storage:
-
-```text
-<baseRepoRoot>/.ai/vcm/harness/
-  pending-changes/
-  applied-changes/
-  issue-drafts/
-  diagnostics/
-
-<baseRepoRoot>/.ai/vcm/harness-engineer/
-  session.json
-```
-
-Guidelines:
-
-- pending changes are review artifacts
-- applied change records are lightweight audit metadata
-- issue drafts are user-reviewable
-- no unnecessary terminal logs
-- no hidden external submissions
-
-## 12. Backend Capabilities
-
-VCM backend should provide APIs for:
-
-- listing harness files
-- reading harness file content
-- validating managed blocks
-- computing diffs
-- storing pending change sets
-- applying confirmed changes
-- discarding pending changes
-- refreshing harness status
-- starting, resuming, restarting, and stopping Harness Engineer
-- creating VCM issue drafts
-- submitting confirmed GitHub issues
-
-GitHub issue creation should be optional and graceful:
-
-- if GitHub auth is unavailable, keep the issue draft and show manual copy
-- if network fails, preserve the draft and allow retry
-
-## 13. Safety and Permissions
-
-Default safety rules:
-
-- Harness Engineer can read project harness files.
-- Harness Engineer can write only through VCM pending change sets by default.
-- Direct file writes should be reserved for confirmed apply operations.
-- VCM should validate paths before applying changes.
-- External issue submission always requires user confirmation.
-- Fixed managed block edits are blocked unless performed by the VCM installer.
-
-The safest default is:
-
-```text
-AI proposes.
-VCM diffs.
-User approves.
-VCM applies.
-```
-
-## 14. Relation to Current Workflow
-
-VCM 0.4 should not change the task execution model by default.
-
-Current behavior remains:
-
-- PM coordinates the task.
-- Architect plans and evaluates complex fixes.
-- Coder implements.
-- Reviewer validates.
-- Gate Reviewer optionally performs gate reviews.
-- Translator remains a project translation tool role.
-- Harness Engineer maintains harness quality.
-
-Harness Engineer is not included in:
-
-- role tab bar for a task
-- VCM round completion detection
-- task close cleanup
-- PM dispatch flow
-
-It is opened from Harness Studio as a project tool session.
-
-## 15. Implementation Phases
-
-### Phase 1: Harness Engineer Role
-
-- Add `harness-engineer` role definition.
-- Install `.claude/agents/harness-engineer.md`.
-- Add project-scoped session persistence.
-- Add UI entry to open Harness Engineer session.
-- Ensure it is not part of task round state.
-
-Success condition: users can start or resume Harness Engineer for a project
-without affecting active tasks.
-
-### Phase 2: Harness Inventory and Status UI
-
-- Add Harness Studio shell.
-- List agents, skills, root context, tools, and project docs.
-- Show managed block status.
-- Show stale, missing, and modified harness files.
-
-Success condition: users can understand current harness state without opening
-files manually.
-
-### Phase 3: Diff-Based Harness Changes
-
-- Add pending change set model.
-- Let Harness Engineer propose changes.
-- Show diffs in UI.
-- Require user confirmation before apply.
-- Refresh harness status after apply.
-
-Success condition: no harness change is applied invisibly.
-
-### Phase 4: Session Impact and Worktree Sync
-
-- Track `harnessRevision` for project harness changes.
-- Mark sessions with older revisions as `outdated`.
-- Offer `Notify role` for running stale sessions.
-- Keep restart available for stronger reload needs.
-- Apply harness changes only inside the active task worktree and commit them immediately.
-- Make Review Diff show the latest active task worktree commit diff.
-
-Success condition: harness updates do not leave active task worktrees or active
-role sessions silently stale.
-
-### Phase 5: VCM Issue Feedback
-
-- Add VCM issue draft model.
-- Add issue draft UI.
-- Add optional GitHub issue submission after confirmation.
-- Add privacy checks and manual copy fallback.
-
-Success condition: Harness Engineer can help users report VCM product or fixed
-template problems upstream safely.
-
-## 16. Open Decisions
-
-Before implementation, decide:
-
-- final role name: `harness-engineer` or `harness-maintainer`
-- exact editable sections in each harness file
-- whether pending change sets store full file snapshots or patches
-- GitHub integration method for issue submission
-- whether Harness Engineer can run validation commands directly
-- how to show session restart impact in the UI
-- whether applied change audit records should be committed or ignored
-
-## 17. Design Summary
-
-VCM 0.4 should optimize the workflow VCM already has.
-
-The important product move is not free-form workflow editing. The important
-move is making harness configuration visible, reviewable, and improvable.
-
-Harness Engineer gives users an AI collaborator that understands both VCM's
-fixed harness and the project's local harness. Harness Studio gives users a
-safe place to inspect and apply changes. The GitHub issue feedback flow closes
-the loop when a project-level harness problem is actually a VCM product or
-template problem.
-
-VCM 0.5 can then build on this foundation with the full custom workflow engine.