ultra-builder-pro-cli 0.10.0 → 0.11.0

package/skills/ultra-research/references/problem-product.md

@@ -0,0 +1,39 @@
+# Problem and product research
+
+Read this reference when the problem, value, market context, or product direction is
+uncertain.
+
+## Establish the problem
+
+- Identify the affected actor, current behavior, observable cost, and desired outcome.
+- Distinguish user evidence from stakeholder belief and solution preference.
+- Find current alternatives, including manual work or doing nothing.
+- State what evidence would disprove the problem framing.
+
+Use repository artifacts, support data, interviews, analytics, or primary external
+sources that actually exist. Do not invent quotes, demand, or market size.
+
+## Decide how much market work is needed
+
+Market sizing and competitive research are optional. Use them only when they affect a
+funding, positioning, pricing, or build-versus-buy decision.
+
+When needed:
+
+1. define the market boundary and time period;
+2. show the calculation inputs and sources;
+3. separate direct, adjacent, and substitute alternatives;
+4. explain how the evidence changes the product decision.
+
+Do not present unsourced top-down totals or call a category competitor-free.
+
+## Record the result
+
+Update the discovery specification with:
+
+- problem and affected actors;
+- observed evidence and source quality;
+- desired outcome and non-goals;
+- material alternatives and tradeoffs;
+- assumptions, validation method, and blocking questions;
+- the accepted product decision and why it follows from the evidence.

package/skills/ultra-research/references/quality-delivery.md

@@ -0,0 +1,34 @@
+# Quality and delivery research
+
+Read this reference when acceptance depends on operational risk, security, migration,
+deployment, recovery, or release constraints.
+
+## Risk-driven quality
+
+Identify failures that would materially affect users, data, authorization, money,
+availability, or recoverability. For each relevant risk, record:
+
+- trigger and affected boundary;
+- expected behavior and observable signal;
+- prevention, detection, and recovery;
+- verification method and owner.
+
+Apply security, performance, accessibility, and resilience checks according to the
+actual product surface. Do not impose generic categories or coverage percentages when
+they do not define acceptance.
+
+## Delivery path
+
+Capture the environments, configuration authority, migration order, compatibility
+window, health and readiness checks, observability, rollout, rollback, and operator
+actions needed for this product.
+
+Prefer existing repository and platform workflows. Add a new service, dependency, or
+deployment mechanism only when the accepted architecture requires it.
+
+## Record the result
+
+Update the architecture and product specifications with testable quality scenarios,
+delivery constraints, failure behavior, recovery evidence, and release acceptance.
+Keep exact volatile commands in the repository's runbook when they are operational
+procedure rather than durable architecture.

package/skills/ultra-research/references/synthesis.md

@@ -0,0 +1,38 @@
+# Baseline synthesis and validation
+
+Read this reference after the selected research lanes are complete.
+
+## Traceability check
+
+Verify that each accepted outcome has:
+
+1. supporting problem, user, or constraint evidence;
+2. an explicit decision and scope boundary;
+3. testable acceptance behavior;
+4. a compatible architecture or delivery path;
+5. a named unresolved blocker when any link is missing.
+
+Check the reverse direction as well: every proposed component, dependency, and quality
+requirement must support an accepted outcome or constraint.
+
+## Consistency check
+
+- Use one term for each actor, boundary, and authoritative data source.
+- Remove duplicate narratives and stale alternatives.
+- Keep source links next to the claims they support.
+- Separate durable decisions from volatile external facts.
+- Preserve explicit non-goals and rejected alternatives only when they prevent a
+  likely future mistake.
+
+## Handoff
+
+Report:
+
+- validated scope and decisive evidence;
+- specification files changed;
+- accepted decisions and material uncertainty;
+- blockers, or an explicit statement that none remain;
+- one next action.
+
+Do not create a parallel summary document solely for model consumption. The planning
+workflow should read the smallest authoritative baseline sections it needs.

package/skills/ultra-research/references/users-scope.md

@@ -0,0 +1,40 @@
+# Users, behavior, and scope
+
+Read this reference when actors, workflows, acceptance, boundaries, or success signals
+are unclear.
+
+## Actors and scenarios
+
+Model only actors supported by evidence. Prefer roles and jobs over fictional persona
+biographies. For each material scenario, capture:
+
+- trigger and preconditions;
+- actor goal;
+- main flow and system response;
+- important failure or recovery path;
+- observable completion signal.
+
+## Acceptance and scope
+
+Turn scenarios into testable behavior. Each requirement should name the observable
+outcome, relevant constraints, and how success can be verified.
+
+Define:
+
+- included behavior required for the accepted outcome;
+- explicit non-goals;
+- dependencies and assumptions;
+- deferred work only when a real sequencing decision exists.
+
+Avoid arbitrary release buckets or a fixed number of stories. Scope follows the
+validated outcome and delivery constraint.
+
+## Success signals
+
+Choose metrics only when they will guide a decision. Define the event, population,
+window, source, owner, and interpretation. Do not invent target values; record a
+baseline, a user-approved target, or the experiment needed to establish one.
+
+Update the product specification with actors, scenarios, acceptance, scope, non-goals,
+and decision-relevant success signals. Keep business facts in their source system and
+link them rather than copying volatile datasets into the specification.

package/skills/ultra-review/SKILL.md

@@ -1,125 +1,81 @@
 ---
 name: ultra-review
-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
+description: Run independent specification-fidelity and engineering reviews over one current diff using bounded workers and file-based evidence. Use when implementation needs a read-only review gate before task completion or delivery.
 ---
 
-# /ultra-review - Ultra Review System
+# Review one current diff
 
-Review one explicit diff at the current HEAD. The top-level gates are independent:
+Keep two verdict axes independent:
 
-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?
+1. `spec_fidelity`: intent, acceptance, delta, documentation impact, and public seam;
+2. `engineering_standards`: correctness, safety, maintainability, testing,
+   observability, and recovery.
 
-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.
+One axis cannot compensate for the other. Preserve each finding's source, severity,
+file and line, and axis during coordination.
 
-## Usage
+## Scope and context
 
-```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>
-```
-
-## Phase 1: Scope and Context
-
-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.
+1. Resolve one explicit diff range and file set. Include staged and unstaged changes
+   for a default working-tree review.
+2. Bind the single matching change through `change.list` and `task.list`; require an id
+   when ambiguous.
+3. Compile `change.context` for the review role and gate with only the intent, delta,
+   acceptance, tests, diff paths, and public-seam contract needed for this review.
 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. Create `.ultra/reviews/<session-id>/` with the reviewed HEAD, range, change id,
+   selected workers, and a pending verdict.
 
-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.
+## Run the independent fidelity axis
 
-## Phase 2: Specialist Selection
+Always dispatch `review-spec` with only the accepted intent, delta, acceptance criteria,
+public-seam context, current HEAD, and diff scope. Do not give it engineering findings
+or an implementation rationale that is not part of the accepted contract. It writes
+`spec-fidelity.json` with `axis: spec_fidelity`.
 
-Five engineering specialists feed the two-axis result:
+## Select engineering specialists
 
-| 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 |
+Use the smallest set that covers the diff. The delivery gate runs all five:
 
-`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.
+- `review-code`: correctness, security, and live-path reachability;
+- `review-tests`: behavioral coverage and feedback-loop evidence;
+- `review-errors`: hidden failures, recovery, and observability;
+- `review-design`: types, boundaries, complexity, and coupling;
+- `review-comments`: stale or misleading comments and documentation.
 
-## Phase 3: Background Execution (Zero Context Pollution)
+Record why any engineering specialist is skipped. The independent specification
+worker is required for every change-linked review.
 
-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:
+## Execute bounded workers
 
-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.
+Use the current host's native bounded-worker mechanism. Dispatch `review-spec` and the
+selected engineering workers independently. Each worker must inspect only the supplied
+diff and role context. Resolve `references/unified-schema.md` from this
+Skill directory and pass that absolute path as `SCHEMA_PATH`; never make a worker infer
+the plugin installation root. Each worker writes `<session>/<worker>.json` following
+that contract, limits output to actionable findings, and returns only a short file
+acknowledgement to the parent context.
 
-Do not copy worker transcripts into the parent context. Findings flow through files.
-
-## Phase 4: Wait & Coordinate (File-Based)
-
-Validate worker files:
+Resolve bundled paths relative to this skill directory. Validate the exact expected
+artifacts before coordination:
 
 ```bash
-python3 "$CLAUDE_PLUGIN_ROOT/skills/ultra-review/scripts/review_wait.py" {SESSION_PATH} agents {AGENT_COUNT}
+python3 scripts/review_wait.py <session-path> agents spec-fidelity review-code review-tests
 ```
 
-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
-```
-
-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.
-
-## Phase 5: Report to User
-
-`SUMMARY.json` must contain:
+Pass only the engineering worker stems actually selected. Missing or invalid required
+artifacts make the corresponding axis incomplete; a partial set is never a pass.
 
-- 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.
+Run `review-coordinator` only after validation. It may merge duplicate root causes but
+must retain source identifiers and the highest original severity.
+Validate its summary with the same waiter.
 
-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.
+## Report and handoff
 
-## Convergence handoff
+Report both axis verdicts first, followed by blocking findings and artifact paths.
+Review is read-only except for review artifacts; fixes are a separate implementation
+action. Recheck only unresolved or changed scope after fixes.
 
-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.
+At the final HEAD, compile review context with one convergence action. Delivery must
+submit separate review evidence rows for `spec_fidelity` and
+`engineering_standards`; a single aggregate pass is invalid.

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

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