vibe-coding-master 0.0.17 → 0.2.0

package/dist/backend/services/session-service.js

@@ -41,6 +41,7 @@ export function createSessionService(deps) {
             cwd: taskRepoRoot,
             env: {
                 VCM_API_URL: deps.apiUrl,
+                VCM_TASK_REPO_ROOT: taskRepoRoot,
                 VCM_TASK_SLUG: taskSlug,
                 VCM_ROLE: role,
                 VCM_SESSION_ID: claudeSessionId
@@ -224,9 +225,6 @@ function getHandoffArtifactPath(paths, role) {
     if (role === "architect") {
         return paths.architecturePlanPath;
     }
-    if (role === "coder") {
-        return paths.implementationLogPath;
-    }
     if (role === "reviewer") {
         return paths.reviewReportPath;
     }

package/dist/backend/services/task-service.js

@@ -7,7 +7,8 @@ export function createTaskService(deps) {
         async createTask(repoRoot, input) {
             assertValidTaskSlug(input.taskSlug);
             const config = await deps.projectService.loadConfig(repoRoot);
-            const taskPath = getTaskPath(repoRoot, config.stateRoot, input.taskSlug);
+            const taskStoreRoot = deps.projectService.getProjectDataRoot(repoRoot);
+            const taskPath = getTaskPath(taskStoreRoot, input.taskSlug);
             const shouldCreateWorktree = input.createWorktree !== false;
             const taskBranch = shouldCreateWorktree
                 ? `feature/${input.taskSlug}`
@@ -22,7 +23,7 @@ export function createTaskService(deps) {
                     statusCode: 409
                 });
             }
-            if (!(await deps.git.isIgnored(repoRoot, `${config.stateRoot}/tasks/.probe`))) {
+            if (!(await deps.git.isIgnored(repoRoot, `${config.stateRoot}/.probe`))) {
                 throw new VcmError({
                     code: "VCM_STATE_NOT_IGNORED",
                     message: `${config.stateRoot}/ is not ignored by Git.`,
@@ -39,7 +40,7 @@ export function createTaskService(deps) {
                 });
             }
             if (!shouldCreateWorktree) {
-                const activeInlineTask = await findActiveInlineTask(deps.fs, repoRoot, config.stateRoot);
+                const activeInlineTask = await findActiveInlineTask(deps.fs, taskStoreRoot);
                 if (activeInlineTask) {
                     throw new VcmError({
                         code: "INLINE_TASK_EXISTS",
@@ -108,14 +109,14 @@ export function createTaskService(deps) {
             await deps.artifactService.createArtifactTemplates({
                 repoRoot: taskRepoRoot,
                 taskSlug: input.taskSlug,
-                handoffDir: task.handoffDir
+                handoffDir: task.handoffDir,
+                branch: task.branch
             });
             await this.saveTask(repoRoot, task);
             return task;
         },
         async listTasks(repoRoot) {
-            const config = await deps.projectService.loadConfig(repoRoot);
-            const tasksDir = path.join(repoRoot, config.stateRoot, "tasks");
+            const tasksDir = path.join(deps.projectService.getProjectDataRoot(repoRoot), "tasks");
             if (!(await deps.fs.pathExists(tasksDir))) {
                 return [];
             }
@@ -128,8 +129,7 @@ export function createTaskService(deps) {
         },
         async loadTask(repoRoot, taskSlug) {
             assertValidTaskSlug(taskSlug);
-            const config = await deps.projectService.loadConfig(repoRoot);
-            const taskPath = getTaskPath(repoRoot, config.stateRoot, taskSlug);
+            const taskPath = getTaskPath(deps.projectService.getProjectDataRoot(repoRoot), taskSlug);
             if (!(await deps.fs.pathExists(taskPath))) {
                 throw new VcmError({
                     code: "TASK_MISSING",
@@ -140,8 +140,7 @@ export function createTaskService(deps) {
             return deps.fs.readJson(taskPath);
         },
         async saveTask(repoRoot, task) {
-            const config = await deps.projectService.loadConfig(repoRoot);
-            await deps.fs.writeJsonAtomic(getTaskPath(repoRoot, config.stateRoot, task.taskSlug), task);
+            await deps.fs.writeJsonAtomic(getTaskPath(deps.projectService.getProjectDataRoot(repoRoot), task.taskSlug), task);
         },
         async updateTaskStatus(repoRoot, taskSlug, status) {
             const task = await this.loadTask(repoRoot, taskSlug);
@@ -165,7 +164,7 @@ export function createTaskService(deps) {
             const config = await deps.projectService.loadConfig(repoRoot);
             const task = await this.loadTask(repoRoot, taskSlug);
             const taskRepoRoot = getTaskRuntimeRepoRoot(task);
-            const statePaths = getTaskStatePaths(repoRoot, taskRepoRoot, config.stateRoot, config.handoffRoot, taskSlug);
+            const statePaths = getTaskStatePaths(deps.projectService.getProjectDataRoot(repoRoot), taskRepoRoot, config.stateRoot, config.handoffRoot, taskSlug);
             const removedStatePaths = [];
             const cleanedAt = now();
             if (task.worktreePath) {
@@ -194,8 +193,8 @@ export function createTaskService(deps) {
 export function getTaskRuntimeRepoRoot(task) {
     return task.worktreePath ?? task.repoRoot;
 }
-function getTaskPath(repoRoot, stateRoot, taskSlug) {
-    return path.join(repoRoot, stateRoot, "tasks", `${taskSlug}.json`);
+function getTaskPath(taskStoreRoot, taskSlug) {
+    return path.join(taskStoreRoot, "tasks", `${taskSlug}.json`);
 }
 function getTaskWorktreePath(repoRoot, taskSlug) {
     return path.join(repoRoot, ".claude", "worktrees", taskSlug);
@@ -206,8 +205,8 @@ async function ensureTaskRuntimeStateDirs(fs, taskRepoRoot, stateRoot) {
     await fs.ensureDir(path.join(taskRepoRoot, stateRoot, "orchestration"));
     await fs.ensureDir(path.join(taskRepoRoot, stateRoot, "translation"));
 }
-async function findActiveInlineTask(fs, repoRoot, stateRoot) {
-    const tasksDir = path.join(repoRoot, stateRoot, "tasks");
+async function findActiveInlineTask(fs, taskStoreRoot) {
+    const tasksDir = path.join(taskStoreRoot, "tasks");
     if (!(await fs.pathExists(tasksDir))) {
         return undefined;
     }
@@ -220,9 +219,9 @@ async function findActiveInlineTask(fs, repoRoot, stateRoot) {
     }
     return undefined;
 }
-function getTaskStatePaths(baseRepoRoot, taskRepoRoot, stateRoot, handoffRoot, taskSlug) {
+function getTaskStatePaths(taskStoreRoot, taskRepoRoot, stateRoot, handoffRoot, taskSlug) {
     return [
-        path.join(baseRepoRoot, stateRoot, "tasks", `${taskSlug}.json`),
+        getTaskPath(taskStoreRoot, taskSlug),
         path.join(taskRepoRoot, stateRoot, "sessions", `${taskSlug}.json`),
         path.join(taskRepoRoot, stateRoot, "messages", `${taskSlug}.jsonl`),
         path.join(taskRepoRoot, stateRoot, "orchestration", `${taskSlug}.json`),

package/dist/backend/templates/handoff.js

@@ -22,36 +22,16 @@ TBD
 TBD
 `;
 }
-export function renderImplementationLogTemplate(taskSlug) {
-    return `# Implementation Log: ${taskSlug}
+export function renderKnownIssuesTemplate(taskSlug) {
+    return `# Known Issues: ${taskSlug}
 
-## Summary
-
-TBD
-
-## Files Changed
-
-TBD
-
-## Validation
+## Task Issues
 
-TBD
-
-## Deviations From Architecture Plan
-
-TBD
+No unresolved task issues recorded yet.
 
-## Follow-ups
+## Escalation To Docs
 
-TBD
-`;
-}
-export function renderValidationLogTemplate(taskSlug) {
-    return `# Validation Log: ${taskSlug}
-
-## Validation
-
-Not run yet.
+At task close, promote still-relevant confirmed issues to \`docs/known-issues.md\`; delete this task-local file with the rest of \`.ai/vcm/\` runtime state.
 `;
 }
 export function renderReviewReportTemplate(taskSlug) {
@@ -101,8 +81,66 @@ TBD
 
 TBD
 
+## Known Issues Disposition
+
+TBD
+
 ## Decision
 
+TBD
+`;
+}
+export function renderFinalAcceptanceTemplate(taskSlug) {
+    return `# Final Acceptance: ${taskSlug}
+
+## Decision
+
+TBD
+
+## Evidence Reviewed
+
+TBD
+
+## Scope Traceability
+
+### Expected Changes
+
+TBD
+
+### Supporting Changes
+
+TBD
+
+### Approved Deviations
+
+TBD
+
+### Unexplained Changes
+
+TBD
+
+### High-Risk Unexpected Changes
+
+TBD
+
+## Validation Summary
+
+TBD
+
+## Review And Docs Sync
+
+TBD
+
+## Known Issues Disposition
+
+TBD
+
+## Cleanup Readiness
+
+TBD
+
+## Final User Summary
+
 TBD
 `;
 }

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,22 +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.
-- VCM orchestration is strictly sequential. Do not parallelize work across multiple roles or dispatch messages to multiple target roles at once.
-- 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.
 `;
 }