ultra-builder-pro-cli 0.5.0

package/skills/ultra-review/SKILL.md

@@ -0,0 +1,437 @@
+---
+name: ultra-review
+description: "Parallel code review orchestration with 6 specialized agents + coordinator. Zero context pollution - all output via JSON files."
+user-invocable: true
+---
+
+# /ultra-review - Ultra Review System
+
+Orchestrates parallel code review using specialized agents. All findings written to JSON files to prevent context window pollution.
+
+## Workflow Tracking (MANDATORY)
+
+**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
+
+## Usage
+
+```
+/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
+
+# 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
+
+# 4. Cleanup (see Lifecycle Management below)
+
+# 5. Detect diff scope (priority order)
+```
+
+**Scope resolution priority:**
+
+| 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) |
+
+**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"
+```
+
+**Range scope details** (`--range RANGE`):
+```bash
+git diff RANGE --name-only
+DIFF_RANGE="RANGE"
+```
+
+### Phase 2: Agent Selection
+
+Based on the mode argument and file classification:
+
+**Mode: `full` (default)**
+Select all applicable agents based on diff content:
+
+| 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:
+
+```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:**
+
+```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)
+
+## Delta Logic
+
+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)
+
+**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",
+      "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"
+    }
+  ]
+}
+```
+
+**Fields**:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Session directory name |
+| `branch` | Git branch at review time |
+| `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) |
+
+**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
+```

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

@@ -0,0 +1,127 @@
+# Ultra Review - Unified JSON Schema v1
+
+All review agents MUST output findings in this exact format. No deviations.
+
+## Schema
+
+```json
+{
+  "$schema": "ultra-review-findings-v1",
+  "agent": "<agent-name>",
+  "session": "<timestamp>-<branch>",
+  "timestamp": "<ISO 8601>",
+  "scope": {
+    "files_analyzed": ["src/foo.ts", "src/bar.ts"],
+    "total_lines_analyzed": 342,
+    "diff_only": true
+  },
+  "summary": {
+    "total_findings": 5,
+    "by_severity": { "P0": 1, "P1": 2, "P2": 1, "P3": 1 },
+    "verdict": "REQUEST_CHANGES"
+  },
+  "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,
+      "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"
+    }
+  ],
+  "positive_observations": [
+    "Clean separation between domain and infrastructure layers"
+  ],
+  "metadata": {
+    "duration_ms": 15000,
+    "model": "claude-opus-4-6",
+    "turns_used": 12
+  }
+}
+```
+
+## Field Definitions
+
+### Top-Level
+
+| 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 |
+
+### Finding Object
+
+| 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 |
+
+### Category Enum
+
+| 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 |
+
+### Verdict Rules
+
+| Condition | Verdict |
+|-----------|---------|
+| Any P0 finding | `REQUEST_CHANGES` |
+| P1 count > 3 | `REQUEST_CHANGES` |
+| P1 count > 0 | `COMMENT` |
+| No P0 or P1 | `APPROVE` |
+
+### 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 |
+
+## Output Rules
+
+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>"`

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

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""Review Verdict Update - Update SUMMARY.json and index.json after P0 fixes.
+
+Usage:
+    python3 review_verdict_update.py <session_path> [new_verdict]
+
+If new_verdict is omitted, recalculates from current P0/P1 counts in SUMMARY.json:
+  - P0 > 0 → REQUEST_CHANGES (no change)
+  - P1 > 3 → REQUEST_CHANGES (no change)
+  - P1 > 0 → COMMENT
+  - else → APPROVE
+
+Exit codes:
+    0 - Updated successfully
+    1 - Error (file not found, parse error, etc.)
+"""
+
+import json
+import sys
+from pathlib import Path
+
+
+def recalculate_verdict(data: dict) -> str:
+    """Recalculate verdict from finding counts."""
+    summary = data.get("summary", {})
+    by_severity = summary.get("by_severity", {})
+    p0 = by_severity.get("P0", 0)
+    p1 = by_severity.get("P1", 0)
+
+    if p0 > 0:
+        return "REQUEST_CHANGES"
+    if p1 > 3:
+        return "REQUEST_CHANGES"
+    if p1 > 0:
+        return "COMMENT"
+    return "APPROVE"
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__, file=sys.stderr)
+        sys.exit(1)
+
+    session_path = Path(sys.argv[1])
+    forced_verdict = sys.argv[2] if len(sys.argv) >= 3 else None
+
+    summary_file = session_path / "SUMMARY.json"
+    if not summary_file.exists():
+        print(f"Error: {summary_file} not found", file=sys.stderr)
+        sys.exit(1)
+
+    # Update SUMMARY.json
+    try:
+        data = json.loads(summary_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        print(f"Error reading SUMMARY.json: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    old_verdict = data.get("verdict", "UNKNOWN")
+
+    if forced_verdict:
+        new_verdict = forced_verdict
+    else:
+        new_verdict = recalculate_verdict(data)
+
+    if old_verdict == new_verdict:
+        print(f"Verdict unchanged: {old_verdict}")
+        sys.exit(0)
+
+    data["verdict"] = new_verdict
+    summary_file.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(f"SUMMARY.json: {old_verdict} → {new_verdict}")
+
+    # Update index.json
+    reviews_dir = session_path.parent
+    index_file = reviews_dir / "index.json"
+    session_id = session_path.name
+
+    if index_file.exists():
+        try:
+            index_data = json.loads(index_file.read_text(encoding="utf-8"))
+            for entry in index_data.get("sessions", []):
+                if entry.get("id") == session_id:
+                    entry["verdict"] = new_verdict
+                    # Update P0/P1 counts from summary
+                    by_sev = data.get("summary", {}).get("by_severity", {})
+                    entry["p0"] = by_sev.get("P0", 0)
+                    entry["p1"] = by_sev.get("P1", 0)
+                    break
+            index_file.write_text(json.dumps(index_data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            print(f"index.json: updated session {session_id}")
+        except (json.JSONDecodeError, OSError) as e:
+            print(f"Warning: failed to update index.json: {e}", file=sys.stderr)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()