ultra-builder-pro-cli 0.8.1 → 0.10.0

package/skills/ultra-review/SKILL.md

@@ -1,453 +1,125 @@
 ---
 name: ultra-review
-description: "Parallel code review orchestration with 6 specialized agents + coordinator. Zero context pollution - all output via JSON files."
+description: "Run two independent review axes over one current diff, using bounded specialist workers and file-based evidence without context pollution."
 user-invocable: true
 runtime: all
 mcp_tools_required:
   - change.list
+  - change.get
+  - change.context
+  - change.breadcrumb
   - task.list
 ---
 
 # /ultra-review - Ultra Review System
 
-Orchestrates parallel code review using specialized agents. All findings written to JSON files to prevent context window pollution.
+Review one explicit diff at the current HEAD. The top-level gates are independent:
 
-## Workflow Tracking (MANDATORY)
+1. `spec_fidelity`: does the implementation satisfy intent, acceptance, delta,
+   documentation impact, and public seam?
+2. `engineering_standards`: is the implementation correct, safe, maintainable,
+   tested, observable, and recoverable?
 
-**On command start**, create tasks for each major step using `TaskCreate`:
-
-| Step | Subject | activeForm |
-|------|---------|------------|
-| 1 | Setup & Scope Detection | Detecting diff scope... |
-| 2 | Agent Selection | Selecting review agents... |
-| 3 | Background Execution | Running review agents... |
-| 4 | Wait & Coordinate | Waiting for agent results... |
-| 5 | Report to User | Generating review report... |
-
-**Before each step**: `TaskUpdate` → `status: "in_progress"`
-**After each step**: `TaskUpdate` → `status: "completed"`
-**On context recovery**: `TaskList` → resume from last incomplete step
+One axis cannot compensate for the other. The coordinator may deduplicate the same
+root cause but must preserve each source finding's severity, confidence, file/line,
+and axis; it may not silently downgrade or rerank findings.
 
 ## Usage
 
+```text
+/ultra-review              # applicable specialists
+/ultra-review all          # all five specialists; delivery gate
+/ultra-review quick        # review-code only
+/ultra-review security     # review-code + review-errors
+/ultra-review tests        # review-tests only
+/ultra-review recheck      # unresolved P0/P1 scope
+/ultra-review delta        # files changed since last review
+/ultra-review --range <range> | --pr <number>
 ```
-/ultra-review              # Full review (smart skip based on diff content)
-/ultra-review all          # Force ALL 6 agents, no auto-skip (pre-merge gate)
-/ultra-review quick        # Quick review (review-code only)
-/ultra-review security     # Security focus (review-code + review-errors)
-/ultra-review tests        # Test quality focus (review-tests only)
-/ultra-review recheck      # Re-check only P0/P1 files from last session
-/ultra-review delta        # Review only changes since last review session
-/ultra-review <agents...>  # Custom: e.g., /ultra-review tests errors types
-```
-
-### Scope Options (combinable with any mode)
-
-```
-/ultra-review --pr 123            # Review PR #123 diff (base...head)
-/ultra-review --range main..HEAD  # Review specific commit range
-/ultra-review --range abc123      # Review single commit
-/ultra-review security --pr 42    # Security review scoped to PR #42
-```
-
-## Orchestration Flow
-
-### Phase 1: Setup & Scope Detection
-
-```python
-# 1. Determine session context
-BRANCH = git branch --show-current            # e.g., "feat/task-3-auth"
-ITER = count existing sessions matching this branch + 1  # iteration number
-CHANGE_ID = active change whose linked tasks/diff match this scope, else null
-
-# 2. Create session directory with full context
-SESSION_ID = "<YYYYMMDD-HHmmss>-<branch>-iter<N>"
-# e.g., "20260214-103000-feat-task-3-auth-iter2"
-SESSION_PATH = ".ultra/reviews/{SESSION_ID}/"
-mkdir -p SESSION_PATH
 
