vibe-coding-master 0.7.38 → 0.7.40

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

@@ -81,10 +81,10 @@ Do not accept when required role evidence is missing, required Gate Review evide
 
 ## Output
 
-Write or update:
+Write a complete candidate outside \`.ai/vcm\`, then submit it:
 
 \`\`\`text
-.ai/vcm/handoffs/final-acceptance.md
+.ai/tools/vcm-artifact final-acceptance --file <candidate> --mode final
 \`\`\`
 
 Use this structure:

package/dist/backend/templates/harness/vcm-long-running-validation-skill.js

@@ -15,7 +15,7 @@ The hard ceiling is 60 minutes per job, enforced by the job worker itself. No ap
 
 1. Start the command with an explicit ceiling: \`.ai/tools/run-long-check --timeout <duration> -- <command>\`. Pass the validation executable and its arguments directly. Do not use a shell command-string wrapper, pipeline its output, or append another command: run-long-check already captures stdout/stderr, and shell wrappers can hide the validation exit code. Pick the ceiling from \`docs/TESTING.md\` guidance or a realistic estimate, never above 60m. The tool prints the job id and creates job state under \`.ai/vcm/jobs/<job-id>/\`.
 2. In the same turn, run \`.ai/tools/watch-job <job-id>\` as its own Bash tool call. The default watch window is 8 minutes.
-3. If watch-job exits 125, the job is still running: run \`.ai/tools/watch-job <job-id>\` again immediately. Do not end the turn between windows.
+3. If watch-job exits 125, the job is still running and a bounded handoff is active for the next watcher: run \`.ai/tools/watch-job <job-id>\` again immediately. Do not end the turn between windows.
 4. Repeat until watch-job reports a terminal result.
 5. Read the final status and the relevant log tail.
 6. Record command, result, duration, and required follow-up wherever the caller normally records command evidence.
@@ -44,7 +44,8 @@ Treat watch-job exit codes as explicit results:
 A running job requires a live foreground watcher:
 
 - watch-job renews the job supervision lease while it runs.
-- If no watcher renews the lease for about 2 minutes, the worker kills the command process group and records \`orphaned\`. A job cannot keep running unsupervised.
+- A normal exit 125 records a five-minute handoff deadline for the next model-generated watcher call. The next watcher renews the lease and clears that handoff when it starts.
+- Without a normal handoff, about two minutes without lease renewal causes the worker to kill the command process group and record \`orphaned\`. An expired handoff is also recorded as \`orphaned\` with a distinct reason.
 - VCM also blocks ending the turn while a job is running. Stay in the turn and keep watching.
 - Only one validation job may run at a time; run-long-check refuses to start a second one.
 
@@ -56,6 +57,7 @@ A running job requires a live foreground watcher:
 .ai/vcm/jobs/<job-id>/stdout.log
 .ai/vcm/jobs/<job-id>/stderr.log
 .ai/vcm/jobs/<job-id>/lease
+.ai/vcm/jobs/<job-id>/watch-handoff.json   # present only between normal watch windows
 \`\`\`
 
 ## Timeout

package/dist/backend/templates/harness/vcm-propose-memory-skill.js

@@ -6,7 +6,7 @@ planning-session memory candidate and provides an exact path.
 
 - Treat every \`<VCM-memory>\` block as read-only. This skill creates a proposal;
   it never edits active memory.
-- Write only to the exact path assigned by VCM. It must be either a role draft
+- Submit only to the exact path assigned by VCM. It must be either a role draft
   under \`.ai/vcm/memory-review/runs/<run-id>/drafts/\` or a planning candidate
   under \`.ai/vcm/memory-review/candidates/\` in the active task worktree.
 - If VCM did not provide a path, do not create a proposal.
@@ -79,5 +79,7 @@ Evidence: <task artifact, code, or durable documentation>
 \`\`\`
 
 Use \`Decision: no-change\` when the completed task produced no qualifying
-memory. End the turn after writing the assigned draft.`;
+memory. Write the proposal to a candidate outside \`.ai/vcm\`, submit it with
+\`.ai/tools/vcm-artifact memory-proposal --file <candidate> --path <assigned-path> --mode final\`,
+and end the turn only after VCM accepts it.`;
 }

