vibe-coding-master 0.7.27 → 0.7.28

package/README.md

@@ -148,12 +148,15 @@ the active task worktree:
 - `.claude/agents/**`
 - `.claude/skills/**`
 - `.claude/settings.json` hooks
-- `.ai/tools/**`
+- VCM protocol and runtime tools under `.ai/tools/**`
 - `.gitignore` entries for VCM runtime state and task worktrees
-- generated-context tooling
+- initial project-owned generated-context tooling
 - pull request template
 
 VCM preserves user-authored content outside VCM managed blocks.
+VCM seeds `.ai/tools/generate-module-index` and
+`.ai/tools/generate-public-surface` only when missing. After installation these
+generators belong to the project and later harness updates do not replace them.
 
 The fixed harness install is deterministic and creates a commit in the active
 task worktree. Bootstrap is AI-assisted and is run through the Harness Engineer

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

@@ -229,13 +229,7 @@ const DURABLE_DOC_TEMPLATES = [
         content: "# Testing\n"
     },
 ];
-const WHOLE_FILES = [
-    {
-        path: ".ai/tools/check-durable-docs",
-        category: "durable-docs-tool",
-        mode: 0o755,
-        templatePath: "scripts/harness-tools/check-durable-docs"
-    },
+const PROJECT_OWNED_FILES = [
     {
         path: ".ai/tools/generate-module-index",
         category: "generated-context-tool",
@@ -247,6 +241,14 @@ const WHOLE_FILES = [
         category: "generated-context-tool",
         mode: 0o755,
         templatePath: "scripts/harness-tools/generate-public-surface"
+    }
+];
+const WHOLE_FILES = [
+    {
+        path: ".ai/tools/check-durable-docs",
+        category: "durable-docs-tool",
+        mode: 0o755,
+        templatePath: "scripts/harness-tools/check-durable-docs"
     },
     {
         path: ".claude/skills/vcm-architecture-interview/SKILL.md",
@@ -397,6 +399,9 @@ async function main() {
     for (const file of WHOLE_FILES) {
         await installWholeFile({ projectRoot, file, dryRun, operations });
     }
+    for (const file of PROJECT_OWNED_FILES) {
+        await installProjectOwnedFile({ projectRoot, file, dryRun, operations });
+    }
     await removeLegacyFlatSkillFiles({ projectRoot, dryRun, operations });
     await removeLegacyCodexHarnessPaths({ projectRoot, dryRun, operations });
     await installManifest({
@@ -511,6 +516,14 @@ async function buildManifest(projectRoot) {
             ...fixedDirectories().map((directory) => manifestEntry(directory, "directory", directoryCategory(directory), "vcm-created")),
             manifestEntry("docs/GLOSSARY.md", "file", "project-glossary", "project-owned"),
             manifestEntry("docs/CODING_STANDARDS.md", "file", "project-coding-standards", "project-owned"),
+            ...PROJECT_OWNED_FILES.map((file) => ({
+                path: file.path,
+                entryType: "file",
+                category: file.category,
+                ownership: "project-owned",
+                source: "vcm-template",
+                lifecycle: "long-term"
+            })),
             ...WHOLE_FILES.map((file) => ({
                 path: file.path,
                 entryType: "file",
@@ -820,6 +833,23 @@ async function installWholeFile({ projectRoot, file, dryRun, operations }) {
         action: "write fixed VCM file"
     });
 }
+async function installProjectOwnedFile({ projectRoot, file, dryRun, operations }) {
+    const targetPath = resolveInside(projectRoot, file.path);
+    if (await pathExists(targetPath)) {
+        operations.push(skip(file.path, "exists; project-owned"));
+        return;
+    }
+    const content = await wholeFileContent(file);
+    await writeIfChanged({
+        targetPath,
+        relativePath: file.path,
+        content: ensureTrailingNewline(content),
+        mode: file.mode,
+        dryRun,
+        operations,
+        action: "seed project-owned VCM file"
+    });
+}
 async function removeLegacyFlatSkillFiles({ projectRoot, dryRun, operations }) {
     const wholeFilesByPath = new Map(WHOLE_FILES.map((file) => [file.path, file]));
     for (const legacy of LEGACY_FLAT_SKILL_FILES) {

package/dist/backend/services/gate-review-service.js

@@ -1014,10 +1014,12 @@ async function readArchitectureBriefError(fs, taskRepoRoot) {
     const content = await fs.readText(absolutePath);
     const check = checkMarkdownArtifact("architecture-brief", relativePath, content);
     if (check.status !== "ok") {
-        return `${relativePath} is incomplete. Complete and confirm Architect Interview before requesting architecture-plan review.`;
+        return `${relativePath} is incomplete and cannot start architecture-plan review. ${formatArtifactCheckFailure(check)}`;
     }
-    if (!/^\s*Architecture Brief Status\s*:\s*confirmed\s*$/im.test(content)) {
-        return `${relativePath} is not confirmed. Obtain explicit user confirmation before architecture planning.`;
+    const status = /^\s*Architecture Brief Status\s*:\s*(.+?)\s*$/im.exec(content)?.[1]?.trim();
+    if (status?.toLowerCase() !== "confirmed") {
+        return `${relativePath} is not confirmed and cannot start architecture-plan review. `
+            + `Architecture Brief Status must be exactly "confirmed"; found ${renderFoundValue(status)}.`;
     }
     return undefined;
 }
@@ -1032,12 +1034,8 @@ async function readValidationReportError(fs, taskRepoRoot) {
     if (check.status === "ok") {
         return undefined;
     }
-    const details = [
-        check.missingHeadings.length > 0 ? `missing headings: ${check.missingHeadings.join(", ")}` : "",
-        check.invalidFields.length > 0 ? check.invalidFields.join(" ") : "",
-        check.hasPlaceholder ? "contains placeholders" : ""
-    ].filter(Boolean).join("; ");
-    return `${relativePath} is incomplete and cannot start validation-adequacy review.${details ? ` ${details}` : ""}`;
+    return `${relativePath} is incomplete and cannot start validation-adequacy review. `
+        + formatValidationArtifactFailure(check, content);
 }
 async function readArchitectureEvidenceError(fs, taskRepoRoot) {
     const relativePath = ".ai/vcm/handoffs/architecture-evidence.md";
@@ -1049,8 +1047,10 @@ async function readArchitectureEvidenceError(fs, taskRepoRoot) {
     if (content.trim().length === 0) {
         return `${relativePath} is empty. Complete architecture evidence before requesting architecture-plan review.`;
     }
-    if (!/^\s*Architecture Evidence Status\s*:\s*complete\s*$/im.test(content)) {
-        return `${relativePath} is incomplete. Finish current-worktree evidence before requesting architecture-plan review.`;
+    const status = /^\s*Architecture Evidence Status\s*:\s*(.+?)\s*$/im.exec(content)?.[1]?.trim();
+    if (status?.toLowerCase() !== "complete") {
+        return `${relativePath} is incomplete and cannot start architecture-plan review. `
+            + `Architecture Evidence Status must be exactly "complete"; found ${renderFoundValue(status)}.`;
     }
     return undefined;
 }
@@ -1260,18 +1260,35 @@ async function validateValidationApprovalInput(fs, taskRepoRoot) {
     if (check.status === "ok") {
         return;
     }
-    const details = [
-        `status=${check.status}`,
-        check.missingHeadings.length > 0 ? `missing headings: ${check.missingHeadings.join(", ")}` : "",
-        check.invalidFields.length > 0 ? check.invalidFields.join(" ") : "",
-        check.hasPlaceholder ? "contains placeholders" : ""
-    ].filter(Boolean).join("; ");
     throw new VcmError({
         code: "GATE_REVIEW_VALIDATION_INPUT_INCOMPLETE",
-        message: `Validation-adequacy cannot approve incomplete Tester evidence in ${relativePath}. ${details}`,
+        message: `Validation-adequacy cannot approve incomplete Tester evidence in ${relativePath}. `
+            + formatValidationArtifactFailure(check, content),
         statusCode: 500
     });
 }
+function formatValidationArtifactFailure(check, content) {
+    return /^\s*Test Result\s*:\s*incomplete\s*$/im.test(content ?? "")
+        ? 'Test Result must be exactly one of "pass|fail"; found "incomplete".'
+        : formatArtifactCheckFailure(check);
+}
+function formatArtifactCheckFailure(check) {
+    const details = [
+        check.status === "missing" ? "Artifact is missing." : "",
+        check.status === "empty" ? "Artifact is empty." : "",
+        check.missingHeadings.length > 0
+            ? `Missing headings: ${check.missingHeadings.join(", ")}.`
+            : "",
+        ...check.invalidFields,
+        check.hasPlaceholder ? "Replace every standalone TBD, Not run yet, or draft-status placeholder." : ""
+    ].filter(Boolean);
+    return details.length > 0
+        ? details.join(" ")
+        : "Artifact is not in a gate-ready terminal state.";
+}
+function renderFoundValue(value) {
+    return value && value.trim().length > 0 ? JSON.stringify(value.trim()) : "<missing>";
+}
 function validateRequestChangeFindings(findings) {
     if (findings.length === 0) {
         throw new VcmError({

package/dist/backend/templates/handoff.js

@@ -1,7 +1,8 @@
+import { ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_PLAN_RESULTS, DOCS_SYNC_DECISIONS, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, STRICT_NONE_VALUE, TEST_RESULTS, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
 export function renderArchitectureBriefTemplate(taskSlug) {
     return `# Architecture Brief: ${taskSlug}
 
-Architecture Brief Status: interviewing|confirmed
+Architecture Brief Status: ${renderArtifactOptions(ARCHITECTURE_BRIEF_STATUSES)}
 
 ## Accepted Outcome
 
@@ -17,7 +18,7 @@ TBD
 
 ## Unresolved User Decisions
 
-TBD
+${STRICT_NONE_VALUE}
 
 ## User Confirmation
 
@@ -27,7 +28,7 @@ TBD
 export function renderArchitecturePlanTemplate(taskSlug) {
     return `# Architecture Plan: ${taskSlug}
 
-Planning Result: complete|incomplete|user clarification required
+Planning Result: ${renderArtifactOptions(ARCHITECTURE_PLAN_RESULTS)}
 
 ## Accepted Scope
 
@@ -100,10 +101,13 @@ TBD
 Task-specific context and coder guidance go here, not in source-code comments.
 Source-code comments should only describe durable behavior, contracts, invariants,
 error boundaries, or non-obvious logic that should remain useful after this task.
+Use an ID matching \`[A-Z]{2,6}-[0-9]{1,4}\`, choose exactly one Action
+(\`create\`, \`change\`, or \`delete\`), put the repo-relative File path in
+backticks, and enumerate every implementation item explicitly.
 
 | ID | Action | File | Symbol Or Site | Coder Work | Allowed Implementation Freedom | Behavior / Contract Proof Point |
 | --- | --- | --- | --- | --- | --- | --- |
-| TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+| <ID> | <create|change|delete> | \`<repo-relative-file>\` | TBD | TBD | TBD | TBD |
 
 ## Scaffold Build Evidence
 
@@ -143,7 +147,7 @@ At task close, promote still-relevant confirmed issues to \`docs/known-issues.md
 export function renderTestReportTemplate(taskSlug) {
     return `# Test Report: ${taskSlug}
 
-Test Result: pass|fail|incomplete
+Test Result: ${renderArtifactOptions(TEST_RESULTS)}
 
 ## Evidence Reviewed
 
@@ -165,11 +169,11 @@ TBD
 
 ### Remaining Validation
 
-TBD
+${STRICT_NONE_VALUE}
 
 ## L3 Coverage
 
-L3 Required: yes|no
+L3 Required: ${renderArtifactOptions(L3_REQUIRED_VALUES)}
 
 ### Trigger Assessment
 
@@ -179,7 +183,7 @@ TBD
 
 | Flow | Trigger | Case ID | Test File | Entry Point | Final Observable Result | Action | Result |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+| TBD | TBD | TBD | TBD | TBD | TBD | <${renderArtifactOptions(L3_ACTIONS)}> | TBD |
 
 ### L3 Commands And Evidence
 
@@ -199,27 +203,27 @@ TBD
 
 ## Failed Expectations
 
-TBD
+${STRICT_NONE_VALUE}
 
 ## Reproduction Steps
 
-TBD
+${STRICT_NONE_VALUE}
 
 ## Skipped Checks With Reasons
 
-TBD
+${STRICT_NONE_VALUE}
 
 ## Coverage Gaps
 
-TBD
+${STRICT_NONE_VALUE}
 
 ## Blocking Validation Issues
 
-TBD
+${STRICT_NONE_VALUE}
 
 ## User Approval Evidence
 
-TBD
+${STRICT_NONE_VALUE}
 `;
 }
 export function renderCoderCompletionTemplate(taskSlug) {
@@ -348,7 +352,7 @@ TBD
 
 ## Decision
 
-TBD
+${renderArtifactOptions(DOCS_SYNC_DECISIONS)}
 `;
 }
 export function renderFinalAcceptanceTemplate(taskSlug) {
@@ -356,7 +360,7 @@ export function renderFinalAcceptanceTemplate(taskSlug) {
 
 ## Decision
 
-TBD
+${renderArtifactOptions(FINAL_ACCEPTANCE_DECISIONS)}
 
 ## Evidence Reviewed
 

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

@@ -78,7 +78,7 @@ ${renderRoleMemoryRules("architect")}
 - \`Architecture Decision\`: use the required Changed Behavior Flow, Ownership, Data Flow, Lifecycle, Boundaries, Invariants, Failure Model, and Decision Rationale subsections. Describe why the design fits verified current code.
 - \`Module/File Plan\`: list each affected module, changed or created file, file responsibility, why it is in scope, expected change, dependency direction, user-visible behavior change, durable comment needs, and every non-private callable surface intended for use outside its file. For every ledger item that consumes or sources cross-module data, name the module and symbol that owns or produces the data, trace the source-to-consumer path, and identify every field, parameter, accessor, trait method, command field, dependency, or other cross-file surface required by that path.
 - \`Public Surface Impact\`: state changed APIs, routes, commands, events, exports, storage formats, configuration, UI behavior, visibility changes, side effects, error boundaries, expected callers, or explicitly state none.
-- \`Scaffold Manifest\`: an item ledger — one entry per implementation item. An item is one of: a created body or surface (\`create\`), one required change site — one contiguous edit region inside an existing body or surface (\`change\`), or one deletion of a body, site, or file (\`delete\`). An item not in the ledger is not in the plan; coder must not implement it.
+- \`Scaffold Manifest\`: an item ledger — one entry per implementation item. Use columns in the exact order \`ID | Action | File | ...\`; use an ID matching \`AA-1\` through \`AAAAAA-9999\`, an Action of exactly \`create\`, \`change\`, or \`delete\`, and a backticked repo-relative File path. An item is one created body or surface, one required change site — one contiguous edit region inside an existing body or surface — or one deletion of a body, site, or file. An item not in the ledger is not in the plan; coder must not implement it.
 - Each ledger entry carries, in this column order: a unique stable ID such as \`SCF-001\`, action, exact file path, symbol or site, coder work, allowed implementation freedom, and a behavior/contract proof point. Per-file evidence, why-in-scope, and durable-comment needs live in the Module/File Plan, not in the ledger. Open-ended coverage language ("as work proceeds", "replicate", "etc.", "and others") is forbidden anywhere in the ledger.
 - IDs and markers correspond one to one: every \`create\`, \`change\`, and \`delete\` entry has exactly one \`VCM:CODE <ID>\` marker pre-placed at its declared file and site; a \`delete\` marker sits on the code to be removed and leaves with it.
 - The Scaffold Manifest is complete only when the ledger ID set and the tree's \`VCM:CODE\` ID set are equal, each ID appears exactly once on each side, and each marker sits in its declared file (\`.ai/tools/check-scaffold-ledger\` automates the check). Any mismatch means the plan is not complete.

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

@@ -46,7 +46,18 @@ ${renderRoleMemoryRules("coder")}
 - Use workers when the task has at least 20 \`VCM:CODE\` markers and the marker distribution can form at least two worker-sized groups.
 - Under a complete scaffold, marker implementations are order-independent — signatures, types, and cross-item contracts are frozen by the scaffold — so never serialize worker-sized groups for presumed implementation-order dependencies. When a group's module-scoped checks need peers that are still unimplemented, narrow that worker's assigned validation scope instead of serializing.
 - An item counts as blocked only when a genuine implementation attempt has produced objective compile/check evidence already reported under the failure rules; prediction never blocks an item. A blocked marker item never exempts the remaining markers from worker dispatch.
-- Before invoking workers, count \`VCM:CODE\` markers by module and create one runtime state file per worker under \`.ai/vcm/coder-workers/tasks/<worker-id>.json\` with \`status: running\`.
+- Before invoking workers, count \`VCM:CODE\` markers by module and create one runtime state file per worker under \`.ai/vcm/coder-workers/tasks/<worker-id>.json\` with exactly this initial shape:
+
+\`\`\`json
+{
+  "workerId": "<worker-id>",
+  "status": "running",
+  "reportPath": ".ai/vcm/coder-workers/reports/<worker-id>.md",
+  "handled": false
+}
+\`\`\`
+
+- After a worker completes, its state must retain those fields, set \`status\` to \`completed\`, and add the exact \`commitHash\` from its report. Only Coder changes \`handled\` to \`true\` after inspecting that report and commit.
 - Create one worker task for each module with more than 10 \`VCM:CODE\` markers.
 - Group modules with 10 or fewer \`VCM:CODE\` markers into one small-modules worker when their combined marker count is more than 10.
 - If the combined small-module marker count is 10 or fewer, Coder handles those modules directly after worker results return.

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

@@ -14,8 +14,19 @@ You are \`vcm-coder-worker\`, a bounded implementation worker invoked by Coder.
 ### Worker Runtime State
 
 - Worker runtime status is only \`running\` or \`completed\`.
-- Coder creates the assigned worker state with \`status: running\` and assigns its state path and report path.
+- Coder creates the assigned worker state with this exact initial shape:
+
+\`\`\`json
+{
+  "workerId": "<worker-id>",
+  "status": "running",
+  "reportPath": ".ai/vcm/coder-workers/reports/<worker-id>.md",
+  "handled": false
+}
+\`\`\`
+
 - After the sweep of assigned items and their assigned checks, commit the assigned files. After the commit succeeds, write the assigned report with the commit hash and \`Implementation Result: success|has_failed_items\`, then update only the assigned worker state to \`completed\` with the same \`commitHash\` as the final step.
+- The completed state must retain \`workerId\`, \`reportPath\`, and \`handled: false\`, set \`status\` to \`completed\`, and add \`"commitHash": "<exact-report-commit-hash>"\`.
 - Use \`completed\` only after every assigned item reached a terminal state. A successful item has green assigned proof and its marker removed. A failed item has a genuine attempt committed with objective failure evidence and its marker retained. Use \`success\` only when every item succeeded; otherwise use \`has_failed_items\`.
 - If execution is interrupted before the sweep, commit, or report completes, leave the worker state as \`running\`. Coder must resume the worker or take over the remaining work.
 - Do not set \`handled: true\`; only Coder may do that after reviewing and integrating the worker result.

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

@@ -155,11 +155,11 @@ L3 Required: yes|no
 - Use \`pass\` only when required validation completed and no blocking test failure, missing required coverage, unacceptable test weakness, or unresolved validation risk remains.
 - Use \`fail\` only when tests fail, coverage is insufficient and Tester continuation cannot resolve it, required validation is blocked from completion, test quality is unacceptable, or validation risk needs project-manager routing.
 - Use \`incomplete\` only when required validation remains, no blocking issue has been found, and another Tester turn can continue the recorded remaining work.
-- When \`Test Result: pass\`, \`Failed Expectations\`, \`Coverage Gaps\`, \`Blocking Validation Issues\`, and \`User Approval Evidence\` must be \`None\`.
-- When \`Test Result: incomplete\`, \`Completed Validation\` and \`Remaining Validation\` must both contain concrete progress, while \`Failed Expectations\`, \`Coverage Gaps\`, \`Blocking Validation Issues\`, and \`User Approval Evidence\` must be \`None\`.
+- When \`Test Result: pass\`, the entire body of \`Remaining Validation\`, \`Failed Expectations\`, \`Coverage Gaps\`, \`Blocking Validation Issues\`, and \`User Approval Evidence\` must be exactly \`None.\` with no additional text.
+- When \`Test Result: incomplete\`, \`Completed Validation\` and \`Remaining Validation\` must both contain concrete progress, while the entire body of \`Failed Expectations\`, \`Coverage Gaps\`, \`Blocking Validation Issues\`, and \`User Approval Evidence\` must be exactly \`None.\` with no additional text.
 - When \`Test Result: fail\`, \`Blocking Validation Issues\` must list concrete blocking evidence.
 - When \`Coverage Gaps\` is not \`None\`, \`Test Result\` must be \`fail\`, \`User Approval Evidence\` must contain the user's exact authorization, and every recorded gap must match that authorization.
-- When no gap has been approved, \`User Approval Evidence\` must be \`None\`.
+- When no gap has been approved, the entire \`User Approval Evidence\` section must be exactly \`None.\` with no additional text.
 - For feature or cross-boundary changes, map required L2 integration coverage and mandatory L3 coverage separately. If required coverage is unavailable, report it as a blocking issue.
 - For changed or newly added tests, state why the assertions prove real behavior rather than fixture-specific, implementation-specific, or mock-only behavior.
 - Report confirmed unresolved issues that should survive current-task cleanup in \`.ai/vcm/handoffs/test-report.md\`; do not write \`.ai/vcm/handoffs/known-issues.md\` (architect-owned).

package/dist/backend/templates/harness/vcm-architecture-interview-skill.js

@@ -65,14 +65,14 @@ Architecture Brief Status: interviewing|confirmed
 
 ## Unresolved User Decisions
 
-...
+None.
 
 ## User Confirmation
 
 ...
 \`\`\`
 
-Record concise confirmed requirements and constraints. Tag each entry under Confirmed User Decisions with its provenance and depth — [user-stated | architect-proposed, user-approved | architect-inferred] and [intent-level | mechanism-level] — and record the user's real input faithfully as a short summary; never present an architect inference as a user requirement. Record correctness-critical mechanism choices surfaced during the interview with their options, your recommendation, the user's decision, and the rejected alternative, so later stages can tell a chosen mechanism from an inferred one. Keep this to decisions and their provenance — not a full implementation design, and not a transcript. Use \`None\` under Unresolved User Decisions only when no user-owned decision remains.
+Record concise confirmed requirements and constraints. Tag each entry under Confirmed User Decisions with its provenance and depth — [user-stated | architect-proposed, user-approved | architect-inferred] and [intent-level | mechanism-level] — and record the user's real input faithfully as a short summary; never present an architect inference as a user requirement. Record correctness-critical mechanism choices surfaced during the interview with their options, your recommendation, the user's decision, and the rejected alternative, so later stages can tell a chosen mechanism from an inferred one. Keep this to decisions and their provenance — not a full implementation design, and not a transcript. When no user-owned decision remains, the entire Unresolved User Decisions section must be exactly \`None.\` with no additional text.
 
 Maintain the evidence artifact with this structure:
 

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

@@ -94,7 +94,7 @@ Use this structure:
 
 ## Decision
 
-accepted | accepted-with-known-risks | needs-coder-follow-up | needs-architect-follow-up | needs-docs-sync | blocked-by-user-decision
+accepted|accepted-with-known-risks|needs-coder-follow-up|needs-architect-follow-up|needs-docs-sync|blocked-by-user-decision
 
 ## Evidence Reviewed
 

package/dist/backend/templates/harness/vcm-route-message-skill.js

@@ -56,9 +56,7 @@ type: task
 workflow_flow: code-change
 workflow_step: coder-implementation
 workflow_status: active
-artifact_refs:
-  - .ai/vcm/handoffs/architecture-plan.md
-  - docs/plans/example.md
+artifact_refs: .ai/vcm/handoffs/architecture-plan.md, docs/plans/example.md
 ---
 
 Summary:
@@ -84,8 +82,7 @@ For non-PM reports, use:
 \`\`\`md
 ---
 type: result
-artifact_refs:
-  - .ai/vcm/handoffs/example.md
+artifact_refs: .ai/vcm/handoffs/example.md
 ---
 
 Summary:

package/dist/shared/validation/artifact-check.js

@@ -1,3 +1,4 @@
+import { ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_PLAN_RESULTS, DOCS_SYNC_DECISIONS, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, STRICT_NONE_VALUE, TEST_RESULTS } from "./artifact-contract.js";
 const REQUIRED_HEADINGS = {
     "architecture-brief": [
         "Accepted Outcome",
@@ -128,40 +129,37 @@ export function checkMarkdownArtifact(kind, artifactPath, content) {
 }
 function validateArtifactFields(kind, content) {
     if (kind === "architecture-plan") {
-        const result = /^\s*Planning Result\s*:\s*(.+?)\s*$/im.exec(content)?.[1]?.trim().toLowerCase();
-        if (!result) {
-            return ["Planning Result is required and must be complete."];
-        }
-        return result === "complete"
+        const result = readInlineField(content, "Planning Result");
+        return result === ARCHITECTURE_PLAN_RESULTS[0]
             ? []
-            : [`Planning Result must be complete; received "${result}".`];
+            : [renderExactFieldError("Planning Result", [ARCHITECTURE_PLAN_RESULTS[0]], result)];
     }
     if (kind === "architecture-brief") {
-        const status = /^\s*Architecture Brief Status\s*:\s*(\S+)\s*$/im.exec(content)?.[1]?.toLowerCase();
-        const invalidFields = status === "interviewing" || status === "confirmed"
+        const status = readInlineField(content, "Architecture Brief Status");
+        const invalidFields = isAllowedValue(status, ARCHITECTURE_BRIEF_STATUSES)
             ? []
-            : ["Architecture Brief Status must be interviewing or confirmed."];
+            : [renderExactFieldError("Architecture Brief Status", ARCHITECTURE_BRIEF_STATUSES, status)];
         if (status === "confirmed") {
-            const unresolved = readArtifactSectionValue(content, "Unresolved User Decisions");
-            if (!unresolved || !/^none\.?$/i.test(unresolved)) {
-                invalidFields.push("Unresolved User Decisions must be None when Architecture Brief Status is confirmed.");
+            const unresolved = readArtifactSectionContent(content, "Unresolved User Decisions");
+            if (!isExactNone(unresolved)) {
+                invalidFields.push(renderExactSectionError("Unresolved User Decisions", STRICT_NONE_VALUE, unresolved, "when Architecture Brief Status is confirmed"));
             }
         }
         return invalidFields;
     }
     if (kind === "test-report") {
-        const result = /^\s*Test Result\s*:\s*(\S+)\s*$/im.exec(content)?.[1]?.toLowerCase();
-        const invalidFields = result === "pass" || result === "fail" || result === "incomplete"
+        const result = readInlineField(content, "Test Result");
+        const invalidFields = isAllowedValue(result, TEST_RESULTS)
             ? []
-            : ["Test Result must be pass, fail, or incomplete."];
-        const l3Required = /^\s*L3 Required\s*:\s*(\S+)\s*$/im.exec(content)?.[1]?.toLowerCase();
-        if (l3Required !== "yes" && l3Required !== "no") {
-            invalidFields.push("L3 Required must be yes or no.");
+            : [renderExactFieldError("Test Result", TEST_RESULTS, result)];
+        const l3Required = readInlineField(content, "L3 Required");
+        if (!isAllowedValue(l3Required, L3_REQUIRED_VALUES)) {
+            invalidFields.push(renderExactFieldError("L3 Required", L3_REQUIRED_VALUES, l3Required));
         }
-        const l3TriggerAssessment = readArtifactSectionValue(content, "Trigger Assessment");
+        const l3TriggerAssessment = readArtifactSectionContent(content, "Trigger Assessment");
         const l3AffectedFlows = readArtifactSectionContent(content, "Affected End-To-End Flows");
-        const l3Commands = readArtifactSectionValue(content, "L3 Commands And Evidence");
-        const l3NotRequiredEvidence = readArtifactSectionValue(content, "Not-Required Evidence");
+        const l3Commands = readArtifactSectionContent(content, "L3 Commands And Evidence");
+        const l3NotRequiredEvidence = readArtifactSectionContent(content, "Not-Required Evidence");
         if (l3Required === "yes") {
             if (!hasSubstantiveSectionValue(l3TriggerAssessment)) {
                 invalidFields.push("Trigger Assessment is required when L3 Required is yes.");
@@ -176,31 +174,31 @@ function validateArtifactFields(kind, content) {
         if (l3Required === "no" && !hasSubstantiveSectionValue(l3NotRequiredEvidence)) {
             invalidFields.push("Not-Required Evidence is required when L3 Required is no.");
         }
-        const coverageGaps = readArtifactSectionValue(content, "Coverage Gaps");
-        const blockingIssues = readArtifactSectionValue(content, "Blocking Validation Issues");
-        const userApproval = readArtifactSectionValue(content, "User Approval Evidence");
-        const failedExpectations = readArtifactSectionValue(content, "Failed Expectations");
-        const completedValidation = readArtifactSectionValue(content, "Completed Validation");
-        const remainingValidation = readArtifactSectionValue(content, "Remaining Validation");
-        const hasCoverageGaps = Boolean(coverageGaps && !/^none\.?$/i.test(coverageGaps));
-        const hasBlockingIssues = Boolean(blockingIssues && !/^none\.?$/i.test(blockingIssues));
-        const hasUserApproval = Boolean(userApproval && !/^none\.?$/i.test(userApproval));
-        const hasFailedExpectations = Boolean(failedExpectations && !/^none\.?$/i.test(failedExpectations));
+        const coverageGaps = readArtifactSectionContent(content, "Coverage Gaps");
+        const blockingIssues = readArtifactSectionContent(content, "Blocking Validation Issues");
+        const userApproval = readArtifactSectionContent(content, "User Approval Evidence");
+        const failedExpectations = readArtifactSectionContent(content, "Failed Expectations");
+        const completedValidation = readArtifactSectionContent(content, "Completed Validation");
+        const remainingValidation = readArtifactSectionContent(content, "Remaining Validation");
+        const hasCoverageGaps = hasSubstantiveSectionValue(coverageGaps);
+        const hasBlockingIssues = hasSubstantiveSectionValue(blockingIssues);
+        const hasUserApproval = hasSubstantiveSectionValue(userApproval);
+        const hasFailedExpectations = hasSubstantiveSectionValue(failedExpectations);
         if (result === "pass") {
-            if (!coverageGaps || hasCoverageGaps) {
-                invalidFields.push("Coverage Gaps must be None when Test Result is pass.");
+            if (!isExactNone(coverageGaps)) {
+                invalidFields.push(renderExactSectionError("Coverage Gaps", STRICT_NONE_VALUE, coverageGaps, "when Test Result is pass"));
             }
-            if (!blockingIssues || hasBlockingIssues) {
-                invalidFields.push("Blocking Validation Issues must be None when Test Result is pass.");
+            if (!isExactNone(blockingIssues)) {
+                invalidFields.push(renderExactSectionError("Blocking Validation Issues", STRICT_NONE_VALUE, blockingIssues, "when Test Result is pass"));
             }
-            if (!userApproval || hasUserApproval) {
-                invalidFields.push("User Approval Evidence must be None when Test Result is pass.");
+            if (!isExactNone(userApproval)) {
+                invalidFields.push(renderExactSectionError("User Approval Evidence", STRICT_NONE_VALUE, userApproval, "when Test Result is pass"));
             }
-            if (!failedExpectations || hasFailedExpectations) {
-                invalidFields.push("Failed Expectations must be None when Test Result is pass.");
+            if (!isExactNone(failedExpectations)) {
+                invalidFields.push(renderExactSectionError("Failed Expectations", STRICT_NONE_VALUE, failedExpectations, "when Test Result is pass"));
             }
-            if (hasSubstantiveSectionValue(remainingValidation)) {
-                invalidFields.push("Remaining Validation must be None when Test Result is pass.");
+            if (!isExactNone(remainingValidation)) {
+                invalidFields.push(renderExactSectionError("Remaining Validation", STRICT_NONE_VALUE, remainingValidation, "when Test Result is pass"));
             }
         }
         if (result === "incomplete") {
@@ -210,17 +208,17 @@ function validateArtifactFields(kind, content) {
             if (!hasSubstantiveSectionValue(remainingValidation)) {
                 invalidFields.push("Remaining Validation must list continuation work when Test Result is incomplete.");
             }
-            if (hasCoverageGaps) {
-                invalidFields.push("Coverage Gaps must be None when Test Result is incomplete.");
+            if (!isExactNone(coverageGaps)) {
+                invalidFields.push(renderExactSectionError("Coverage Gaps", STRICT_NONE_VALUE, coverageGaps, "when Test Result is incomplete"));
             }
-            if (hasBlockingIssues) {
-                invalidFields.push("Blocking Validation Issues must be None when Test Result is incomplete.");
+            if (!isExactNone(blockingIssues)) {
+                invalidFields.push(renderExactSectionError("Blocking Validation Issues", STRICT_NONE_VALUE, blockingIssues, "when Test Result is incomplete"));
             }
-            if (hasUserApproval) {
-                invalidFields.push("User Approval Evidence must be None when Test Result is incomplete.");
+            if (!isExactNone(userApproval)) {
+                invalidFields.push(renderExactSectionError("User Approval Evidence", STRICT_NONE_VALUE, userApproval, "when Test Result is incomplete"));
             }
-            if (hasFailedExpectations) {
-                invalidFields.push("Failed Expectations must be None when Test Result is incomplete.");
+            if (!isExactNone(failedExpectations)) {
+                invalidFields.push(renderExactSectionError("Failed Expectations", STRICT_NONE_VALUE, failedExpectations, "when Test Result is incomplete"));
             }
         }
         if (result === "fail" && !hasBlockingIssues) {
@@ -235,22 +233,15 @@ function validateArtifactFields(kind, content) {
             }
         }
         else if (hasUserApproval) {
-            invalidFields.push("User Approval Evidence must be None when no Coverage Gaps are recorded.");
+            invalidFields.push(renderExactSectionError("User Approval Evidence", STRICT_NONE_VALUE, userApproval, "when no Coverage Gaps are recorded"));
         }
         return invalidFields;
     }
     if (kind === "docs-sync-report") {
-        return validateDecision(content, ["synced", "unchanged", "blocked"]);
+        return validateDecision(content, DOCS_SYNC_DECISIONS);
     }
     if (kind === "final-acceptance") {
-        return validateDecision(content, [
-            "accepted",
-            "accepted-with-known-risks",
-            "needs-coder-follow-up",
-            "needs-architect-follow-up",
-            "needs-docs-sync",
-            "blocked-by-user-decision"
-        ]);
+        return validateDecision(content, FINAL_ACCEPTANCE_DECISIONS);
     }
     return [];
 }
@@ -261,7 +252,7 @@ function hasCompleteL3FlowMapping(value) {
     if (!value) {
         return false;
     }
-    const allowedActions = new Set(["run-existing", "updated", "added"]);
+    const allowedActions = new Set(L3_ACTIONS);
     return value
         .split(/\r?\n/)
         .map((line) => line.trim())
@@ -274,10 +265,10 @@ function hasCompleteL3FlowMapping(value) {
     });
 }
 function validateDecision(content, allowed) {
-    const decision = readArtifactSectionValue(content, "Decision")?.toLowerCase();
-    return decision && allowed.includes(decision)
+    const decision = readArtifactSectionContent(content, "Decision")?.trim();
+    return decision && allowed.includes(decision.toLowerCase())
         ? []
-        : [`Decision must be one of: ${allowed.join(", ")}.`];
+        : [renderExactSectionError("Decision", allowed.join("|"), decision)];
 }
 export function readArtifactSectionValue(content, heading) {
     return readArtifactSectionContent(content, heading)
@@ -285,7 +276,7 @@ export function readArtifactSectionValue(content, heading) {
         .map((line) => line.trim())
         .find(Boolean);
 }
-function readArtifactSectionContent(content, heading) {
+export function readArtifactSectionContent(content, heading) {
     const match = new RegExp(`^#{1,6}\\s+${escapeRegExp(heading)}\\s*$`, "im").exec(content);
     if (!match || match.index === undefined) {
         return undefined;
@@ -297,6 +288,29 @@ function readArtifactSectionContent(content, heading) {
         : afterHeading.slice(0, nextHeading.index);
     return section.trim();
 }
+function readInlineField(content, field) {
+    return new RegExp(`^\\s*${escapeRegExp(field)}\\s*:\\s*(.+?)\\s*$`, "im")
+        .exec(content)?.[1]?.trim().toLowerCase();
+}
+function isAllowedValue(value, allowed) {
+    return value !== undefined && allowed.includes(value);
+}
+function isExactNone(value) {
+    return value?.trim() === STRICT_NONE_VALUE;
+}
+function renderExactFieldError(field, allowed, found) {
+    return `${field} must be exactly one of "${allowed.join("|")}"; found ${renderFoundValue(found)}.`;
+}
+function renderExactSectionError(section, expected, found, condition) {
+    const suffix = condition ? ` ${condition}` : "";
+    return `${section} must contain exactly "${expected}"${suffix}; found ${renderFoundValue(found)}.`;
+}
+function renderFoundValue(value) {
+    if (value === undefined || value.trim().length === 0) {
+        return "<missing>";
+    }
+    return JSON.stringify(value.trim().replace(/\s+/g, " "));
+}
 function hasHeading(content, heading) {
     const pattern = new RegExp(`^#{1,6}\\s+${escapeRegExp(heading)}\\s*$`, "im");
     return pattern.test(content);

package/dist/shared/validation/artifact-contract.js

@@ -0,0 +1,22 @@
+export const STRICT_NONE_VALUE = "None.";
+export const ARCHITECTURE_BRIEF_STATUSES = ["interviewing", "confirmed"];
+export const ARCHITECTURE_PLAN_RESULTS = [
+    "complete",
+    "incomplete",
+    "user clarification required"
+];
+export const TEST_RESULTS = ["pass", "fail", "incomplete"];
+export const L3_REQUIRED_VALUES = ["yes", "no"];
+export const L3_ACTIONS = ["run-existing", "updated", "added"];
+export const DOCS_SYNC_DECISIONS = ["synced", "unchanged", "blocked"];
+export const FINAL_ACCEPTANCE_DECISIONS = [
+    "accepted",
+    "accepted-with-known-risks",
+    "needs-coder-follow-up",
+    "needs-architect-follow-up",
+    "needs-docs-sync",
+    "blocked-by-user-decision"
+];
+export function renderArtifactOptions(values) {
+    return values.join("|");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.7.27",
+  "version": "0.7.28",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [

package/scripts/uninstall-vcm-harness.mjs

@@ -137,6 +137,11 @@ async function processEntry(context) {
     return;
   }
 
+  if (entry.ownership === "project-owned") {
+    context.operations.push(skip(entry.path, "project-owned; preserved"));
+    return;
+  }
+
   if (entry.ownership === "managed-block" || uninstallAction === "remove-managed-block") {
     await removeManagedBlock(context);
     return;