vibe-coding-master 0.7.39 → 0.7.41

package/dist/backend/templates/handoff.js

@@ -1,4 +1,4 @@
-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, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
+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, renderArtifactOptions } from "../../shared/validation/artifact-contract.js";
 const CURRENT_HANDOFF_NOTICE = "<!-- VCM current handoff: replace this file with one complete, self-contained snapshot of the current result. Restate all still-relevant evidence; do not refer to a prior revision, route message, Session, or transcript as evidence. -->";
 export function renderArchitectureBriefTemplate(taskSlug) {
     return `# Architecture Brief: ${taskSlug}
@@ -109,6 +109,8 @@ 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.
+When no scaffold item exists, replace the table with exactly \`No scaffold items.\`;
+an empty table is invalid.
 
 | ID | Action | File | Symbol Or Site | Coder Work | Allowed Implementation Freedom | Behavior / Contract Proof Point |
 | --- | --- | --- | --- | --- | --- | --- |
@@ -137,6 +139,64 @@ TBD
 TBD
 `;
 }
+export function renderArchitectureEvidenceTemplate(taskSlug) {
+    return `# Architecture Evidence: ${taskSlug}
+
+${CURRENT_HANDOFF_NOTICE}
+
+Architecture Evidence Status: ${renderArtifactOptions(ARCHITECTURE_EVIDENCE_STATUSES)}
+
+## Planning Boundary
+
+TBD
+
+## Entry Points And Behavior Paths
+
+TBD
+
+## State And Lifecycle
+
+TBD
+
+## Callers And Consumers
+
+TBD
+
+## Existing Assumptions
+
+TBD
+
+## Related Class Inventories
+
+TBD
+
+## External Boundaries
+
+TBD
+
+## Code And Docs Conflicts
+
+TBD
+
+## Evidence Commands
+
+TBD
+`;
+}
+export function renderPlanningProgressTemplate(taskSlug) {
+    return `# Planning Progress: ${taskSlug}
+
+${CURRENT_HANDOFF_NOTICE}
+
+Planning Progress Status: ${renderArtifactOptions(PLANNING_PROGRESS_STATUSES)}
+
+## Planning Steps
+
+| Step | Scope | Deliverable | Done Criterion | Status | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| Architecture Evidence Verification | TBD | TBD | TBD | pending | TBD |
+`;
+}
 export function renderKnownIssuesTemplate(taskSlug) {
     return `# Known Issues: ${taskSlug}
 
@@ -260,7 +320,7 @@ export function renderCoderCompletionTemplate(taskSlug) {
 
 ${CURRENT_HANDOFF_NOTICE}
 
-Decision: ready_for_review|incomplete|failed
+Decision: ${renderArtifactOptions(CODER_COMPLETION_DECISIONS)}
 
 ## Scaffold Completion
 
@@ -306,7 +366,7 @@ export function renderArchitectDebugTemplate(taskSlug) {
 
 ${CURRENT_HANDOFF_NOTICE}
 
-Status: pending|completed
+Status: ${renderArtifactOptions(ARCHITECT_DEBUG_STATUSES)}
 
 ## PM-Routed Failure
 
@@ -352,6 +412,77 @@ TBD
 TBD
 `;
 }