package/dist/backend/templates/harness/vcm-report-harness-issue-skill.js

@@ -5,7 +5,7 @@ This skill records feedback only. It must not call Harness Engineer directly and
 
 ## Write Location
 
-Write one markdown file under:
+Submit one markdown file under:
 
 \`\`\`
 \${VCM_BASE_REPO_ROOT}/.ai/vcm/harness-feedback/pending/
@@ -47,5 +47,6 @@ Use this structure:
 - Include enough evidence for Harness Engineer to verify the issue.
 - Do not include secrets, private logs, or unnecessary source content.
 - Continue the current VCM role work after writing the report unless the original task is blocked.
+- Write the report to a candidate outside \`.ai/vcm\`, then run \`.ai/tools/vcm-artifact harness-feedback --file <candidate> --path <feedback-path> --mode final\`.
 `;
 }

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

@@ -32,10 +32,10 @@ Allowed message types:
 
 ## Route File
 
-Write or update exactly one file:
+Write the message to a candidate outside \`.ai/vcm\`, then submit it:
 
 \`\`\`text
-.ai/vcm/handoffs/messages/<from-role>-<to-role>.md
+.ai/tools/vcm-artifact route-message --file <candidate> --path .ai/vcm/handoffs/messages/<from-role>-<to-role>.md --mode final
 \`\`\`
 
 Use one allowed route above. The file name is authoritative. Do not put from/to in frontmatter and do not create alternate message paths.
@@ -53,9 +53,6 @@ For PM dispatch, use:
 \`\`\`md
 ---
 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
 ---
 
@@ -75,7 +72,7 @@ Stop conditions:
 ...
 \`\`\`
 
-PM route files should declare the workflow checkpoint fields defined by the \`vcm-task-state\` skill. Non-PM reports must not declare workflow state.
+Project Manager must obtain an accepted \`vcm-workflow-review\` transition for the exact target before submitting this route. Do not put workflow approval or checkpoint fields in the route file.
 
 For non-PM reports, use:
 
@@ -112,7 +109,7 @@ Formal messages should include:
 
 ## Turn Rule
 
-After writing or updating the route file, end the current Claude Code turn immediately.
+After VCM accepts the route file, end the current Claude Code turn immediately.
 
 Do not:
 

package/dist/backend/templates/harness/vcm-task-state-skill.js

@@ -7,18 +7,7 @@ The declaration is recoverable context, not a workflow controller. It does not a
 
 ## Declaration
 
-For a PM role dispatch, put the current declaration in the route-file frontmatter:
-
-\`\`\`yaml
-workflow_flow: code-change
-workflow_step: coder-implementation
-workflow_branch: none
-workflow_resume_point: none
-workflow_status: active
-workflow_evidence_refs: .ai/vcm/handoffs/architecture-plan.md
-\`\`\`
-
-For a checkpoint without a role route, run:
+Record a recoverable checkpoint with:
 
 \`\`\`bash
 .ai/tools/update-task-state --flow code-change --step awaiting-user --status awaiting-user
@@ -26,7 +15,7 @@ For a checkpoint without a role route, run:
 
 Supply only fields that changed. Use \`none\` to clear branch or resume point. Repeat \`--evidence\` for evidence paths.
 
-Declare the selected flow before its first dispatch, update the step on later PM dispatches, and update no-route checkpoints such as waiting for the user, waiting for Gate Review, or completion.
+Declare the selected flow before its first dispatch, update the step before later PM dispatches, and update no-route checkpoints such as waiting for the user, waiting for Gate Review, or completion. Do not put task-state or workflow-approval fields in route-message frontmatter.
 
 If declaration fails, report the warning when relevant and continue the existing workflow. Never delay routing, Gate Review, final acceptance, or task close because task state is unavailable.
 `;

package/dist/backend/templates/harness/vcm-workflow-review-skill.js

