vibe-coding-master 0.7.6 → 0.7.8

package/README.md

@@ -181,6 +181,12 @@ By default:
 Roles for the same task share the same task worktree. VCM does not create one
 worktree per role.
 
+Project Manager may record an advisory task checkpoint under
+`.ai/vcm/workflow/state.json`. VCM restores and displays this context after a
+restart, but it does not infer transitions or choose the next role. Current
+artifacts, Gate Review state, Round/Turn state, and the role rules remain
+authoritative.
+
 Typical flow:
 
 ```text
@@ -412,10 +418,16 @@ Post-task processing is ordered by the backend:
 ```text
 Final Acceptance
   -> Review Task Harness
-  -> Memory proposals and Harness Engineer review, when Auto Memory is enabled
+  -> Workflow-role memory proposals, when Auto Memory is enabled
+  -> Harness Engineer memory review, when Auto Memory is enabled
   -> Task Harness Retrospective
 ```
 
+Memory proposal prompts sent to Project Manager, Architect, Coder, Tester, and
+an enabled Gate Reviewer use their normal task sessions and participate in
+Round/Turn tracking. Harness Engineer review and retrospective work remain tool
+role activity and do not participate in Round completion.
+
 When Auto Memory is disabled, Review Task Harness does not collect proposals or
 ask Harness Engineer to update memory. When enabled, both automatic and manual
 review requests complete the memory phase before retrospective analysis. A
@@ -430,6 +442,11 @@ It stops every running session owned by the task, including Translator and
 Harness Engineer, then removes task-owned worktree/branch state. Commit or
 preserve anything important before closing.
 
+Uncommitted changes, unmerged commits, and cleanup failures are reported as
+warnings; they do not block logical task closure. VCM may discard the task
+worktree and task branch even when they contain commits that are not present on
+the connected repository branch.
+
 ## Troubleshooting
 
 ### The page does not open
@@ -517,7 +534,11 @@ npm start
 ## Documentation
 
 - `docs/ARCHITECTURE.md`: repository architecture
+- `docs/CODING_STANDARDS.md`: shared implementation and test standards
+- `docs/GLOSSARY.md`: allowed durable abbreviations
 - `docs/TESTING.md`: validation strategy
+- `docs/known-issues.md`: current unresolved durable issues
+- `src/backend/gateway/ARCHITECTURE.md`: mobile gateway sub-area architecture
 - `docs/vcm-cc-best-practices.md`: current VCM Claude Code harness practice
 - `docs/v0.5-custom-workflow-plan.md`: deferred custom workflow proposal
 - `docs/cc-best-practices.md`: archived generic Claude Code harness notes

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

@@ -142,6 +142,13 @@ export function registerHarnessRoutes(app, deps) {
         const taskSlug = await normalizeOptionalTaskSlug(deps, project.repoRoot, request.query.taskSlug);
         return deps.harnessFeedbackService.getState(project.repoRoot, taskSlug);
     });
+    app.post("/api/projects/harness/feedback/send", async (request) => {
+        const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
+        return deps.harnessFeedbackService.sendPendingFeedback(project.repoRoot, {
+            taskSlug: task.taskSlug,
+            feedbackPath: request.body?.feedbackPath ?? ""
+        });
+    });
     app.post("/api/projects/harness/task-retrospective", async (request) => {
         const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
         const trigger = request.body?.trigger === "auto" ? "auto" : "manual";

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

@@ -26,6 +26,7 @@ import { renderVcmProposeMemorySkillRules } from "../templates/harness/vcm-propo
 import { renderVcmReportHarnessIssueSkillRules } from "../templates/harness/vcm-report-harness-issue-skill.js";
 import { renderVcmRouteMessageSkillRules } from "../templates/harness/vcm-route-message-skill.js";
 import { renderUpdateTaskStateTool, renderVcmTaskStateSkillRules } from "../templates/harness/vcm-task-state-skill.js";
+import { renderCheckScaffoldLedgerTool } from "../templates/harness/check-scaffold-ledger.js";
 import { readVcmPackageVersion } from "../app-version.js";
 const CLI_DIR = path.dirname(fileURLToPath(import.meta.url));
 const APP_ROOT = path.resolve(CLI_DIR, "../../..");
@@ -295,6 +296,12 @@ const WHOLE_FILES = [
         mode: 0o755,
         content: renderUpdateTaskStateTool()
     },
+    {
+        path: ".ai/tools/check-scaffold-ledger",
+        category: "runtime-tool",
+        mode: 0o755,
+        content: renderCheckScaffoldLedgerTool()
+    },
     {
         path: ".ai/tools/run-long-check",
         category: "runtime-tool",

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

@@ -21,6 +21,23 @@ export function createHarnessFeedbackService(deps) {
             warnings: []
         };
     }
+    async function sendPendingFeedback(repoRoot, input) {
+        await cleanupLegacyState(repoRoot);
+        const feedbackPath = input.feedbackPath.trim();
+        const pending = await listPendingFeedback(repoRoot);
+        const feedback = pending.find((item) => item.path === feedbackPath);
+        if (!feedback) {
+            throw new VcmError({
+                code: "HARNESS_FEEDBACK_NOT_PENDING",
+                message: "The selected Harness Feedback is no longer pending.",
+                statusCode: 404,
+                hint: "Refresh Harness Studio and select a feedback item that is still listed in the Inbox."
+            });
+        }
+        const session = await ensureIdleHarnessEngineer(repoRoot, input.taskSlug);
+        await submitTerminalInput(deps.runtime, session.id, buildPendingFeedbackPrompt(repoRoot, feedback.path));
+        return session;
+    }
     async function startTaskRetrospective(repoRoot, input) {
         await cleanupLegacyState(repoRoot);
         const taskSlug = input.taskSlug.trim();
@@ -155,6 +172,16 @@ export function createHarnessFeedbackService(deps) {
             "End your turn after writing the result."
         ].join("\n");
     }
+    function buildPendingFeedbackPrompt(repoRoot, feedbackPath) {
+        return [
+            "[VCM Harness Feedback]",
+            "",
+            "Review this feedback:",
+            resolveRepoPath(repoRoot, feedbackPath),
+            "",
+            "Verify the issue against the current harness and project evidence. Report your findings and proposed changes to the user."
+        ].join("\n");
+    }
     async function loadTaskRetrospectiveMarker(repoRoot, taskSlug) {
         const markerPath = resolveRepoPath(repoRoot, getTaskRetrospectiveMarkerPath(taskSlug));
         if (!(await deps.fs.pathExists(markerPath))) {
@@ -185,6 +212,7 @@ export function createHarnessFeedbackService(deps) {
     }
     return {
         getState,
+        sendPendingFeedback,
         startTaskRetrospective,
         assertHarnessEngineerAvailable
     };

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

@@ -23,6 +23,7 @@ import { renderVcmProposeMemorySkillRules } from "../templates/harness/vcm-propo
 import { renderVcmReportHarnessIssueSkillRules } from "../templates/harness/vcm-report-harness-issue-skill.js";
 import { renderVcmRouteMessageSkillRules } from "../templates/harness/vcm-route-message-skill.js";
 import { renderUpdateTaskStateTool, renderVcmTaskStateSkillRules } from "../templates/harness/vcm-task-state-skill.js";
+import { renderCheckScaffoldLedgerTool } from "../templates/harness/check-scaffold-ledger.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { VcmError } from "../errors.js";
 import { bumpHarnessRevision, readHarnessRevisionState } from "./harness-revision.js";
@@ -215,6 +216,13 @@ const HARNESS_FILES = [
         ownership: "raw-file",
         renderRules: renderUpdateTaskStateTool
     },
+    {
+        kind: "tool-check-scaffold-ledger",
+        path: ".ai/tools/check-scaffold-ledger",
+        title: "Check Scaffold Ledger Tool",
+        ownership: "raw-file",
+        renderRules: renderCheckScaffoldLedgerTool
+    },
     {
         kind: "agent-project-manager",
         path: ".claude/agents/project-manager.md",

package/dist/backend/services/job-guard-service.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 const ACTIVE_JOB_STATUSES = new Set(["queued", "starting", "running"]);
-const ACTIVE_CODER_WORKER_STATUSES = new Set(["planned", "running", "completed", "failed"]);
+const ACTIVE_CODER_WORKER_STATUSES = new Set(["running", "completed"]);
 const QUEUED_JOB_FRESH_MS = 120_000;
 export const MAX_CONSECUTIVE_STOP_BLOCKS = 3;
 export function createJobGuardService(deps = {}) {
@@ -147,7 +147,6 @@ async function findActiveCoderWorkerTasks(taskRepoRoot) {
             workerId: typeof state.workerId === "string" ? state.workerId : path.basename(entry, ".json"),
             status,
             reportPath: typeof state.reportPath === "string" ? state.reportPath : undefined,
-            error: typeof state.error === "string" ? state.error : undefined,
             stateMtimeMs
         });
     }
@@ -177,9 +176,10 @@ function buildCoderWorkerBlockReason(tasks) {
     const reports = tasks
         .map((task) => task.reportPath)
         .filter((reportPath) => Boolean(reportPath));
-    const reportHint = reports.length > 0 ? ` Test report(s): ${reports.join(", ")}.` : "";
+    const reportHint = reports.length > 0 ? ` Worker report(s): ${reports.join(", ")}.` : "";
     return `VCM: coder worker task ${listing} is still unhandled. Do not end the Coder turn while worker tasks are unhandled. `
-        + `Wait for worker subagents, test reports and commits, resolve failed or incomplete workers, set \`handled: true\` in each worker state, and continue.${reportHint}`;
+        + `Wait for running workers; inspect every completed worker report, implementation result, item disposition, and commit; `
+        + `then set \`handled: true\` in each worker state and continue.${reportHint}`;
 }
 function latestMtime(...values) {
     return values.reduce((latest, value) => value !== undefined && (latest === undefined || value > latest) ? value : latest, undefined);

package/dist/backend/templates/handoff.js

@@ -101,9 +101,15 @@ 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.
 
-| ID | File / Action | Current Evidence / Why In Scope | Coder Work | Allowed Freedom | Expected VCM:CODE | Durable Comment Needs | Behavior / Contract Proof Points |
-| --- | --- | --- | --- | --- | --- | --- | --- |
-| SCF-001 | TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+| ID | Action | File | Symbol Or Site | Coder Work | Allowed Implementation Freedom | Behavior / Contract Proof Point |
+| --- | --- | --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD | TBD | TBD |
+
+## Scaffold Build Evidence
+
+| Check | Command | Result | Scaffold Commit |
+| --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD |
 
 ## Tester Coverage Hints
 
@@ -187,11 +193,9 @@ Decision: ready_for_review|incomplete|failed
 
 ## Scaffold Completion
 
-TBD
-
-## Remaining Markers
-
-TBD
+| ID | Action | Result | Marker State | Proof Evidence |
+| --- | --- | --- | --- | --- |
+| TBD | TBD | TBD | TBD | TBD |
 
 ## Changed Files
 

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

@@ -54,20 +54,37 @@ ${renderRoleMemoryRules("architect")}
 - Do not begin Architecture Decision, Code Scaffolding, or a complete architecture plan unless \`architecture-brief.md\` has \`Architecture Brief Status: confirmed\`.
 - Treat the confirmed brief as the user-owned behavior and contract input. Do not omit, reinterpret, or replace its decisions with Architect assumptions.
 - Before coder work starts, write \`.ai/vcm/handoffs/architecture-plan.md\`, choose the minimum necessary code scaffolding, and include a Scaffold Manifest for task-specific context and coder guidance.
-- The architecture-plan handoff is not complete until required code scaffolding, callable surfaces, contract comments, and \`VCM:CODE\` placeholders have been written.
+- The architecture-plan handoff is not complete until every \`create\`, \`change\`, and \`delete\` ledger item, every new or changed non-private callable surface, contract comments, and all \`VCM:CODE\` placeholders have been scaffolded and committed, and the scaffolded workspace passes the project's compile/typecheck L0 check.
+- Do not defer scaffold creation to the coder turn anywhere in the plan: every signature, placeholder, and ledger item the plan needs must exist at \`Planning Result: complete\`. If something cannot be scaffolded yet, the plan is incomplete or needs user clarification.
+
+#### Planning Work Plan
+
+- When starting architecture planning for a confirmed brief, first write a \`Current Code Reality / Scope Discovery\` row to \`.ai/vcm/handoffs/planning-progress.md\`, with its scope, deliverable, done criterion, and status. Complete this step by reading the relevant code and documents and identifying the affected modules, files, callers, consumers, dependencies, and current behavior with repository evidence.
+- After \`Current Code Reality / Scope Discovery\` is complete, add the remaining planning steps: one head step for cross-module work (architecture decision, boundaries, ownership, invariants, build-configuration proofs), one middle step per affected module from the module index in dependency order — split a module into per-file steps when it exceeds one round — and one tail step for cross-module wiring, whole-plan ledger reconciliation, and final build evidence. A small task degrades to head, one middle step, and tail.
+- Bind every step to repository facts and machine checks: scope is module or file paths from the module index; deliverable is plan sections or ledger ID ranges; done criterion is a tool output or recorded check result — never a self-assessment.
+- Update \`planning-progress.md\` at the end of every planning round: mark completed steps with their evidence and leave remaining steps unchanged. Do not shrink, merge, or drop a remaining step without recording the change and its reason.
+- If the round ends before all steps are done, report \`Planning Result: incomplete\` with the progress record; project-manager routes continuation. Never compress remaining enumeration or scaffolding into summary rows to reach \`Planning Result: complete\` within the current round — an honest \`incomplete\` with recorded progress is the required outcome.
+- \`planning-progress.md\` is task-runtime state for continuation and routing, not part of the reviewed plan; \`architecture-plan.md\` alone remains the executable plan of record.
 
 #### Plan Document
 
-- \`architecture-plan.md\` must start with \`Planning Result: complete|incomplete|user clarification required\` and use these sections: Accepted Scope, Current Code Reality, Architecture Decision, Module/File Plan, Public Surface Impact, Scaffold Manifest, Tester Coverage Hints, Docs Impact, Known Risks, and Coder Handoff Notes.
-- Use \`Planning Result: complete\` only when the plan document and required code scaffold are complete and consistent. Include the same Planning Result in the route message to project-manager; do not select the next route.
+- \`architecture-plan.md\` must start with \`Planning Result: complete|incomplete|user clarification required\` and use these sections: Accepted Scope, Current Code Reality, Architecture Decision, Module/File Plan, Public Surface Impact, Scaffold Manifest, Scaffold Build Evidence, Tester Coverage Hints, Docs Impact, Known Risks, and Coder Handoff Notes.
+- Use \`Planning Result: complete\` only when: the plan document is complete; the Scaffold Manifest ledger reconciles one to one against the committed markers; and \`Scaffold Build Evidence\` records a green compile/typecheck run at the current scaffold commit hash. Include the same Planning Result in the route message to project-manager; do not select the next route.
 - \`architecture-plan.md\` is the current executable plan, not a changelog. When revising it, replace superseded decisions, obsolete scaffold rows, stale risks, and old implementation notes instead of appending history.
 - \`Accepted Scope\`: state the PM-routed task scope and the confirmed brief's required user-visible outcome and decisions, plus any explicit non-scope that prevents accidental expansion.
-- \`Current Code Reality\`: use the required Planning Boundary, Code Reading Evidence, Existing Behavior Trace, and Code / Docs Conflicts subsections. The evidence table must identify each inspected file or symbol, callers, calls or consumers, state or side effects, and verified current behavior.
+- \`Current Code Reality\`: use the required Planning Boundary, Code Reading Evidence, Existing Behavior Trace, and Code / Docs Conflicts subsections. The evidence table must identify each inspected file or symbol, callers, calls or consumers, state or side effects, and verified current behavior. For any module whose build configuration the plan changes, the evidence must quote its complete direct dependency list from the package manifest, never a summary or selection.
+- Any enumeration the plan presents as complete over the codebase — call-site inventories, module or file lists, symbol sets — must either record the deterministic, repository-local command that generates it (run at the scaffold commit, the set transcribed from its output) or be explicitly marked as judgment-derived with the evidence basis for its completeness. A complete-claimed enumeration with neither is not evidence.
 - \`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, and every non-private callable surface intended for use outside its file.
+- \`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.
 - \`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\`: provide one stable row per implementation unit or file context that coder must complete: row ID, file action, current code or integration-point evidence and why the file is in scope, coder work, allowed implementation freedom, expected \`VCM:CODE\` placeholders, durable code comment needs, and behavior/contract proof points.
-- Give each Scaffold Manifest row a stable ID such as \`SCF-001\`; use that ID in any related \`VCM:CODE\` marker so coder can report completion by ID.
+- \`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.
+- 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.
+- \`Scaffold Build Evidence\`: the exact compile/typecheck commands run on the committed scaffold, their results, and the scaffold commit hash. A missing, red, or stale-hash result means the plan is not complete.
+- When the plan introduces or changes a build configuration — a new compilation target, a feature-gated or restricted-runtime variant, a new artifact type, or a build-environment constraint — scaffold that configuration and add to \`Scaffold Build Evidence\` one named check per configuration that fails when the claim is false, run green at the scaffold commit; choose proving checks from the project coding standards when defined there. A build-configuration claim without its named green check means the plan is not complete.
+- The compile/typecheck and build-configuration checks in \`Scaffold Build Evidence\` must cover every wired exemplar, so each new cross-module call path is proven compilable at the scaffold stage. A call path that exists only in plan prose, over stub scaffold that never names the surfaces it will invoke, is not proven and the plan is not complete.
+- Plan-stage build checks prove dependency closure and build shape only; full artifact builds and environment validation that require implemented bodies are implementation-stage proof and must be listed as proof points on the corresponding ledger items instead.
 - \`Tester Coverage Hints\`: list behavior scenarios, edge conditions, public-contract risks, or runtime paths tester should consider. Do not design test cases, validation levels, commands, coverage matrices, or final validation strategy.
 - \`Docs Impact\`: list every touched module and state whether its \`<module>/ARCHITECTURE.md\` is expected to change, stay unchanged, or require code-diff review before deciding; also state whether changes belong in \`docs/ARCHITECTURE.md\`, \`.ai/generated/public-surface.json\`, or no durable architecture doc.
 - \`Known Risks\`: state concrete remaining technical risks, uncertainty, or validation risks that coder or tester must pay attention to.
@@ -77,7 +94,9 @@ ${renderRoleMemoryRules("architect")}
 
 #### Code Scaffolding
 
-- Create or update only the minimum module/file scaffolding needed to make boundaries, callable surfaces, and placeholders unambiguous.
+- Create or update only the minimum module/file scaffolding needed to make boundaries, callable surfaces, and placeholders unambiguous. Minimum limits depth (no business implementation), never breadth: every \`create\`, \`change\`, and \`delete\` item must be scaffolded.
+- When a required configuration, package manifest, or build-definition change cannot safely contain a \`VCM:CODE\` marker, complete and commit it directly as Architect-owned scaffold work. Record it in the Module/File Plan and Scaffold Build Evidence. Do not add it to the Scaffold Manifest.
+- When the plan introduces a new cross-module call path or seam — a module invoking surfaces it does not invoke today — scaffold one wired exemplar that materializes the full path shape: the imports, interface implementations, and conditional-compilation gating the intended body needs, with placeholder bodies only. Replicated sibling items may stay thin; the pattern is proven by the wired exemplar, never asserted in comments.
 - Source-code comments must describe durable behavior, contracts, invariants, error boundaries, or non-obvious logic that should remain useful after the task is complete.
 - Do not put task-specific context, task labels, implementation-order notes, handoff instructions, temporary plan rationale, or coder guidance in source-code comments.
 - Task labels such as \`RP<n>\`, \`SCF-<n>\`, \`KI-<n>\`, \`Phase <n>\`, or temporary task/round/PR labels must not appear in durable source comments.
@@ -85,7 +104,7 @@ ${renderRoleMemoryRules("architect")}
 - Define every new or changed non-private callable surface directly in code with its signature shape and contract comment.
 - When changing an existing non-private callable surface, update its signature and contract comment in code before coder work starts; leave \`VCM:CODE\` only where implementation must change.
 - Non-private callable surface includes any function, method, type, trait, enum, constant, re-export, or similar symbol that another file can call or depend on.
-- Mark incomplete implementation bodies with \`VCM:CODE <Scaffold Manifest ID>\`; coder must implement them and remove the markers before handoff.
+- Place exactly one \`VCM:CODE <ID>\` marker per ledger item: on each incomplete implementation body, at each required change site inside an existing body, and on each body or site to be deleted. Coder implements or deletes each item and removes its marker when it completes green; a failed item keeps its marker over the committed attempt.
 - Architect scaffolding may include modules, files, signatures, type shapes, durable comments, and placeholder bodies, but not real business implementation beyond minimal scaffold code.
 - Coder may add private implementation helpers, but must not add or change cross-file callable surface without architect replan.
 

package/dist/backend/templates/harness/check-scaffold-ledger.js

@@ -0,0 +1,226 @@
+export function renderCheckScaffoldLedgerTool() {
+    return `#!/usr/bin/env python3
+"""Scaffold-ledger reconciliation — machine enforcement of the Scaffold Manifest bijection.
+
+The architecture plan's Scaffold Manifest is an item ledger: one entry per implementation
+item, one unique ID per entry, and exactly one \`VCM:CODE <ID>\` marker in the tree per
+\`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
+     (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;
+  4. the manifest contains no open-ended coverage language ("as work proceeds",
+     "replicate", "etc.", "and others").
+
+Markers are scanned in git-tracked source files only (\`.md\` files and \`.ai/\` are excluded:
+prose may quote markers legitimately). Pure read; findings go to stderr; exit 0 clean,
+1 on findings. \`--plan <path>\` overrides the default plan location. No plan file at all
+means there is nothing to check (exit 0) — a docs-only or planning-free task.
+"""
+import argparse
+import re
+import subprocess
+import sys
+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")
+# 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")
+FORBIDDEN = [
+    re.compile(r"as work proceeds", re.IGNORECASE),
+    re.compile(r"\\breplicate\\b", re.IGNORECASE),
+    re.compile(r"\\betc\\.", re.IGNORECASE),
+    re.compile(r"\\band others\\b", re.IGNORECASE),
+]
+
+
+def manifest_section(plan_text: str) -> tuple[int, list[str]] | None:
+    """(start line number, section lines) of the Scaffold Manifest section, or None."""
+    lines = plan_text.splitlines()
+    start = None
+    for index, line in enumerate(lines):
+        if start is None:
+            if MANIFEST_HEADING.match(line):
+                start = index + 1
+        elif SECTION_HEADING.match(line):
+            return (start, lines[start : index])
+    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."""
+    entries: dict[str, dict] = {}
+    findings: list[str] = []
+    header_checked = False
+    for offset, line in enumerate(section):
+        line_no = section_start + offset + 1
+        stripped = line.strip()
+        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"
+                    )
+            continue
+        entry_id = id_match.group(1)
+        if entry_id in entries:
+            findings.append(
+                f"{plan}:{line_no}  [ledger] duplicate ledger ID {entry_id} "
+                f"(first at line {entries[entry_id]['line']}) -> one entry per item"
+            )
+            continue
+        action_cell = cells[1].lower() if len(cells) > 1 else ""
+        action = action_cell if action_cell in ACTIONS else None
+        declared = None
+        if len(cells) > 2:
+            path_match = PATH_TOKEN.search(cells[2])
+            declared = path_match.group(1) if path_match else None
+        if action is None:
+            findings.append(
+                f"{plan}:{line_no}  [ledger] {entry_id} action column is not exactly "
+                f"one of create/change/delete -> classify the item in column 2"
+            )
+        if declared is None:
+            findings.append(
+                f"{plan}:{line_no}  [ledger] {entry_id} has no declared file path in "
+                f"column 3 -> bind the item to its exact file"
+            )
+        entries[entry_id] = {"path": declared, "action": action, "line": line_no}
+    return entries, findings
+
+
+def forbidden_language(section_start: int, section: list[str], plan: str) -> list[str]:
+    findings = []
+    for offset, line in enumerate(section):
+        for pattern in FORBIDDEN:
+            if pattern.search(line):
+                findings.append(
+                    f"{plan}:{section_start + offset + 1}  [ledger] open-ended coverage "
+                    f"language ({pattern.pattern}) -> enumerate every item explicitly"
+                )
+    return findings
+
+
+def tree_markers(root: Path) -> tuple[dict[str, list[tuple[str, int]]], list[str]]:
+    """{id: [(path, line)]} for tracked source markers, plus malformed-marker findings."""
+    result = subprocess.run(
+        ["git", "grep", "-In", "VCM:CODE", "--", ".", ":!*.md", ":!.ai"],
+        capture_output=True,
+        text=True,
+        cwd=root,
+    )
+    markers: dict[str, list[tuple[str, int]]] = {}
+    findings: list[str] = []
+    for raw in result.stdout.splitlines():
+        parts = raw.split(":", 2)
+        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>\`"
+            )
+    return markers, findings
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Scaffold Manifest ledger <-> VCM:CODE marker bijection check."
+    )
+    parser.add_argument("--plan", default=None, help=f"plan path (default {PLAN})")
+    args = parser.parse_args()
+
+    root = Path(__file__).resolve().parents[2]
+    plan_path = Path(args.plan) if args.plan else root / PLAN
+    plan = str(plan_path)
+    if not plan_path.is_file():
+        print(f"no architecture plan at {plan_path}; nothing to check")
+        return 0
+
+    findings: list[str] = []
+    section = manifest_section(plan_path.read_text(errors="replace"))
+    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))
+    findings += parse_findings
+    findings += forbidden_language(*section, str(plan_path))
+
+    markers, marker_findings = tree_markers(root)
+    findings += marker_findings
+
+    for entry_id, sites in sorted(markers.items()):
+        if len(sites) > 1:
+            where = ", ".join(f"{p}:{n}" for p, n in sites)
+            findings.append(
+                f"[ledger] {entry_id} has {len(sites)} markers ({where}) -> exactly one per item"
+            )
+
+    ledger_ids = set(entries)
+    tree_ids = set(markers)
+    for entry_id in sorted(ledger_ids - tree_ids):
+        findings.append(
+            f"{plan}:{entries[entry_id]['line']}  [ledger] {entry_id} has no marker "
+            f"in the tree -> pre-place \`VCM:CODE {entry_id}\` in its declared file"
+        )
+    for entry_id in sorted(tree_ids - ledger_ids):
+        path, line_no = markers[entry_id][0]
+        findings.append(
+            f"{path}:{line_no}  [ledger] marker {entry_id} has no ledger entry "
+            f"-> every item must be manifested"
+        )
+    for entry_id in sorted(ledger_ids & tree_ids):
+        entry = entries[entry_id]
+        if entry["path"]:
+            declared = entry["path"]
+            for path, line_no in markers[entry_id]:
+                if not (path == declared or path.endswith("/" + declared) or declared.endswith("/" + path)):
+                    findings.append(
+                        f"{path}:{line_no}  [ledger] marker {entry_id} is outside its "
+                        f"declared file \`{declared}\`"
+                    )
+
+    for finding in findings:
+        sys.stderr.write(finding + "\\n")
+    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)"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+`;
+}

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

@@ -17,7 +17,7 @@ ${renderRoleMemoryRules("coder")}
 - Before editing production code or tests, read and follow \`docs/CODING_STANDARDS.md\`.
 - Project-specific additions in \`docs/CODING_STANDARDS.md\` are binding when they make the shared baseline more precise.
 - Keep the implementation inside the approved architecture plan, scaffold, and role message.
-- Implement every assigned \`VCM:CODE\` placeholder, track completion by Scaffold Manifest ID when present, and remove all \`VCM:CODE\` markers before handoff.
+- Implement every assigned \`VCM:CODE\` placeholder, track completion by Scaffold Manifest ID when present; remove a marker when its item completes green — a failed item keeps its marker per the failure rules.
 
 ### Inputs
 
@@ -44,21 +44,24 @@ ${renderRoleMemoryRules("coder")}
 
 - Coder may use Claude Code subagents to invoke \`vcm-coder-worker\` for parallel implementation.
 - Use workers when the task has at least 20 \`VCM:CODE\` markers and the marker distribution can form at least two worker-sized groups.
-- 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\`.
+- 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\`.
 - 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.
 - Each worker prompt must include task worktree, architecture plan path, worker state path, report path, assigned modules/files/markers, allowed implementation scope, validation scope, and commit requirement.
 - Invoke worker subagents in parallel only through \`vcm-coder-worker\`.
-- Stay in the same Coder turn until all worker subagents finish and Coder has reviewed and integrated their reports and commits. Do not end the turn to wait for worker callbacks.
-- After workers finish, inspect each report and commit for assigned completion and integration, resolve missing implementation, conflicts, invalid edits, and remaining \`VCM:CODE\` markers, then mark \`handled: true\` in each worker state.
+- Stay in the same Coder turn until every worker state is \`completed\` and Coder has reviewed and integrated all reports and commits. Do not end the turn to wait for worker callbacks.
+- A completed worker reports \`Implementation Result: success|has_failed_items\`; \`completed\` means the full assigned sweep and handoff finished, not that every item passed.
+- After workers finish, inspect each item disposition and commit, integrate successful work and committed failure scenes, resolve integration conflicts or invalid edits, and verify that every remaining marker corresponds to a failed disposition. Only then mark \`handled: true\` in each worker state.
 - Run coder-level baseline validation, summarize worker reports and commits in \`.ai/vcm/handoffs/coder-completion.md\`, and clean \`.ai/vcm/coder-workers/\`.
 
 ### Handoff
 
 - Write \`.ai/vcm/handoffs/coder-completion.md\` before routing back to project-manager. This file is the current implementation completion evidence, not a log; replace stale content instead of appending history.
 - \`coder-completion.md\` must include \`Decision: ready_for_review | incomplete | failed\`.
-- \`coder-completion.md\` must report completed Scaffold Manifest IDs or \`VCM:CODE\` IDs, remaining markers if any, 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.
+- \`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:
 
 \`\`\`md
@@ -68,7 +71,9 @@ Decision: ready_for_review|incomplete|failed
 
 ## Scaffold Completion
 
-## Remaining Markers
+| ID | Action | Result | Marker State | Proof Evidence |
+| --- | --- | --- | --- | --- |
+| <ID> | <create/change/delete> | <done/failed> | <removed/present> | <evidence> |
 
 ## Changed Files
 
@@ -88,7 +93,9 @@ Decision: ready_for_review|incomplete|failed
 \`\`\`
 
 - In the route message back to project-manager, include the \`coder-completion.md\` path, the same \`Decision\`, and a \`Scaffold Completion\` section when the architecture plan contains a Scaffold Manifest.
-- The \`Scaffold Completion\` section must report completed Scaffold Manifest IDs or \`VCM:CODE\` IDs, remaining markers if any, private helpers added, manifest deviations, and compile/typecheck or L0/L1 failures.
+- The Scaffold Completion ID set must equal the Scaffold Manifest ID set, with every ID appearing exactly once.
+- \`done\` requires \`Marker State: removed\` and green proof evidence. \`failed\` requires \`Marker State: present\` and objective failure evidence.
+- Use \`Decision: ready_for_review\` only when every item is \`done\`, \`Decision: failed\` only after the complete sweep contains at least one \`failed\` item, and \`Decision: incomplete\` when the sweep is unfinished.
 
 ### Generated Context
 
@@ -103,7 +110,7 @@ Decision: ready_for_review|incomplete|failed
 - Coder validation is limited to baseline unit-level and fast L0/L1 checks; do not run L2/L3/L4, smoke, integration, or E2E validation unless the role message explicitly assigns a targeted fast L2 check.
 - Run available L0/L1 validation after implementation.
 - Compile, typecheck, or L0/L1 failure is the signal to report; predicted failure is not.
-- If required compile/typecheck/L0/L1 validation cannot run or cannot complete, write \`Decision: failed\`. If the user explicitly approved continuing without the exact check, record the approval and reason; the approval does not change Coder's decision.
+- If required compile/typecheck/L0/L1 validation cannot run or cannot complete, record it as the affected items' failure disposition; the turn-end decision follows the sweep rules. If the user explicitly approved continuing without the exact check, record the approval and reason; the approval does not change Coder's decision.
 - Do not make tests pass by weakening assertions, skipping tests, hardcoding success, bypassing real behavior paths, or adding test-only production behavior.
 
 ### Failure Reporting And Continuation
@@ -111,6 +118,10 @@ Decision: ready_for_review|incomplete|failed
 - Report failure only from objective implementation evidence: compile/typecheck fails, L0/L1 fails, or required compile/typecheck/L0/L1 validation cannot run or complete.
 - Do not report failure based on predicted design failure, public-contract disagreement, architecture disagreement, or validation prediction.
 - Do not stop because of workload, session length, or context size.
+- Never revert implemented work. Commit the actual state at turn end — including failing or non-compiling attempts — as its own commit whose message names the failing checks or errors. The committed failing state is the reproduction scene the fix is verified against.
+- A blocker never ends the turn. Work every assigned ledger item to a terminal state. A completed item has green proof and its marker removed. A failed item has a genuine attempt committed with objective failure evidence and its marker retained. "Cannot proceed", "cannot compile", or "missing dependency" on one item never exempts the others — the scaffold froze every signature and contract, so every remaining item stays attemptable.
+- A failure decision is valid only after the full sweep: every assigned item in a terminal state, and the report carrying a per-item disposition — completed items, and each failed item with its objective evidence and suspected cause. Problems are reported once, consolidated, after the sweep.
+- A turn-budget interruption mid-sweep is \`Decision: incomplete\` with sweep progress for continuation; it is never a vehicle for returning a problem early.
 - Compile/typecheck/L0/L1 failure is not terminal until Coder has attempted to fix implementation-caused failures within the assigned scope.
 - \`Decision: incomplete\` is only for actual interruption or inability to continue the turn; it must not be used for architecture concerns, questions, or predicted risk.
 - If execution is interrupted or the turn must end unexpectedly before all assigned scaffold items are done, write \`coder-completion.md\` with \`Decision: incomplete\`, include completed items, remaining implementation work, validation state, and why continuation is needed. PM decides whether to continue the same route.