vibe-coding-master 0.2.7 → 0.2.8

package/README.md

@@ -405,15 +405,28 @@ CLAUDE.md
 .ai/tools/generate-public-surface
 .ai/tools/run-long-check
 .ai/tools/watch-job
+.ai/tools/vcm-bash-guard
 .github/pull_request_template.md
 ```
 
 Repo-local skills are installed as `.claude/skills/<skill-name>/SKILL.md` so
 Claude Code can register them.
 
-VCM roles must not start background jobs. The only allowed background job is
-`.ai/tools/run-long-check` when used through `vcm-long-running-validation`;
-`.ai/tools/watch-job` enforces a 60 minute maximum timeout.
+VCM roles must not run background Bash. A `PreToolUse` hook
+(`.ai/tools/vcm-bash-guard`) denies `run_in_background`, `nohup`, `setsid`,
+`disown`, and trailing `&` calls in VCM role sessions. The only sanctioned
+long-running mechanism is `.ai/tools/run-long-check` plus
+`.ai/tools/watch-job` through `vcm-long-running-validation`:
+
+- The detached job worker itself enforces the job ceiling (`--timeout`, max 60
+  minutes) and a supervision lease: a job left without a live foreground
+  watcher for about 2 minutes is killed and recorded as `orphaned`.
+- `watch-job` renews the lease and watches in windows of up to 8 minutes; it
+  exits `125` while the job is still running instead of killing it, and the
+  role re-runs it in the same turn until a terminal result.
+- The VCM backend blocks a role from ending its turn while one of its
+  validation jobs is still running.
+- Only one validation job may be active at a time.
 
 If a managed-block file already exists, VCM preserves user-authored content and only inserts or replaces the VCM block:
 
@@ -434,7 +447,7 @@ For `.gitignore`, VCM uses a gitignore-native managed block:
 
 `.ai/vcm/` is the active VCM local control area, and `.claude/worktrees/` is the Claude-compatible task worktree area. VCM keeps the task index in app-local project state under `~/.vcm/projects/`; each task runtime repo keeps its own session, message, orchestration, and translation state.
 
-VCM also JSON-merges `.claude/settings.json` to install Claude Code `UserPromptSubmit` and `Stop` hooks. The hooks post directly to the local VCM backend, so roles do not need a VCM CLI command to confirm delivery or report turn completion.
+VCM also JSON-merges `.claude/settings.json` to install Claude Code `PreToolUse`, `UserPromptSubmit`, `Stop`, and `PermissionRequest` hooks plus a managed `env.BASH_DEFAULT_TIMEOUT_MS` so foreground watch windows fit inside the Bash tool timeout. The hooks post directly to the local VCM backend, so roles do not need a VCM CLI command to confirm delivery or report turn completion. The `Stop` hook forwards the backend response to Claude Code, which lets VCM block turn-end while a validation job is still running.
 
 Bootstrap is AI-assisted. VCM starts a visible temporary Claude Code session in the connected repository and asks it to use the `vcm-harness-bootstrap` skill. Bootstrap fills project-specific content and generated context:
 

package/dist/backend/api/claude-hook-routes.js

@@ -2,8 +2,14 @@ export function registerClaudeHookRoutes(app, deps) {
     app.post("/api/hooks/claude-code", async (request) => {
         return deps.claudeHookService.handleHook(request.body);
     });
+    // The installed Stop hook pipes this response straight to Claude Code, so
+    // the body must be exactly the Stop-hook stdout contract.
     app.post("/api/hooks/claude-code/stop", async (request) => {
-        return deps.claudeHookService.handleStopHook(request.body);
+        const result = await deps.claudeHookService.handleStopHook(request.body);
+        if (result.stopDecision) {
+            return { decision: "block", reason: result.stopDecision.reason };
+        }
+        return {};
     });
     app.post("/api/hooks/claude-code/permission-request", async (request, reply) => {
         const result = await deps.claudeHookService.handlePermissionRequestHook(request.body);

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/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");
 }