ultra-builder-pro-cli 0.5.3 → 0.7.0

package/skills/ultra-verify/SKILL.md

@@ -1,13 +1,13 @@
 ---
 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.
+description: Run independent two-model verification with the current host as primary and a read-only Codex advisor, then verify and synthesize the evidence.
 ---
 
-# Ultra Verify — Three-Way Verification
+# Ultra Verify — Independent Two-Model 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.
+claims, and owns the final answer. Codex is an untrusted read-only advisor. Use this workflow only
+when the user explicitly asks for cross-model verification.
 
 ## Modes
 
@@ -18,11 +18,11 @@ workflow only when the user explicitly asks for cross-model or three-way verific
 
 ## Preconditions
 
-1. Confirm `gemini --version` and `codex --version` plus authentication.
+1. Confirm `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.
+4. Track four steps in the current host plan: primary analysis, advisor launch, completion wait,
+   and verified synthesis.
 
 ## 1. Create the session and write the primary view
 
@@ -33,25 +33,11 @@ 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.
+reading the advisor output. Record the mode, checkout, scope, and evidence boundary.
 
-## 2. Launch both advisors read-only
+## 2. Launch the advisor 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:
+Give the advisor the bounded raw question and evidence without the primary conclusion.
 
 ```bash
 codex exec -s read-only \
@@ -60,10 +46,9 @@ codex exec -s read-only \
   2> "${SESSION_PATH}/codex-error.log"
 ```
 
-Never enable auto-edit, write-capable automation, danger-full-access, or permission bypass for
-either advisor.
+Never enable write-capable automation, danger-full-access, or permission bypass for the advisor.
 
-## 3. Wait for completed outputs
+## 3. Wait for completed output
 
 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.
@@ -73,28 +58,26 @@ 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.
+The waiter reports the advisor as `complete`, `failed`, `empty`, or `pending`. Read the output only
+after its status is `complete` and the file is non-empty. Preserve the error log when it fails.
 
 ## 4. Verify and synthesize
 
-Compare `claude-analysis.md` with each completed advisor output:
+Compare `claude-analysis.md` with `codex-output.md`:
 
 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.
+2. Separate verified agreement, useful dissent, and unsupported assertions.
+3. Explain scope, version, and assumption differences before judging the result.
 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.
+Use `references/confidence-system.md` for evidence-based confidence and
+`references/cross-verify-modes.md` for mode-specific 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
+- Advisor failure: return the primary analysis with an explicit single-source warning.
+- Never block the underlying user task solely because the advisor is absent, unauthenticated, or
   slow.
 
 ## Session files
@@ -102,8 +85,6 @@ overrides failing tests or authoritative runtime evidence.
 ```text
 .ultra/collab/<SESSION_ID>/
   claude-analysis.md
-  gemini-output.md
-  gemini-error.log
   codex-output.md
   codex-error.log
   metadata.json

package/skills/ultra-verify/evals/evals.json

