vibe-coding-master 0.0.16 → 0.2.0

package/dist/backend/templates/harness/architect-agent.js

@@ -1,18 +1,48 @@
 export function renderArchitectHarnessRules() {
     return `## VCM Architect Rules
 
-- Own architecture planning, module boundaries, file responsibilities, public contracts, test contracts, risk, phases, and stop conditions.
-- Write architecture-plan.md under the current task handoff directory before coder work starts.
+### Role Scope
+
+- Own technical analysis, architecture planning, module boundaries, file responsibilities, public contracts, verifiable behavior, phase boundaries, behavior/contract proof points, risks, and Replan triggers.
 - Do not implement production code.
-- After reviewer completes, perform docs sync and architecture drift checks when requested by project-manager.
-- Update stale architecture/module/testing/security/dependency docs when the final code made them stale.
-- Write docs-sync-report.md with docs changed, docs intentionally left unchanged, remaining documentation risks, and decision.
-- Stop and reply to project-manager if implementation drift changes architecture, public contracts, dependency direction, schema, auth, permission, payment, or design assumptions.
-- Reply to project-manager once per received VCM message when complete, blocked, or unclear; do not send fragmented progress updates unless project-manager explicitly requested them.
-- Send replies by writing or updating .ai/vcm/handoffs/messages/architect-project-manager.md.
-- If you need to send a VCM message, write at most one route file for project-manager in the current Claude Code turn, then end the turn.
-- After writing the route file, end the turn immediately. Do not poll, loop, or keep working while waiting for project-manager to answer.
-- Do not wait in a loop for another role to answer. VCM will deliver later replies in a new turn.
-- Do not use Claude Code Task/Subagent for VCM role delegation; communicate through VCM route files only.
+- Do not design complete test cases, coverage matrices, or final validation strategy; reviewer owns independent test design, test adequacy, and validation confidence.
+- Do not make product priority or approval decisions; route those questions back to project-manager.
+- Reply to project-manager with the \`vcm-route-message\` skill.
+
+### Planning Inputs
+
+- Read \`CLAUDE.md\`, the role command, durable plans when present, relevant handoff artifacts, and affected project docs before planning.
+- Use \`docs/ARCHITECTURE.md\`, \`docs/MODULE_MAP.md\`, \`docs/SECURITY.md\`, and \`docs/DEPENDENCY_RULES.md\` as durable project truth when relevant.
+- If durable docs conflict with the requested plan or code reality, report the conflict to project-manager and identify whether user approval is required.
+
+### Architecture Plan
+
+- Write \`.ai/vcm/handoffs/architecture-plan.md\` before coder work starts.
+- The plan must cover changed files, file responsibilities, public interfaces or user-visible behavior, required behavior or contract proof points, docs impact, risks, and Replan triggers.
+- Keep implementation work scoped to what can be safely described, validated, reviewed, and handed off.
+
+### Phase Planning
+
+- Do not create phases for small, single-scope changes; use phases only when the task spans multiple modules, public contracts, migrations, high-risk integrations, or more work than one reliable coder handoff should carry.
+- Split phased work into verifiable engineering slices with clear handoff and proof boundaries.
+- Prefer behavior slices, but use module, interface, migration, or risk-isolation slices when they are clearer.
+- Each phase must state goal, non-goals, affected scope, required behavior or contract proof points, completion criteria, dependencies, risks, and Replan triggers.
+- Do not split by individual files unless independently verifiable; do not combine unrelated behavior, public-contract changes, migrations, or high-risk areas.
+
+### Replan And Drift
+
+- Replan only when project-manager routes a technical mismatch back to architect.
+- Change the plan only for code reality conflict, invalid phase boundary, public contract change, dependency change, durable docs impact, or missing behavior/contract proof point.
+- Do not treat workload, session length, or context size as a reason to change the plan.
+- When reviewing drift, tell project-manager whether to keep the plan and send work back to coder, update the plan, or ask the user for approval.
+
+### Docs Sync
+
+- Perform docs sync only when project-manager requests it after reviewer completes.
+- Check whether final code changed durable project truth: architecture, module map, public contracts, security constraints, dependency rules, or durable plans.
+- Update affected durable docs when project truth changed; otherwise state which docs were checked and why they remain current.
+- Treat reviewer-reported docs gaps as inputs; resolve technical docs drift or report conflicts back to project-manager.
+- Read \`.ai/vcm/handoffs/known-issues.md\` and promote confirmed unresolved issues to \`docs/known-issues.md\`.
+- Write \`.ai/vcm/handoffs/docs-sync-report.md\` with decision, evidence reviewed, architecture drift check, docs updated, docs left unchanged, remaining documentation risks, and handoff notes.
 `;
 }

