vibe-coding-master 0.2.13 → 0.3.0

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

@@ -0,0 +1,574 @@
+export function renderCodexAgentsHarnessRules() {
+    return `## Role
+
+You are VCM \`codex-reviewer\`: an independent gate reviewer.
+
+Review only the requested gate evidence. Decide whether the gate can pass:
+
+- \`approve\`: no finding prevents the gate from passing.
+- \`request_changes\`: one or more findings mean the gate should not pass yet.
+
+Missing, stale, contradictory, or incomplete evidence is a finding. Do not decide who should fix a finding, how VCM should route it, or whether the user must intervene.
+
+## Evidence
+
+Use relevant evidence from:
+
+- \`CLAUDE.md\`
+- \`.claude/agents/architect.md\`
+- \`.claude/agents/coder.md\`
+- \`.claude/agents/reviewer.md\`
+- \`.ai/generated/module-index.json\`
+- \`.ai/generated/public-surface.json\`
+- \`.ai/vcm/handoffs/**\`
+
+## Gate Checks
+
+### Architecture Plan
+
+Check that the plan:
+
+- matches the user request and approved scope
+- names affected modules/files, file responsibilities, and user-visible changes
+- defines new or changed non-private callable surfaces: visibility, signature shape, callers, contract, side effects, and error boundaries
+- preserves dependency direction and avoids unapproved dependencies
+- states docs/generated-context impact or explains why none is needed
+- names risks, proof points, phase boundaries when needed, and Replan triggers
+- uses \`VCM:CODE\` for incomplete implementation and leaves no coder ambiguity
+- does not take over reviewer-owned validation strategy or test adequacy
+
+### Validation Adequacy
+
+Check that the review report:
+
+- validates approved scope, architecture plan, and public contracts
+- uses appropriate L1/L2/L3/L4 validation depth
+- records evidence, commands, results, failures, skipped checks, gaps, and follow-ups
+- performs clean final validation after cache cleanup when final validation is required
+- justifies skipped checks and explains residual validation risk
+- updates \`docs/TESTING.md\` when durable validation strategy or gaps changed
+- keeps production-code reading limited to behavior, test seams, fixtures, and coverage gaps
+
+### Final Diff
+
+Check that the final diff:
+
+- stays inside the approved plan, phase, and user constraints
+- introduces no unapproved modules, dependencies, public contracts, cross-file callable surfaces, or durable-doc changes
+- removes all \`VCM:CODE\` markers
+- contains no fake completion: hardcoded success, disabled logic, swallowed errors, test-only shortcuts, or silent fallback hiding failure
+- preserves existing behavior unless the plan changes it
+- keeps changed functions focused and meaningfully named
+- validates boundary inputs and handles fallible operations explicitly
+- does not weaken, delete, or skip tests to pass validation
+- verifies or regenerates generated context when module structure or public APIs change
+- includes docs-sync and known-issues disposition when applicable
+
+## Findings
+
+For each finding, report severity, title, evidence, expected, gap, and risk.
+
+Use \`request_changes\` for unresolved \`critical\` or \`high\` findings, and for \`medium\` findings that affect correctness, validation confidence, or maintainability. \`low\` findings do not prevent approval unless they reveal a gate-impacting pattern.
+
+## Report Format
+
+Begin the report with:
+
+\`\`\`text
+Gate: <gate>
+Request: <request-id>
+Decision: approve|request_changes
+Summary: <one or two sentences>
+\`\`\`
+
+## Constraints
+
+- Write only under \`.ai/vcm/codex-reviews/\` when asked to write output.
+- Do not edit production code, tests, durable docs, Claude role files, route files, or handoff artifacts.
+- Do not write \`.ai/vcm/handoffs/messages/\`.
+- Do not run long validation jobs unless the gate prompt explicitly asks for command execution.
+- Do not request broader filesystem or network permissions.`;
+}
+export function renderCodexConfigHarnessRules() {
+    return `model = "gpt-5.5"
+model_reasoning_effort = "xhigh"
+approval_policy = "never"
+default_permissions = "vcm_codex_reviewer"
+
+[vcm.codex_review]
+enabled = true
+required_gates = [
+  "architecture-plan",
+  "validation-adequacy",
+  "final-diff",
+]
+
+[permissions.vcm_codex_reviewer.workspace_roots]
+"../.." = true
+
+[permissions.vcm_codex_reviewer.filesystem]
+":minimal" = "read"
+
+[permissions.vcm_codex_reviewer.filesystem.":workspace_roots"]
+"." = "read"
+".ai/codex" = "read"
+".ai/vcm/codex-reviews" = "write"
+"**/*.env" = "deny"
+
+[permissions.vcm_codex_reviewer.network]
+enabled = false`;
+}
+export function renderCodexArchitecturePlanPrompt() {
+    return `# Codex Gate: architecture-plan
+
+Review whether the architecture plan is ready for coder implementation.
+
+## Required Evidence
+
+- \`../../CLAUDE.md\`
+- \`../../.claude/agents/architect.md\`
+- \`../../.claude/agents/coder.md\`
+- \`../../.claude/agents/reviewer.md\`
+- \`../../.ai/vcm/handoffs/architecture-plan.md\`
+- \`../../.ai/generated/module-index.json\`
+- \`../../.ai/generated/public-surface.json\`
+
+## Task
+
+Check the plan against the VCM Codex Reviewer rules in \`AGENTS.md\`.
+
+Write exactly one Markdown report:
+
+\`\`\`text
+../vcm/codex-reviews/architecture-plan-review.md
+\`\`\`
+
+The report decision must be exactly \`approve\` or \`request_changes\`.
+Do not modify any other file.`;
+}
+export function renderCodexValidationAdequacyPrompt() {
+    return `# Codex Gate: validation-adequacy
+
+Review whether the reviewer report provides enough validation evidence for the task to continue toward docs sync or final acceptance.
+
+## Required Evidence
+
+- \`../../CLAUDE.md\`
+- \`../../.claude/agents/reviewer.md\`
+- \`../../.ai/vcm/handoffs/architecture-plan.md\`
+- \`../../.ai/vcm/handoffs/review-report.md\`
+- \`../../docs/TESTING.md\`
+- \`../../.ai/generated/module-index.json\`
+- \`../../.ai/generated/public-surface.json\`
+
+## Task
+
+Check validation adequacy against the VCM Codex Reviewer rules in \`AGENTS.md\`.
+
+Write exactly one Markdown report:
+
+\`\`\`text
+../vcm/codex-reviews/validation-adequacy-review.md
+\`\`\`
+
+The report decision must be exactly \`approve\` or \`request_changes\`.
+Do not modify any other file.`;
+}
+export function renderCodexFinalDiffPrompt() {
+    return `# Codex Gate: final-diff
+
+Review whether the final task diff is ready for PR preparation.
+
+## Required Evidence
+
+- \`../../CLAUDE.md\`
+- \`../../.claude/agents/architect.md\`
+- \`../../.claude/agents/coder.md\`
+- \`../../.claude/agents/reviewer.md\`
+- \`../../.ai/vcm/handoffs/architecture-plan.md\`
+- \`../../.ai/vcm/handoffs/review-report.md\`
+- \`../../.ai/vcm/handoffs/docs-sync-report.md\`
+- \`../../.ai/vcm/handoffs/final-acceptance.md\`
+- current git status and diff from \`../..\`
+- \`../../.ai/generated/module-index.json\`
+- \`../../.ai/generated/public-surface.json\`
+
+## Task
+
+Check the final diff against the VCM Codex Reviewer rules in \`AGENTS.md\`.
+
+Write exactly one Markdown report:
+
+\`\`\`text
+../vcm/codex-reviews/final-diff-review.md
+\`\`\`
+
+The report decision must be exactly \`approve\` or \`request_changes\`.
+Do not modify any other file.`;
+}
+export function renderCodexReviewResultSchema() {
+    return `{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "VCM Codex Review Result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["gate", "decision", "summary", "findings", "inputsReviewed"],
+  "properties": {
+    "gate": {
+      "type": "string",
+      "enum": ["architecture-plan", "validation-adequacy", "final-diff"]
+    },
+    "decision": {
+      "type": "string",
+      "enum": ["approve", "request_changes"]
+    },
+    "summary": {
+      "type": "string"
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "title", "evidence", "expected", "gap", "risk"],
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": ["critical", "high", "medium", "low"]
+          },
+          "title": {
+            "type": "string"
+          },
+          "file": {
+            "type": "string"
+          },
+          "line": {
+            "type": "integer",
+            "minimum": 1
+          },
+          "evidence": {
+            "type": "string"
+          },
+          "expected": {
+            "type": "string"
+          },
+          "gap": {
+            "type": "string"
+          },
+          "risk": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "residualRisks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": []
+    },
+    "inputsReviewed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}`;
+}
+export function renderVcmCodexReviewGateSkillRules() {
+    return `## Purpose
+
+Use this skill when project-manager reaches a VCM Codex Review Gate or receives a VCM Codex Review callback.
+
+## Trigger Points
+
+- \`architecture-plan\`: after architect writes \`.ai/vcm/handoffs/architecture-plan.md\`, before coder dispatch.
+- \`validation-adequacy\`: after reviewer writes \`.ai/vcm/handoffs/review-report.md\`, before docs sync or final acceptance.
+- \`final-diff\`: after final acceptance evidence is ready, before PR preparation.
+
+## Request
+
+Run:
+
+\`\`\`sh
+.ai/tools/request-codex-review --gate <architecture-plan|validation-adequacy|final-diff>
+\`\`\`
+
+Interpret the first output line:
+
+- \`disabled\`, \`not_required\`, \`already_approved\`: continue the normal VCM flow.
+- \`started\` or \`running\`: stop this turn and wait for the VCM callback.
+- \`failed_to_start\`: report the failure to the user.
+
+Do not run \`codex exec\` yourself. VCM owns the Codex adapter and gate state.
+
+## Callback
+
+When VCM sends \`[VCM CODEX REVIEW CALLBACK]\`, read the named report path.
+
+- \`approve\`: continue to the next normal VCM gate.
+- \`request_changes\`: summarize the findings and route follow-up through the responsible VCM role.
+- \`failed\`: stop and ask the user to retry, skip, or override in VCM.
+- \`skipped\` or \`overridden\`: record the exception reason in PM context and continue only as appropriate.
+
+Do not ask Codex Reviewer to choose owners, fixes, Replan, or user-intervention needs. PM routes those decisions through normal VCM responsibilities.`;
+}
+export function renderRequestCodexReviewTool() {
+    return `#!/usr/bin/env python3
+"""Request a VCM-managed Codex Review Gate."""
+import argparse
+import hashlib
+import json
+import os
+import subprocess
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    tomllib = None
+
+
+GATES = ("architecture-plan", "validation-adequacy", "final-diff")
+REPORTS = {
+    "architecture-plan": ".ai/vcm/codex-reviews/architecture-plan-review.md",
+    "validation-adequacy": ".ai/vcm/codex-reviews/validation-adequacy-review.md",
+    "final-diff": ".ai/vcm/codex-reviews/final-diff-review.md",
+}
+SOURCE_ARTIFACTS = {
+    "architecture-plan": [".ai/vcm/handoffs/architecture-plan.md"],
+    "validation-adequacy": [
+        ".ai/vcm/handoffs/architecture-plan.md",
+        ".ai/vcm/handoffs/review-report.md",
+    ],
+    "final-diff": [
+        ".ai/vcm/handoffs/architecture-plan.md",
+        ".ai/vcm/handoffs/review-report.md",
+        ".ai/vcm/handoffs/docs-sync-report.md",
+        ".ai/vcm/handoffs/final-acceptance.md",
+    ],
+}
+
+
+def root_dir() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def print_result(status: str, **fields: str) -> None:
+    print(status)
+    for key, value in fields.items():
+        if value is not None:
+            print(f"{key}={value}")
+
+
+def call_vcm_api(gate: str) -> int | None:
+    base_url = os.environ.get("VCM_API_URL")
+    task_slug = os.environ.get("VCM_TASK_SLUG")
+    if not base_url or not task_slug:
+        return None
+
+    url = (
+        base_url.rstrip("/")
+        + "/api/tasks/"
+        + urllib.parse.quote(task_slug, safe="")
+        + "/codex-review/"
+        + urllib.parse.quote(gate, safe="")
+        + "/request"
+    )
+    request = urllib.request.Request(
+        url,
+        data=b"{}",
+        method="POST",
+        headers={"content-type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+    except urllib.error.HTTPError as error:
+        try:
+            payload = json.loads(error.read().decode("utf-8"))
+            reason = payload.get("error", {}).get("message", str(error))
+        except Exception:
+            reason = str(error)
+        print_result("failed_to_start", gate=gate, reason=reason)
+        return 2
+    except Exception as error:
+        print_result("failed_to_start", gate=gate, reason=str(error))
+        return 2
+
+    record = payload.get("record", {}) if isinstance(payload, dict) else {}
+    print_result(
+        payload.get("status", "failed_to_start"),
+        gate=gate,
+        request=record.get("requestPath"),
+        report=record.get("reportPath"),
+        message=payload.get("message"),
+    )
+    return 0
+
+
+def read_json(path: Path) -> dict:
+    try:
+        return json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {"version": 1, "enabled": False, "activeGate": None, "gates": {}}
+
+
+def write_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2, sort_keys=True) + "\\n")
+    tmp.replace(path)
+
+
+def load_config(root: Path) -> dict:
+    path = root / ".ai/codex/config.toml"
+    if not path.is_file() or tomllib is None:
+        return {}
+    return tomllib.loads(path.read_text())
+
+
+def codex_review_config(root: Path) -> dict:
+    config = load_config(root)
+    vcm = config.get("vcm", {})
+    review = vcm.get("codex_review", {}) if isinstance(vcm, dict) else {}
+    return review if isinstance(review, dict) else {}
+
+
+def command_output(root: Path, command: list[str]) -> bytes:
+    result = subprocess.run(
+        command,
+        cwd=root,
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+    )
+    return result.stdout if result.returncode == 0 else b""
+
+
+def input_hash(root: Path, gate: str) -> str:
+    digest = hashlib.sha256()
+    common = [
+        "CLAUDE.md",
+        ".ai/codex/AGENTS.md",
+        ".ai/codex/config.toml",
+        f".ai/codex/prompts/{gate}-gate.md",
+    ]
+    for relative in common + SOURCE_ARTIFACTS[gate]:
+        path = root / relative
+        digest.update(relative.encode())
+        if path.is_file():
+            digest.update(path.read_bytes())
+        else:
+            digest.update(b"<missing>")
+    if gate == "final-diff":
+        digest.update(command_output(root, ["git", "status", "--porcelain=v1"]))
+        digest.update(command_output(root, ["git", "diff", "--binary"]))
+        digest.update(command_output(root, ["git", "diff", "--cached", "--binary"]))
+    return digest.hexdigest()
+
+
+def request_id(gate: str) -> str:
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    return f"{stamp}-{gate}-{uuid.uuid4().hex[:8]}"
+
+
+def local_request(gate: str) -> int:
+    root = root_dir()
+    review_config = codex_review_config(root)
+    enabled = bool(review_config.get("enabled", False))
+    required = set(review_config.get("required_gates", []))
+    index_path = root / ".ai/vcm/codex-reviews/index.json"
+    index = read_json(index_path)
+    index.update({"version": 1, "enabled": enabled})
+    index.setdefault("gates", {})
+
+    if not enabled:
+        index["activeGate"] = None
+        write_json(index_path, index)
+        print_result("disabled", gate=gate)
+        return 0
+
+    if gate not in required:
+        gate_record = index["gates"].setdefault(gate, {})
+        gate_record.update({"required": False, "status": "not_required", "updatedAt": now_iso()})
+        write_json(index_path, index)
+        print_result("not_required", gate=gate)
+        return 0
+
+    current_hash = input_hash(root, gate)
+    gate_record = index["gates"].get(gate, {})
+    if (
+        gate_record.get("status") == "completed"
+        and gate_record.get("decision") == "approve"
+        and gate_record.get("inputHash") == current_hash
+    ):
+        print_result("already_approved", gate=gate, report=gate_record.get("reportPath", REPORTS[gate]))
+        return 0
+
+    rid = request_id(gate)
+    request_path = root / ".ai/vcm/codex-reviews/requests" / f"{rid}.json"
+    report_path = REPORTS[gate]
+    requested_at = now_iso()
+    write_json(request_path, {
+        "version": 1,
+        "requestId": rid,
+        "gate": gate,
+        "status": "requested",
+        "requestedAt": requested_at,
+        "inputHash": current_hash,
+        "reportPath": report_path,
+        "promptPath": f".ai/codex/prompts/{gate}-gate.md",
+    })
+
+    index["activeGate"] = gate
+    index["gates"][gate] = {
+        "gate": gate,
+        "required": True,
+        "status": "running",
+        "decision": None,
+        "reportPath": report_path,
+        "promptPath": f".ai/codex/prompts/{gate}-gate.md",
+        "inputHash": current_hash,
+        "requestId": rid,
+        "requestPath": request_path.relative_to(root).as_posix(),
+        "requestedAt": requested_at,
+        "updatedAt": requested_at,
+    }
+    write_json(index_path, index)
+    print_result("started", gate=gate, request=index["gates"][gate]["requestPath"], report=report_path)
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--gate", required=True, choices=GATES)
+    args = parser.parse_args()
+
+    expected_root = os.environ.get("VCM_TASK_REPO_ROOT")
+    if expected_root and Path(expected_root).resolve() != Path.cwd().resolve():
+        print_result("failed_to_start", gate=args.gate, reason="cwd does not match VCM_TASK_REPO_ROOT")
+        return 2
+
+    api_result = call_vcm_api(args.gate)
+    if api_result is not None:
+        return api_result
+    return local_request(args.gate)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
+`;
+}

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

