ultra-builder-pro-cli 0.9.0 → 0.11.0

package/skills/ultra-review/references/unified-schema.md

@@ -1,127 +1,102 @@
-# Ultra Review - Unified JSON Schema v1
+# Review artifact contract
 
-All review agents MUST output findings in this exact format. No deviations.
+Use this contract for every specialist artifact. Write JSON to the assigned file and
+return only a one-line acknowledgement to the parent.
 
-## Schema
+## Specialist artifact
 
 ```json
 {
-  "$schema": "ultra-review-findings-v1",
-  "agent": "<agent-name>",
-  "session": "<timestamp>-<branch>",
-  "timestamp": "<ISO 8601>",
+  "$schema": "ultra-review-findings-v2",
+  "agent": "review-code",
+  "axis": "engineering_standards",
+  "session": "<session-id>",
+  "timestamp": "<ISO-8601>",
   "scope": {
-    "files_analyzed": ["src/foo.ts", "src/bar.ts"],
-    "total_lines_analyzed": 342,
+    "head": "<full-git-head>",
+    "range": "<diff-range>",
+    "files_analyzed": ["src/example.ts"],
     "diff_only": true
   },
-  "summary": {
-    "total_findings": 5,
-    "by_severity": { "P0": 1, "P1": 2, "P2": 1, "P3": 1 },
-    "verdict": "REQUEST_CHANGES"
-  },
+  "status": "complete",
   "findings": [
     {
-      "id": "<agent-name>-001",
-      "severity": "P0",
-      "confidence": 95,
-      "category": "security",
-      "subcategory": "injection",
-      "title": "SQL injection via string concatenation",
-      "file": "src/api/handler.ts",
-      "line": 45,
+      "id": "review-code-001",
+      "axis": "engineering_standards",
+      "severity": "P1",
+      "category": "correctness",
+      "title": "Retry path commits the same payment twice",
+      "file": "src/payments/retry.ts",
+      "line": 42,
       "line_end": 47,
-      "code_snippet": "const query = `SELECT * FROM users WHERE id = ${userId}`",
-      "description": "User-controlled input directly interpolated into SQL query string.",
-      "suggestion": "Use parameterized query: db.query('SELECT * FROM users WHERE id = $1', [userId])",
-      "claude_md_rule": "security.forbidden_patterns.sql_string_concat"
+      "trigger": "The provider times out after committing the first request.",
+      "impact": "A retry can create a duplicate charge.",
+      "evidence": "retryPayment calls charge() again without an idempotency key.",
+      "suggestion": "Persist and reuse one idempotency key for the operation."
     }
   ],
-  "positive_observations": [
-    "Clean separation between domain and infrastructure layers"
-  ],
-  "metadata": {
-    "duration_ms": 15000,
-    "model": "claude-opus-4-6",
-    "turns_used": 12
-  }
+  "positive_observations": [],
+  "limitations": []
 }
 ```
 
-## Field Definitions
-
-### Top-Level
+Use `axis: "spec_fidelity"` for the independent acceptance review and
+`axis: "engineering_standards"` for engineering specialists.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `$schema` | string | YES | Always `"ultra-review-findings-v1"` |
-| `agent` | string | YES | Agent name: `review-code`, `review-tests`, `review-errors`, `review-comments`, `review-design` |
-| `session` | string | YES | Session ID provided in the task prompt |
-| `timestamp` | string | YES | ISO 8601 timestamp when review completed |
-| `scope` | object | YES | What was analyzed |
-| `summary` | object | YES | Aggregate counts |
-| `findings` | array | YES | Individual findings (can be empty) |
-| `positive_observations` | array | YES | Good patterns found (can be empty) |
-| `metadata` | object | YES | Execution metadata |
+## Required finding fields
 