@@ -4,47 +4,45 @@
     {
       "id": 1,
       "prompt": "/ultra-verify decision 'Should we use PostgreSQL or MongoDB for our new microservice?'",
-      "expected_output": "Claude answers first, then launches Gemini and Codex in parallel, collects all three analyses, and presents a synthesis with consensus scoring",
+      "expected_output": "Claude writes its analysis first, launches Codex read-only, verifies both analyses, and returns one evidence-backed synthesis",
       "assertions": [
-        "Claude writes its own analysis BEFORE reading external AI output",
-        "Launches Gemini and Codex in parallel (run_in_background)",
-        "Creates session directory under .ultra/collab/ with verify-decision in name",
-        "Reads all three output files with Read tool",
-        "Presents confidence level (consensus/majority/no consensus)",
-        "Includes per-AI recommendation summary and trade-off matrix"
+        "Claude writes its own analysis before reading advisor output",
+        "Launches Codex with a read-only sandbox",
+        "Creates a session directory under .ultra/collab/",
+        "Verifies consequential claims against authoritative evidence",
+        "Separates verified agreement, useful dissent, and unsupported assertions"
       ]
     },
     {
       "id": 2,
-      "prompt": "/ultra-verify diagnose 'API returns 500 intermittently under load, logs show connection pool exhaustion'",
-      "expected_output": "Three sets of hypotheses collected and ranked by consensus count",
+      "prompt": "/ultra-verify diagnose 'API returns 500 intermittently under load'",
+      "expected_output": "Independent hypotheses are reconciled through discriminating checks and evidence strength",
       "assertions": [
-        "Each AI provides top-3 hypotheses",
-        "Hypotheses ranked by consensus count (3/3 > 2/3 > 1/3)",
-        "Each hypothesis includes evidence and verification steps",
-        "Recommended investigation order based on consensus"
+        "Both analyses provide ranked hypotheses",
+        "Duplicate hypotheses are merged by root cause",
+        "Each retained hypothesis includes a verification step",
+        "Investigation order follows evidence strength and verification cost"
       ]
     },
     {
       "id": 3,
       "prompt": "/ultra-verify audit",
-      "expected_output": "Three-way code audit with findings graded by consensus (3=critical, 2=high, 1=investigate)",
+      "expected_output": "Findings are deduplicated and verified against the current checkout without vote-based severity",
       "assertions": [
-        "Sends same audit prompt to all three AIs",
-        "Findings graded by how many AIs found them",
-        "3/3 findings marked Critical, 2/3 marked High, 1/3 marked Investigate",
-        "Action items prioritized by consensus count"
+        "Uses the same scope and severity model for both analyses",
+        "Verifies every reported location",
+        "Retains uniquely reported findings when source evidence confirms them",
+        "Severity does not depend on model agreement"
       ]
     },
     {
       "id": 4,
-      "prompt": "/ultra-verify estimate 'Implement OAuth2 login with Google and GitHub providers'",
-      "expected_output": "Three effort estimates compared for convergence",
+      "prompt": "/ultra-verify estimate 'Implement OAuth2 login with two providers'",
+      "expected_output": "Two estimates are reconciled by scope, assumptions, dependencies, and risk",
       "assertions": [
-        "Each AI provides estimate with breakdown and assumptions",
-        "Convergence analysis (within 20% = high confidence)",
-        "Outlier estimates investigated",
-        "Final recommended estimate with confidence level"
+        "Both analyses include work breakdowns and assumptions",
+        "Large differences are explained rather than averaged mechanically",
+        "Final range is supported by the reconciled work breakdown"
       ]
     }
   ]

package/skills/ultra-verify/references/confidence-system.md

@@ -1,38 +1,21 @@
-# Confidence System
+# Evidence-Based Confidence
 
-Confidence scoring based on AI consensus for cross-verify results.
+Cross-model agreement is a signal, not an authority. Assign confidence only after checking claims
+against source code, tests, runtime output, or primary documentation.
 
 ## Levels
 
-### Consensus (3/3 Agree)
-- **Confidence**: Highest
-- **Action**: Strongly recommended — proceed with high confidence
-- **Display**: `[CONSENSUS 3/3]`
+- **Verified agreement**: both analyses agree and the consequential claims have authoritative
+  supporting evidence.
+- **Resolved dissent**: the analyses differ, but current evidence supports one position and explains
+  the disagreement.
+- **Unresolved**: available evidence cannot distinguish the positions or key assumptions remain
+  untested.
+- **Single source**: the advisor failed or returned no usable output; no cross-model corroboration is
+  available.
 
-### Majority (2/3 Agree)
-- **Confidence**: High
-- **Action**: Recommended — investigate the dissenting view for edge cases or alternative perspectives
-- **Display**: `[MAJORITY 2/3]` + note which AI dissented and why
+## Reporting
 
-### No Consensus (All Differ)
-- **Confidence**: Low
-- **Action**: Decompose the problem into smaller questions, gather more data, or accept that the answer is genuinely ambiguous
-- **Display**: `[NO CONSENSUS]` + summary of each position
-
-## Application by Mode
-
-| Mode | Consensus | Majority | No Consensus |
-|------|-----------|----------|--------------|
-| decision | Strong recommendation | Recommended + dissent analysis | Present all options, suggest decomposition |
-| diagnose | Investigate first | Investigate second | Check all, may need more data |
-| audit | Critical — fix now | High — likely real | Investigate — may be false positive |
-| estimate | Use average, high confidence | Investigate outlier | Decompose task further |
-
-## Degraded Confidence
-
-When only 2 AIs respond (one failed):
-
-- **2/2 Agree**: Equivalent to Majority (not Consensus — missing perspective)
-- **2/2 Differ**: Low confidence — note missing third opinion
-
-When only 1 AI responds: Claude-only analysis — explicitly mark as single-source, no consensus scoring.
+Record which claims were verified, the evidence used, useful dissent, unsupported assertions, and
+remaining uncertainty. Model agreement never upgrades a claim contradicted by tests or runtime
+evidence, and a uniquely reported finding remains valid when independently verified.

package/skills/ultra-verify/references/cross-verify-modes.md

@@ -1,73 +1,28 @@
 # Ultra Verify Modes
 
-Four modes for three-way AI verification. All modes follow the safe orchestration contract in the parent `SKILL.md`.
+All four modes compare an independently written primary analysis with one read-only external
+advisor. Agreement is useful corroboration, not proof; evidence decides the final result.
 
 ## 1. Decision (`decision`)
 
-For architecture decisions, technology choices, or design trade-offs.
-
-**Flow:**
-1. Present the decision context, constraints, and options to all three AIs independently
-2. Each AI provides: recommendation, pros/cons, risks, trade-offs
-3. Synthesis ranks options by consensus:
-   - 3/3 recommend same → **Strong recommendation**
-   - 2/3 agree → **Recommended** with dissenting view analyzed
-   - All different → Present all three with trade-off matrix
-
-**Output structure:**
-- Per-AI recommendation summary
-- Consensus matrix (which AI recommends what)
-- Trade-off analysis
-- Final recommendation with confidence level
+Give both analyses the same decision context, constraints, and options. Compare recommendation,
+trade-offs, risks, and assumptions. When they differ, identify the assumption or evidence that
+caused the split and resolve it before recommending an option.
 
 ## 2. Diagnose (`diagnose`)
 
-For bug diagnosis, root cause analysis, or troubleshooting.
-
-**Flow:**
-1. Provide symptoms, error messages, relevant code, and recent changes to all three AIs
-2. Each AI provides its top-3 hypotheses with evidence and verification steps
-3. Synthesis:
-   - Hypotheses appearing in 3/3 lists → **Most likely** (investigate first)
-   - Hypotheses in 2/3 lists → **Probable** (investigate second)
-   - Unique hypotheses → **Worth checking** (may catch edge cases)
-
-**Output structure:**
-- Ranked hypothesis list (by consensus count)
-- Per-hypothesis: description, evidence, verification steps, suggested fix
-- Recommended investigation order
+Provide symptoms, exact errors, relevant code, and recent changes. Each analysis should rank its
+root-cause hypotheses and provide discriminating checks. Merge duplicate hypotheses, retain useful
+unique ones, and order investigation by evidence strength and verification cost.
 
 ## 3. Audit (`audit`)
 
-For code review, security audit, or quality assessment.
-
-**Flow:**
-1. Provide the code scope to all three AIs with the same audit prompt
-2. Each AI reports findings with severity and location
-3. Synthesis grades findings by consensus:
-   - Found by 3/3 → **Critical** — fix immediately
-   - Found by 2/3 → **High** — likely real, investigate
-   - Found by 1/3 → **Investigate** — may be false positive or edge case
-
-**Output structure:**
-- Findings table: description, severity, consensus count, which AIs found it
-- Grouped by consensus level (Critical → High → Investigate)
-- Action items prioritized by consensus
+Use the same code scope and severity model for both analyses. Deduplicate findings by root cause,
+verify every location against the current checkout, and retain a single-model finding when source
+evidence confirms it. Never derive severity from model agreement alone.
 
 ## 4. Estimate (`estimate`)
 
-For effort estimation, complexity assessment, or timeline planning.
-
-**Flow:**
-1. Describe the task, requirements, and constraints to all three AIs
-2. Each AI provides: estimate (time/effort), breakdown, assumptions, risks
-3. Synthesis evaluates convergence:
-   - All within 20% of each other → **High confidence** estimate (use average)
-   - One outlier → **Moderate confidence** — investigate the outlier's reasoning
-   - All significantly different → **Low confidence** — task needs decomposition
-
-**Output structure:**
-- Per-AI estimate with breakdown and assumptions
-- Convergence analysis
-- Recommended estimate with confidence level
-- Risk factors that could shift the estimate
+Require a breakdown, assumptions, dependencies, and risk range from both analyses. Explain large
+differences by locating mismatched scope or assumptions. Return a range supported by the reconciled
+work breakdown rather than averaging estimates mechanically.

package/skills/ultra-verify/scripts/verify_wait.py

@@ -1,23 +1,8 @@
 #!/usr/bin/env python3
-"""Verify Wait - File-based completion waiter for /ultra-verify pipeline.
+"""File-based completion waiter for the Ultra Verify advisor.
 