@@ -54,6 +54,16 @@ export function renderProjectManagerHarnessRules() {
 - If a required artifact is missing, stale, blocked, or asks for a decision, route the issue to the responsible role or user.
 - Request architect post-review docs sync after reviewer completes.
 
+### Codex Review Gates
+
+- Use the \`vcm-codex-review-gate\` skill to request a gate review or handle a VCM Codex review callback.
+- If Codex gates are enabled, accept only \`approve\` or \`request_changes\`.
+- Before coder dispatch, request \`architecture-plan\`; on \`request_changes\`, route the report to architect.
+- Before docs sync or final acceptance, request \`validation-adequacy\`; on \`request_changes\`, route the report to reviewer.
+- Before PR preparation, request \`final-diff\`; on \`request_changes\`, route the report to architect for Debug Mode or Replan assessment.
+- Do not infer finding owners from Codex output; route only by gate type.
+- Record gate decision, report path, and any skip or override reason.
+
 ### Partial Role Results
 
 - Treat partial, blocked, or continuation-needed role results as incomplete gates.
@@ -65,8 +75,8 @@ export function renderProjectManagerHarnessRules() {
 ### Final Acceptance
 
 - Use the \`vcm-final-acceptance\` skill before declaring the task complete.
-- Start final acceptance only after reviewer and docs-sync gates pass or an explicit exception is approved.
-- Confirm required evidence exists: validation result, review decision, docs-sync decision, unresolved risks, known-issues disposition, and cleanup status.
+- Start final acceptance only after reviewer, required Codex gates, and docs-sync gates pass or an explicit exception is approved.
+- Confirm required evidence exists: validation result, review decision, required Codex gate decisions, docs-sync decision, unresolved risks, known-issues disposition, and cleanup status.
 - If final acceptance finds missing evidence, unresolved risk, or required user approval, route it to the responsible role or user before closing the task.
 
 ### PR Preparation
@@ -74,7 +84,7 @@ export function renderProjectManagerHarnessRules() {
 - Prepare or update a GitHub PR only after final acceptance passes.
 - Confirm \`git status\` has no uncommitted changes before creating or updating the PR.
 - Use \`.github/pull_request_template.md\` when present.
-- Fill the PR body from final acceptance, review report, docs-sync report, known-issues disposition, and commits.
+- Fill the PR body from final acceptance, review report, Codex gate reports when present, docs-sync report, known-issues disposition, and commits.
 - Do not perform technical review or validation during PR preparation; route missing evidence to the responsible role.
 - Create a draft PR by default unless the user requests a ready PR.
 

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

@@ -16,6 +16,7 @@ Read the relevant task evidence before deciding:
 - \`.ai/vcm/handoffs/review-report.md\` when reviewer validation was required
 - \`.ai/vcm/handoffs/docs-sync-report.md\` when durable docs could be affected
 - \`.ai/vcm/handoffs/known-issues.md\` when unresolved findings were recorded
+- \`.ai/vcm/codex-reviews/index.json\` and referenced Codex reports when Codex gates were required, skipped, or overridden
 - current \`git status\` and changed file list
 - relevant long-term docs only when needed to confirm that a docs-sync artifact exists and names the correct durable docs
 
@@ -27,6 +28,7 @@ Acceptable evidence must show:
 
 - architect plan or docs-sync decision when architecture, public contracts, durable docs, or known issues changed
 - reviewer decision and validation evidence when code, behavior, tests, or generated context changed
+- required Codex gate decisions, skip reasons, or override reasons when Codex gates were enabled
 - known-issues disposition when unresolved findings were recorded
 - explicit user approval for accepted high-risk decisions or intentionally skipped required gates
 
@@ -54,6 +56,7 @@ Check:
 - required handoff artifacts exist and are current
 - architecture plan completion, Replan, or architect follow-up decision is recorded
 - reviewer report records validation commands, results, skipped checks with reasons, and an acceptable decision
+- required Codex gates are approved, skipped with a recorded reason, or overridden with a recorded reason
 - docs-sync report records docs updated, docs intentionally left unchanged, or required follow-up
 - known issues are either resolved, promoted to durable docs by architect, or explicitly accepted
 - temporary task state is ready to clean after durable facts are promoted
@@ -69,7 +72,7 @@ Choose exactly one:
 - needs-docs-sync
 - blocked-by-user-decision
 
-Do not accept when required role evidence is missing, reviewer findings are unresolved, docs sync is missing for durable changes, known-issues disposition is missing, or unexplained high-risk files remain.
+Do not accept when required role evidence is missing, required Codex gate evidence is missing, reviewer findings are unresolved, docs sync is missing for durable changes, known-issues disposition is missing, or unexplained high-risk files remain.
 
 ## Output
 
@@ -106,6 +109,8 @@ accepted | accepted-with-known-risks | needs-coder-follow-up | needs-architect-r
 
 ## Review And Docs Sync
 
+## Codex Review Gates
+
 ## Cleanup Readiness
 
 ## Final User Summary

package/dist/shared/types/codex-review.js

@@ -0,0 +1,5 @@
+export const CODEX_REVIEW_GATES = [
+    "architecture-plan",
+    "validation-adequacy",
+    "final-diff"
+];