-### Finding Object
+Every finding needs a stable id, axis, severity, category, concise title, repository-
+relative file, tight line range, triggering condition, observable impact, source
+evidence, and smallest complete remediation.
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string | YES | Unique ID: `<agent-name>-<NNN>` (zero-padded 3 digits) |
-| `severity` | enum | YES | `P0` (critical), `P1` (high), `P2` (medium), `P3` (low) |
-| `confidence` | int | YES | 0-100. Only include findings with confidence >= 75 |
-| `category` | enum | YES | See Category Enum below |
-| `subcategory` | string | NO | Free-text refinement of category |
-| `title` | string | YES | One-line summary (max 80 chars) |
-| `file` | string | YES | Relative file path from repo root |
-| `line` | int | YES | Start line number |
-| `line_end` | int | NO | End line number (if multi-line) |
-| `code_snippet` | string | YES | Relevant code (max 5 lines) |
-| `description` | string | YES | Detailed explanation |
-| `suggestion` | string | YES | Concrete fix or recommendation |
-| `claude_md_rule` | string | NO | Reference to CLAUDE.md rule if applicable |
+Severity is impact-based:
 
-### Category Enum
+- P0: exploitable critical security issue, destructive data loss, or deterministic
+  critical outage;
+- P1: material correctness, authorization, reliability, or delivery failure;
+- P2: bounded defect or maintainability risk with a concrete cost;
+- P3: optional improvement that does not block the accepted outcome.
 
-| Value | Used By |
-|-------|---------|
-| `security` | review-code, review-errors |
-| `error-handling` | review-errors, review-code |
-| `code-quality` | review-code, review-design |
-| `test-quality` | review-tests |
-| `type-design` | review-design |
-| `comments` | review-comments |
-| `simplification` | review-design |
-| `performance` | review-code, review-design |
-| `architecture` | review-code, review-design |
-| `integration` | review-code |
-| `scope-drift` | review-code |
-| `spec-compliance` | review-code |
-| `forbidden-pattern` | review-code, review-tests, review-comments |
+Do not report a concern without a plausible execution path. Do not encode a style
+preference as a defect. Preserve the source specialist's severity during coordination.
 
-### Verdict Rules
+## Coordinator summary
 
-| Condition | Verdict |
-|-----------|---------|
-| Any P0 finding | `REQUEST_CHANGES` |
-| P1 count > 3 | `REQUEST_CHANGES` |
-| P1 count > 0 | `COMMENT` |
-| No P0 or P1 | `APPROVE` |
+`SUMMARY.json` contains:
 
-### Severity Mapping
-
-| Level | Name | Criteria | Action |
-|-------|------|----------|--------|
-| **P0** | Critical | Security vulnerability, data loss, correctness bug, empty catch block | Must block merge |
-| **P1** | High | Logic error, SOLID violation, performance regression, mock violation, catch returning null | Should fix before merge |
-| **P2** | Medium | Code smell, maintainability, deep nesting, optional chaining hiding errors | Fix or create follow-up |
-| **P3** | Low | Style, naming, minor suggestion, informational type quality notes | Optional |
+```json
+{
+  "$schema": "ultra-review-summary-v2",
+  "session": "<session-id>",
+  "head": "<full-git-head>",
+  "status": "complete",
+  "verdict": "REQUEST_CHANGES",
+  "axes": {
+    "spec_fidelity": {
+      "verdict": "PASS",
+      "evidence_refs": ["spec-fidelity.json"]
+    },
+    "engineering_standards": {
+      "verdict": "FAIL",
+      "evidence_refs": ["review-code.json", "review-tests.json"]
+    }
+  },
+  "workers": {
+    "completed": ["review-code", "review-tests"],
+    "failed": [],
+    "skipped": []
+  },
+  "findings": [],
+  "positive_observations": [],
+  "limitations": []
+}
+```
 