+export function renderArchitectureDiagnosisTemplate(taskSlug) {
+    return `# Architecture Diagnosis: ${taskSlug}
+
+${CURRENT_HANDOFF_NOTICE}
+
+## Diagnosis Boundary
+
+TBD
+
+## Documents And Runtime Evidence
+
+TBD
+
+## Code Reading Closure
+
+TBD
+
+## Current Architecture
+
+TBD
+
+## Previous Debug Failure
+
+TBD
+
+## Failure Trace
+
+TBD
+
+## Architecture Assessment
+
+TBD
+
+## Required Architecture Direction
+
+TBD
+
+## Implementation And Validation
+
+### Changed Files And Public Surface
+
+TBD
+
+### Baseline Tests
+
+TBD
+
+### Diagnostic And L0/L1 Validation
+
+TBD
+
+### L2/L3 Validation
+
+| Level | Applicable | Command Or Test | Failure Path | Result | Evidence |
+| --- | --- | --- | --- | --- | --- |
+| L2 | TBD | TBD | TBD | TBD | TBD |
+| L3 | TBD | TBD | TBD | TBD | TBD |
+
+### Generated Context
+
+TBD
+
+### Commit
+
+TBD
+
+## Final Disposition
+
+${renderArtifactOptions(ARCHITECTURE_DIAGNOSIS_DISPOSITIONS)}
+`;
+}
 export function renderDocsSyncReportTemplate(taskSlug) {
     return `# Docs Sync Report: ${taskSlug}
 
@@ -390,6 +521,30 @@ TBD
 ${renderArtifactOptions(DOCS_SYNC_DECISIONS)}
 `;
 }