@@ -0,0 +1,62 @@
+export function renderVcmWorkflowReviewSkillRules() {
+    return `## Purpose
+
+Use this skill before every Project Manager dispatch to Architect, Coder, or Tester. VCM validates the proposed transition against the confirmed task Flow Record and real task artifacts.
+
+## Submission
+
+Read the current \`.ai/vcm/handoffs/workflow-progress.md\`. Copy its Revision, Flow, Status, and Dispatch History exactly, increment Revision by one, and propose one dispatch:
+
+\`\`\`md
+# Workflow Progress: <task-slug>
+
+Revision: <previous-revision + 1>
+Flow: <copy confirmed Flow exactly>
+Status: <copy confirmed Status exactly>
+
+## Dispatch History
+
+<copy exactly; use none when empty>
+
+## Proposed Dispatch
+
+Requested Flow: <none|code-change|architect-debug|architecture-diagnosis|docs-only|validation-only>
+Target Role: <architect|coder|tester>
+Evidence: <current artifact, Gate result, or user request supporting this dispatch>
+
+## User Override
+
+Authorization ID: none
+Authorization Quote: none
+Violated Rule: none
+\`\`\`
+
+Use \`Requested Flow\` only to start a flow, switch a top-level flow, enter or replace a Branch, or return from a Branch. Otherwise use \`none\`.
+
+Submit the candidate outside \`.ai/vcm\`:
+
+\`\`\`text
+.ai/tools/vcm-artifact workflow-progress --file <candidate> --mode final
+\`\`\`
+
+An accepted submission grants exactly one matching PM route. Then use \`vcm-route-message\` for that target role.
+
+If VCM rejects the transition, remain in the current PM turn and choose a legal dispatch. Do not write the route file first.
+
+## User Override
+
+Only direct user authorization may override a rejected transition. To request confirmation, resubmit the same transition with:
+
+\`\`\`text
+Authorization ID: request
+Authorization Quote: <exact proposed exception for the user>
+Violated Rule: <copy the exact VCM rejection reason>
+\`\`\`
+
+Wait for VCM's user decision callback. If approved, resubmit the unchanged transition with the returned Authorization ID, exact Authorization Text, and the same Violated Rule. The approval applies once and only to that exact transition.
+
+## Completion
+
+When the active flow has completed without another role dispatch, increment Revision, copy the confirmed history exactly, set \`Status: completed\`, and set every Proposed Dispatch and User Override value to \`none\`. VCM accepts completion only when the flow's required final artifact and Gate evidence exists.
+`;
+}

package/dist/backend/templates/message-envelope.js

@@ -17,10 +17,10 @@ ${artifactRefs}
 
 Instructions:
 - Read the message and execute only within this VCM task.