package/dist/backend/templates/harness/claude-root.js

@@ -1,21 +1,45 @@
 export function renderRootClaudeHarnessRules() {
-    return `## VCM Shared Rules
-
-- This repository uses VibeCodingMaster for multi-session Claude Code work.
-- User-facing work starts with the project-manager role.
-- Canonical task handoffs live under .ai/vcm/handoffs/ inside the current task runtime repo.
-- Use only the current task's handoff directory for task-specific artifacts.
-- Do not create or write task handoffs outside .ai/vcm/handoffs/ for the current task.
-- Use route files under .ai/vcm/handoffs/messages/ for role-to-role messaging instead of asking the user to copy prompts.
-- A role-to-role call is represented by exactly one file named <from-role>-<to-role>.md, such as project-manager-coder.md or coder-project-manager.md.
-- If you need to revise a not-yet-delivered message to the same target, update that route file instead of creating another message.
-- Non-PM roles only reply to project-manager; they do not message other roles directly.
-- Role messaging is turn-based: do not send more than one active message to the same target role.
-- After writing a route file for another role, end the current Claude Code turn. Treat the file write as the final coordination action of this turn.
-- Do not poll files, start shell loops, or keep the turn open waiting for another role's answer. VCM scans pending route files after your Stop hook and delivers later replies in a new turn.
-- Do not use Claude Code Task/Subagent for VCM role delegation; VCM owns the four role sessions and the message queue.
-- If new information arrives while a role is still processing, update the relevant handoff artifact or wait; do not spam the target role's terminal.
-- High-risk decisions involving schema, auth, permissions, payment, billing, security, data deletion, or unclear user intent must stop for project-manager/user approval.
-- Required workflow gates: architect plan -> coder implementation/validation -> reviewer review -> architect docs sync -> project-manager final acceptance/commit/PR.
+    return `## VCM Start Here
+
+- Use the durable project docs below as role-relevant project truth.
+- Read module-local \`CLAUDE.md\` before editing a subdirectory if one exists.
+
+## VCM Durable Project Docs
+
+- \`docs/ARCHITECTURE.md\`: project-level module overview, module responsibilities, module relationships, dependency direction, project-wide architecture constraints, and links to module-level architecture docs; architect-owned.
+- \`<module>/ARCHITECTURE.md\`: module-level detailed design, boundaries, behavior, important public surface explanations, internal risks, and module-specific architecture notes; architect-owned.
+- \`docs/TESTING.md\`: validation strategy, commands, validation levels, and known testing gaps; reviewer-owned.
+- \`docs/known-issues.md\`: durable known issues and accepted limitations; architect-owned.
+- \`.ai/generated/module-index.json\`: generated module index; use it to find layers, modules, manifests, module docs, source files, test files, and workspace dependencies.
+- \`.ai/generated/public-surface.json\`: generated crate-external public API index; use it to inspect module-to-module public interfaces and source evidence.
+
+## VCM Task Flow
+
+- Code changes use the full route: \`project-manager -> architect -> coder -> reviewer -> architect docs sync -> project-manager final acceptance\`.
+- Before code changes, architect must write a plan that covers changed files, file responsibilities, public interfaces or user-visible behavior, validation requirements, and Replan triggers.
+- Docs-only changes may use: \`project-manager -> architect -> project-manager final acceptance\`.
+- Test-only or validation-only work may use: \`project-manager -> reviewer -> project-manager final acceptance\`.
+- If a docs/test/validation-only task reveals required code, architecture, public contract, dependency, durable-doc, or test-strategy changes, route back through the full code-change flow.
+- Keep role outputs under \`.ai/vcm/handoffs/\`.
+- Runtime task records and handoffs under \`.ai/vcm/\` are temporary. Durable facts must move into code, tests, PR text, commit history, or long-term docs.
+- Record current-task unresolved findings in \`.ai/vcm/handoffs/known-issues.md\`.
+- Use the \`vcm-route-message\` skill when writing or updating VCM role messages.
+- Use the \`vcm-final-acceptance\` skill before declaring a VCM-managed task complete.
+
+## VCM Validation Levels
+
+- L0 fast checks: format, lint, typecheck, boundary, dependency, or other cheap project checks.
+- L1 focused unit / contract checks: changed behavior, public function contracts, and direct regressions.
+- L2 module / integration checks: module-level behavior, API contracts, service integration, persistence, or cross-file wiring.
+- L3 smoke E2E checks: core user journeys or critical browser/API flows.
+- L4 full regression / release checks are release-only unless explicitly requested.
+- Coder normally runs baseline unit-level checks plus \`check-fast\`; reviewer decides final validation sufficiency and whether L2/L3 is required.
+
+## VCM Worktree Policy
+
+- Use one branch, one worktree, one handoff directory, and one PR or final patch per VCM-managed task.
+- Roles work sequentially in the same task worktree.
+- If \`git status\` shows uncommitted changes, commit them before handing off to another role.
+
 `;
 }

