vibe-coding-master 0.4.14 → 0.4.16

package/README.md

@@ -24,8 +24,9 @@ When Gate Review Gates are enabled for a task, or when a Gate Reviewer session a
 - Optional Gate Reviewer VCM flow role when any Gate Review Gate is enabled.
 - Role session recovery through persisted Claude session ids and `claude --resume`.
 - Permission mode selection before start, resume, or restart:
-  - `default`
   - `bypassPermissions`
+  - `plan`
+  - `default`
 - PM-mediated role messaging through VCM-dispatched route files.
 - Manual and automatic orchestration modes.
 - Two-stage VCM harness setup: deterministic fixed install plus AI-assisted bootstrap.

package/dist/backend/adapters/claude-adapter.js

@@ -29,8 +29,8 @@ export function createClaudeAdapter(runner) {
             else if (effort !== "default") {
                 args.push("--effort", effort);
             }
-            if (permissionMode === "bypassPermissions") {
-                args.push("--permission-mode", "bypassPermissions");
+            if (permissionMode !== "default") {
+                args.push("--permission-mode", permissionMode);
             }
             return {
                 command,

package/dist/backend/api/harness-routes.js

@@ -52,10 +52,12 @@ export function registerHarnessRoutes(app, deps) {
     });
     app.post("/api/projects/harness/bootstrap/start", async (request) => {
         const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
+        await deps.harnessFeedbackService.assertHarnessEngineerAvailable(project.repoRoot);
         return deps.harnessService.startHarnessBootstrap(project.repoRoot, task.worktreePath, request.body ?? {});
     });
     app.post("/api/projects/harness/bootstrap/restart", async (request) => {
         const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
+        await deps.harnessFeedbackService.assertHarnessEngineerAvailable(project.repoRoot);
         return deps.harnessService.restartHarnessBootstrap(project.repoRoot, task.worktreePath, request.body ?? {});
     });
     app.post("/api/projects/harness/bootstrap/stop", async () => {
@@ -64,6 +66,7 @@ export function registerHarnessRoutes(app, deps) {
     });
     app.post("/api/projects/harness/bootstrap/run", async (request) => {
         const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
+        await deps.harnessFeedbackService.assertHarnessEngineerAvailable(project.repoRoot);
         return deps.harnessService.runHarnessBootstrap(project.repoRoot, task.worktreePath);
     });
     app.get("/api/projects/harness/engineer/session", async () => {
@@ -94,6 +97,28 @@ export function registerHarnessRoutes(app, deps) {
         const project = await requireCurrentProject(deps.projectService);
         return deps.sessionService.notifyProjectHarnessEngineerHarnessUpdated(project.repoRoot);
     });
+    app.get("/api/projects/harness/feedback", async (request) => {
+        const project = await requireCurrentProject(deps.projectService);
+        const taskSlug = await normalizeOptionalTaskSlug(deps, project.repoRoot, request.query.taskSlug);
+        return deps.harnessFeedbackService.getState(project.repoRoot, taskSlug);
+    });
+    app.post("/api/projects/harness/feedback/decision", async (request) => {
+        const project = await requireCurrentProject(deps.projectService);
+        const action = request.body?.action;
+        if (action !== "approve" && action !== "reject" && action !== "comment") {
+            throw new VcmError({
+                code: "HARNESS_FEEDBACK_DECISION_INVALID",
+                message: "Harness feedback decision action is invalid.",
+                statusCode: 400
+            });
+        }
+        const taskSlug = await normalizeOptionalTaskSlug(deps, project.repoRoot, request.body?.taskSlug);
+        return deps.harnessFeedbackService.decide(project.repoRoot, {
+            action,
+            taskSlug,
+            comment: typeof request.body?.comment === "string" ? request.body.comment : undefined
+        });
+    });
 }
 function degradedHarnessStatus(error) {
     return {
@@ -151,3 +176,11 @@ async function requireHarnessTaskContext(deps, taskSlug) {
     const task = await deps.taskService.loadTask(project.repoRoot, normalizedTaskSlug);
     return { project, task };
 }
+async function normalizeOptionalTaskSlug(deps, repoRoot, taskSlug) {
+    const normalizedTaskSlug = taskSlug?.trim();
+    if (!normalizedTaskSlug) {
+        return undefined;
+    }
+    await deps.taskService.loadTask(repoRoot, normalizedTaskSlug);
+    return normalizedTaskSlug;
+}

package/dist/backend/cli/install-vcm-harness.js

@@ -16,6 +16,7 @@ import { renderReviewerHarnessRules } from "../templates/harness/reviewer-agent.
 import { renderVcmFinalAcceptanceSkillRules } from "../templates/harness/vcm-final-acceptance-skill.js";
 import { renderVcmHarnessBootstrapSkillRules } from "../templates/harness/vcm-harness-bootstrap-skill.js";
 import { renderVcmLongRunningValidationSkillRules } from "../templates/harness/vcm-long-running-validation-skill.js";
+import { renderVcmReportHarnessIssueSkillRules } from "../templates/harness/vcm-report-harness-issue-skill.js";
 import { renderVcmRouteMessageSkillRules } from "../templates/harness/vcm-route-message-skill.js";
 const HARNESS_VERSION = "0.3.0-fixed";
 const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -203,6 +204,12 @@ const WHOLE_FILES = [
         mode: 0o644,
         content: renderSkillFile("VCM Gate Review Skill", "vcm-gate-review", "Use when project-manager reaches a Gate Review trigger or receives a VCM Gate Review callback.", renderVcmGateReviewSkillRules())
     },
+    {
+        path: ".claude/skills/vcm-report-harness-issue/SKILL.md",
+        category: "skill",
+        mode: 0o644,
+        content: renderSkillFile("VCM Report Harness Issue Skill", "vcm-report-harness-issue", "Use when a VCM role notices a reusable harness problem and needs to record feedback for Harness Engineer review.", renderVcmReportHarnessIssueSkillRules())
+    },
     {
         path: ".ai/tools/request-gate-review",
         category: "runtime-tool",
@@ -422,6 +429,7 @@ function fixedDirectories() {
         ".claude/skills/vcm-long-running-validation/",
         ".claude/skills/vcm-route-message/",
         ".claude/skills/vcm-gate-review/",
+        ".claude/skills/vcm-report-harness-issue/",
         ".ai/vcm/translations/",
         ".ai/vcm/gate-reviews/",
         ".ai/tools/",

package/dist/backend/server.js

@@ -11,6 +11,7 @@ import { createGitAdapter } from "./adapters/git-adapter.js";
 import { createAppSettingsService } from "./services/app-settings-service.js";
 import { createClaudeTranscriptService } from "./services/claude-transcript-service.js";
 import { createGateReviewService } from "./services/gate-review-service.js";
+import { createHarnessFeedbackService } from "./services/harness-feedback-service.js";
 import { createTranslationWorkerService } from "./services/translation-worker-service.js";
 import { createHarnessService, createScriptFixedHarnessInstaller } from "./services/harness-service.js";
 import { createNodeFileSystemAdapter } from "./adapters/filesystem.js";
@@ -79,6 +80,7 @@ export async function createServer(deps, options = {}) {
     registerHarnessRoutes(app, {
         projectService: deps.projectService,
         harnessService: deps.harnessService,
+        harnessFeedbackService: deps.harnessFeedbackService,
         sessionService: deps.sessionService,
         taskService: deps.taskService
     });
@@ -185,6 +187,11 @@ export function createDefaultServerDeps(options = {}) {
         harnessEngineerSessions: sessionService,
         runFixedInstaller: createScriptFixedHarnessInstaller(path.join(getAppRoot(), "scripts/install-vcm-harness.mjs"))
     });
+    const harnessFeedbackService = createHarnessFeedbackService({
+        fs,
+        runtime,
+        sessionService
+    });
     const commandDispatcher = createCommandDispatcher({
         runtime,
         sessionService,
@@ -264,6 +271,7 @@ export function createDefaultServerDeps(options = {}) {
         appSettings,
         runtime,
         harnessService,
+        harnessFeedbackService,
         gatewayService,
         jobGuard: createJobGuardService(),
         translationWorkerService
@@ -281,6 +289,7 @@ export function createDefaultServerDeps(options = {}) {
         sessionService,
         artifactService,
         harnessService,
+        harnessFeedbackService,
         commandDispatcher,
         claudeHookService,
         messageService,

package/dist/backend/services/app-settings-service.js

@@ -283,7 +283,7 @@ function normalizeRoleLaunchTemplateEntry(input, fallback) {
     };
 }
 function normalizeClaudePermissionMode(input, fallback) {
-    if (input === "bypassPermissions" || input === "default") {
+    if (input === "bypassPermissions" || input === "plan" || input === "default") {
         return input;
     }
     return fallback;

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

@@ -88,6 +88,7 @@ export function createClaudeHookService(deps) {
             sessionId: session?.id,
             claudeSessionId: stringOrUndefined(input.event.session_id)
         });
+        await deps.harnessFeedbackService?.recordHarnessEngineerHook(context.project.repoRoot, eventName);
         return {
             ok: true,
             eventName,

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

@@ -0,0 +1,406 @@
+import path from "node:path";
+import { resolveRepoPath, toRepoRelativePath } from "../adapters/filesystem.js";
+import { VcmError } from "../errors.js";
+import { submitTerminalInput } from "../runtime/terminal-submit.js";
+const FEEDBACK_ROOT = ".ai/vcm/harness-feedback";
+const PENDING_DIR = `${FEEDBACK_ROOT}/pending`;
+const ACTIVE_DIR = `${FEEDBACK_ROOT}/active`;
+const COMPLETED_DIR = `${FEEDBACK_ROOT}/completed`;
+const STATE_PATH = `${FEEDBACK_ROOT}/state.json`;
+export function createHarnessFeedbackService(deps) {
+    const now = deps.now ?? (() => new Date().toISOString());
+    async function getState(repoRoot, activeTaskSlug) {
+        await maybeDispatchNext(repoRoot, activeTaskSlug);
+        return buildStateReport(repoRoot);
+    }
+    async function decide(repoRoot, input) {
+        const state = await loadStoredState(repoRoot);
+        if (!state || state.status !== "awaiting_user_approval") {
+            throw new VcmError({
+                code: "HARNESS_FEEDBACK_NOT_AWAITING_APPROVAL",
+                message: "There is no Harness feedback waiting for user approval.",
+                statusCode: 409
+            });
+        }
+        if (input.action === "reject") {
+            await completeActive(repoRoot, state, "rejected", input.comment);
+            await clearStoredState(repoRoot);
+            return getState(repoRoot, input.taskSlug);
+        }
+        const taskSlug = input.taskSlug?.trim();
+        if (!taskSlug) {
+            throw new VcmError({
+                code: "HARNESS_FEEDBACK_TASK_REQUIRED",
+                message: "Select an active task before asking Harness Engineer to continue feedback work.",
+                statusCode: 409
+            });
+        }
+        if (input.action === "comment") {
+            const session = await ensureIdleHarnessEngineer(repoRoot, taskSlug);
+            const timestamp = now();
+            const nextState = {
+                ...state,
+                status: "analyzing",
+                active: {
+                    ...state.active,
+                    updatedAt: timestamp,
+                    lastPromptAt: timestamp
+                }
+            };
+            await persistStoredState(repoRoot, nextState);
+            await submitTerminalInput(deps.runtime, session.id, buildFeedbackCommentPrompt(repoRoot, nextState.active, input.comment ?? ""));
+            return buildStateReport(repoRoot);
+        }
+        const session = await ensureIdleHarnessEngineer(repoRoot, taskSlug);
+        const timestamp = now();
+        const nextState = {
+            ...state,
+            status: "applying",
+            active: {
+                ...state.active,
+                updatedAt: timestamp,
+                lastPromptAt: timestamp
+            }
+        };
+        await persistStoredState(repoRoot, nextState);
+        await submitTerminalInput(deps.runtime, session.id, buildFeedbackApplyPrompt(repoRoot, nextState.active, input.comment ?? ""));
+        return buildStateReport(repoRoot);
+    }
+    async function recordHarnessEngineerHook(repoRoot, eventName) {
+        if (eventName !== "Stop" && eventName !== "StopFailure") {
+            return;
+        }
+        const state = await loadStoredState(repoRoot);
+        if (!state) {
+            return;
+        }
+        const timestamp = now();
+        if (state.status === "analyzing") {
+            await persistStoredState(repoRoot, {
+                ...state,
+                status: "awaiting_user_approval",
+                active: {
+                    ...state.active,
+                    updatedAt: timestamp
+                }
+            });
+            return;
+        }
+        if (state.status === "applying") {
+            await completeActive(repoRoot, {
+                ...state,
+                active: {
+                    ...state.active,
+                    updatedAt: timestamp
+                }
+            }, "applied");
+            await clearStoredState(repoRoot);
+        }
+    }
+    async function assertHarnessEngineerAvailable(repoRoot) {
+        const state = await loadStoredState(repoRoot);
+        if (!state) {
+            return;
+        }
+        throw new VcmError({
+            code: "HARNESS_ENGINEER_FEEDBACK_ACTIVE",
+            message: "Harness Engineer is reserved for an active Harness feedback item.",
+            statusCode: 409,
+            hint: state.status === "awaiting_user_approval"
+                ? "Review, approve, comment, or reject the current Harness feedback before starting another Harness Engineer task."
+                : "Wait for the current Harness feedback turn to finish before starting another Harness Engineer task."
+        });
+    }
+    async function maybeDispatchNext(repoRoot, activeTaskSlug) {
+        const state = await loadStoredState(repoRoot);
+        if (state) {
+            return;
+        }
+        const pending = await listPendingFeedback(repoRoot);
+        const next = pending[0];
+        const taskSlug = activeTaskSlug?.trim();
+        if (!next || !taskSlug) {
+            return;
+        }
+        const session = await getIdleHarnessEngineer(repoRoot, taskSlug);
+        if (!session) {
+            return;
+        }
+        const timestamp = now();
+        const analysisPath = `${ACTIVE_DIR}/${next.id}/analysis.md`;
+        const applyReportPath = `${ACTIVE_DIR}/${next.id}/apply-report.md`;
+        const active = {
+            ...next,
+            feedbackPath: next.path,
+            analysisPath,
+            applyReportPath,
+            startedAt: timestamp,
+            updatedAt: timestamp,
+            lastPromptAt: timestamp
+        };
+        const nextState = {
+            version: 1,
+            status: "analyzing",
+            active
+        };
+        await persistStoredState(repoRoot, nextState);
+        await deps.fs.ensureDir(resolveRepoPath(repoRoot, path.posix.dirname(analysisPath)));
+        await submitTerminalInput(deps.runtime, session.id, await buildFeedbackAnalysisPrompt(repoRoot, active));
+    }
+    async function getIdleHarnessEngineer(repoRoot, taskSlug) {
+        const existing = await deps.sessionService.getProjectHarnessEngineerSession(repoRoot);
+        if (existing?.status === "running" && existing.activityStatus === "running") {
+            return undefined;
+        }
+        const session = await deps.sessionService.ensureProjectHarnessEngineerSession(repoRoot, {
+            taskSlug,
+            cols: 120,
+            rows: 32
+        });
+        if (session.status !== "running" || session.activityStatus === "running") {
+            return undefined;
+        }
+        if (!deps.runtime.getSession(session.id)) {
+            return undefined;
+        }
+        return session;
+    }
+    async function ensureIdleHarnessEngineer(repoRoot, taskSlug) {
+        const session = await getIdleHarnessEngineer(repoRoot, taskSlug);
+        if (!session) {
+            throw new VcmError({
+                code: "HARNESS_ENGINEER_BUSY",
+                message: "Harness Engineer is busy or unavailable.",
+                statusCode: 409,
+                hint: "Wait for the current Harness Engineer turn to finish, then retry."
+            });
+        }
+        return session;
+    }
+    async function buildStateReport(repoRoot) {
+        const [state, pending] = await Promise.all([
+            loadStoredState(repoRoot),
+            listPendingFeedback(repoRoot)
+        ]);
+        if (!state) {
+            return {
+                version: 1,
+                status: pending.length > 0 ? "queued" : "idle",
+                queuedCount: pending.length,
+                pending,
+                warnings: []
+            };
+        }
+        const active = await readActiveItem(repoRoot, state);
+        return {
+            version: 1,
+            status: state.status,
+            queuedCount: Math.max(0, pending.length - (pending.some((item) => item.id === state.active.id) ? 1 : 0)),
+            pending: pending.filter((item) => item.id !== state.active.id),
+            active,
+            warnings: []
+        };
+    }
+    async function readActiveItem(repoRoot, state) {
+        const feedbackContent = await readOptionalText(repoRoot, state.active.feedbackPath) ?? "";
+        const analysisContent = await readOptionalText(repoRoot, state.active.analysisPath);
+        const applyReportContent = await readOptionalText(repoRoot, state.active.applyReportPath);
+        return {
+            id: state.active.id,
+            title: state.active.title,
+            path: state.active.path,
+            reporterRole: state.active.reporterRole,
+            taskSlug: state.active.taskSlug,
+            summary: state.active.summary,
+            status: state.status,
+            startedAt: state.active.startedAt,
+            updatedAt: state.active.updatedAt,
+            feedbackContent,
+            analysisPath: state.active.analysisPath,
+            analysisContent,
+            applyReportPath: state.active.applyReportPath,
+            applyReportContent
+        };
+    }
+    async function listPendingFeedback(repoRoot) {
+        const pendingDir = resolveRepoPath(repoRoot, PENDING_DIR);
+        if (!(await deps.fs.pathExists(pendingDir))) {
+            return [];
+        }
+        const names = await deps.fs.readDir(pendingDir);
+        const markdownFiles = names
+            .filter((name) => name.endsWith(".md") && !name.includes("/") && !name.includes("\\"))
+            .sort();
+        const items = await Promise.all(markdownFiles.map(async (name) => {
+            const relativePath = `${PENDING_DIR}/${name}`;
+            const content = await readOptionalText(repoRoot, relativePath) ?? "";
+            return parseFeedbackItem(relativePath, content);
+        }));
+        return items;
+    }
+    function parseFeedbackItem(relativePath, content) {
+        const id = sanitizeFeedbackId(path.posix.basename(relativePath, ".md"));
+        const metadata = parseSimpleMetadata(content);
+        const title = firstHeading(content)
+            ?? metadata.summary
+            ?? metadata["observed problem"]
+            ?? id;
+        return {
+            id,
+            title: compactLine(title),
+            path: relativePath,
+            reporterRole: metadata["reporter role"] ?? metadata.reporter,
+            taskSlug: metadata["task slug"] ?? metadata.task,
+            summary: metadata.summary
+        };
+    }
+    async function buildFeedbackAnalysisPrompt(repoRoot, active) {
+        const feedback = await readOptionalText(repoRoot, active.feedbackPath) ?? "";
+        return [
+            "[VCM Harness Feedback Analysis]",
+            "",
+            "Analyze this harness feedback. Do not edit files yet.",
+            "",
+            `Base repository root: ${repoRoot}`,
+            `Feedback file: ${resolveRepoPath(repoRoot, active.feedbackPath)}`,
+            `Result path: ${resolveRepoPath(repoRoot, active.analysisPath)}`,
+            "",
+            "Rules:",
+            "- Decide whether the reported issue is a real reusable harness problem.",
+            "- Inspect relevant harness files before judging.",
+            "- If the issue is not real or does not need a harness change, say so in the result file.",
+            "- If it should be fixed, write a short proposal with affected files, proposed diff shape, risks, validation, and whether a VCM GitHub issue is needed.",
+            "- Do not edit harness files or product source during this analysis turn.",
+            "- End your turn after writing the result file.",
+            "",
+            "<HARNESS_FEEDBACK>",
+            feedback.trimEnd(),
+            "</HARNESS_FEEDBACK>"
+        ].join("\n");
+    }
+    function buildFeedbackCommentPrompt(repoRoot, active, comment) {
+        return [
+            "[VCM Harness Feedback Revision]",
+            "",
+            "The user reviewed your harness feedback analysis and added comments.",
+            "",
+            `Feedback file: ${resolveRepoPath(repoRoot, active.feedbackPath)}`,
+            `Current analysis path: ${resolveRepoPath(repoRoot, active.analysisPath)}`,
+            `Rewrite the analysis result at: ${resolveRepoPath(repoRoot, active.analysisPath)}`,
+            "",
+            "Rules:",
+            "- Do not edit harness files yet.",
+            "- Address the user's comments and keep the proposal concise.",
+            "- End your turn after updating the analysis result file.",
+            "",
+            "<USER_COMMENT>",
+            comment.trim(),
+            "</USER_COMMENT>"
+        ].join("\n");
+    }
+    function buildFeedbackApplyPrompt(repoRoot, active, comment) {
+        return [
+            "[VCM Harness Feedback Approved]",
+            "",
+            "The user approved this harness improvement. Apply only the approved harness changes.",
+            "",
+            `Base repository root: ${repoRoot}`,
+            `Feedback file: ${resolveRepoPath(repoRoot, active.feedbackPath)}`,
+            `Approved analysis path: ${resolveRepoPath(repoRoot, active.analysisPath)}`,
+            `Write completion report to: ${resolveRepoPath(repoRoot, active.applyReportPath)}`,
+            "",
+            "Rules:",
+            "- Work in the active task worktree.",
+            "- Edit only harness files and project harness docs that are necessary for the approved change.",
+            "- Do not edit product source code.",
+            "- Do not overwrite VCM fixed managed blocks; draft an issue instead if a fixed template is wrong.",
+            "- Stage the harness changes and create a commit yourself.",
+            "- Write the completion report with files changed, commit id if available, validation run, and any follow-up.",
+            "- End your turn after the report is written.",
+            ...(comment.trim()
+                ? ["", "<USER_APPROVAL_COMMENT>", comment.trim(), "</USER_APPROVAL_COMMENT>"]
+                : [])
+        ].join("\n");
+    }
+    async function completeActive(repoRoot, state, outcome, comment = "") {
+        const completedDir = `${COMPLETED_DIR}/${state.active.id}`;
+        await deps.fs.ensureDir(resolveRepoPath(repoRoot, completedDir));
+        const feedbackContent = await readOptionalText(repoRoot, state.active.feedbackPath);
+        const analysisContent = await readOptionalText(repoRoot, state.active.analysisPath);
+        const applyReportContent = await readOptionalText(repoRoot, state.active.applyReportPath);
+        if (feedbackContent !== undefined) {
+            await deps.fs.writeText(resolveRepoPath(repoRoot, `${completedDir}/feedback.md`), feedbackContent);
+        }
+        if (analysisContent !== undefined) {
+            await deps.fs.writeText(resolveRepoPath(repoRoot, `${completedDir}/analysis.md`), analysisContent);
+        }
+        if (applyReportContent !== undefined) {
+            await deps.fs.writeText(resolveRepoPath(repoRoot, `${completedDir}/apply-report.md`), applyReportContent);
+        }
+        await deps.fs.writeJsonAtomic(resolveRepoPath(repoRoot, `${completedDir}/decision.json`), {
+            version: 1,
+            id: state.active.id,
+            title: state.active.title,
+            outcome,
+            comment,
+            completedAt: now()
+        });
+        await deps.fs.removePath?.(resolveRepoPath(repoRoot, state.active.feedbackPath), { force: true });
+        await deps.fs.removePath?.(resolveRepoPath(repoRoot, path.posix.dirname(state.active.analysisPath)), { recursive: true, force: true });
+    }
+    async function loadStoredState(repoRoot) {
+        const statePath = resolveRepoPath(repoRoot, STATE_PATH);
+        if (!(await deps.fs.pathExists(statePath))) {
+            return undefined;
+        }
+        const state = await deps.fs.readJson(statePath);
+        if (state?.version !== 1 || !state.active?.id || !state.status) {
+            return undefined;
+        }
+        return state;
+    }
+    async function persistStoredState(repoRoot, state) {
+        await deps.fs.writeJsonAtomic(resolveRepoPath(repoRoot, STATE_PATH), state);
+    }
+    async function clearStoredState(repoRoot) {
+        await deps.fs.removePath?.(resolveRepoPath(repoRoot, STATE_PATH), { force: true });
+    }
+    async function readOptionalText(repoRoot, relativePath) {
+        const absolutePath = resolveRepoPath(repoRoot, relativePath);
+        if (!(await deps.fs.pathExists(absolutePath))) {
+            return undefined;
+        }
+        return deps.fs.readText(absolutePath);
+    }
+    return {
+        getState,
+        decide,
+        recordHarnessEngineerHook,
+        assertHarnessEngineerAvailable
+    };
+}
+function parseSimpleMetadata(content) {
+    const result = {};
+    for (const line of content.split(/\r?\n/).slice(0, 80)) {
+        const match = /^[-*]?\s*([A-Za-z][A-Za-z -]{1,40})\s*:\s*(.+)$/.exec(line.trim());
+        if (!match) {
+            continue;
+        }
+        result[match[1].trim().toLowerCase()] = match[2].trim();
+    }
+    return result;
+}
+function firstHeading(content) {
+    const heading = content.split(/\r?\n/).find((line) => /^#{1,3}\s+\S/.test(line));
+    return heading?.replace(/^#{1,3}\s+/, "").trim();
+}
+function compactLine(value) {
+    return value.replace(/\s+/g, " ").trim().slice(0, 160);
+}
+function sanitizeFeedbackId(value) {
+    const sanitized = value.replace(/[^A-Za-z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    return sanitized || "feedback";
+}
+export function getHarnessFeedbackRelativePath(repoRoot, absolutePath) {
+    return toRepoRelativePath(repoRoot, absolutePath);
+}

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

@@ -13,6 +13,7 @@ import { renderReviewerHarnessRules } from "../templates/harness/reviewer-agent.
 import { renderVcmFinalAcceptanceSkillRules } from "../templates/harness/vcm-final-acceptance-skill.js";
 import { renderVcmHarnessBootstrapSkillRules } from "../templates/harness/vcm-harness-bootstrap-skill.js";
 import { renderVcmLongRunningValidationSkillRules } from "../templates/harness/vcm-long-running-validation-skill.js";
+import { renderVcmReportHarnessIssueSkillRules } from "../templates/harness/vcm-report-harness-issue-skill.js";
 import { renderVcmRouteMessageSkillRules } from "../templates/harness/vcm-route-message-skill.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { VcmError } from "../errors.js";
@@ -104,6 +105,14 @@ const HARNESS_FILES = [
         ownership: "whole-file",
         renderRules: renderVcmGateReviewSkillRules
     },
+    {
+        kind: "skill-vcm-report-harness-issue",
+        path: ".claude/skills/vcm-report-harness-issue/SKILL.md",
+        title: "VCM Report Harness Issue Skill",
+        frontmatter: renderSkillFrontmatter("vcm-report-harness-issue", "Use when a VCM role notices a reusable harness problem and needs to record feedback for Harness Engineer review."),
+        ownership: "whole-file",
+        renderRules: renderVcmReportHarnessIssueSkillRules
+    },
     {
         kind: "agent-gate-reviewer",
         path: ".claude/agents/gate-reviewer.md",

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

@@ -72,6 +72,7 @@ export function createSessionService(deps) {
             cwd: startCommand.cwd,
             env: {
                 VCM_API_URL: deps.apiUrl,
+                VCM_BASE_REPO_ROOT: repoRoot,
                 VCM_TASK_REPO_ROOT: taskRepoRoot,
                 VCM_TASK_SLUG: taskSlug,
                 VCM_ROLE: role,
@@ -151,6 +152,7 @@ export function createSessionService(deps) {
             cwd: startCommand.cwd,
             env: {
                 VCM_API_URL: deps.apiUrl,
+                VCM_BASE_REPO_ROOT: repoRoot,
                 VCM_TASK_REPO_ROOT: activeTaskRepoRoot ?? repoRoot,
                 VCM_TASK_SLUG: activeTaskSlug ?? PROJECT_GATE_REVIEWER_SCOPE,
                 VCM_ROLE: GATE_REVIEWER_ROLE,
@@ -246,6 +248,7 @@ export function createSessionService(deps) {
             cwd: startCommand.cwd,
             env: {
                 VCM_API_URL: deps.apiUrl,
+                VCM_BASE_REPO_ROOT: repoRoot,
                 VCM_TASK_REPO_ROOT: taskContext.taskRepoRoot,
                 VCM_TASK_SLUG: taskContext.taskSlug,
                 VCM_ROLE: TRANSLATOR_ROLE,
@@ -322,6 +325,7 @@ export function createSessionService(deps) {
             cwd: startCommand.cwd,
             env: {
                 VCM_API_URL: deps.apiUrl,
+                VCM_BASE_REPO_ROOT: repoRoot,
                 VCM_TASK_REPO_ROOT: taskContext.taskRepoRoot,
                 VCM_TASK_SLUG: taskContext.taskSlug,
                 VCM_ROLE: HARNESS_ENGINEER_ROLE,
@@ -426,6 +430,7 @@ export function createSessionService(deps) {
             cwd: startCommand.cwd,
             env: {
                 VCM_API_URL: deps.apiUrl,
+                VCM_BASE_REPO_ROOT: repoRoot,
                 VCM_TASK_REPO_ROOT: targetCwd,
                 VCM_TASK_SLUG: normalizeProjectScopedRecordForPersistence(session).taskSlug,
                 VCM_ROLE: session.role,
@@ -1438,6 +1443,9 @@ function normalizeClaudePermissionMode(value) {
     if (value === "bypassPermissions" || value === "dangerously-skip-permissions") {
         return "bypassPermissions";
     }
+    if (value === "plan") {
+        return "plan";
+    }
     return "default";
 }
 function normalizeClaudeModel(value) {

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

@@ -5,8 +5,15 @@ export function renderRootClaudeHarnessRules() {
 - 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.
+- Use \`vcm-report-harness-issue\` when you notice a reusable VCM harness problem. Record feedback; do not contact Harness Engineer directly.
 - Project-manager uses \`vcm-gate-review\` at enabled Gate Review trigger points and on VCM Gate Review callbacks.
 
+## VCM Harness Scope
+
+VCM harness includes root \`CLAUDE.md\`, \`.claude/agents/**\`, \`.claude/skills/**\`, \`.ai/tools/**\`, \`.claude/settings.json\`, VCM managed blocks, generated-context tooling, bootstrap rules, routing rules, validation rules, Gate Review rules, Translator rules, and Harness Engineer rules.
+
+If a reusable harness problem is suspected, it is enough to record a concise feedback report with evidence. Harness Engineer decides whether it is real, whether it should be fixed, and which files are in scope.
+
 ## VCM Background Jobs
 
 - 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.