-- If you write or update a VCM route file, use the vcm-route-message skill.
-- If PM sends a VCM message after handling this, write or update .ai/vcm/handoffs/messages/project-manager-<target-role>.md.
-- If a non-PM role sends a VCM message after handling this, reply only to project-manager with .ai/vcm/handoffs/messages/<your-role>-project-manager.md.
-- After writing a route file, end this Claude Code turn immediately.
+- Submit every VCM route file through the vcm-route-message skill and .ai/tools/vcm-artifact.
+- If PM sends a VCM message after handling this, submit .ai/vcm/handoffs/messages/project-manager-<target-role>.md.
+- If a non-PM role sends a VCM message after handling this, submit only .ai/vcm/handoffs/messages/<your-role>-project-manager.md.
+- After VCM accepts a route file, end this Claude Code turn immediately.
 - Do not poll, loop, or wait for another role in this turn. VCM scans route files after your Stop hook and delivers later replies in a new turn.
 [/VCM MESSAGE]
 `;

package/dist/shared/types/workflow.js

@@ -1 +1,7 @@
-export {};
+export const WORKFLOW_FLOWS = [
+    "code-change",
+    "architect-debug",
+    "architecture-diagnosis",
+    "docs-only",
+    "validation-only"
+];

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

@@ -1,91 +1,8 @@
-import { ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_PLAN_RESULTS, DOCS_SYNC_DECISIONS, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS } from "./artifact-contract.js";
-const REQUIRED_HEADINGS = {
-    "architecture-brief": [
-        "Accepted Outcome",
-        "Confirmed User Decisions",
-        "Existing Constraints",
-        "Unresolved User Decisions",
-        "User Confirmation"
-    ],
-    "architecture-plan": [
-        "Accepted Scope",
-        "Current Code Reality",
-        "Planning Boundary",
-        "Code Reading Evidence",
-        "Existing Behavior Trace",
-        "Code / Docs Conflicts",
-        "Architecture Decision",
-        "Changed Behavior Flow",
-        "Ownership",
-        "Data Flow",
-        "Lifecycle",
-        "Boundaries",
-        "Invariants",
-        "Failure Model",
-        "Decision Rationale",
-        "Module/File Plan",
-        "Public Surface Impact",
-        "Scaffold Manifest",
-        "Scaffold Build Evidence",
-        "Tester Coverage Hints",
-        "Docs Impact",
-        "Known Risks",
-        "Coder Handoff Notes"
-    ],
-    "known-issues": [
-        "Task Issues",
-        "Escalation To Docs"
-    ],
-    "test-report": [
-        "Evidence Reviewed",
-        "Tests Added Or Updated",
-        "Coverage Mapping",
-        "Validation Progress",
-        "Completed Validation",
-        "Remaining Validation",
-        "L3 Coverage",
-        "Trigger Assessment",
-        "Affected End-To-End Flows",
-        "L3 Commands And Evidence",
-        "Not-Required Evidence",
-        "Commands Run Or Checked",
-        "Validation Results",
-        "Test Infrastructure",
-        "Affected Files",
-        "Boundary Evidence",
-        "Defect-Class Sweep",
-        "Repair Commit",
-        "Failed Expectations",
-        "Reproduction Steps",
-        "Skipped Checks With Reasons",
-        "Coverage Gaps",
-        "Blocking Validation Issues",
-        "User Approval Evidence"
-    ],
-    "docs-sync-report": [
-        "Summary",
-        "Architecture Drift Check",
-        "Docs Updated",
-        "Docs Reviewed And Left Unchanged",
-        "Public Contract / Module Boundary Notes",
-        "Remaining Documentation Risks",
-        "Known Issues Disposition",
-        "Decision"
-    ],
-    "final-acceptance": [
-        "Decision",
-        "Evidence Reviewed",
-        "Scope Traceability",
-        "Validation Summary",
-        "Review And Docs Sync",
-        "Known Issues Disposition",
-        "Gate Review Gates",
-        "Cleanup Readiness",
-        "Final User Summary"
-    ]
-};
+import { ARCHITECT_DEBUG_STATUSES, ARCHITECTURE_BRIEF_STATUSES, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS, ARCHITECTURE_EVIDENCE_STATUSES, ARCHITECTURE_PLAN_RESULTS, CODER_COMPLETION_DECISIONS, DOCS_SYNC_DECISIONS, FINAL_ACCEPTANCE_DECISIONS, L3_ACTIONS, L3_REQUIRED_VALUES, PLANNING_PROGRESS_STATUSES, STRICT_NONE_VALUE, TEST_INFRASTRUCTURE_STATUSES, TEST_RESULTS } from "./artifact-contract.js";
+import { getArtifactDefinition } from "./artifact-registry.js";
 const PLACEHOLDER_PATTERN = /(^|\n)\s*(TBD|Not run yet\.?|status:\s*draft)\s*(\n|$)/i;
-export function checkMarkdownArtifact(kind, artifactPath, content) {
+export function checkMarkdownArtifact(kind, artifactPath, content, options = {}) {
+    const requiredHeadings = getArtifactDefinition(kind).requiredHeadings;
     if (content === null) {
         return {
             kind,
@@ -93,7 +10,7 @@ export function checkMarkdownArtifact(kind, artifactPath, content) {
             exists: false,
             isEmpty: true,
             hasPlaceholder: false,
-            missingHeadings: [...REQUIRED_HEADINGS[kind]],
+            missingHeadings: [...requiredHeadings],
             invalidFields: [],
             status: "missing"
         };
@@ -106,14 +23,18 @@ export function checkMarkdownArtifact(kind, artifactPath, content) {
             exists: true,
             isEmpty: true,
             hasPlaceholder: false,
-            missingHeadings: [...REQUIRED_HEADINGS[kind]],
+            missingHeadings: [...requiredHeadings],
             invalidFields: [],
             status: "empty"
         };
     }
-    const missingHeadings = REQUIRED_HEADINGS[kind].filter((heading) => !hasHeading(trimmed, heading));
-    const hasPlaceholder = PLACEHOLDER_PATTERN.test(trimmed);
-    const invalidFields = validateArtifactFields(kind, trimmed);
+    const headingErrors = validateHeadingContract(trimmed, requiredHeadings);
+    const missingHeadings = headingErrors.missing;
+    const hasPlaceholder = options.mode === "draft" ? false : PLACEHOLDER_PATTERN.test(trimmed);
+    const invalidFields = [
+        ...headingErrors.invalid,
+        ...validateArtifactFields(kind, trimmed, options.mode ?? "final")
+    ];
     const isWorkInProgress = kind === "test-report"
         && /^\s*Test Result\s*:\s*incomplete\s*$/im.test(trimmed);
     return {
@@ -132,18 +53,22 @@ export function checkMarkdownArtifact(kind, artifactPath, content) {
             : "incomplete"
     };
 }
-function validateArtifactFields(kind, content) {
+function validateArtifactFields(kind, content, mode) {
     if (kind === "architecture-plan") {
         const result = readInlineField(content, "Planning Result");
-        return result === ARCHITECTURE_PLAN_RESULTS[0]
+        return isAllowedValue(result, ARCHITECTURE_PLAN_RESULTS)
+            && (mode === "draft" || result === ARCHITECTURE_PLAN_RESULTS[0])
             ? []
-            : [renderExactFieldError("Planning Result", [ARCHITECTURE_PLAN_RESULTS[0]], result)];
+            : [renderExactFieldError("Planning Result", mode === "draft" ? ARCHITECTURE_PLAN_RESULTS : [ARCHITECTURE_PLAN_RESULTS[0]], result)];
     }
     if (kind === "architecture-brief") {
         const status = readInlineField(content, "Architecture Brief Status");
         const invalidFields = isAllowedValue(status, ARCHITECTURE_BRIEF_STATUSES)
             ? []
             : [renderExactFieldError("Architecture Brief Status", ARCHITECTURE_BRIEF_STATUSES, status)];
+        if (mode === "final" && status !== "confirmed") {
+            invalidFields.push(renderExactFieldError("Architecture Brief Status", ["confirmed"], status));
+        }
         if (status === "confirmed") {
             const unresolved = readArtifactSectionContent(content, "Unresolved User Decisions");
             if (!isExactNone(unresolved)) {
@@ -152,6 +77,31 @@ function validateArtifactFields(kind, content) {
         }
         return invalidFields;
     }
+    if (kind === "architecture-evidence") {
+        return validateLifecycleField(content, "Architecture Evidence Status", ARCHITECTURE_EVIDENCE_STATUSES, "complete", mode);
+    }
+    if (kind === "planning-progress") {
+        return validateLifecycleField(content, "Planning Progress Status", PLANNING_PROGRESS_STATUSES, "complete", mode);
+    }
+    if (kind === "coder-completion") {
+        const decision = readInlineField(content, "Decision");
+        if (!isAllowedValue(decision, CODER_COMPLETION_DECISIONS)) {
+            return [renderExactFieldError("Decision", CODER_COMPLETION_DECISIONS, decision)];
+        }
+        if (mode === "final" && decision === "incomplete") {
+            return [renderExactFieldError("Decision", ["ready_for_review", "failed"], decision)];
+        }
+        return [];
+    }
+    if (kind === "architect-debug") {
+        return validateLifecycleField(content, "Status", ARCHITECT_DEBUG_STATUSES, "completed", mode);
+    }
+    if (kind === "architecture-diagnosis") {
+        const disposition = readArtifactSectionContent(content, "Final Disposition")?.trim().toLowerCase();
+        return isAllowedValue(disposition, ARCHITECTURE_DIAGNOSIS_DISPOSITIONS)
+            ? []
+            : [renderExactSectionError("Final Disposition", ARCHITECTURE_DIAGNOSIS_DISPOSITIONS.join("|"), disposition)];
+    }
     if (kind === "test-report") {
         const result = readInlineField(content, "Test Result");
         const invalidFields = isAllowedValue(result, TEST_RESULTS)
@@ -256,6 +206,9 @@ function validateArtifactFields(kind, content) {
             }
         }
         if (result === "incomplete") {
+            if (mode === "final") {
+                invalidFields.push("Test Result must be pass or fail for final submission.");
+            }
             if (!hasSubstantiveSectionValue(completedValidation)) {
                 invalidFields.push("Completed Validation must record progress when Test Result is incomplete.");
             }
@@ -299,6 +252,57 @@ function validateArtifactFields(kind, content) {
     }
     return [];
 }
+function validateLifecycleField(content, field, allowed, finalValue, mode) {
+    const value = readInlineField(content, field);
+    if (!isAllowedValue(value, allowed)) {
+        return [renderExactFieldError(field, allowed, value)];
+    }
+    if (mode === "final" && finalValue && value !== finalValue) {
+        return [renderExactFieldError(field, [finalValue], value)];
+    }
+    return [];
+}
+function validateHeadingContract(content, required) {
+    const headings = readMarkdownHeadings(content);
+    const missing = required.filter((heading) => !headings.some((candidate) => candidate.text === heading));
+    const invalid = [];
+    for (const heading of required) {
+        const matches = headings.filter((candidate) => candidate.text === heading);
+        if (matches.length > 1) {
+            invalid.push(`Heading ${heading} must appear exactly once; found ${matches.length}.`);
+        }
+    }
+    let previousIndex = -1;
+    for (const heading of required) {
+        const index = headings.findIndex((candidate) => candidate.text === heading);
+        if (index < 0) {
+            continue;
+        }
+        if (index < previousIndex) {
+            invalid.push(`Heading ${heading} is out of the required order.`);
+        }
+        previousIndex = Math.max(previousIndex, index);
+    }
+    return { missing, invalid };
+}
+function readMarkdownHeadings(content) {
+    const result = [];
+    let fenced = false;
+    for (const line of content.split(/\r?\n/)) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            fenced = !fenced;
+            continue;
+        }
+        if (fenced) {
+            continue;
+        }
+        const match = /^(#{2,6})\s+(.+?)\s*#*\s*$/.exec(line);
+        if (match) {
+            result.push({ level: match[1].length, text: match[2].trim() });
+        }
+    }
+    return result;
+}
 function hasSubstantiveSectionValue(value) {
     return Boolean(value && !/^(none|tbd)\.?$/i.test(value.trim()));
 }

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

@@ -1,10 +1,19 @@
 export const STRICT_NONE_VALUE = "None.";
 export const ARCHITECTURE_BRIEF_STATUSES = ["interviewing", "confirmed"];
+export const ARCHITECTURE_EVIDENCE_STATUSES = ["incomplete", "complete"];
+export const PLANNING_PROGRESS_STATUSES = ["active", "complete"];
 export const ARCHITECTURE_PLAN_RESULTS = [
     "complete",
     "incomplete",
     "user clarification required"
 ];
+export const CODER_COMPLETION_DECISIONS = ["ready_for_review", "incomplete", "failed"];
+export const ARCHITECT_DEBUG_STATUSES = ["pending", "completed"];
+export const ARCHITECTURE_DIAGNOSIS_DISPOSITIONS = [
+    "analysis completed",
+    "diagnosis implementation completed",
+    "user clarification required"
+];
 export const TEST_RESULTS = ["pass", "fail", "incomplete"];
 export const TEST_INFRASTRUCTURE_STATUSES = [
     "none",