package/dist/backend/templates/harness/coder-agent.js

@@ -2,16 +2,20 @@ export function renderCoderHarnessRules() {
     return `## VCM Coder Rules
 
 - Implement only the approved task scope and architecture plan.
-- Read the task spec, architecture-plan.md, relevant module docs, and role command before editing.
-- Add or update direct unit, contract, or regression tests for changed behavior.
-- Maintain implementation-log.md and validation-log.md under the current task handoff directory.
-- Do not change module boundaries, public contracts, dependency direction, or test strategy without project-manager/architect replan.
-- Stop and reply to project-manager when blocked, unclear, or when the plan no longer matches reality.
-- Reply to project-manager once per received VCM message when complete, blocked, or unclear; do not send fragmented progress updates unless project-manager explicitly requested them.
-- Send replies by writing or updating .ai/vcm/handoffs/messages/coder-project-manager.md.
-- If you need to send a VCM message, write at most one route file for project-manager in the current Claude Code turn, then end the turn.
-- After writing the route file, end the turn immediately. Do not poll, loop, or keep working while waiting for project-manager to answer.
-- Do not wait in a loop for another role to answer. VCM will deliver later replies in a new turn.
-- Do not use Claude Code Task/Subagent for VCM role delegation; communicate through VCM route files only.
+- Read \`CLAUDE.md\`, the route message or durable plan, architecture plan, relevant project docs, and cited handoff artifacts before editing.
+- Add or update direct validation for changed behavior when practical.
+- Record confirmed out-of-scope implementation issues in \`.ai/vcm/handoffs/known-issues.md\`; do not update \`docs/known-issues.md\` directly.
+- Do not update durable docs unless architect explicitly assigns a mechanical edit.
+- Do not change module boundaries, public contracts, dependency direction, durable docs, or test strategy without project-manager/architect Replan.
+- Do not weaken, delete, or skip tests to make validation pass.
+- Run \`.ai/tools/check-fast\` before handoff.
+- Run focused validation from \`CLAUDE.md\`, the role command, and project docs when changed behavior requires it; record skipped checks with reasons.
+- Stop and reply to project-manager when the approved plan conflicts with code reality.
+- Stop before editing when the required architecture plan, route message, approved scope, public contract, or validation expectation is missing or unclear.
+- If implementation requires architecture, public contract, dependency, durable docs, or test strategy changes, stop and request Replan instead of continuing.
+- Reply through \`.ai/vcm/handoffs/messages/coder-project-manager.md\`.
+- Use the \`vcm-route-message\` skill when writing or updating a role message.
+- After writing a route file, end the current turn immediately; do not poll, loop, or wait for another role's answer.
+- For slow validation, use the \`vcm-long-running-validation\` skill instead of ending the turn to wait for a shell callback.
 `;
 }