+export function renderWorkflowProgressTemplate(taskSlug) {
+    return `# Workflow Progress: ${taskSlug}
+
+Revision: 0
+Flow: none
+Status: not-started
+
+## Dispatch History
+
+none
+
+## Proposed Dispatch
+
+Requested Flow: none
+Target Role: none
+Evidence: none
+
+## User Override
+
+Authorization ID: none
+Authorization Quote: none
+Violated Rule: none
+`;
+}
 export function renderFinalAcceptanceTemplate(taskSlug) {
     return `# Final Acceptance: ${taskSlug}
 

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

@@ -23,12 +23,13 @@ ${renderRoleMemoryRules("architect")}
 
 - Follow the preloaded \`vcm-code-navigation\` skill whenever work requires code definitions, implementations, references, callers, callees, or behavior paths. This applies in every Architect mode and in direct user communication.
 - Use LSP for semantic relationships. Use Glob to locate files, Read to inspect complete code, and generated context, architecture documents, or runtime evidence for boundaries LSP does not model.
-- Do not use the Grep tool or shell text-search commands such as \`grep\`, \`rg\`, or \`git grep\`.
+- LSP startup or indexing time is not a reason to replace a required semantic query with text matching. Wait for the role-session LSP and follow the skill's bounded retry procedure.
 - If LSP cannot resolve a required project-owned relationship, record it as unresolved. Do not replace semantic evidence with text matches.
 
 ### Work Persistence
 
 - Treat Architect artifacts, not Session memory, as continuation state.
+- Write each owned artifact to a candidate outside \`.ai/vcm\`, then submit it with \`.ai/tools/vcm-artifact <artifact-kind> --file <candidate> --mode draft|final\`. Only an accepted submission updates the authoritative artifact.
 - Write each verified code fact, confirmed user decision, architecture decision, root cause, and validation result to its owning artifact as soon as it becomes an input to later work.
 - Before ending any turn, ensure all information required to continue the current Architect work is present in the current artifacts.
 - Keep artifacts current and self-contained. Replace superseded content instead of appending conversation history or investigation logs.
@@ -102,7 +103,7 @@ ${renderRoleMemoryRules("architect")}
 - When the repeated-workaround threshold is met, \`Architecture Decision\` must explicitly fix the owning behavior, confirm that local handling is intended and correct the owning documentation, or record the unresolved issue and affected call sites through Known Issues Sync. Extracting the workaround into a helper is not an upstream disposition.
 - \`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. 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.
+- \`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. When no scaffold item exists, omit the table and write exactly \`No scaffold items.\`; an empty table is invalid.
 - 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/check-scaffold-ledger.js

@@ -7,7 +7,8 @@ item, one unique ID per entry, and exactly one \`VCM:CODE <ID>\` marker in the t
 \`create\`/\`change\`/\`delete\` entry. This tool checks:
 
   1. the ledger header follows the mandated column order (\`ID | Action | File | ...\`),
-     every ledger ID is unique, classified by its whole-cell action column
+     every data-row ID matches the documented grammar as a complete cell and is unique,
+     classified by its whole-cell action column
      (create/change/delete), and bound to a declared file path in the file column;
   2. the ledger ID set equals the tree marker ID set, each ID exactly once on each side;
   3. every marker sits in its entry's declared file;
@@ -28,14 +29,15 @@ from pathlib import Path
 PLAN = ".ai/vcm/handoffs/architecture-plan.md"
 MANIFEST_HEADING = re.compile(r"^##\\s+Scaffold Manifest\\s*$")
 SECTION_HEADING = re.compile(r"^##\\s+\\S")
-ID_TOKEN = re.compile(r"\\b([A-Z]{2,6}-\\d{1,4})\\b")
+ID_PATTERN = re.compile(r"[A-Z]{2,6}-\\d{1,4}")
+EMPTY_MANIFEST = "No scaffold items."
+TABLE_SEPARATOR_CELL = re.compile(r":?-{3,}:?")
 # Mandated column order: ID | action | file | symbol/site | work | freedom | proof.
 # The action is read from its own cell as a whole-cell verb — never sniffed from the
 # row text, so paths or prose containing action words cannot flip an item's class.
 ACTIONS = frozenset({"create", "change", "delete"})
 PATH_TOKEN = re.compile(r"\`([^\`\\s]+/[^\`\\s]+|[^\`\\s]+\\.[A-Za-z0-9]{1,8})\`")
-MARKER_ID = re.compile(r"VCM:CODE[:\\s]\\s*([A-Za-z]{2,6}-\\d{1,4})")
-MARKER_ANY = re.compile(r"VCM:CODE")
+MARKER_ANY = re.compile(r"VCM:CODE(?![A-Za-z0-9_])")
 FORBIDDEN = [
     re.compile(r"as work proceeds", re.IGNORECASE),
     re.compile(r"\\breplicate\\b", re.IGNORECASE),
@@ -57,36 +59,66 @@ def manifest_section(plan_text: str) -> tuple[int, list[str]] | None:
     return None if start is None else (start, lines[start:])
 
 
-def parse_ledger(section_start: int, section: list[str], plan: str) -> tuple[dict, list[str]]:
-    """{id: {"path", "action", "line"}} plus parse findings. Positional parsing per the
-    mandated column order; the first non-entry table row is validated as the header."""
+def is_separator_row(cells: list[str]) -> bool:
+    return bool(cells) and all(TABLE_SEPARATOR_CELL.fullmatch(cell.replace(" ", "")) for cell in cells)
+
+
+def parse_ledger(section_start: int, section: list[str], plan: str) -> tuple[dict, list[str], bool]:
+    """{id: {"path", "action", "line"}}, parse findings, and explicit-empty state."""
     entries: dict[str, dict] = {}
     findings: list[str] = []
-    header_checked = False
+    header_line = None
+    separator_seen = False
+    explicit_empty_line = None
     for offset, line in enumerate(section):
         line_no = section_start + offset + 1
         stripped = line.strip()
+        if stripped == EMPTY_MANIFEST:
+            if explicit_empty_line is not None:
+                findings.append(
+                    f"{plan}:{line_no}  [ledger] duplicate \`{EMPTY_MANIFEST}\` declaration "
+                    f"(first at line {explicit_empty_line})"
+                )
+            else:
+                explicit_empty_line = line_no
+            continue
         if not stripped.startswith("|"):
             continue
         cells = [cell.strip() for cell in stripped.strip("|").split("|")]
-        if not cells or set(cells[0]) <= {"-", ":", " "}:
-            continue  # separator row
-        id_match = ID_TOKEN.search(cells[0])
-        if not id_match:
-            if not header_checked:
-                header_checked = True
-                head = [cell.lower() for cell in cells[:3]] + ["", "", ""]
-                if not (
-                    "id" in head[0]
-                    and "action" in head[1]
-                    and ("file" in head[2] or "path" in head[2])
-                ):
-                    findings.append(
-                        f"{plan}:{line_no}  [ledger] header columns must be "
-                        f"\`ID | Action | File | ...\` -> fix the ledger column order"
-                    )
+
+        if header_line is None:
+            header_line = line_no
+            head = [cell.lower() for cell in cells[:3]]
+            if head != ["id", "action", "file"]:
+                findings.append(
+                    f"{plan}:{line_no}  [ledger] header columns must begin exactly "
+                    f"\`ID | Action | File | ...\` -> fix the ledger column order"
+                )
             continue
-        entry_id = id_match.group(1)
+
+        if not separator_seen:
+            if is_separator_row(cells):
+                separator_seen = True
+                continue
+            findings.append(
+                f"{plan}:{line_no}  [ledger] missing Markdown separator row after "
+                f"the Scaffold Manifest header"
+            )
+            separator_seen = True
+        elif is_separator_row(cells):
+            findings.append(
+                f"{plan}:{line_no}  [ledger] unexpected separator row inside Scaffold Manifest data"
+            )
+            continue
+
+        id_cell = cells[0] if cells else ""
+        if not ID_PATTERN.fullmatch(id_cell):
+            findings.append(
+                f"{plan}:{line_no}  [ledger] ID cell \`{id_cell}\` must match "
+                f"\`[A-Z]{{2,6}}-[0-9]{{1,4}}\` exactly"
+            )
+            continue
+        entry_id = id_cell
         if entry_id in entries:
             findings.append(
                 f"{plan}:{line_no}  [ledger] duplicate ledger ID {entry_id} "
@@ -110,7 +142,30 @@ def parse_ledger(section_start: int, section: list[str], plan: str) -> tuple[dic
                 f"column 3 -> bind the item to its exact file"
             )
         entries[entry_id] = {"path": declared, "action": action, "line": line_no}
-    return entries, findings
+    if explicit_empty_line is not None:
+        if header_line is not None:
+            findings.append(
+                f"{plan}:{explicit_empty_line}  [ledger] \`{EMPTY_MANIFEST}\` cannot be "
+                f"combined with a Scaffold Manifest table"
+            )
+        return entries, findings, True
+
+    if header_line is None:
+        findings.append(
+            f"{plan}:{section_start + 1}  [ledger] Scaffold Manifest must contain the "
+            f"required table or the exact line \`{EMPTY_MANIFEST}\`"
+        )
+        return entries, findings, False
+    if not separator_seen:
+        findings.append(
+            f"{plan}:{header_line}  [ledger] Scaffold Manifest table is missing its separator row"
+        )
+    if not entries:
+        findings.append(
+            f"{plan}:{header_line}  [ledger] Scaffold Manifest contains no valid entries; "
+            f"use the exact line \`{EMPTY_MANIFEST}\` only when no scaffold item exists"
+        )
+    return entries, findings, False
 
 
 def forbidden_language(section_start: int, section: list[str], plan: str) -> list[str]:
@@ -140,14 +195,22 @@ def tree_markers(root: Path) -> tuple[dict[str, list[tuple[str, int]]], list[str
         if len(parts) < 3:
             continue
         path, line_no, content = parts[0], int(parts[1]), parts[2]
-        id_match = MARKER_ID.search(content)
-        if id_match:
-            markers.setdefault(id_match.group(1), []).append((path, line_no))
-        elif MARKER_ANY.search(content):
-            findings.append(
-                f"{path}:{line_no}  [ledger] marker without a parseable ID -> "
-                f"use \`VCM:CODE <ID>\`"
-            )
+        for occurrence in MARKER_ANY.finditer(content):
+            token_match = re.match(r"\\s+(\\S+)", content[occurrence.end():])
+            if token_match is None:
+                findings.append(
+                    f"{path}:{line_no}  [ledger] marker without an ID -> "
+                    f"use \`VCM:CODE <ID>\`"
+                )
+                continue
+            marker_id = token_match.group(1)
+            if not ID_PATTERN.fullmatch(marker_id):
+                findings.append(
+                    f"{path}:{line_no}  [ledger] marker ID \`{marker_id}\` must match "
+                    f"\`[A-Z]{{2,6}}-[0-9]{{1,4}}\` exactly"
+                )
+                continue
+            markers.setdefault(marker_id, []).append((path, line_no))
     return markers, findings
 
 
@@ -170,7 +233,7 @@ def main() -> int:
     if section is None:
         sys.stderr.write(f"{plan_path}:1  [ledger] no \`## Scaffold Manifest\` section\\n")
         return 1
-    entries, parse_findings = parse_ledger(*section, str(plan_path))
+    entries, parse_findings, explicit_empty = parse_ledger(*section, str(plan_path))
     findings += parse_findings
     findings += forbidden_language(*section, str(plan_path))
 
@@ -213,10 +276,13 @@ def main() -> int:
     if findings:
         sys.stderr.write(f"ledger reconciliation failed with {len(findings)} finding(s)\\n")
         return 1
-    print(
-        f"ledger reconciliation clean: {len(ledger_ids)} ledger item(s), "
-        f"{len(tree_ids)} marker(s)"
-    )
+    if explicit_empty:
+        print("ledger explicitly empty: 0 ledger item(s), 0 marker(s)")
+    else:
+        print(
+            f"ledger reconciliation clean: {len(ledger_ids)} ledger item(s), "
+            f"{len(tree_ids)} marker(s)"
+        )
     return 0
 
 

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

@@ -4,13 +4,21 @@ export function renderRootClaudeHarnessRules() {
 - Use the durable project docs below as role-relevant project truth.
 - Read module-local \`CLAUDE.md\` before editing a subdirectory if one exists.
 - \`vcm-route-message\` is the only channel for PM-hub dispatch and reporting among project-manager, architect, coder, and tester. Gate Review and tool-role work use their dedicated VCM skills and controllers. Follow the route skill's write-then-stop rule.
-- Project-manager uses \`vcm-task-state\` to declare the current workflow checkpoint. This state is recoverable context only; flow rules and task artifacts remain authoritative.
+- Before every PM dispatch to Architect, Coder, or Tester, project-manager must use \`vcm-workflow-review\`. Only an accepted Workflow Progress transition grants the next route.
+- \`vcm-task-state\` is recoverable context only. Workflow permission comes only from accepted \`workflow-progress.md\` submissions.
 - 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.
 - The root \`<VCM-memory>\` block is shared project memory. Treat every \`<VCM-memory>\` block as read-only and use \`vcm-propose-memory\` only when VCM assigns an exact memory proposal or candidate path.
 - Only the user may approve scope reduction, skipped required validation, Gate Review skip or override, skipped required docs sync, accepted unresolved task-scope risk, or weakening of baseline Harness rules. PM may record and route the user's approval but cannot grant it.
 - Project-manager runs \`vcm-gate-review\` unconditionally at every Gate Review trigger point and on VCM Gate Review callbacks; the tool reports the authoritative enable state.
 
+## VCM Managed Artifacts
+
+- VCM-managed Markdown under \`.ai/vcm/handoffs/\`, Coder Worker reports, request-scoped Gate Review reports, route messages, memory proposals, Harness Feedback, and retrospective reports must be submitted with \`.ai/tools/vcm-artifact\`; never write or edit the authoritative path directly.
+- Write the candidate outside \`.ai/vcm/\`, then run \`.ai/tools/vcm-artifact <kind> --file <candidate> --mode <draft|final>\`. Dynamic artifacts also require the exact VCM-assigned \`--path\`.
+- Use \`draft\` while an allowed lifecycle remains incomplete. Use \`final\` before routing or consuming a terminal artifact. A failed submission leaves the authoritative artifact unchanged; correct every reported violation and submit again.
+- Do not route, review, or rely on a candidate file. Only the VCM-written authoritative path is workflow evidence.
+
 ## 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, tool-role rules, and Harness Engineer rules.

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

@@ -16,7 +16,6 @@ ${renderRoleMemoryRules("coder")}
 
 - Follow the preloaded \`vcm-code-navigation\` skill whenever implementation requires code definitions, implementations, references, callers, callees, or behavior paths.
 - Use LSP for semantic relationships. Use Glob to locate files and Read to inspect complete code.
-- Do not use the Grep tool or shell text-search commands such as \`grep\`, \`rg\`, or \`git grep\`.
 - If LSP cannot resolve a required project-owned relationship, record it as unresolved in the completion evidence. Do not replace semantic evidence with text matches.
 
 ### Shared Coding Standards
@@ -78,7 +77,7 @@ ${renderRoleMemoryRules("coder")}
 
 ### Handoff
 
-- Write \`.ai/vcm/handoffs/coder-completion.md\` before routing back to project-manager. This file is the complete, self-contained current implementation completion evidence, not a log. Each revision must restate every Scaffold Manifest disposition, changed file, helper, deviation, generated-context result, baseline-test change, L0/L1 command and result, worker result, commit, and objective failure still needed to review the current implementation without a prior revision. Replace stale content instead of appending history.
+- Submit \`.ai/vcm/handoffs/coder-completion.md\` before routing back to project-manager: write a candidate outside \`.ai/vcm\`, then run \`.ai/tools/vcm-artifact coder-completion --file <candidate> --mode draft|final\`. This file is the complete, self-contained current implementation completion evidence, not a log. Each revision must restate every Scaffold Manifest disposition, changed file, helper, deviation, generated-context result, baseline-test change, L0/L1 command and result, worker result, commit, and objective failure still needed to review the current implementation without a prior revision. Replace stale content instead of appending history.
 - \`coder-completion.md\` must include \`Decision: ready_for_review | incomplete | failed\`.
 - \`coder-completion.md\` must report every Scaffold Manifest item disposition in the fixed Scaffold Completion table, plus changed files, private helpers added, manifest deviations as report-only facts, generated context status, baseline tests added or updated, L0/L1 commands and results, worker commits and integration status when workers were used, and compile/typecheck or L0/L1 failures.
 - Use this structure:

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

@@ -25,7 +25,7 @@ You are \`vcm-coder-worker\`, a bounded implementation worker invoked by Coder.
 }
 \`\`\`
 
-- 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.
+- After the sweep of assigned items and their assigned checks, commit the assigned files. After the commit succeeds, write the assigned report to a candidate outside \`.ai/vcm\`, submit it with \`.ai/tools/vcm-artifact coder-worker-report --file <candidate> --path <assigned-report-path> --mode final\`, 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.

package/dist/backend/templates/harness/gate-review.js

@@ -21,8 +21,7 @@ Follow the preloaded \`vcm-code-navigation\` skill whenever a gate requires code
 implementations, references, callers, callees, or behavior paths. Use LSP for
 semantic relationships, Glob to locate files, Read to inspect complete code,
 and generated context, architecture documents, or runtime evidence for
-boundaries LSP does not model. Do not use the Grep tool or shell text-search
-commands such as \`grep\`, \`rg\`, or \`git grep\`. If LSP cannot resolve
+boundaries LSP does not model. If LSP cannot resolve
 a required project-owned relationship, treat that evidence as unresolved and
 return \`request_changes\`; do not replace semantic evidence with text matches.
 
@@ -338,7 +337,7 @@ evidence.
 
 ## Output
 
-For an active VCM Gate Review request, write only the assigned report under \`.ai/vcm/gate-reviews/\`. Start with:
+For an active VCM Gate Review request, write only the assigned report under \`.ai/vcm/gate-reviews/\`. Write a candidate outside \`.ai/vcm\`, then submit it with \`.ai/tools/vcm-artifact gate-review-report --file <candidate> --path <assigned-report-path> --mode final\`. Start with:
 
 \`\`\`text
 Gate: <gate>
@@ -472,7 +471,7 @@ If there are no findings, write:
 None.
 \`\`\`
 
-Use Bash only for read-only inspection such as \`git diff\`, \`git status\`, \`git show\`, \`ls\`, \`sed\`, or \`cat\`. Do not run shell text-search commands, tests, builds, formatters, generators, package managers, or commands that modify files.
+Use Bash only for read-only inspection such as \`git diff\`, \`git status\`, \`git show\`, \`ls\`, \`sed\`, or \`cat\`. Do not run tests, builds, formatters, generators, package managers, or commands that modify files.
 
 Review only code, architecture, and documents; do not perform validation. Do not edit code, tests, durable docs, role files, route files, or handoff artifacts. Do not assign findings or remediation work to VCM roles, choose fixes, decide Replan, or decide whether user intervention is needed.
 

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

@@ -131,7 +131,7 @@ For each pending feedback:
 Process every assigned feedback before completing the retrospective. A
 feedback item is processed even when it is rejected or already covered.
 
-Write the complete retrospective report before deleting any feedback file.
+Write the complete retrospective report to a candidate outside \`.ai/vcm\` and submit it with \`.ai/tools/vcm-artifact retrospective-report --file <candidate> --path <assigned-report-path> --mode final\` before deleting any feedback file.
 After the report contains a disposition for every assigned feedback, delete
 those feedback files from \`.ai/vcm/harness-feedback/pending/\`.
 
@@ -158,6 +158,23 @@ Do not edit harness files during retrospective analysis. Write a concise analysi
 - affected roles, skills, tools, or docs
 - pending feedback path and disposition
 
+Use this report structure:
+
+\`\`\`md
+# Task Harness Retrospective: <task>
+
+## Findings
+
+## Feedback Dispositions
+
+## Recommended Harness Changes
+
+## VCM Issue Drafts
+
+<!-- Include Memory Review only when VCM assigns Auto Memory Review. -->
+## Memory Review
+\`\`\`
+
 ## VCM Feedback
 
 If the issue is a VCM product, installer, UI, or fixed template problem, draft a

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

@@ -52,7 +52,7 @@ PM Managed Mode applies only when the user explicitly asks to complete the curre
 
 PM owns task flow selection. Every user request that asks VCM to perform delivery work must enter one of these flows or branches:
 
-- After selecting a flow, use \`vcm-task-state\` to declare the flow and first step before the first role dispatch.
+- Before every dispatch to Architect, Coder, or Tester, use \`vcm-workflow-review\` and obtain an accepted Workflow Progress transition for that exact target. A rejection keeps PM in the current turn.
 
 - Code-change flow: use the complete Code-Change Flow defined below.
 - Architect Debug Flow or Branch: use Architect Debug Flow And Branch below.
@@ -113,7 +113,7 @@ The flow completes only when Final Acceptance returns:
 ### Routing
 
 - Use the PM-hub routes allowed by the \`vcm-route-message\` skill.
-- Include the current \`vcm-task-state\` declaration in every PM route file. At a checkpoint without a role route, declare the new step with \`.ai/tools/update-task-state\`.
+- Write a PM route file only after \`vcm-workflow-review\` accepts the matching target. The approval is one-time and contains the workflow state; do not duplicate workflow metadata in the route file.
 - Keep only one active role handoff at a time.
 - Route user-originated or flow-required architecture, scope, contract, dependency, public surface, durable docs, and implementation-plan questions to Architect.
 - Do not treat Coder architecture doubts, design concerns, scaffold objections, or validation predictions as architecture questions.
@@ -300,6 +300,7 @@ Communication-Only Flow does not run Gate Review, validation, docs sync, Final A
 
 ### Dispatch
 
+- Use \`vcm-workflow-review\` before every dispatch to Architect, Coder, or Tester. Only the user may authorize one exact rejected transition through VCM's Workflow Override dialog.
 - Use the \`vcm-route-message\` skill for every role dispatch, question, result, blocker, or finding.
 - Formal route messages contain PM-owned routing context only.
 - PM dispatch messages must include: target role, accepted task scope, current task repo root and branch, reason for this route, source artifact or evidence, required output artifact, next gate, stop conditions, and user constraints.

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

@@ -14,6 +14,7 @@ ${renderRoleMemoryRules("tester")}
 ### Inputs
 
 - Read tester role message, the VCM task record or durable plan, architecture plan, \`docs/CODING_STANDARDS.md\`, \`docs/TESTING.md\`, relevant tests, fixtures, and validation docs.
+- Write \`test-report.md\` to a candidate outside \`.ai/vcm\`, then submit it with \`.ai/tools/vcm-artifact test-report --file <candidate> --mode draft|final\`. Use draft only for \`Test Result: incomplete\`; pass or fail must use final.
 - Read affected production code only as needed to design tests, understand public contracts, and identify validation coverage gaps.
 - Use \`.ai/generated/module-index.json\` and \`.ai/generated/public-surface.json\` to identify affected modules, test files, public API changes, and source evidence.
 

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

@@ -47,6 +47,11 @@ Routine technical architecture decisions remain Architect-owned; do not turn ord
 
 ## Artifact
 
+Write brief and evidence candidates outside \`.ai/vcm\`. Submit updates with
+\`.ai/tools/vcm-artifact architecture-brief --file <candidate> --mode draft|final\`
+and \`.ai/tools/vcm-artifact architecture-evidence --file <candidate> --mode draft|final\`.
+Use final only for confirmed brief and complete evidence.
+
 Maintain exactly this structure:
 
 \`\`\`md

package/dist/backend/templates/harness/vcm-code-navigation-skill.js

@@ -6,9 +6,9 @@ Use this skill when Architect, Coder, or Reviewer must establish symbol definiti
 ## Navigation Order
 
 1. Define the affected feature or module boundary and locate entry symbols with \`.ai/generated/module-index.json\` and \`.ai/generated/public-surface.json\` when available.
-2. Start each navigation run with LSP \`documentSymbol\` on a known affected project source file. This initializes the actual role-session language server and proves that it can parse that file; an executable version probe is not workspace readiness.
+2. If \`LSP\` is not listed initially, call \`ToolSearch\` with query \`select:LSP\` to load the deferred plugin tool. Then start each navigation run with LSP \`documentSymbol\` on a known affected project source file. This initializes the actual role-session language server and proves that it can parse that file; an executable version probe is not workspace readiness.
 3. Use LSP workspace or file symbols, definitions, implementations, references, and incoming or outgoing call hierarchy to resolve project-owned relationships.
-4. If an initial workspace-symbol request is empty or reports indexing, do not conclude that the symbol is absent. After a successful file-symbol request, retry the same bounded workspace query at most two more times. If it still cannot resolve, record the operation and result as unresolved.
+4. If an initial workspace-symbol request is empty or reports indexing, wait and retry; startup or indexing time does not permit replacing a required semantic query with text matching. After a successful file-symbol request, retry the same bounded workspace query at most two more times. If it still cannot resolve, record the operation and result as unresolved.
 5. Read the complete project-owned callable unit at every resolved location.
 6. Expand one project-owned dependency hop at a time until the required behavior path has no unresolved symbol.
 7. Use Glob, generated context, architecture documents, and runtime evidence to locate dynamic registrations, configuration or string edges, macros, documentation, and external boundaries that LSP does not model.
@@ -17,8 +17,7 @@ Use this skill when Architect, Coder, or Reviewer must establish symbol definiti
 
 - Record each resolved relationship and whether it came from LSP, runtime evidence, an external boundary, or a generated boundary.
 - When an empty LSP result contradicts a direct call in the code, another LSP result, or runtime evidence, treat the relationship as unresolved. Record the contradiction and use exact fallback evidence.
-- If LSP is unavailable or cannot resolve a required project-owned relationship, record that limitation and leave the relationship unresolved. Do not substitute text search for semantic navigation.
-- Do not use the Grep tool or shell text-search commands such as \`grep\`, \`rg\`, or \`git grep\`.
+- If LSP is unavailable or cannot resolve a required project-owned relationship, record that limitation and leave the relationship unresolved.
 - Generated indexes and architecture docs locate likely code; reading current-worktree implementation establishes behavior.
 
 ## Context Boundary

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: