ultra-builder-pro-cli 0.5.0

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

@@ -0,0 +1,120 @@
+#!/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.
+
+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
+
+Exit codes:
+    0 - All expected files found
+    1 - Timeout (default 5 minutes)
+    2 - Invalid arguments
+"""
+
+import glob
+import json
+import sys
+import time
+from pathlib import Path
+
+POLL_INTERVAL = 2  # seconds
+DEFAULT_TIMEOUT = 300  # 5 minutes
+
+
+def wait_for_agents(session_path: Path, expected_count: int, timeout: int) -> bool:
+    """Wait for expected_count review-*.json files to appear.
+
+    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"]
+    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))
+            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."""
+    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})")
+                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
+
+
+def main():
+    if len(sys.argv) < 3:
+        print(__doc__, file=sys.stderr)
+        sys.exit(2)
+
+    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)
+            sys.exit(2)
+        expected = int(sys.argv[3])
+        ok = wait_for_agents(session_path, expected, timeout)
+        sys.exit(0 if ok else 1)
+
+    elif mode == "summary":
+        ok = wait_for_summary(session_path, timeout)
+        sys.exit(0 if ok else 1)
+
+    else:
+        print(f"Error: unknown mode '{mode}'. Use 'agents' or 'summary'.", file=sys.stderr)
+        sys.exit(2)
+
+
+if __name__ == "__main__":
+    main()

package/skills/ultra-status/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: ultra-status
+description: "Real-time project status — progress, risk analysis, workflow routing. Reads task.list + session.list from state.db; reads test/delivery reports from files."
+runtime: all
+mcp_tools_required:
+  - task.list
+  - task.get
+  - session.list
+  - session.subscribe_events
+cli_fallback: "status --cost --json"
+---
+
+# ultra-status — Phase 3.6
+
+Single-call dashboard. Pulls task state from state.db (authoritative), layers
+in `.ultra/test-report.json` + `.ultra/delivery-report.json` (file artifacts),
+reports progress + risks + workflow routing.
+
+## Workflow
+
+### Phase 0 — Environment validation
+
+| Check | If missing |
+|-------|-----------|
+| `.ultra/tasks/tasks.json` projection present (or state.db reachable) | suggest `/ultra-init` |
+| At least one task visible via `task.list` | suggest `/ultra-plan` |
+| `task.list` returns valid rows | surface error |
+
+### Phase 1 — Load data
+
+```jsonc
+// MCP: task.list (no filter — get all tasks)
+{}
+// → { tasks: [...], count: N }
+
+// MCP: session.list (active sessions; Phase 4.5.4)
+{ "status": "running" }
+// → { sessions: [...], count: N }
+
+// MCP: session.subscribe_events (recent events for the "last event" panel)
+{ "since_id": 0, "limit": 20 }
+// → { events: [...], next_since_id: M }
+```
+
+**CLI fallback**: `ultra-tools task list` + `ultra-tools session list`.
+
+Also read:
+- `.ultra/test-report.json` — if present
+- `.ultra/delivery-report.json` — if present
+
+Extract:
+- Task stats: by status (`pending`/`in_progress`/`completed`/`blocked`), by priority (P0-P3)
+- Current `in_progress` task, next `pending` task (topological order)
+- Active sessions: count, per-runtime breakdown, orphan warnings
+- Most recent 20 events (by `events.id` DESC) — "last event" panel
+- Test passed / failed / stale (compare `git_commit` to HEAD)
+- Delivery readiness (tag + pushed)
+
+### Phase 2 — Progress report
+
+Compact multi-section output:
+- **Overview**: progress bar `[████░░░░] 50%`, completion %, velocity (completed tasks / elapsed days)
+- **Tasks**: counts per status + per priority
+- **Test**: pass/fail, `run_count`, `blocking_issues` if any
+- **Delivery**: `version` + `pushed` + last tag
+- **Risks**: auto-detected list (see Phase 3)
+- **Next**: recommended next task (see Phase 4)
+
+### Phase 3 — Risk detection
+
+Auto-detect:
+- **Blockers**: tasks with unsatisfied dependencies
+- **Stalled**: `in_progress` for >3 days (check `updated_at`)
+- **Overdue**: past `estimated_days` from when moved to `in_progress`
+- **Complexity spike**: 3+ consecutive `pending` tasks with complexity ≥7
+- **Test stale**: `test-report.json.git_commit ≠ HEAD`
+- **Orphan sessions**: any session with `lease_expires_at < now()` still status=running
+  (uninitialized by orphan-reaper; escalate)
+
+| Icon | Meaning | Action |
+|------|---------|--------|
+| 🟢 | on track | continue |
+| 🟡 | minor issues | review stalled |
+| 🟠 | significant risks | address blockers |
+| 🔴 | critical | stop and resolve |
+
+### Phase 4 — Next-task recommendation
+
+Select next optimal task by:
+1. Priority (P0 > P1 > P2 > P3)
+2. Dependencies resolved (only `pending` with all deps `completed`)
+3. Complexity sweet spot (prefer 3-5, avoid clustering 7+)
+4. Context continuity (favor same component as recent completed task)
+
+### Phase 5 — Workflow routing (▶ Next Up)
+
+Detect position from artifacts:
+
+| Condition | Route |
+|-----------|-------|
+| No `.ultra/` | `/ultra-init` |
+| Specs have `[NEEDS CLARIFICATION]` or missing | `/ultra-research` |
+| No tasks | `/ultra-plan` |
+| Any `pending` | `/ultra-dev` (show which) |
+| All `completed` | `/ultra-test` |
+| `test-report.json.passed === true` | `/ultra-deliver` |
+| `test-report.json.passed === false` | `/ultra-dev` (show blocking issues) |
+| `delivery-report.json` exists + fresh | Done; suggest next milestone |
+
+**Safety checks before routing**:
+- Routing to deliver but `test-report.git_commit ≠ HEAD` → warn "Tests stale"
+- `git status --porcelain` non-empty → warn "Uncommitted changes"
+
+**Output block**:
+```markdown
+---
+## ▶ Next Up
+**{command}** — {description}
+`/clear` then `/{command}`
+---
+**Also available**: `/{alt}` — {description}
+---
+```
+
+## Single-task mode (`$1` supplied)
+
+When `task-id` provided:
+```jsonc
+// MCP: task.get
+{ "id": "<id>" }
+```
+Display: title, status, priority, complexity, deps, files_modified (if set),
+session_id (if active), `context_file`, `trace_to`, stale flag, update history.
+
+## MCP → CLI fallback matrix
+
+| Purpose | MCP tool | CLI fallback |
+|---------|----------|--------------|
+| List tasks | `task.list` | `ultra-tools task list` |
+| Single task detail | `task.get` | `ultra-tools task get <id>` |
+| Cost panel (Phase 6.3) | — | `ultra-tools status --cost --json --since 7d` |
+
+## Cost panel (Phase 6.3)
+
+`ultra-tools status --cost --json` returns `{period, by_runtime, top_tasks,
+total_cost_usd}`. Render under the progress section when the user asks
+"how much did we spend?" or `/ultra-status --cost` is invoked. `--since 7d`
+is the conventional weekly window; override with ISO-8601 for custom ranges.
+
+## What this skill DOES NOT do
+
+- Does NOT modify state
+- Does NOT run tests / build / deploy
+- Does NOT require all artifacts (partial reports are tolerated)
+
+## Integration
+
+| | |
+|---|---|
+| **Input** | state.db (via `task.list`/`task.get`), `test-report.json`, `delivery-report.json`, git HEAD |
+| **Output** | console report (Chinese per project rule) |
+| **When** | anytime — idempotent read-only |

package/skills/ultra-test/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: ultra-test
+description: "Pre-delivery quality audit — Anti-Pattern + Coverage Gap + Wiring + E2E + Performance + Security. Writes .ultra/test-report.json; no state.db writes."
+runtime: all
+mcp_tools_required:
+  - task.list
+cli_fallback: "task list"
+---
+
+# ultra-test — Phase 3.5
+
+Project-level quality audit before `/ultra-deliver`. Auditors are orthogonal;
+each writes a JSON gate result; the skill aggregates into `.ultra/test-report.json`.
+This is **not** for running unit tests (that is `/ultra-dev`). This is the
+pre-ship gate.
+
+## Prerequisites
+
+- `task.list` returns ≥1 task with `status=completed`
+- Repo has test files (Step 0 pre-check)
+
+## Workflow
+
+### Step 0 — Pre-Execution
+
+1. Detect project type from config (`package.json` / `Cargo.toml` / `go.mod` / `pyproject.toml` / …)
+2. `task.list { status: "completed" }` → confirm ≥1 task delivered
+3. Find test files (suffix `.test.*`, `.spec.*`, `test_*.py`, `*_test.go`)
+
+Block with instructive error if any precheck fails.
+
+### Step 1 — Anti-Pattern Detection
+
+Detect fake / meaningless tests that waste CI time.
+
+| Pattern | Example | Severity |
+|---------|---------|----------|
+| Tautology | `assert True`, `expect(true).toBe(true)` | CRITICAL |
+| Empty test | function body is just `pass` / `{}` | CRITICAL |
+| Core-logic mock | `jest.mock()` on domain/service/state files | CRITICAL |
+
+Use Grep with language-appropriate regex; count matches per file.
+
+**Gate**: any CRITICAL match → fail.
+
+### Step 2 — Coverage Gap Analysis
+
+Find exported functions / classes with **zero** test references.
+
+1. Enumerate exports in `src/` (or language equivalent)
+2. For each symbol, grep test files for its name
+3. Bucket:
+   - HIGH: core business logic untested
+   - MEDIUM: utility untested
+   - LOW: config/constant untested
+
+**Output**: `.ultra/docs/test-coverage-gaps.md`
+**Gate**: any HIGH → fail.
+
+### Step 2.5 — Wiring Verification
+
+Detect orphan code — files that exist and pass tests but are not reachable.
+
+1. Enumerate exported symbols in source files
+2. For each export, grep **non-test** source for imports
+3. Report exports with 0 non-test imports as orphaned
+
+Also check boundary wiring:
+- Component → API (fetch/axios targets a real route)
+- API → DB (handler imports a real client)
+- Form → handler (onSubmit is not `() => {}`)
+- State → render (state appears in JSX/template)
+
+Stub detection (Level-2 substantive):
+- Functions returning empty `[]` / `{}` without real work
+- `console.log`-only bodies
+- Handlers calling only `e.preventDefault()`
+- Components returning only `<div>Placeholder</div>`
+
+**Output**: append to `test-coverage-gaps.md` under `## Wiring Gaps`.
+**Gate**: any HIGH orphan or stub → fail.
+
+### Step 3 — E2E Testing (conditional)
+
+**Trigger**: project has web UI or API endpoints.
+
+1. Start dev server (detect `scripts.dev` / `scripts.start`)
+2. Navigate key pages/endpoints
+3. Verify elements render; check console errors
+4. Exercise primary user flows
+
+**Method per runtime**:
+- Claude: `mcp__claude-in-chrome__*` or Playwright via Bash
+- Others: Playwright via `npx playwright` (CLI portable)
+
+**Gate**: critical pages fail / major errors → fail.
+
+### Step 4 — Performance (conditional, frontend only)
+
+Lighthouse on dev server. Core Web Vitals gates:
+- LCP < 2.5s
+- INP < 200ms
+- CLS < 0.1
+
+**Gate**: any metric above threshold → fail.
+
+### Step 5 — Security Audit
+
+Dependency vulnerability scan via project's native tool:
+- `npm audit --json` / `pnpm audit --json` / `yarn audit --json`
+- `cargo audit --json`
+- `pip-audit --format=json`
+- `govulncheck ./...`
+
+**Severity**:
+- Critical/High → fail
+- Medium → warn
+- Low → info
+
+### Step 6 — Auto-Fix Loop
+
+If any gate failed, loop (max 5 attempts):
+
+1. Read `blocking_issues`
+2. Fix what is fixable without user input:
+   - Coverage Gap → write missing tests
+   - Anti-Pattern → rewrite fake tests
+   - E2E error → fix the code
+   - Performance → code-level optimizations (lazy, splitting, memoization)
+3. External blockers (upstream CVE, breaking dep bump) → break, report, ask user
+4. If all gates pass → exit loop
+
+If max reached → surface remaining issues; `passed=false`.
+
+### Step 7 — Persist `.ultra/test-report.json`
+
+```jsonc
+{
+  "timestamp": "<ISO8601>",
+  "git_commit": "<HEAD>",
+  "passed": true,
+  "run_count": 1,
+  "gates": {
+    "anti_pattern":  { "passed": true, "critical": 0, "warning": 1 },
+    "coverage_gaps": { "passed": true, "high": 0, "medium": 3, "low": 5 },
+    "wiring":        { "passed": true, "orphans": 0, "stubs": 0 },
+    "e2e":           { "passed": true, "skipped": false },
+    "performance":   { "passed": true, "lcp": 1.8, "inp": 150, "cls": 0.05 },
+    "security":      { "passed": true, "critical": 0, "high": 0, "medium": 2 }
+  },
+  "blocking_issues": []
+}
+```
+
+Rules:
+- File exists → increment `run_count`
+- `passed = true` iff all gates `.passed === true`
+- `blocking_issues` lists human-readable strings for any fail
+
+### Step 8 — Report
+
+Print a compact summary (emoji-free, ≤20 lines). Suggest `/ultra-deliver` only
+when `passed=true`.
+
+## Quality Gates — summary
+
+| Gate | Requirement |
+|------|-------------|
+| Anti-Pattern | 0 critical |
+| Coverage Gaps | 0 HIGH |
+| Wiring | 0 HIGH orphan, 0 HIGH stub |
+| E2E | all flows pass (if applicable) |
+| Performance | all Core Web Vitals (if frontend) |
+| Security | 0 critical/high |
+
+## MCP → CLI fallback matrix
+
+| Purpose | MCP tool | CLI fallback |
+|---------|----------|--------------|
+| Confirm ≥1 completed task | `task.list { status: "completed" }` | `ultra-tools task list --status completed` |
+| Confirm risky auto-fix | none | current Host's native user-interaction surface |
+
+## What this skill DOES NOT do
+
+- Does NOT run unit tests (that is `/ultra-dev`)
+- Does NOT mutate state.db (auditing is read-only against state)
+- Does NOT release or tag (that is `/ultra-deliver`)
+
+## Integration
+
+| | |
+|---|---|
+| **Input** | Source + test files, state.db (read-only) |
+| **Output** | `.ultra/test-report.json`, `.ultra/docs/test-coverage-gaps.md` |
+| **Next** | `/ultra-deliver` (only when `passed=true`) |

package/skills/ultra-think/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: ultra-think
+description: "Deep analysis with adversarial reasoning — Evidence-First + Multi-Perspective + Steel-Man + Pre-Mortem + Sensitivity. Produces a recommendation with confidence bounds."
+runtime: all
+cli_fallback: "direct user interaction"
+---
+
+# ultra-think — Phase 3.6
+
+Reasoning harness for complex decisions / diagnostics / architecture calls.
+Enforces Evidence-First labelling and adversarial stress-tests before issuing
+a recommendation with explicit confidence.
+
+## Workflow
+
+### Step 1 — Scope Check
+
+If the problem is ambiguous / underspecified, ask up to **3** clarifying
+questions through the current Host's native user-interaction surface.
+If the problem is simple, **skip the framework**, answer concisely, and mark
+downstream steps `completed` with note `"skipped: simple answer path"`.
+
+### Step 2 — Evidence Gathering
+
+Every factual claim about tech/API/best-practices must be verified via:
+- Repo source (Read/Grep)
+- Official docs (Context7 MCP: `mcp__context7__query-docs`)
+- Community (Exa MCP: `mcp__exa__web_search_exa`)
+- Web search (fallback)
+
+Label each assertion:
+- **Fact** — verified, cite source (URL / file path)
+- **Inference** — deduced from facts (show the derivation chain)
+- **Speculation** — unverified; list verification steps the user can run
+
+**Iron law**: never trade accuracy for speed. Wrong-with-confidence > "I don't know + here's how to check".
+
+### Step 3 — Multi-Perspective Analysis
+
+Generate **≥3 distinct approaches**. For each, apply whichever lenses are relevant:
+- **Technical** — feasibility, scalability, security, maintainability
+- **Business** — value, cost, time-to-market, competitive advantage
+- **User** — needs, experience, edge cases, accessibility
+- **System** — integration, dependencies, emergent behaviors
+
+### Step 4 — Adversarial Stress-Testing
+
+Apply all four techniques:
+
+| Technique | Question |
+|-----------|----------|
+| **Steel Man** | For the option you're inclined to REJECT, build its strongest possible case. What do you discover? |
+| **Pre-Mortem** | Assume the recommended option has failed in 6 months. List the 3 most likely causes. |
+| **Sensitivity** | Which single assumption, if wrong, would reverse your recommendation? |
+| **Second-Order** | What new problems does the recommendation create 6-12 months out? |
+
+### Step 5 — Synthesis
+
+Recommendation with quantified confidence (0-100%) and explicit uncertainty bounds.
+
+## Output Structure (adapt to problem type)
+
+### Problem Statement
+1-2 sentences: core decision + key constraints.
+
+### Analysis
+Deep analysis using relevant lenses from Step 3.
+
+### Options Comparison (skip for diagnostic/investigative problems)
+| Criterion | Weight | Option A | Option B | Option C |
+|-----------|-------:|----------|----------|----------|
+Quantified where possible.
+
+### Adversarial Findings
+- **Strongest counter-argument** (steel man for rejected option)
+- **Pre-mortem top risk** (most likely failure + mitigation)
+- **Assumption sensitivity** (load-bearing assumption)
+
+### Recommendation
+- **Choice**: <option>
+- **Confidence**: <X>% because <rationale>
+- **Key Assumptions**: what must be true
+- **What would change my mind**: specific evidence / outcome
+
+### Verification Plan
+Concrete steps to validate the decision — metrics, tests, time-boxed experiments.
+
+### Next Steps
+Ordered, actionable items.
+
+## MCP → CLI fallback matrix
+
+| Purpose | MCP tool | CLI fallback |
+|---------|----------|--------------|
+| Clarifying questions | none | current Host's native user-interaction surface |
+
+## What this skill DOES NOT do
+
+- Does NOT modify state.db or project files
+- Does NOT implement the recommendation (that's `/ultra-dev` after `/ultra-plan`)
+- Does NOT replace independent review — output is one model's analysis
+
+## Integration
+
+| | |
+|---|---|
+| **Input** | the problem statement in `$ARGUMENTS`, optional repo context via Read/Grep, docs via Context7/Exa |
+| **Output** | structured Markdown report (Chinese per project rule) |
+| **Feeds** | decisions captured in `.ultra/specs/architecture.md` via Dual-Write Mode of `/ultra-dev` |

package/skills/ultra-verify/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: ultra-verify
+description: Run three-way verification with the current host as primary and read-only Gemini and Codex advisors, then verify and synthesize the evidence.
+---
+
+# Ultra Verify — Three-Way Verification
+
+Claude Code remains primary. It writes the first independent analysis, verifies consequential
+claims, and owns the final answer. Gemini and Codex are untrusted read-only advisors. Use this
+workflow only when the user explicitly asks for cross-model or three-way verification.
+
+## Modes
+
+- `decision <question>`: architecture or product decision.
+- `diagnose <symptoms>`: independent root-cause hypotheses.
+- `audit <scope>`: evidence-backed findings.
+- `estimate <task>`: estimates with explicit assumptions.
+
+## Preconditions
+
+1. Confirm `gemini --version` and `codex --version` plus authentication.
+2. Define the exact workspace, question, evidence standard, and response shape.
+3. Do not send secrets, unrelated files, or an unbounded home directory.
+4. Track the four workflow steps in the current host plan: primary analysis, advisor launch,
+   completion wait, and verified synthesis.
+
+## 1. Create the session and write the primary view
+
+```bash
+SESSION_ID="$(date +%Y%m%d-%H%M%S)-verify-<mode>"
+SESSION_PATH=".ultra/collab/${SESSION_ID}"
+mkdir -p "${SESSION_PATH}"
+```
+
+Write Claude Code's evidence-backed analysis to `${SESSION_PATH}/claude-analysis.md` before
+reading either advisor. Record the mode, checkout, scope, and evidence boundary.
+
+## 2. Launch both advisors read-only
+
+Give both advisors the same bounded raw question and evidence, without the primary conclusion.
+Launch them concurrently when the host supports independent shell sessions; otherwise start both
+before collecting either result.
+
+Gemini:
+
+```bash
+gemini --approval-mode plan \
+  --output-format text \
+  -p "<bounded prompt>" \
+  > "${SESSION_PATH}/gemini-output.md" \
+  2> "${SESSION_PATH}/gemini-error.log"
+```
+
+Codex:
+
+```bash
+codex exec -s read-only \
+  -o "${SESSION_PATH}/codex-output.md" \
+  "<bounded prompt>" \
+  2> "${SESSION_PATH}/codex-error.log"
+```
+
+Never enable auto-edit, write-capable automation, danger-full-access, or permission bypass for
+either advisor.
+
+## 3. Wait for completed outputs
+
+Run the bundled waiter in an asynchronous or yielded shell session and poll it at bounded
+intervals; never hold one blocking tool call longer than 60 seconds.
+
+```bash
+python3 "$CLAUDE_PLUGIN_ROOT/skills/ultra-verify/scripts/verify_wait.py" \
+  "${SESSION_PATH}" --timeout 1200
+```
+
+The waiter reports each advisor as `complete`, `failed`, `empty`, or `pending`. Read an advisor
+output only after the corresponding status is `complete` and the file is non-empty. Preserve its
+error log when it fails.
+
+## 4. Verify and synthesize
+
+Compare `claude-analysis.md` with each completed advisor output:
+
+1. Verify claims against the current checkout, tests, runtime, or primary documentation.
+2. Separate consensus, majority views, useful dissent, and unsupported assertions.
+3. Explain scope, version, and assumption differences before scoring agreement.
+4. Write `synthesis.md` and `metadata.json`, then return one Claude Code-owned conclusion.
+
+Use `references/confidence-system.md` for scoring and
+`references/cross-verify-modes.md` for mode-specific evidence expectations. Model agreement never
+overrides failing tests or authoritative runtime evidence.
+
+## Degraded operation
+
+- One advisor fails: continue with the primary view plus the available advisor and name the gap.
+- Both advisors fail: return primary-only analysis with an explicit single-source warning.
+- Never block the underlying user task solely because an advisor is absent, unauthenticated, or
+  slow.
+
+## Session files
+
+```text
+.ultra/collab/<SESSION_ID>/
+  claude-analysis.md
+  gemini-output.md
+  gemini-error.log
+  codex-output.md
+  codex-error.log
+  metadata.json
+  synthesis.md
+```