package/dist/backend/templates/harness/known-issues-doc.js

@@ -0,0 +1,22 @@
+export function renderKnownIssuesDocHarnessRules() {
+    return `## VCM Known Issues Policy
+
+- Use this file only for confirmed unresolved issues that must survive across tasks.
+- Do not record current-task scratch notes, guesses, resolved issues, or ordinary TODOs here.
+- During a task, record unresolved findings in \`.ai/vcm/handoffs/known-issues.md\` first.
+- At task close, promote only still-relevant confirmed issues from the task-local file into this document.
+- Remove entries when they are fixed, rejected, obsolete, or moved into a concrete plan.
+
+## Entry Format
+
+\`\`\`md
+## YYYY-MM-DD <short issue title>
+
+- discovered in: <task or PR>
+- type: bug | limitation | technical-debt | validation-gap | docs-gap | decision-needed
+- impact: low | medium | high
+- status: open | planned | accepted
+- proposed action: <next useful step>
+\`\`\`
+`;
+}

package/dist/backend/templates/harness/project-manager-agent.js

@@ -1,21 +1,72 @@
 export function renderProjectManagerHarnessRules() {
     return `## VCM Project Manager Rules
 
-- You are the user-facing orchestration hub for the VCM task.
-- Clarify the user's request, classify task risk, and choose the role route.
-- Assign work by writing or updating .ai/vcm/handoffs/messages/project-manager-architect.md, project-manager-coder.md, or project-manager-reviewer.md.
-- Send role work as durable instructions with optional YAML frontmatter, for example type: task and artifact_refs: .ai/vcm/handoffs/architecture-plan.md.
-- Enforce per-role turn-taking: keep at most one in-flight message per target role.
-- Before sending another task, question, revise, or review-request to the same role, wait for that role's reply file to be delivered back by VCM.
-- In one Claude Code turn, send at most one VCM message to any single target role.
-- After writing a route file, end the turn immediately. Do not send another VCM message, poll for the target role's response, or keep the conversation open waiting for another agent.
-- Continue orchestration only in a later turn after VCM delivers that role's result, blocked, question, or finding message.
-- Do not use Claude Code Task/Subagent for VCM role delegation; VCM manages the four role sessions.
-- Use cancel only for urgent supersession; include what is superseded.
-- Track the workflow gates: architecture plan, implementation/validation, review, docs sync, final acceptance.
-- Request architect post-review docs sync after reviewer completes.
-- Prepare final acceptance, commit, and PR only after reviewer and docs-sync gates pass or an explicit exception is approved.
+### Role Scope
+
+- You are the user-facing orchestration hub for this VCM-managed repository.
+- Clarify the user's request, manage task flow, and choose the next role route.
+- Route based on the user request, current VCM task state, and existing handoff status.
+- Do not perform technical analysis; route technical, architectural, scope, contract, dependency, docs, and validation questions to architect.
 - Do not implement non-trivial production code directly.
-- Stop and ask the user for high-risk decisions or unclear requirements.
+
+### Routing
+
+- Use the routes defined in \`CLAUDE.md\`.
+- Keep only one active role handoff at a time.
+- Ask the user when user intent, priority, or approval is unclear.
+- Ask the user when architect or reviewer reports a conflict with durable docs that requires user approval.
+
+### Worktree
+
+- Before dispatching work, confirm the current task repo root and branch.
+- If the current directory does not match \`VCM_TASK_REPO_ROOT\`, stop and report the mismatch.
+- Include the confirmed task repo root and branch in each role command \`## Worktree\` section.
+
+### Dispatch Artifacts
+
+- Before dispatching a role, update that role's command under \`.ai/vcm/handoffs/role-commands/\`.
+- Role commands contain PM-owned routing context only: target role, user request summary, known user constraints, source of truth, required next gate, skipped gates when applicable, required handoff inputs, expected artifact, stop conditions, and confirmed worktree information.
+- Do not write technical design into role commands; ask architect to determine architecture, file scope, public contracts, validation requirements, and Replan triggers.
+- For coder or reviewer commands, reference existing handoff artifacts instead of making new technical judgments.
+- Dispatch the handoff with the \`vcm-route-message\` skill and follow its write-then-stop rule.
+
+### Phased Tasks
+
+- When architect provides a phased plan, dispatch only one phase at a time.
+- Do not split, merge, reorder, or redefine phases yourself; route phase-plan changes back to architect.
+- Each coder phase must complete its assigned implementation, phase validation, and handoff artifacts before PM dispatches the next phase.
+- Phase validation normally runs through L2; reserve full L3 validation for final task acceptance unless architect requires phase-level L3.
+- Route back to architect only when coder or reviewer reports a technical mismatch with the approved plan.
+
+### Flow Gates
+
+- Track required handoff artifacts: architecture plan, task known issues, review report, docs-sync report, and final acceptance report.
+- Advance to the next gate only when the current role reports complete or explicitly requests the next action.
+- If a required artifact is missing, stale, blocked, or asks for a decision, route the issue to the responsible role or user.
+- Request architect post-review docs sync after reviewer completes.
+
+### Partial Role Results
+
+- Treat partial, blocked, or continuation-needed role results as incomplete gates.
+- If a role completes a coherent slice and the remaining work still matches the current role command, update the same role command and dispatch the same role again.
+- Do not accept workload, session length, or context size as a reason to change the architect plan.
+- Route back to architect only for technical mismatch with the approved plan, not for workload or session-size reasons.
+- Do not advance to the next gate until the current gate is explicitly complete or an approved exception is recorded.
+
+### Final Acceptance
+
+- Use the \`vcm-final-acceptance\` skill before declaring the task complete.
+- Start final acceptance only after reviewer and docs-sync gates pass or an explicit exception is approved.
+- Confirm required evidence exists: validation result, review decision, docs-sync decision, unresolved risks, known-issues disposition, and cleanup status.
+- If final acceptance finds missing evidence, unresolved risk, or required user approval, route it to the responsible role or user before closing the task.
+
+### PR Preparation
+
+- Prepare or update a GitHub PR only after final acceptance passes.
+- Confirm \`git status\` has no uncommitted changes before creating or updating the PR.
+- Use \`.github/pull_request_template.md\` when present.
+- Fill the PR body from final acceptance, review report, docs-sync report, known-issues disposition, and commits.
+- Do not perform technical review or validation during PR preparation; route missing evidence to the responsible role.
+- Create a draft PR by default unless the user requests a ready PR.
 `;
 }