-Polls the session directory for expected AI output files.
-Blocks until both AIs produce output OR timeout. Returns structured JSON on stdout.
-
-Two exit conditions only:
-    1. Both AIs have output (non-empty + stable size) → exit 0, status="complete"
-    2. Timeout → exit 0, status="timeout" (JSON status field tells the story)
-
-Expected files:
-    - gemini-output.md  (Gemini)
-    - codex-output.md   (Codex)
-
-Usage:
-    python3 verify_wait.py <session_path> [--timeout SECONDS]
-
-Exit codes:
-    0 - Always (result expressed via JSON status field)
-    2 - Invalid arguments (missing path, bad --timeout)
+Poll the session directory until the expected output is non-empty and stable, or until timeout.
+The JSON result carries the operational status; timeout is not a process error.
 """
 
 import json
@@ -25,106 +10,84 @@ import sys
 import time
 from pathlib import Path
 
-POLL_INTERVAL = 3  # seconds
-DEFAULT_TIMEOUT = 1200  # 20 min — runs via run_in_background (no Bash 600s limit)
-
-# Each AI produces exactly one output file
-EXPECTED = {
-    "gemini": "gemini-output.md",
-    "codex": "codex-output.md",
-}
+POLL_INTERVAL = 3
+DEFAULT_TIMEOUT = 1200
+ADVISOR = "codex"
+OUTPUT_FILE = "codex-output.md"
 
 
 def _file_size(path: Path) -> int:
-    """Return file size in bytes, or -1 if not found."""
     try:
         return path.stat().st_size
     except (FileNotFoundError, OSError):
         return -1
 
 
-def _check_output(session_path: Path, name: str) -> dict:
-    """Check if an AI has produced non-empty output."""
-    output = session_path / EXPECTED[name]
+def _check_output(session_path: Path) -> dict:
+    output = session_path / OUTPUT_FILE
     if _file_size(output) > 0:
-        return {"name": name, "status": "complete", "file": str(output)}
-    return {"name": name, "status": "pending", "file": None}
+        return {"name": ADVISOR, "status": "complete", "file": str(output)}
+    return {"name": ADVISOR, "status": "pending", "file": None}
 
 
-def _timeout_status(session_path: Path, name: str) -> dict:
-    """Determine final status at timeout. Check error logs and empty files."""
-    output = session_path / EXPECTED[name]
-    error = session_path / f"{name}-error.log"
+def _timeout_status(session_path: Path) -> dict:
+    output = session_path / OUTPUT_FILE
+    error = session_path / f"{ADVISOR}-error.log"
     output_size = _file_size(output)
     if output_size > 0:
-        return {"name": name, "status": "complete", "file": str(output)}
+        return {"name": ADVISOR, "status": "complete", "file": str(output)}
     if _file_size(error) > 0:
-        return {"name": name, "status": "failed", "file": str(error)}
+        return {"name": ADVISOR, "status": "failed", "file": str(error)}
     if output_size == 0:
-        return {"name": name, "status": "empty", "file": str(output)}
-    return {"name": name, "status": "pending", "file": None}
+        return {"name": ADVISOR, "status": "empty", "file": str(output)}
+    return {"name": ADVISOR, "status": "pending", "file": None}
 
 
-def main():
+def main() -> None:
     if len(sys.argv) < 2:
         print(__doc__, file=sys.stderr)
         sys.exit(2)
 
     session_path = Path(sys.argv[1])
     timeout = DEFAULT_TIMEOUT
-
     if "--timeout" in sys.argv:
         idx = sys.argv.index("--timeout")
-        if idx + 1 < len(sys.argv):
-            try:
-                timeout = int(sys.argv[idx + 1])
-            except ValueError:
-                print(f"Error: --timeout must be integer: {sys.argv[idx + 1]}", file=sys.stderr)
-                sys.exit(2)
+        if idx + 1 >= len(sys.argv):
+            print("Error: --timeout requires an integer", file=sys.stderr)
+            sys.exit(2)
+        try:
+            timeout = int(sys.argv[idx + 1])
+        except ValueError:
+            print(f"Error: --timeout must be integer: {sys.argv[idx + 1]}", file=sys.stderr)
+            sys.exit(2)
+        if timeout < 0:
+            print("Error: --timeout must be non-negative", file=sys.stderr)
+            sys.exit(2)
 
     if not session_path.is_dir():
         print(f"Error: session directory not found: {session_path}", file=sys.stderr)
         sys.exit(2)
 
     deadline = time.monotonic() + timeout
-    prev_sizes = {name: _file_size(session_path / f) for name, f in EXPECTED.items()}
-
-    # Poll loop — exit condition 1: both outputs ready + stable
+    previous_size = _file_size(session_path / OUTPUT_FILE)
     while time.monotonic() < deadline:
-        cur_sizes = {name: _file_size(session_path / f) for name, f in EXPECTED.items()}
-        gemini = _check_output(session_path, "gemini")
-        codex = _check_output(session_path, "codex")
-
-        gemini_done = gemini["status"] == "complete" and cur_sizes["gemini"] == prev_sizes["gemini"]
-        codex_done = codex["status"] == "complete" and cur_sizes["codex"] == prev_sizes["codex"]
-
-        if gemini_done and codex_done:
+        current_size = _file_size(session_path / OUTPUT_FILE)
+        advisor = _check_output(session_path)
+        stable = advisor["status"] == "complete" and current_size == previous_size
+        if stable:
             elapsed = int(timeout - (deadline - time.monotonic()))
-            print(json.dumps({"status": "complete", "gemini": gemini, "codex": codex, "elapsed_seconds": elapsed}))
-            sys.exit(0)
-
-        prev_sizes = cur_sizes
-
-        # Progress display
-        remaining = int(deadline - time.monotonic())
-        parts = []
-        for name, done, result in [("gemini", gemini_done, gemini), ("codex", codex_done, codex)]:
-            if done:
-                parts.append(f"{name}:complete")
-            elif result["status"] == "complete":
-                parts.append(f"{name}:stabilizing")
-            else:
-                parts.append(f"{name}:waiting")
-        done_count = int(gemini_done) + int(codex_done)
-        sys.stderr.write(f"\r  [{done_count}/2] {' | '.join(parts)} ({remaining}s remaining)  ")
+            print(json.dumps({"status": "complete", ADVISOR: advisor, "elapsed_seconds": elapsed}))
+            return
+
+        state = "stabilizing" if advisor["status"] == "complete" else "waiting"
+        remaining = max(0, int(deadline - time.monotonic()))
+        sys.stderr.write(f"\r  [0/1] {ADVISOR}:{state} ({remaining}s remaining)  ")
         sys.stderr.flush()
+        previous_size = current_size
         time.sleep(POLL_INTERVAL)
 
-    # Exit condition 2: timeout — check error logs NOW for final status
-    gemini = _timeout_status(session_path, "gemini")
-    codex = _timeout_status(session_path, "codex")
-    print(json.dumps({"status": "timeout", "gemini": gemini, "codex": codex, "elapsed_seconds": timeout}))
-    sys.exit(0)
+    advisor = _timeout_status(session_path)
+    print(json.dumps({"status": "timeout", ADVISOR: advisor, "elapsed_seconds": timeout}))
 
 
 if __name__ == "__main__":

package/spec/cli-protocol.md

@@ -100,13 +100,24 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `session.admission_check` | `session admission`         | 4.5   | any     |
 | `session.heartbeat`       | `session heartbeat`         | 4.5   | mcp     |
 | `session.subscribe_events`| `session subscribe`         | 4.5   | any     |
+| `change.create`           | `change create`             | 9     | mcp     |
+| `change.update`           | `change update`             | 9     | mcp     |
+| `change.get`              | `change get`                | 9     | any     |
+| `change.list`             | `change list`               | 9     | any     |
+| `change.context`          | `change context`            | 9     | mcp     |
+| `change.converge`         | `change converge`           | 9     | mcp     |
+| `change.archive`          | `change archive`            | 9     | mcp     |
+| `system.doctor`           | `system doctor`             | 9     | mcp     |
 | `plan.export`             | `plan export`               | 8a    | mcp     |
 | `plan.get`                | `plan get`                  | 8a    | any     |
 
 Current executable maintenance surfaces are `task init-project`,
 `session close|get|list|admission|heartbeat|subscribe|reap`, `status`, `db`,
 `migrate`, and `legacy-memory`. In particular, `task create|update|list|get`
-are not CLI fallbacks. The full access policy lives in
+and all `change` lifecycle verbs are not CLI fallbacks. Change state must use
+the live MCP server; `system doctor` may additionally be exposed by the
+maintenance CLI because it is the recovery path when MCP startup is degraded.
+The full access policy lives in
 `docs/STATE-DB-ACCESS-POLICY.md` (Phase 2.2 / R25).
 
 ## 6. Versioning