-## Output Rules
+The overall verdict is `APPROVE` only when both axes pass, artifacts are complete and
+current, and no P0 or P1 finding remains. Use `REQUEST_CHANGES` for a failed axis or
+blocking finding, and `INCOMPLETE` when required evidence or workers are missing.
+Each axis verdict is `PASS`, `FAIL`, or `INCOMPLETE`; the overall verdict is `APPROVE`,
+`REQUEST_CHANGES`, or `INCOMPLETE`.
 
-1. Write the JSON to the file path provided in the task prompt
-2. JSON MUST be valid - use `JSON.stringify` equivalent formatting
-3. Only report findings with confidence >= 75
-4. Do NOT output the JSON to the conversation - write it to the file only
-5. After writing the file, output a one-line summary: `"Wrote N findings (P0:X P1:X P2:X P3:X) to <filepath>"`
+Validate JSON before acknowledgement. Never paste full JSON or worker transcripts into
+the parent conversation.

package/skills/ultra-review/scripts/review_wait.py

@@ -1,88 +1,254 @@
 #!/usr/bin/env python3
-"""Review Wait - File-based completion waiter for /ultra-review pipeline.
-
-Polls the session directory for expected review JSON files and/or SUMMARY.json.
-Returns a one-line verdict on stdout. Blocks until complete or timeout.
+"""Wait for and validate Ultra review v2 artifacts.
 
 Usage:
-    python3 review_wait.py <session_path> agents <count>   # Wait for N review-*.json files
-    python3 review_wait.py <session_path> summary           # Wait for SUMMARY.json only
+    python3 review_wait.py <session_path> agents <artifact-stem> [<artifact-stem> ...]
+    python3 review_wait.py <session_path> summary
 
-Exit codes:
-    0 - All expected files found
-    1 - Timeout (default 5 minutes)
-    2 - Invalid arguments
+The agents mode validates the exact named JSON files. The summary mode validates the
+two-axis verdict contract. Timeout and poll intervals can be shortened in tests with
+UBP_REVIEW_WAIT_TIMEOUT and UBP_REVIEW_WAIT_POLL.
 """
 
-import glob
 import json
+import os
+import re
 import sys
 import time
 from pathlib import Path
 
-POLL_INTERVAL = 2  # seconds
-DEFAULT_TIMEOUT = 300  # 5 minutes
+FINDINGS_SCHEMA = "ultra-review-findings-v2"
+SUMMARY_SCHEMA = "ultra-review-summary-v2"
+AXES = {"spec_fidelity", "engineering_standards"}
+SEVERITIES = {"P0", "P1", "P2", "P3"}
+AXIS_VERDICTS = {"PASS", "FAIL", "INCOMPLETE"}
+OVERALL_VERDICTS = {"APPROVE", "REQUEST_CHANGES", "INCOMPLETE"}
+ARTIFACT_STEM = re.compile(r"^[a-z][a-z0-9-]*$")
+FINDING_FIELDS = {
+    "id", "axis", "severity", "category", "title", "file", "line", "trigger",
+    "impact", "evidence", "suggestion",
+}
+
+
+def env_seconds(name: str, default: float) -> float:
+    try:
+        value = float(os.environ.get(name, default))
+    except (TypeError, ValueError):
+        return default
+    return value if value > 0 else default
+
+
+DEFAULT_TIMEOUT = env_seconds("UBP_REVIEW_WAIT_TIMEOUT", 300.0)
+POLL_INTERVAL = env_seconds("UBP_REVIEW_WAIT_POLL", 2.0)
+
+
+def read_json(path: Path):
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        return None, f"unreadable JSON: {error}"
+    if not isinstance(data, dict):
+        return None, "top-level value must be an object"
+    return data, None
+
+
+def nonempty_string(value) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def validate_finding(finding, artifact_axis: str, seen_ids):
+    if not isinstance(finding, dict):
+        return "finding must be an object"
+    missing = sorted(FINDING_FIELDS - set(finding))
+    if missing:
+        return f"finding missing fields: {', '.join(missing)}"
+    if not nonempty_string(finding.get("id")):
+        return "finding id must be a non-empty string"
+    if finding["id"] in seen_ids:
+        return f"duplicate finding id: {finding['id']}"
+    seen_ids.add(finding["id"])
+    if finding.get("axis") != artifact_axis:
+        return "finding axis must match artifact axis"
+    if finding.get("severity") not in SEVERITIES:
+        return "finding severity must be P0, P1, P2, or P3"
+    for field in ["category", "title", "file", "trigger", "impact", "evidence", "suggestion"]:
+        if not nonempty_string(finding.get(field)):
+            return f"finding {field} must be a non-empty string"
+    if not isinstance(finding.get("line"), int) or finding["line"] < 1:
+        return "finding line must be a positive integer"
+    line_end = finding.get("line_end")
+    if line_end is not None and (not isinstance(line_end, int) or line_end < finding["line"]):
+        return "finding line_end must be at or after line"
+    return None
+
+
+def validate_specialist(data):
+    if data.get("$schema") != FINDINGS_SCHEMA:
+        return f"$schema must be {FINDINGS_SCHEMA}"
+    if not nonempty_string(data.get("agent")):
+        return "agent must be a non-empty string"
+    axis = data.get("axis")
+    if axis not in AXES:
+        return "axis must be spec_fidelity or engineering_standards"
+    for field in ["session", "timestamp"]:
+        if not nonempty_string(data.get(field)):
+            return f"{field} must be a non-empty string"
+    scope = data.get("scope")
+    if not isinstance(scope, dict):
+        return "scope must be an object"
+    for field in ["head", "range"]:
+        if not nonempty_string(scope.get(field)):
+            return f"scope.{field} must be a non-empty string"
+    if not isinstance(scope.get("files_analyzed"), list) or not all(
+        nonempty_string(item) for item in scope["files_analyzed"]
+    ):
+        return "scope.files_analyzed must be a string array"
+    if not isinstance(scope.get("diff_only"), bool):
+        return "scope.diff_only must be boolean"
+    if data.get("status") != "complete":
+        return "status must be complete"
+    findings = data.get("findings")
+    if not isinstance(findings, list):
+        return "findings must be an array"
+    seen_ids = set()
+    for finding in findings:
+        error = validate_finding(finding, axis, seen_ids)
+        if error:
+            return error
+    for field in ["positive_observations", "limitations"]:
+        if not isinstance(data.get(field), list):
+            return f"{field} must be an array"
+    return None
 
 
-def wait_for_agents(session_path: Path, expected_count: int, timeout: int) -> bool:
-    """Wait for expected_count review-*.json files to appear.
+def evaluate_artifacts(session_path: Path, expected):
+    done = []
+    missing = []
+    invalid = []
+    errors = {}
+    for stem in expected:
+        path = session_path / f"{stem}.json"
+        if not path.exists():
+            missing.append(stem)
+            continue
+        data, error = read_json(path)
+        if error is None:
+            error = validate_specialist(data)
+        if error:
+            invalid.append(stem)
+            errors[stem] = error
+        else:
+            done.append(stem)
+    return done, missing, invalid, errors
 
-    Returns structured JSON on stdout:
-    - status: "complete" (all agents) or "partial" (>=1 agent on timeout)
-    - agents_done / agents_missing: lists of agent names
-    - count: number of completed agents
 