-# 3. Update session index (placeholder — verdict filled in Phase 5)
-# Append entry to .ultra/reviews/index.json with verdict="pending"
-# See Session Index below for full schema
+## Phase 1: Scope and Context
 
-# 4. Cleanup (see Lifecycle Management below)
+1. Resolve one diff range and `DIFF_FILES`. Include staged and unstaged changes for
+   default working-tree review.
+2. Bind to the single matching change through `change.list`/`task.list`; require an
+   explicit id if ambiguous.
+3. Compile `change.context` with `role=review`, `gate=review`, spec/delta/test refs,
+   current diff paths, and the public-seam execution contract.
+4. Stop on stale HEAD, blocked readiness, empty scope, or missing acceptance evidence.
+5. Create `.ultra/reviews/<session-id>/` and an index entry with reviewed HEAD,
+   change id, mode, range, and `verdict=pending`.
 
-# 5. Detect diff scope (priority order)
-```
+The spec-fidelity axis reads only the bounded intent/delta/baseline/acceptance packet;
+the engineering axis reads the bounded diff and test evidence. Do not load unrelated
+project history or external provider payloads.
 
-**Scope resolution priority:**
+## Phase 2: Specialist Selection
 
-| Flag | Diff Command | DIFF_RANGE |
-|------|-------------|------------|
-| `--pr NUMBER` | `gh pr diff NUMBER --name-only` | PR base...head |
-| `--range RANGE` | `git diff RANGE --name-only` | Specified range |
-| _(default)_ | `git diff --name-only HEAD` + `git diff --cached --name-only` | HEAD (unstaged + staged) |
+Five engineering specialists feed the two-axis result:
 
-**PR scope details** (`--pr NUMBER`):
-```bash
-# Get PR metadata for session naming
-gh pr view NUMBER --json headRefName,baseRefName,title
-# Get changed files
-gh pr diff NUMBER --name-only
-# Set DIFF_RANGE to base...head for agents
-DIFF_RANGE="$(gh pr view NUMBER --json baseRefName -q .baseRefName)..HEAD"
-```
+| Worker | Scope |
+|---|---|
+| `review-code` | correctness, security, live-path reachability |
+| `review-tests` | meaningful coverage, mocks, red/green evidence |
+| `review-errors` | swallowed failures, recovery, observability |
+| `review-design` | types, boundaries, complexity, coupling |
+| `review-comments` | stale or misleading comments/docs |
 
-**Range scope details** (`--range RANGE`):
-```bash
-git diff RANGE --name-only
-DIFF_RANGE="RANGE"
-```
+`all` always runs all five. Other modes may skip a worker only when its scope is
+provably absent, and the skip reason is written to the session. Spec fidelity is never
+skipped for a change-linked review.
 
-**Continuous-change linkage**:
+## Phase 3: Background Execution (Zero Context Pollution)
 
-Call `change.list` and `task.list`, then bind the review to the single active or
-blocked change whose linked task files intersect `DIFF_FILES`. If multiple
-changes match, require an explicit scope instead of guessing. Write
-`change_id` and reviewed HEAD into `SUMMARY.json` and the session index so
-`/ultra-deliver` can use this artifact as review evidence. Initial-baseline
-reviews may use `change_id: null`.
+Launch selected workers in background mode using multiple Task tool calls in a single
+message when the current host supports it. Each bounded worker must:
 
-### Phase 2: Agent Selection
+1. read its installed worker instructions;
+2. inspect only `DIFF_FILES`, `DIFF_RANGE`, and supplied role context;
+3. write `{SESSION_PATH}/{worker}.json` following
+   `$CLAUDE_PLUGIN_ROOT/skills/ultra-review/references/unified-schema.md`;
+4. return at most 12 findings with confidence >= 75, ordered by its own severity;
+5. output only a one-line file acknowledgement after the artifact exists.
 
-Based on the mode argument and file classification:
+Do not copy worker transcripts into the parent context. Findings flow through files.
 
-**Mode: `full` (default)**
-Select all applicable agents based on diff content:
+## Phase 4: Wait & Coordinate (File-Based)
 
-| Agent | Skip Condition | Warning |
-|-------|---------------|---------|
-| review-code | Never skip | - |
-| review-tests | No test files in diff AND no source files without tests | WARN: "Code changed without test updates" |
-| review-errors | No error handling code detected | - |
-| review-design | No type definitions AND no function-level changes in diff | - |
-| review-comments | No comment changes in diff | - |
-
-**Auto-skip detection commands:**
-```bash
-# Has type definitions?
-grep -l "interface \|type \|class \|enum " <diff_files>
-
-# Has comment changes?
-git diff HEAD -- <diff_files> | grep "^[+-].*//\|^[+-].*\*\|^[+-].*#"
-
-# Has test files?
-echo "<diff_files>" | grep -E "\.(test|spec)\.(ts|tsx|js|jsx)$|test_.*\.py$|.*_test\.go$"
-
-# Has error handling?
-grep -l "try\|catch\|\.catch\|throw\|Error(" <diff_files>
-```
-
-**Mode: `all`** → Force ALL 6 agents, no auto-skip. Use for pre-merge gates (`/ultra-dev`).
-**Mode: `quick`** → review-code only
-**Mode: `security`** → review-code + review-errors
-**Mode: `tests`** → review-tests only
-**Mode: `recheck`** → See Recheck Logic below
-**Mode: `delta`** → See Delta Logic below
-**Mode: custom** → Parse agent names from arguments
-
-### Phase 3: Background Execution (Zero Context Pollution)
-
-Launch ALL selected agents in **background mode** (`run_in_background: true`) using multiple Task tool calls in a single message. This prevents agent output from polluting the main conversation context.
-
-Each agent receives this prompt template:
-
-```
-You are running as part of /ultra-review pipeline.
-
-SESSION_PATH: {SESSION_PATH}
-OUTPUT_FILE: {agent-name}.json
-DIFF_FILES: {comma-separated file list}
-DIFF_RANGE: {resolved DIFF_RANGE from Phase 1}
-
-Review the changed files and write your findings as JSON to:
-{SESSION_PATH}/{agent-name}.json
-
-Follow the ultra-review-findings-v1 schema exactly. Read the schema from:
-$CLAUDE_PLUGIN_ROOT/skills/ultra-review/references/unified-schema.md
-
-Only report findings with confidence >= 75.
-
-After writing the JSON file, output one line: "Wrote N findings (P0:X P1:X P2:X P3:X) to <filepath>"
-```
-
-**Important**: Use `subagent_type` matching the agent name (e.g., `review-code`, `review-tests`, etc.).
-
-**Important**: Set `run_in_background: true` on every Task call. Do NOT read TaskOutput — this avoids injecting agent results into main context.
-
-Maximum 12 findings per agent. If you find more, report only the top 12 by severity (P0 first),
-then confidence. Note total count in your output line: "Wrote 12/23 findings..."
-
-**CRITICAL PROHIBITION**: After launching background agents, you MUST:
-1. Call `review_wait.py` IMMEDIATELY — do NOT process idle notifications
-2. NEVER call TaskOutput for any review agent — their output goes to JSON files only
-3. Ignore all agent idle/completion messages between launch and wait script return
-4. The ONLY information path from agents is: wait script → Read SUMMARY.json
-
-Violation of these rules causes context overflow. The review agents write to files; you read from files.
-
-### Phase 4: Wait & Coordinate (File-Based)
-
-**Step 4a: Wait for agents** — Use Bash to block until all agents finish writing:
+Validate worker files:
 
 ```bash
 python3 "$CLAUDE_PLUGIN_ROOT/skills/ultra-review/scripts/review_wait.py" {SESSION_PATH} agents {AGENT_COUNT}
 ```
 
-This polls for `review-*.json` files every 2 seconds. Timeout: 5 minutes.
-Output is structured JSON on stdout:
-- `status: "complete"` → all agents done, proceed normally
-- `status: "partial"` → timeout, log missing agents, pass only `agents_done` to coordinator, note partial review in SUMMARY
-- Exit code 1 (0 agents) → skip review, warn user, allow ultra-dev to continue
-
-**Step 4b: Launch coordinator in background:**
-
-Launch review-coordinator with `run_in_background: true`:
-
-```
-You are the review coordinator.
-
-SESSION_PATH: {SESSION_PATH}
-AGENTS_RUN: {list of agents from wait output}
-
-Read all review-*.json files in the session directory, deduplicate findings,
-compute verdict, and generate SUMMARY.md + SUMMARY.json.
-```
-
-**Step 4c: Wait for coordinator:**
+Then run the installed `review-coordinator` over valid artifacts plus the independent
+spec-fidelity assessment. It writes `SUMMARY.json` and `SUMMARY.md`. Validate:
 
 ```bash
 python3 "$CLAUDE_PLUGIN_ROOT/skills/ultra-review/scripts/review_wait.py" {SESSION_PATH} summary
 ```
 
-Output is a single verdict line (~15 tokens).
-
-### Phase 5: Report to User
-
-After `review_wait.py summary` returns:
-
-1. **Read SUMMARY.json** (one Read call, ~500 tokens) to get verdict and counts
-2. **Update index.json** — fill in the placeholder entry with actual verdict, p0, p1, total from SUMMARY.json
-3. Present a concise summary:
-
-```markdown
-## Review Complete
-
-**Verdict**: {APPROVE | COMMENT | REQUEST_CHANGES}
-**Findings**: X total (P0: A, P1: B, P2: C, P3: D)
-**Agents**: N ran, M succeeded
-
-### Top Findings
-1. [P0] {title} - {file}:{line}
-2. [P1] {title} - {file}:{line}
-3. ...
-(show up to 5 most critical findings)
-
-Full report: {SESSION_PATH}/SUMMARY.md
-```
-
-Then ask the user:
-1. **Fix all** - Fix all P0 and P1 issues
-2. **Fix P0 only** - Fix only critical issues
-3. **View full report** - Read SUMMARY.md
-4. **Skip** - No fixes needed
-
-## Recheck Logic
-
-When mode is `recheck`:
-1. Find the most recent session **for the current branch** in `index.json`
-2. Read its `SUMMARY.json`
-3. Extract files with P0 or P1 findings
-4. Run review-code only on those specific files
-5. Compare with previous findings to show delta (resolved / new / unchanged)
+Partial worker completion is explicit. Zero valid worker files blocks the engineering
+axis. A coordinator may merge duplicate root causes but must retain source ids and the
+highest original severity/confidence without reinterpreting priorities.
 
-## Delta Logic
+## Phase 5: Report to User
 
-When mode is `delta`:
-1. Find the most recent session **for the current branch** in `index.json`
-2. Read its `SUMMARY.json` to get the scope of last review
-3. Identify files changed since the last review:
-   ```bash
-   # If last session was commit-based, diff from that commit
-   git diff --name-only <last-reviewed-commit>..HEAD
-   # If last session was working-tree-based, diff current unstaged + staged
-   git diff --name-only HEAD
-   ```
-4. **Exclude** files that have NOT changed since last review (already reviewed)
-5. Run full agent set only on the newly changed files
-6. In coordinator, merge with previous session findings (carry forward unresolved P0/P1)
+`SUMMARY.json` must contain:
 
-**Use case**: Iterative development — fix issues, add code, only review what's new.
-
-## Session Index
-
-A lightweight index file tracks all sessions for cross-referencing:
-
-**File**: `.ultra/reviews/index.json`
-
-```json
-{
-  "sessions": [
-    {
-      "id": "20260214-103000-feat-task-3-auth-iter1",
-      "branch": "feat/task-3-auth",
-      "change_id": "auth-change",
-      "iteration": 1,
-      "mode": "full",
-      "timestamp": "2026-02-14T10:30:00Z",
-      "verdict": "REQUEST_CHANGES",
-      "p0": 2,
-      "p1": 3,
-      "total": 12,
-      "parent": null
-    },
-    {
-      "id": "20260214-113000-feat-task-3-auth-iter2",
-      "branch": "feat/task-3-auth",
-      "iteration": 2,
-      "mode": "recheck",
-      "timestamp": "2026-02-14T11:30:00Z",
-      "verdict": "COMMENT",
-      "p0": 0,
-      "p1": 1,
-      "total": 4,
-      "parent": "20260214-103000-feat-task-3-auth-iter1"
-    }
-  ]
-}
-```
+- session/change id, reviewed HEAD/range, workers run/skipped;
+- `axes.spec_fidelity` and `axes.engineering_standards`, each with its own verdict and
+  evidence refs;
+- unchanged source findings with axis/source provenance;
+- overall verdict: `REQUEST_CHANGES` when either axis has P0/P1 or fails;
+- incomplete/partial status and exact rerun command.
 
-**Fields**:
+Report the two axis verdicts first, then P0/P1 findings and the report path. Fixes are a
+separate implementation action; review itself is read-only except for review artifacts.
+After fixes, use `recheck` or `delta` rather than rerunning unrelated scope.
 
-| Field | Description |
-|-------|-------------|
-| `id` | Session directory name |
-| `branch` | Git branch at review time |
-| `change_id` | Continuous change reviewed, or null for initial baseline |
-| `iteration` | Nth review for this branch (auto-incremented) |
-| `mode` | Review mode used (full/quick/security/recheck/delta) |
-| `timestamp` | ISO 8601 |
-| `verdict` | APPROVE / COMMENT / REQUEST_CHANGES |
-| `p0`, `p1`, `total` | Finding counts from SUMMARY.json |
-| `parent` | Previous session ID for this branch (forms iteration chain) |
+## Convergence handoff
 
-**Branch-scoped queries**:
-- `recheck` / `delta`: filter `index.json` by `branch == current branch`, take latest
-- Avoids cross-task pollution when multiple branches are active
-
-## Lifecycle Management
-
-**Cleanup strategy** (runs at Phase 1 of every `/ultra-review`):
-
-| Rule | Action |
-|------|--------|
-| Session > 7 days AND verdict = APPROVE | Delete directory + remove from index |
-| Session > 7 days AND verdict = COMMENT | Delete directory + remove from index |
-| Session > 7 days AND verdict = REQUEST_CHANGES | **Keep** (unresolved P0s should not be silently deleted) |
-| Session > 30 days (any verdict) | Delete directory + remove from index |
-| Per-branch limit: > 5 sessions | Delete oldest APPROVE/COMMENT sessions for that branch |
-
-**Implementation**:
-```python
-# In Phase 1, after creating session directory:
-index = read index.json (or create if missing)
-
-# 1. Remove stale sessions
-now = current_time()
-for session in index.sessions:
-    age_days = (now - session.timestamp).days
-    if age_days > 30:
-        delete(session)
-    elif age_days > 7 and session.verdict != 'REQUEST_CHANGES':
-        delete(session)
-
-# 2. Per-branch cap (keep latest 5)
-branch_sessions = [s for s in index.sessions if s.branch == current_branch]
-if len(branch_sessions) > 5:
-    # Sort by timestamp, keep latest 5, delete rest (except REQUEST_CHANGES)
-    to_remove = sorted(branch_sessions, key=timestamp)[:-5]
-    for s in to_remove:
-        if s.verdict != 'REQUEST_CHANGES':
-            delete(s)
-
-# 3. Write updated index
-write index.json
-```
-
-## Fix Flow
-
-When user selects "Fix all" or "Fix P0 only" after review:
-
-**Step 0: Context Reset** (if verdict is REQUEST_CHANGES):
-- Run `/compact` to clear TDD cycle history from context
-- After compact, read `.ultra/workflow-state.json` to restore task context
-- Read `SUMMARY.json` fresh to get actionable findings
-- Then proceed with fixes below
-
-1. **Read SUMMARY.json** — extract actionable P0/P1 items, sort by severity (P0 first)
-2. **Group by file** — organize findings per file
-3. **For each file with findings** (with circuit breaker tracking):
-   a. Read the file once
-   b. Apply ALL P0/P1 fixes for that file (batch within same file)
-   c. Run the RELEVANT test file only:
-      - Detect: `foo.ts` → `foo.test.ts` / `foo.spec.ts`
-      - Run: `npx jest <test-file> --bail` or `pytest <test-file> -x`
-   d. If test passes → mark findings as addressed, move to next file
-   e. If test fails from THIS fix → increment per-file failure counter, revert, try alternative approach
-   f. If test fails from pre-existing issue → note it, continue
-   g. **Circuit Breaker**: If same file has 3 consecutive fix failures (test fails after each attempt):
-      - Display: "Circuit breaker: {filename} — 3 consecutive fix failures. Likely architectural issue, not isolated bug."
-      - Use AskUserQuestion:
-        - A) "Skip this file, continue with others"
-        - B) "Manually inspect this file" (exit auto-fix, user takes over)
-        - C) "Abandon this fix round" (end fix flow, write UNRESOLVED.md)
-   h. **Global Circuit Breaker**: If 3+ files trigger per-file circuit breaker:
-      - Display: "Multiple files failing repeatedly — suggests systematic issue, not isolated bugs."
-      - Recommend ending fix flow, write all unresolved findings to UNRESOLVED.md with tag `ARCHITECTURAL_CONCERN`
-4. **After all files fixed**: run FULL test suite once as validation
-5. **Update verdict** — after all P0 fixes applied and tests pass:
-   ```bash
-   python3 "$CLAUDE_PLUGIN_ROOT/skills/ultra-review/scripts/review_verdict_update.py" {SESSION_PATH}
-   ```
-   This recalculates the verdict from current P0/P1 counts and updates both SUMMARY.json and index.json.
-   Without this step, pre_stop_check will block on stale REQUEST_CHANGES verdict.
-6. **Optionally**: `/ultra-review recheck` (counts as iteration, respects max 2 cap)
-
-**Important**: The main agent (not review agents) performs fixes. Review agents are read-only by design.
-
-## Integration with ultra-dev
-
-This skill integrates with the TDD workflow:
-- After `tdd-runner` confirms tests pass
-- Before `commit` or PR creation
-- Quick mode for iterative development
-- Full mode for pre-merge gate
-- Recheck mode after fixing review findings
-- Delta mode for incremental review during long development sessions
-
-## Error Handling
-
-- If no diff detected: inform user, suggest using `--range` or `--pr` to specify scope
-- If `--pr` fails (no gh CLI or no PR): fall back to default diff and warn user
-- If an agent fails to write JSON: note in coordinator input, skip that agent's findings
-- If coordinator fails: fall back to reading individual JSON files and presenting raw findings
-- If no agents selected (all skipped): inform user with skip reasons
-
-## Directory Structure
-
-```
-.ultra/reviews/
-  ├── index.json                                    # Session index (all sessions metadata)
-  ├── 20260214-103000-feat-task-3-auth-iter1/       # First review
-  │   ├── review-code.json
-  │   ├── review-tests.json
-  │   ├── review-errors.json
-  │   ├── review-design.json
-  │   ├── review-comments.json
-  │   ├── SUMMARY.json
-  │   └── SUMMARY.md
-  └── 20260214-113000-feat-task-3-auth-iter2/       # Recheck after fixes
-      ├── review-code.json
-      ├── SUMMARY.json
-      └── SUMMARY.md
-```
+At the final HEAD, recompile `change.context` with `role=review` and a next action of
+`Converge and deliver the verified change`. The delivery workflow must submit two
+separate `review` evidence rows: one with `axis=spec_fidelity`, one with
+`axis=engineering_standards`. A single aggregate “review passed” row is invalid.