vibe-coding-master 0.2.7 → 0.2.9

package/dist/backend/server.js

@@ -19,6 +19,7 @@ import { createWeixinIlinkChannel } from "./gateway/channels/weixin-ilink-channe
 import { createGatewayAuditLog } from "./gateway/gateway-audit-log.js";
 import { createGatewayService } from "./gateway/gateway-service.js";
 import { createGatewaySettingsService } from "./gateway/gateway-settings-service.js";
+import { createJobGuardService } from "./services/job-guard-service.js";
 import { createProjectService } from "./services/project-service.js";
 import { createSessionRegistry } from "./runtime/session-registry.js";
 import { createSessionService } from "./services/session-service.js";
@@ -218,7 +219,8 @@ export function createDefaultServerDeps(options = {}) {
         roundService,
         translationService,
         appSettings,
-        gatewayService
+        gatewayService,
+        jobGuard: createJobGuardService()
     });
     return {
         appSettings,

package/dist/backend/services/claude-hook-service.js

@@ -34,6 +34,11 @@ export function createClaudeHookService(deps) {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
+        deps.jobGuard?.notePromptSubmitted({
+            repoRoot: context.project.repoRoot,
+            taskSlug: input.taskSlug,
+            role: input.role
+        });
         const session = await deps.sessionService.recordClaudeHookEvent(context.project.repoRoot, {
             taskSlug: input.taskSlug,
             role: input.role,
@@ -81,12 +86,33 @@ export function createClaudeHookService(deps) {
             acceptedMessageId: submitted?.id
         };
     }
-    async function handleStopHook(input) {
+    async function processStopHook(input, options) {
         const eventName = parseHookEvent(input.event.hook_event_name ?? "Stop");
         if (eventName !== "Stop") {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
+        if (options.allowBlock && deps.jobGuard) {
+            const verdict = await deps.jobGuard.evaluateStop({
+                repoRoot: context.project.repoRoot,
+                taskSlug: input.taskSlug,
+                role: input.role,
+                taskRepoRoot: context.taskRepoRoot
+            });
+            if (verdict.behavior === "block") {
+                // The role turn stays alive: skip all turn-end bookkeeping so the
+                // round keeps running and no route dispatch happens yet.
+                return {
+                    ok: true,
+                    eventName,
+                    taskSlug: input.taskSlug,
+                    role: input.role,
+                    sessionUpdated: false,
+                    dispatchedCount: 0,
+                    stopDecision: { behavior: "block", reason: verdict.reason }
+                };
+            }
+        }
         const scopedRouteDispatchInput = {
             repoRoot: context.project.repoRoot,
             taskRepoRoot: context.taskRepoRoot,
@@ -194,9 +220,13 @@ export function createClaudeHookService(deps) {
             if (eventName === "UserPromptSubmit") {
                 return handleUserPromptSubmitHook(input);
             }
-            return handleStopHook(input);
+            // Legacy combined endpoint: the installed hook discards the response,
+            // so a block decision could not be enforced. Never block here.
+            return processStopHook(input, { allowBlock: false });
+        },
+        handleStopHook(input) {
+            return processStopHook(input, { allowBlock: true });
         },
-        handleStopHook,
         handlePermissionRequestHook
     };
 }

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

@@ -6,7 +6,6 @@ import { renderArchitectHarnessRules } from "../templates/harness/architect-agen
 import { renderCoderHarnessRules } from "../templates/harness/coder-agent.js";
 import { renderRootClaudeHarnessRules } from "../templates/harness/claude-root.js";
 import { renderGitignoreHarnessRules } from "../templates/harness/gitignore.js";
-import { renderKnownIssuesDocHarnessRules } from "../templates/harness/known-issues-doc.js";
 import { renderProjectManagerHarnessRules } from "../templates/harness/project-manager-agent.js";
 import { renderPullRequestTemplateHarnessRules } from "../templates/harness/pull-request-template.js";
 import { renderReviewerHarnessRules } from "../templates/harness/reviewer-agent.js";
@@ -26,13 +25,22 @@ const MANAGED_BLOCK_PATTERN = /<!-- VCM:BEGIN(?:\s+version=(\d+))? -->[\s\S]*?<!
 const HASH_MANAGED_BLOCK_PATTERN = /# VCM:BEGIN(?:\s+version=(\d+))?\n[\s\S]*?# VCM:END/m;
 const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
 const VCM_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,event}));});'"'"' | curl -fsS --max-time 2 -X POST "\${VCM_API_URL}/api/hooks/claude-code" -H "content-type: application/json" --data-binary @- >/dev/null || true'`;