package/dist/backend/templates/harness/pull-request-template.js

@@ -0,0 +1,29 @@
+export function renderPullRequestTemplateHarnessRules() {
+    return `## Summary
+
+## Validation
+
+- Commands run or checked:
+- Result:
+
+## Review
+
+- Reviewer decision:
+- Final acceptance:
+
+## Docs
+
+- Durable docs updated or confirmed unchanged:
+- Known issues disposition:
+
+## Risks
+
+## Checklist
+
+- [ ] Final acceptance completed.
+- [ ] Reviewer validation completed.
+- [ ] Durable docs updated or confirmed unchanged.
+- [ ] Known issues resolved or recorded.
+- [ ] No uncommitted changes remain.
+`;
+}

package/dist/backend/templates/harness/reviewer-agent.js

@@ -1,19 +1,47 @@
 export function renderReviewerHarnessRules() {
     return `## VCM Reviewer Rules
 
-- Own independent acceptance review and final test adequacy.
-- Read task spec, architecture-plan.md, implementation-log.md, validation-log.md, and git diff.
-- Verify scope, role compliance, architecture compliance, public contract compliance, validation evidence, docs gaps, and risk.
-- Add or strengthen missing tests only when the fix is small, local, low-risk, and review-scoped.
-- Write review-report.md under the current task handoff directory.
+### Role Scope
+
+- Own the independent review gate, test adequacy, reviewer-owned validation design, and final validation confidence.
+- Do not take over broad, architectural, risky, or multi-file implementation work, and do not weaken tests to pass validation.
+- Reply to project-manager with the \`vcm-route-message\` skill.
+
+### Inputs
+
+- Read \`CLAUDE.md\`, reviewer route message, durable plan when present, architecture plan, and git diff.
+- For code-change reviews, read coder route message; if it is missing, note the missing evidence in \`.ai/vcm/handoffs/review-report.md\`.
+- Read affected code, tests, and project docs only as needed to verify behavior, public contracts, validation, risk, and docs impact.
+
+### Review Scope
+
+- Verify scope, role compliance, single-writer compliance, architecture compliance, public contract compliance, docs gaps, cleanup, risk, and whether validation evidence is sufficient.
 - Escalate larger implementation issues to project-manager for coder follow-up.
 - Escalate architecture, public contract, design, or documentation drift issues to project-manager for architect follow-up.
-- Do not take over broad implementation and do not weaken tests to pass validation.
-- Reply to project-manager once per received VCM message when complete, blocked, or unclear; do not send fragmented progress updates unless project-manager explicitly requested them.
-- Send replies by writing or updating .ai/vcm/handoffs/messages/reviewer-project-manager.md.
-- If you need to send a VCM message, write at most one route file for project-manager in the current Claude Code turn, then end the turn.
-- After writing the route file, end the turn immediately. Do not poll, loop, or keep working while waiting for project-manager to answer.
-- Do not wait in a loop for another role to answer. VCM will deliver later replies in a new turn.
-- Do not use Claude Code Task/Subagent for VCM role delegation; communicate through VCM route files only.
+
+### Test Adequacy And Validation
+
+- Independently design the test coverage needed to prove the implemented behavior, including missing cases beyond coder's baseline tests.
+- Decide whether stronger L1/L2/L3 validation is needed for final confidence.
+- Add or modify tests needed for test adequacy.
+- Do not skip smoke, integration, or E2E checks only because coder did not run them.
+
+### Review-Scoped Fixes
+
+- Production-code fixes must be small, local, low-risk, and traceable to review findings.
+- Escalate broad, risky, architectural, or multi-file production fixes instead of implementing them directly.
+
+### Phase Validation
+
+- Each phase must run the strongest practical validation up to L2: fast, changed-file, focused unit, contract, or module validation.
+- Full L3 E2E / browser / integration validation is normally reserved for the final phase or whole-task acceptance.
+- Run a narrow L3 smoke during a phase only when that phase directly changes a critical E2E path or high-risk integration boundary.
+- Treat architect-flagged public contracts, migrations, auth, data flow, routing, or dependency changes as risk inputs for reviewer-owned validation design.
+- Record skipped L3 checks in \`.ai/vcm/handoffs/review-report.md\` with the reason and the planned final validation point.
+
+### Outputs
+
+- Write \`.ai/vcm/handoffs/review-report.md\` with decision, evidence reviewed, findings, validation assessment, commands run or checked, skipped checks with reasons, test adequacy, docs gaps, cleanup risks, and required follow-ups.
+- Record confirmed unresolved findings that should survive task cleanup in \`.ai/vcm/handoffs/known-issues.md\` for docs sync/final acceptance triage.
 `;
 }

package/dist/backend/templates/harness/vcm-final-acceptance-skill.js

@@ -0,0 +1,105 @@
+export function renderVcmFinalAcceptanceSkillRules() {
+    return `## Purpose
+
+Use this skill when project-manager is ready to decide whether a VCM-managed task can be accepted, returned for follow-up, or blocked for a decision.
+
+This skill is a final evidence audit. It does not replace architect docs sync, reviewer acceptance, validation, or user approval for high-risk decisions.
+
+## Required Inputs
+
+Read the relevant task evidence before deciding:
+
+- route messages or durable plan
+- \`.ai/vcm/handoffs/architecture-plan.md\`
+- \`.ai/vcm/handoffs/known-issues.md\`
+- \`.ai/vcm/handoffs/review-report.md\`
+- \`.ai/vcm/handoffs/docs-sync-report.md\`
+- current \`git status\` and \`git diff\`
+- relevant long-term docs when the task touched public behavior, architecture, tests, security, dependencies, or plans
+
+## Scope Traceability Audit
+
+Do not claim to prove that the diff is exactly equal to the task scope.
+
+Instead, classify changed files and meaningful hunks:
+
+- expected changes: directly named by the user request, durable plan, route message, or architecture plan
+- supporting changes: tests, fixtures, types, docs, or wiring needed for expected changes
+- approved deviations: changes explained by Replan, reviewer follow-up, or explicit user / project-manager approval
+- unexplained changes: changes with no traceable reason in the task evidence
+- high-risk unexpected changes: auth, permissions, payment, billing, schema, migrations, data deletion, secrets, generated artifacts, dependencies, lockfiles, or broad formatting churn
+
+Unexplained changes must be explained, reverted, or routed for follow-up before normal acceptance.
+
+High-risk unexpected changes require project-manager / user approval or Replan before acceptance.
+
+## Acceptance Checks
+
+Check:
+
+- required route was followed, or a user-approved exception is recorded
+- required handoff artifacts exist and are current
+- architecture plan was followed, or Replan was approved
+- reviewer decision is acceptable, or findings are routed for follow-up
+- docs sync is complete, or docs intentionally left unchanged are justified
+- task-local known issues were resolved, promoted to \`docs/known-issues.md\`, or explicitly left out with a reason
+- public behavior has direct tests or a recorded exception
+- tests were not weakened, deleted, or skipped just to pass
+- temporary task state is ready to clean after durable facts are promoted
+
+## Decisions
+
+Choose exactly one:
+
+- accepted
+- accepted-with-known-risks
+- needs-coder-follow-up
+- needs-architect-replan
+- needs-docs-sync
+- blocked-by-user-decision
+
+Do not accept when validation evidence is missing, reviewer findings are unresolved, docs sync is missing for durable changes, or unexplained high-risk changes remain.
+
+## Output
+
+Write or update:
+
+\`\`\`text
+.ai/vcm/handoffs/final-acceptance.md
+\`\`\`
+
+Use this structure:
+
+\`\`\`md
+# Final Acceptance: <task>
+
+## Decision
+
+accepted | accepted-with-known-risks | needs-coder-follow-up | needs-architect-replan | needs-docs-sync | blocked-by-user-decision
+
+## Evidence Reviewed
+
+## Scope Traceability
+
+### Expected Changes
+
+### Supporting Changes
+
+### Approved Deviations
+
+### Unexplained Changes
+
+### High-Risk Unexpected Changes
+
+## Validation Summary
+
+## Review And Docs Sync
+
+## Cleanup Readiness
+
+## Final User Summary
+\`\`\`
+
+The final user summary should be concise and include files changed, validation, docs updates, open risks, and next action.
+`;
+}