-    Exit code: 0 if all complete OR partial (>=1), 1 if 0 agents.
-    """
-    all_agents = ["review-code", "review-tests", "review-errors",
-                  "review-design", "review-comments"]
+def wait_for_agents(session_path: Path, expected, timeout: float) -> bool:
     deadline = time.monotonic() + timeout
-    while time.monotonic() < deadline:
-        found = glob.glob(str(session_path / "review-*.json"))
-        if len(found) >= expected_count:
-            names = [Path(f).stem for f in sorted(found)]
-            result = {"status": "complete", "agents_done": names, "agents_missing": [], "count": len(found)}
-            print(json.dumps(result))
+    while True:
+        done, missing, invalid, errors = evaluate_artifacts(session_path, expected)
+        if len(done) == len(expected):
+            print(json.dumps({
+                "status": "complete",
+                "artifacts_done": done,
+                "artifacts_missing": [],
+                "artifacts_invalid": [],
+                "errors": {},
+                "count": len(done),
+            }, sort_keys=True))
             return True
-        remaining = int(deadline - time.monotonic())
-        sys.stderr.write(f"\r  Waiting: {len(found)}/{expected_count} ({remaining}s remaining)")
-        sys.stderr.flush()
-        time.sleep(POLL_INTERVAL)
-
-    # Timeout — report partial results as structured JSON
-    found = glob.glob(str(session_path / "review-*.json"))
-    found_names = [Path(f).stem for f in sorted(found)]
-    missing = [a for a in all_agents if a not in found_names]
-    result = {"status": "partial", "agents_done": found_names, "agents_missing": missing, "count": len(found)}
-    print(json.dumps(result))
-    return len(found) >= 1  # At least 1 agent = partial success
-
-
-def wait_for_summary(session_path: Path, timeout: int) -> bool:
-    """Wait for SUMMARY.json to appear."""
+        if time.monotonic() >= deadline:
+            print(json.dumps({
+                "status": "incomplete",
+                "artifacts_done": done,
+                "artifacts_missing": missing,
+                "artifacts_invalid": invalid,
+                "errors": errors,
+                "count": len(done),
+            }, sort_keys=True))
+            return False
+        time.sleep(min(POLL_INTERVAL, max(0.0, deadline - time.monotonic())))
+
+
+def expected_overall_verdict(data) -> str:
+    verdicts = {data["axes"][axis]["verdict"] for axis in AXES}
+    severities = {finding["severity"] for finding in data["findings"]}
+    if "INCOMPLETE" in verdicts:
+        return "INCOMPLETE"
+    if "FAIL" in verdicts or severities.intersection({"P0", "P1"}):
+        return "REQUEST_CHANGES"
+    return "APPROVE"
+
+
+def validate_summary(data):
+    if data.get("$schema") != SUMMARY_SCHEMA:
+        return f"$schema must be {SUMMARY_SCHEMA}"
+    for field in ["session", "head"]:
+        if not nonempty_string(data.get(field)):
+            return f"{field} must be a non-empty string"
+    if data.get("status") != "complete":
+        return "status must be complete"
+    if data.get("verdict") not in OVERALL_VERDICTS:
+        return "invalid overall verdict"
+    axes = data.get("axes")
+    if not isinstance(axes, dict) or set(axes) != AXES:
+        return "axes must contain exactly spec_fidelity and engineering_standards"
+    for axis in AXES:
+        item = axes[axis]
+        if not isinstance(item, dict) or item.get("verdict") not in AXIS_VERDICTS:
+            return f"invalid {axis} verdict"
+        refs = item.get("evidence_refs")
+        if not isinstance(refs, list) or not refs or not all(nonempty_string(ref) for ref in refs):
+            return f"{axis}.evidence_refs must be a non-empty string array"
+    workers = data.get("workers")
+    if not isinstance(workers, dict):
+        return "workers must be an object"
+    for field in ["completed", "failed", "skipped"]:
+        if not isinstance(workers.get(field), list):
+            return f"workers.{field} must be an array"
+    findings = data.get("findings")
+    if not isinstance(findings, list):
+        return "findings must be an array"
+    seen_ids = set()
+    for finding in findings:
+        axis = finding.get("axis") if isinstance(finding, dict) else None
+        if axis not in AXES:
+            return "summary finding has invalid axis"
+        error = validate_finding(finding, axis, seen_ids)
+        if error:
+            return error
+    for field in ["positive_observations", "limitations"]:
+        if not isinstance(data.get(field), list):
+            return f"{field} must be an array"
+    expected = expected_overall_verdict(data)
+    if data["verdict"] != expected:
+        return f"verdict {data['verdict']} conflicts with evidence; expected {expected}"
+    return None
+
+
+def wait_for_summary(session_path: Path, timeout: float) -> bool:
     summary_path = session_path / "SUMMARY.json"
     deadline = time.monotonic() + timeout
-    while time.monotonic() < deadline:
-        if summary_path.exists() and summary_path.stat().st_size > 0:
-            try:
-                data = json.loads(summary_path.read_text(encoding="utf-8"))
-                verdict = data.get("verdict", "UNKNOWN")
-                p0 = data.get("p0", 0)
-                p1 = data.get("p1", 0)
-                total = data.get("total", 0)
-                print(f"Review complete: {verdict} (P0:{p0} P1:{p1} total:{total})")
+    last_error = "SUMMARY.json is missing"
+    while True:
+        if summary_path.exists():
+            data, error = read_json(summary_path)
+            if error is None:
+                error = validate_summary(data)
+            if error is None:
+                counts = {severity: 0 for severity in sorted(SEVERITIES)}
+                for finding in data["findings"]:
+                    counts[finding["severity"]] += 1
+                print(
+                    f"Review complete: {data['verdict']} "
+                    f"(P0:{counts['P0']} P1:{counts['P1']} P2:{counts['P2']} "
+                    f"P3:{counts['P3']} total:{len(data['findings'])})"
+                )
                 return True
-            except (json.JSONDecodeError, KeyError):
-                pass  # File still being written
-        remaining = int(deadline - time.monotonic())
-        print(
-            f"\r  Waiting for coordinator ({remaining}s remaining)",
-            end="", flush=True
-        )
-        time.sleep(POLL_INTERVAL)
-
-    print("\nTimeout: coordinator did not produce SUMMARY.json")
-    return False
+            last_error = error
+        if time.monotonic() >= deadline:
+            print(json.dumps({"status": "incomplete", "error": last_error}, sort_keys=True))
+            return False
+        time.sleep(min(POLL_INTERVAL, max(0.0, deadline - time.monotonic())))
 
 
 def main():
@@ -92,28 +258,27 @@ def main():
 
     session_path = Path(sys.argv[1])
     mode = sys.argv[2]
-
     if not session_path.is_dir():
         print(f"Error: session directory not found: {session_path}", file=sys.stderr)
         sys.exit(2)
 
-    timeout = DEFAULT_TIMEOUT
-
     if mode == "agents":
-        if len(sys.argv) < 4:
-            print("Error: agents mode requires <count> argument", file=sys.stderr)
+        expected = sys.argv[3:]
+        if not expected or len(expected) != len(set(expected)) or not all(
+            ARTIFACT_STEM.fullmatch(stem) for stem in expected
+        ):
+            print("Error: agents mode requires unique safe artifact stems", file=sys.stderr)
             sys.exit(2)
-        expected = int(sys.argv[3])
-        ok = wait_for_agents(session_path, expected, timeout)
-        sys.exit(0 if ok else 1)
-
+        ok = wait_for_agents(session_path, expected, DEFAULT_TIMEOUT)
     elif mode == "summary":
-        ok = wait_for_summary(session_path, timeout)
-        sys.exit(0 if ok else 1)
-
+        if len(sys.argv) != 3:
+            print("Error: summary mode accepts no additional arguments", file=sys.stderr)
+            sys.exit(2)
+        ok = wait_for_summary(session_path, DEFAULT_TIMEOUT)
     else:
         print(f"Error: unknown mode '{mode}'. Use 'agents' or 'summary'.", file=sys.stderr)
         sys.exit(2)
+    sys.exit(0 if ok else 1)
 
 
 if __name__ == "__main__":