+const VCM_STOP_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,event}));});'"'"' | curl -fsS --max-time 5 -X POST "\${VCM_API_URL}/api/hooks/claude-code/stop" -H "content-type: application/json" --data-binary @- || true'`;
 const VCM_PERMISSION_REQUEST_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,event}));});'"'"' | curl -fsS --max-time 5 -X POST "\${VCM_API_URL}/api/hooks/claude-code/permission-request" -H "content-type: application/json" --data-binary @- || true'`;
-const VCM_HOOK_EVENTS = ["UserPromptSubmit", "Stop", "PermissionRequest"];
+const VCM_BASH_GUARD_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ]; then exit 0; fi; exec python3 "\${CLAUDE_PROJECT_DIR:-.}/.ai/tools/vcm-bash-guard"'`;
+const VCM_BASH_DEFAULT_TIMEOUT_MS = "600000";
+const VCM_HOOK_DEFINITIONS = [
+    { eventName: "PreToolUse", matcher: "Bash", command: VCM_BASH_GUARD_HOOK_COMMAND, timeout: 10 },
+    { eventName: "UserPromptSubmit", command: VCM_HOOK_COMMAND, timeout: 5 },
+    { eventName: "Stop", command: VCM_STOP_HOOK_COMMAND, timeout: 10 },
+    { eventName: "PermissionRequest", command: VCM_PERMISSION_REQUEST_HOOK_COMMAND, timeout: 5 }
+];
 const HARNESS_FILES = [
     {
         kind: "root-claude",
         path: "CLAUDE.md",
         title: "CLAUDE.md",
+        blankLineBeforeEnd: true,
         renderRules: renderRootClaudeHarnessRules
     },
     {
@@ -42,12 +50,6 @@ const HARNESS_FILES = [
         commentStyle: "hash",
         renderRules: renderGitignoreHarnessRules
     },
-    {
-        kind: "docs-known-issues",
-        path: "docs/known-issues.md",
-        title: "Known Issues",
-        renderRules: renderKnownIssuesDocHarnessRules
-    },
     {
         kind: "pull-request-template",
         path: ".github/pull_request_template.md",
@@ -97,6 +99,7 @@ const HARNESS_FILES = [
         kind: "agent-architect",
         path: ".claude/agents/architect.md",
         title: "Architect Agent",
+        blankLineBeforeEnd: true,
         frontmatter: renderAgentFrontmatter("architect", "VCM architecture role for plans, module boundaries, public contracts, verifiable behavior, and docs sync."),
         renderRules: renderArchitectHarnessRules
     },
@@ -111,7 +114,7 @@ const HARNESS_FILES = [
         kind: "agent-reviewer",
         path: ".claude/agents/reviewer.md",
         title: "Reviewer Agent",
-        frontmatter: renderAgentFrontmatter("reviewer", "VCM independent review role for acceptance, test adequacy, scope checks, docs gaps, and risk findings."),
+        frontmatter: renderAgentFrontmatter("reviewer", "VCM independent review role for acceptance, test adequacy, scope checks, and risk findings."),
         renderRules: renderReviewerHarnessRules
     }
 ];
@@ -344,10 +347,11 @@ function renderHarnessStatus(analyses) {
     };
 }
 function renderManagedBlock(definition, rules) {
+    const endSpacing = definition.blankLineBeforeEnd ? "\n\n" : "\n";
     if (definition.commentStyle === "hash") {
-        return `# VCM:BEGIN version=${VCM_HARNESS_VERSION}\n${rules.trimEnd()}\n# VCM:END`;
+        return `# VCM:BEGIN version=${VCM_HARNESS_VERSION}\n${rules.trimEnd()}${endSpacing}# VCM:END`;
     }
-    return `<!-- VCM:BEGIN version=${VCM_HARNESS_VERSION} -->\n${rules.trimEnd()}\n<!-- VCM:END -->`;
+    return `<!-- VCM:BEGIN version=${VCM_HARNESS_VERSION} -->\n${rules.trimEnd()}${endSpacing}<!-- VCM:END -->`;
 }
 function getManagedBlockPattern(definition) {
     return definition.commentStyle === "hash"
@@ -427,29 +431,30 @@ function withVcmClaudeHooks(settings) {
             delete hooks[eventName];
         }
     }
-    for (const eventName of VCM_HOOK_EVENTS) {
-        const existingMatchers = Array.isArray(hooks[eventName])
-            ? hooks[eventName]
+    for (const definition of VCM_HOOK_DEFINITIONS) {
+        const existingMatchers = Array.isArray(hooks[definition.eventName])
+            ? hooks[definition.eventName]
             : [];
-        hooks[eventName] = [
+        hooks[definition.eventName] = [
             ...existingMatchers.filter((entry) => !isVcmHookMatcher(entry)),
-            createVcmHookMatcher(eventName)
+            {
+                ...(definition.matcher ? { matcher: definition.matcher } : {}),
+                hooks: [
+                    {
+                        type: "command",
+                        command: definition.command,
+                        timeout: definition.timeout
+                    }
+                ]
+            }
         ];
     }
+    const env = isPlainObject(settings.env) ? { ...settings.env } : {};
+    env.BASH_DEFAULT_TIMEOUT_MS = VCM_BASH_DEFAULT_TIMEOUT_MS;
     return {
         ...settings,
-        hooks
-    };
-}
-function createVcmHookMatcher(eventName) {
-    return {
-        hooks: [
-            {
-                type: "command",
-                command: eventName === "PermissionRequest" ? VCM_PERMISSION_REQUEST_HOOK_COMMAND : VCM_HOOK_COMMAND,
-                timeout: 5
-            }
-        ]
+        hooks,
+        env
     };
 }
 function isVcmHookMatcher(value) {
@@ -460,12 +465,12 @@ function isVcmHookMatcher(value) {
         if (!isPlainObject(hook)) {
             return false;
         }
-        return typeof hook.command === "string" && hook.command.includes("hook-event");
-    }) || value.hooks.some((hook) => {
-        if (!isPlainObject(hook)) {
+        if (typeof hook.command !== "string") {
             return false;
         }
-        return typeof hook.command === "string" && hook.command.includes("/api/hooks/claude-code");
+        return hook.command.includes("VCM") ||
+            hook.command.includes("/api/hooks/claude-code") ||
+            hook.command.includes("hook-event");
     });
 }
 function isPlainObject(value) {

package/dist/backend/services/job-guard-service.js

@@ -0,0 +1,126 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const ACTIVE_JOB_STATUSES = new Set(["queued", "starting", "running"]);
+const QUEUED_JOB_FRESH_MS = 120_000;
+export const MAX_CONSECUTIVE_STOP_BLOCKS = 3;
+export function createJobGuardService(deps = {}) {
+    const isProcessAlive = deps.isProcessAlive ?? defaultIsProcessAlive;
+    const now = deps.now ?? Date.now;
+    const blockStates = new Map();
+    async function findActiveJobs(taskRepoRoot) {
+        const jobsRoot = path.join(taskRepoRoot, ".ai/vcm/jobs");
+        let entries;
+        try {
+            entries = await fs.readdir(jobsRoot);
+        }
+        catch {
+            return [];
+        }
+        const jobs = [];
+        for (const entry of entries.sort()) {
+            const statusPath = path.join(jobsRoot, entry, "status.json");
+            let status;
+            try {
+                status = JSON.parse(await fs.readFile(statusPath, "utf8"));
+            }
+            catch {
+                continue;
+            }
+            if (typeof status.status !== "string" || !ACTIVE_JOB_STATUSES.has(status.status)) {
+                continue;
+            }
+            const processId = numberOrUndefined(status.processId);
+            const workerPid = numberOrUndefined(status.workerPid);
+            const pid = processId ?? workerPid;
+            if (pid !== undefined) {
+                if (!isProcessAlive(pid)) {
+                    continue;
+                }
+            }
+            else {
+                // queued entry whose worker has not reported a pid yet: only trust it briefly
+                try {
+                    const stat = await fs.stat(statusPath);
+                    if (now() - stat.mtimeMs > QUEUED_JOB_FRESH_MS) {
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            let leaseMtimeMs;
+            try {
+                leaseMtimeMs = (await fs.stat(path.join(jobsRoot, entry, "lease"))).mtimeMs;
+            }
+            catch {
+                leaseMtimeMs = undefined;
+            }
+            jobs.push({
+                jobId: typeof status.jobId === "string" ? status.jobId : entry,
+                status: status.status,
+                startedAt: typeof status.startedAt === "string" ? status.startedAt : undefined,
+                timeoutSeconds: numberOrUndefined(status.timeoutSeconds),
+                processId,
+                workerPid,
+                leaseMtimeMs
+            });
+        }
+        return jobs;
+    }
+    return {
+        findActiveJobs,
+        async evaluateStop(input) {
+            const key = stateKey(input);
+            const jobs = await findActiveJobs(input.taskRepoRoot);
+            if (jobs.length === 0) {
+                blockStates.delete(key);
+                return { behavior: "allow" };
+            }
+            const leaseMtimeMs = jobs.reduce((latest, job) => job.leaseMtimeMs !== undefined && (latest === undefined || job.leaseMtimeMs > latest)
+                ? job.leaseMtimeMs
+                : latest, undefined);
+            let state = blockStates.get(key) ?? { count: 0 };
+            const watcherProgressed = state.count > 0
+                && leaseMtimeMs !== undefined
+                && state.lastLeaseMtimeMs !== undefined
+                && leaseMtimeMs > state.lastLeaseMtimeMs;
+            if (watcherProgressed) {
+                state = { count: 0 };
+            }
+            if (state.count >= MAX_CONSECUTIVE_STOP_BLOCKS) {
+                // The role keeps trying to stop without watching; let it stop so the
+                // round can settle. The job worker lease will reap the job itself.
+                blockStates.delete(key);
+                return { behavior: "allow" };
+            }
+            blockStates.set(key, { count: state.count + 1, lastLeaseMtimeMs: leaseMtimeMs });
+            return { behavior: "block", reason: buildBlockReason(jobs) };
+        },
+        notePromptSubmitted(input) {
+            blockStates.delete(stateKey(input));
+        }
+    };
+}
+function stateKey(input) {
+    return `${input.repoRoot}::${input.taskSlug}::${input.role}`;
+}
+function buildBlockReason(jobs) {
+    const first = jobs[0];
+    const listing = jobs.map((job) => `${job.jobId} (${job.status})`).join(", ");
+    return `VCM: validation job ${listing} is still running. Do not end the turn while a validation job is running. `
+        + `Run \`.ai/tools/watch-job ${first.jobId}\` again now and keep watching until it reports a terminal result `
+        + `(success, failed, timeout, or orphaned), then record the result.`;
+}
+function numberOrUndefined(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}

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

@@ -19,7 +19,7 @@ export function createMessageService(deps) {
         if (!(await deps.fs.pathExists(statePath))) {
             return {
                 taskSlug: input.taskSlug,
-                mode: "manual",
+                mode: "auto",
                 updatedAt: now()
             };
         }

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

@@ -1,24 +1,28 @@
 export function renderArchitectHarnessRules() {
-    return `## VCM Architect Rules
+    return `
+## VCM Architect Rules
 
 ### 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.
+- Own \`docs/known-issues.md\` promotion and durable issue updates.
+- Own architecture docs sync across \`docs/ARCHITECTURE.md\` and affected \`<module>/ARCHITECTURE.md\` files.
 - Do not implement production code.
 - 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.
+- Read the role message, durable plans when present, relevant handoff artifacts, \`docs/ARCHITECTURE.md\`, affected \`<module>/ARCHITECTURE.md\` files when present, and affected project docs before planning.
+- Read \`.ai/generated/module-index.json\` when planning module scope, file scope, dependency direction, or phased work.
+- Read \`.ai/generated/public-surface.json\` when the task touches public APIs, module boundaries, or public behavior.
 - 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.
+- The plan must cover changed files, task-local file responsibilities, affected modules, public interfaces or user-visible behavior, required behavior or contract proof points, docs impact, risks, and Replan triggers.
+- For docs impact, state whether changes belong in \`docs/ARCHITECTURE.md\`, affected \`<module>/ARCHITECTURE.md\`, \`.ai/generated/public-surface.json\`, or no durable architecture doc.
 - Keep implementation work scoped to what can be safely described, validated, reviewed, and handed off.
 
 ### Phase Planning
@@ -39,10 +43,17 @@ export function renderArchitectHarnessRules() {
 ### 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.
+- Update \`docs/ARCHITECTURE.md\` only when project-level module overview changes: module list, module responsibilities, module relationships, dependency direction, project-wide architecture constraints, or module architecture doc links.
+- Update affected \`<module>/ARCHITECTURE.md\` when module-level detailed design changes: boundaries, behavior, important public surface explanations, internal risks, or module-specific architecture notes.
+- Treat \`.ai/generated/public-surface.json\` as the full machine index for public surface. Verify or report its freshness when public APIs changed; do not replace it with prose in architecture docs.
+- When module structure changes, require \`.ai/tools/generate-module-index --check\` or regeneration.
+- When crate-external public APIs change, require \`.ai/tools/generate-public-surface --check\` or regeneration.
 - 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.
+
+### Background Jobs
+
+- Never background a Bash command: no \`run_in_background\`, \`nohup\`, \`setsid\`, \`disown\`, or trailing \`&\`.
+- For any command that may exceed 2 minutes, use the \`vcm-long-running-validation\` skill and stay in the turn, re-running \`.ai/tools/watch-job\` until it reports a terminal result.
 `;
 }

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

@@ -3,16 +3,16 @@ export function renderRootClaudeHarnessRules() {
 
 - Use the durable project docs below as role-relevant project truth.
 - Read module-local \`CLAUDE.md\` before editing a subdirectory if one exists.
+- Use \`vcm-route-message\` whenever a VCM role hands off work, asks another role a question, reports a result, reports a blocker, or raises a finding. Follow its write-then-stop rule.
 - Use \`vcm-long-running-validation\` for long-running validation. Follow the background job limits below.
 
 ## VCM Background Jobs
 
-- Do not start background jobs.
-- The only allowed background job is \`.ai/tools/run-long-check\` when used through the \`vcm-long-running-validation\` skill.
-- \`vcm-long-running-validation\` has a hard maximum timeout of 60 minutes.
-- Do not run or suggest operations expected to exceed 60 minutes without user approval.
-- Design every single validation/build operation to complete within 60 minutes; split anything larger before running it.
-- Do not end the current turn only to wait for a long-running shell callback.
+- Never run the Bash tool with \`run_in_background: true\`. Never detach a process with \`nohup\`, \`setsid\`, \`disown\`, or a trailing \`&\`. VCM denies these calls.
+- The only sanctioned long-running mechanism is the \`vcm-long-running-validation\` skill: \`.ai/tools/run-long-check\` plus \`.ai/tools/watch-job\`.
+- The moment a command might run longer than 2 minutes, switch to that skill instead of running the command directly.
+- While a job is running, stay in the current turn and keep calling \`.ai/tools/watch-job\` until it reports a terminal result; VCM blocks turn-end while a job is running, and a job without a live watcher is killed automatically.
+- Hard ceiling: 60 minutes per job, enforced by the job worker. Do not run or suggest operations expected to exceed 60 minutes without user approval; split larger work first.
 
 ## VCM Durable Project Docs
 
@@ -33,23 +33,19 @@ export function renderRootClaudeHarnessRules() {
 - 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.
+- L1 coder unit checks: changed behavior and direct regressions through project-defined unit tests.
 - 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

@@ -1,21 +1,49 @@
 export function renderCoderHarnessRules() {
-    return `## VCM Coder Rules
-
-- Implement only the approved task scope and architecture plan.
-- 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.
+    return `
+## VCM Coder Rules
+
+### Role Scope
+
+- Own implementation and baseline implementation tests inside the approved task scope, current phase, role message, and architecture plan.
+- Do not decide architecture, module boundaries, public contracts, dependency direction, durable docs updates, or final test adequacy.
+
+### Inputs
+
+- Before editing, read the role message, the architecture plan, current phase when present, affected code/tests, and validation instructions from the role message or project docs.
+- Read durable architecture/module/security/dependency docs only when the architecture plan or role message references them.
+- Stop before editing when the architecture plan, role message, allowed write scope, public contract, or validation expectation is missing or unclear; reply to project-manager instead of inferring it.
+- Use \`.ai/generated/module-index.json\` to locate approved module source and test files.
+- Use \`.ai/generated/public-surface.json\` to avoid accidental public API drift.
+
+### Implementation
+
+- Make only the implementation changes needed for the approved scope.
 - 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.
+- Record confirmed out-of-scope issues found during implementation in \`.ai/vcm/handoffs/known-issues.md\`.
+
+### Generated Context
+
+- Regenerate \`.ai/generated/module-index.json\` with \`.ai/tools/generate-module-index\` after module, manifest, source-file, or test-file changes.
+- Regenerate \`.ai/generated/public-surface.json\` with \`.ai/tools/generate-public-surface\` after crate-external public API or public visibility changes.
+- Do not hand-edit generated context files.
+
+### Baseline Tests
+
+- Add or update baseline unit tests for changed behavior: direct unit coverage, key happy path, key boundary or failure path when applicable.
+- Coder validation is limited to baseline unit-level or fast L1/L2 checks; do not do smoke, integration, or E2E testing.
+- If baseline unit tests cannot be run, explain the reason in the route message to project-manager.
+
+### Replan And Continuation
+
+- Stop and request Replan through project-manager when the approved plan conflicts with code reality.
+- Request Replan only for architecture, public contract, dependency, phase-boundary, validation-boundary, or durable-doc changes that must be decided before implementation can continue.
+- Do not request Replan because of workload, session length, or context size.
+- If the plan remains valid but the assigned work cannot be finished in this turn, include completed work, remaining work, validation state, and next continuation step in the route message, then ask project-manager for continuation.
+- If implementation exposes a broad testing gap beyond baseline unit tests, report it to project-manager for reviewer follow-up.
+
+### Background Jobs
+
+- Never background a Bash command: no \`run_in_background\`, \`nohup\`, \`setsid\`, \`disown\`, or trailing \`&\`.
+- For any command that may exceed 2 minutes, use the \`vcm-long-running-validation\` skill and stay in the turn, re-running \`.ai/tools/watch-job\` until it reports a terminal result.
 `;
 }

package/dist/backend/templates/harness/gitignore.js

@@ -1,7 +1,8 @@
 export function renderGitignoreHarnessRules() {
     return [
-        "# VCM local app state, task metadata, session records, and task worktrees.",
+        "# VCM runtime task metadata, handoffs, session records, logs, and task worktrees.",
         ".ai/vcm/",
-        ".claude/worktrees/"
+        ".claude/worktrees/",
+        ".ai/tools/__pycache__/"
     ].join("\n");
 }

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

@@ -1,5 +1,6 @@
 export function renderProjectManagerHarnessRules() {
-    return `## VCM Project Manager Rules
+    return `
+## VCM Project Manager Rules
 
 ### Role Scope
 
@@ -20,22 +21,21 @@ export function renderProjectManagerHarnessRules() {
 
 - 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.
+- Include the confirmed task repo root and branch in each role message.
 
-### Dispatch Artifacts
+### Dispatch
 
-- 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.
+- Use the \`vcm-route-message\` skill for every role dispatch, question, result, blocker, or finding.
+- Route messages 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 route messages; ask architect to determine architecture, file scope, public contracts, validation requirements, and Replan triggers.
+- For coder or reviewer messages, reference existing handoff artifacts instead of making new technical judgments.
 
 ### 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.
+- Each coder phase must complete its assigned implementation before PM dispatches the next phase.
+- Phase validation normally runs through L2; reserve full L3 validation for final task acceptance.
 - Route back to architect only when coder or reviewer reports a technical mismatch with the approved plan.
 
 ### Flow Gates
@@ -48,7 +48,7 @@ export function renderProjectManagerHarnessRules() {
 ### 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.
+- If a role completes a coherent slice and the remaining work still matches the current route, 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.
@@ -68,5 +68,10 @@ export function renderProjectManagerHarnessRules() {
 - 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.
+
+### Background Jobs
+
+- Never background a Bash command: no \`run_in_background\`, \`nohup\`, \`setsid\`, \`disown\`, or trailing \`&\`.
+- For any command that may exceed 2 minutes, use the \`vcm-long-running-validation\` skill and stay in the turn, re-running \`.ai/tools/watch-job\` until it reports a terminal result.
 `;
 }