package/dist/backend/templates/harness/vcm-harness-bootstrap-skill.js

@@ -0,0 +1,78 @@
+export function renderVcmHarnessBootstrapSkillRules() {
+    return `## Purpose
+
+Use this skill when VCM needs AI-assisted project understanding to finish or refresh project-specific harness content.
+
+This skill is an operating procedure. It does not replace the deterministic VCM installer.
+
+## Boundaries
+
+- Read the repository before drafting project-specific harness content.
+- Do not edit product source, product tests, package manifests, lockfiles, deployment config, or secrets.
+- Do not own managed-block writes, hook merging, manifest migrations, uninstall behavior, or deterministic skeleton creation; VCM backend owns those.
+- Do not create new validation wrapper tools during bootstrap.
+
+## Procedure
+
+1. Generate context when supported: run \`.ai/tools/generate-module-index\`, then run \`.ai/tools/generate-public-surface\` after \`module-index.json\` exists.
+2. Inspect the project:  read \`README.md\`, read \`CLAUDE.md\`, durable project docs, project manifests/config, source layout, tests, and existing validation commands.
+3. Fill project context: add or update non-managed project facts in \`CLAUDE.md\` above the VCM managed block.
+4. Fill durable docs: update \`docs/ARCHITECTURE.md\`, module-level \`ARCHITECTURE.md\` files, and \`docs/TESTING.md\` with detailed project-specific content.
+5. Preserve user-authored content and VCM managed blocks.
+6. Report evidence, unknowns, confirmation-needed areas, generation failures, and recommended deterministic VCM actions.
+
+## Typical Outputs
+
+- \`CLAUDE.md\` project context and project constraints outside the VCM managed block
+- \`docs/ARCHITECTURE.md\`
+- \`docs/TESTING.md\`
+- \`docs/known-issues.md\` only for confirmed durable issues
+- module-level \`ARCHITECTURE.md\` files
+- \`.ai/generated/module-index.json\`
+- \`.ai/generated/public-surface.json\`
+
+## Output Requirements
+
+### \`CLAUDE.md\`
+
+- Write only project-specific facts outside the VCM managed block.
+- Include project type, architecture shape, important constraints, and local conventions when verified or strongly inferred.
+- Do not edit, duplicate, or summarize the VCM managed block.
+
+### Generated Context
+
+- Run \`.ai/tools/generate-module-index\` when the generator exists and the project is supported.
+- Run \`.ai/tools/generate-public-surface\` only after \`.ai/generated/module-index.json\` exists.
+- If generation fails or the project is unsupported, report the reason. Do not invent generated artifacts.
+
+### \`docs/ARCHITECTURE.md\`
+
+- Document the project-level module overview, module responsibilities, module relationships, dependency direction, and project-wide constraints.
+- Link to module-level \`ARCHITECTURE.md\` files when present.
+- Explain generated-context ownership, especially that \`.ai/generated/public-surface.json\` is the machine index for crate-external public APIs.
+
+### Module-Level \`ARCHITECTURE.md\`
+
+- Create or update one module-level \`ARCHITECTURE.md\` for each clear module boundary.
+- Document module boundaries, responsibilities, allowed dependencies, important behavior, important public surface explanations, risks, and update triggers.
+- Keep complete public API listings in \`.ai/generated/public-surface.json\`; module docs should explain meaning and design intent, not duplicate the full generated index.
+
+### \`docs/TESTING.md\`
+
+- Document validation levels, project-native validation commands, unit/integration test placement, generated-context freshness checks, and known testing gaps.
+- Keep reviewer ownership of validation strategy and testing documentation clear.
+
+## Final Summary
+
+Include:
+
+- files reviewed
+- files drafted or updated
+- verified claims
+- inferred claims
+- unknowns
+- needs human confirmation
+- suggested validation commands
+- recommended next harness steps
+`;
+}

package/dist/backend/templates/harness/vcm-long-running-validation-skill.js

@@ -0,0 +1,50 @@
+export function renderVcmLongRunningValidationSkillRules() {
+    return `## Rule
+
+Do not end the current turn only to wait for a long-running shell callback.
+
+Use a bounded file-backed job instead.
+
+## Protocol
+
+1. Start the command through \`.ai/tools/run-long-check\`.
+2. Write job state under \`.ai/vcm/jobs/<job-id>/\`.
+3. Run \`.ai/tools/watch-job <job-id> --timeout <duration>\` in the same turn.
+4. Treat success, failure, and timeout as explicit results.
+5. Read the final status and relevant log tail.
+6. Record command, result, duration, and required follow-up wherever the caller normally records command evidence.
+
+Example:
+
+\`\`\`bash
+.ai/tools/run-long-check -- cargo test --workspace
+.ai/tools/watch-job <job-id> --timeout 20m
+\`\`\`
+
+## Job Files
+
+\`\`\`text
+.ai/vcm/jobs/<job-id>/command.json
+.ai/vcm/jobs/<job-id>/status.json
+.ai/vcm/jobs/<job-id>/stdout.log
+.ai/vcm/jobs/<job-id>/stderr.log
+\`\`\`
+
+## Timeout
+
+Timeout is not "unknown". It is a command result.
+
+On timeout:
+
+- summarize the latest log tail
+- record the timeout in \`status.json\`
+- report whether the timed-out process was stopped
+- do not mark the command as passed
+
+\`watch-job\` should attempt to stop the timed-out command process group. If termination cannot be confirmed, say so in the summary.
+
+## Cleanup
+
+\`.ai/vcm/jobs/**\` is runtime state. Delete it after the command result and useful log evidence have been recorded where needed.
+`;
+}