ultra-builder-pro-cli 0.9.0 → 0.10.0

package/skills/ultra-status/SKILL.md

@@ -1,190 +1,77 @@
 ---
 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."
+description: "Route the project from its authoritative Ultra breadcrumb, readiness gates, task state, and current verification evidence."
+user-invocable: true
 runtime: all
 mcp_tools_required:
+  - change.breadcrumb
+  - change.list
   - task.list
   - task.get
   - session.list
-  - session.subscribe_events
-  - change.list
   - system.doctor
 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.
-It never treats a completed initial delivery as a terminal state: a healthy
-baseline routes the next daily request through `/ultra-change`.
-
-## Authority failure boundary
-
-`task.list` and `task.get` are the only task-state inputs. If either is
-unavailable or returns an authority error, surface it and stop. Never fall back to `.ultra/tasks/tasks.json`.
-On `LEGACY_STATE_MIGRATION_REQUIRED`, instruct the
-user to run `ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>`.
-
-## Workflow
-
-### Phase 0 — Environment validation
-
-| Check | If missing |
-|-------|-----------|
-| state.db reachable through `task.list` | suggest `/ultra-init` only when `.ultra/` is absent; otherwise surface the MCP error |
-| 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 }
-
-// MCP: change.list (continuous-change lane)
-{ "limit": 20 }
-
-// MCP: system.doctor (read-only runtime health)
-{ "repair": false }
-```
-
-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)
-- Active/blocked/ready change, linked task counts, docs impact, and context freshness
-- Runtime health: open incidents, projection lag/failure, orphan sessions, missing change artifacts
-
-### Phase 2 — Progress report
+# ultra-status — One Router, One Next Action
 
-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
-- **Change**: active id/kind/status, docs impact, task completion, context/provider freshness
-- **Runtime**: healthy/degraded with failing doctor checks only
-- **Risks**: auto-detected list (see Phase 3)
-- **Next**: recommended next task (see Phase 4)
+Use this workflow to answer “where are we?” and “what should happen next?” without
+reconstructing project state from prose. `.ultra/state.db` is authoritative; reports
+and Markdown are evidence or projections.
 
-### Phase 3 — Risk detection
+## Read order
 
-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)
-- **Projection/incident failure**: read-only doctor is degraded → route to
-  `/ultra-doctor`; never infer recovery from a generated JSON file
-- **Context stale**: active change manifest head or task set differs from current state
-- **Docs drift**: change has `docs_impact.status=unknown` or declared required file is missing
+1. Call `system.doctor { repair: false }`. If authority is unhealthy, route only to
+   `ultra-doctor` and include the blocking diagnostic.
+2. Call `change.breadcrumb`. It returns the active change, task, role, gate,
+   readiness, blockers, stale status, and one deterministic next action.
+3. Call `task.list` and `session.list` for counts and active execution detail.
+4. Read `.ultra/test-report.json` and `.ultra/delivery-report.json` only when they
+   exist. Treat a report from a different HEAD as stale.
+5. Read git branch, HEAD, and worktree status. Do not mutate anything.
 
-| Icon | Meaning | Action |
-|------|---------|--------|
-| 🟢 | on track | continue |
-| 🟡 | minor issues | review stalled |
-| 🟠 | significant risks | address blockers |
-| 🔴 | critical | stop and resolve |
+Never fall back to `.ultra/tasks/tasks.json`, context Markdown frontmatter, or raw
+SQLite when MCP task state is unavailable. Label that panel unavailable.
 
-### Phase 4 — Next-task recommendation
+## Routing rules
 
-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)
+The breadcrumb owns the primary route. Do not print a menu of every Ultra command.
 
-### 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 and no delivered baseline | `/ultra-plan` |
-| Doctor degraded because of Ultra runtime state | `/ultra-doctor` |
-| No active/blocked/ready change and fresh delivery exists | `/ultra-change` for the next daily change |
-| Active change has any `pending` linked task | `/ultra-dev` (show which) |
-| Active change linked tasks all `completed` | `/ultra-test` |
-| Matching fresh `test-report.json.passed === true` | `/ultra-deliver` |
-| `test-report.json.passed === false` | `/ultra-dev` (show blocking issues) |
-| Change is `ready` | `/ultra-deliver` to reconcile/archive before release completion |
-| Latest change archived and delivery fresh | Baseline healthy; next work starts with `/ultra-change` |
-
-**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>" }
+| State | Route |
+|---|---|
+| doctor unhealthy | `ultra-doctor` |
+| no Ultra project | `ultra-init` |
+| no baseline specs or tasks | `ultra-research` or `ultra-plan`, matching the missing artifact |
+| readiness blocked or context stale | recompile through `ultra-change`, `ultra-plan`, or `ultra-dev` as named by the breadcrumb |
+| implementation task ready | `ultra-dev <task-id>` |
+| all scoped tasks complete, test report missing/stale | `ultra-test` |
+| review or convergence incomplete | `ultra-review all` or `ultra-deliver`, matching the gate |
+| ready change | `ultra-deliver` |
+| archived change and clean HEAD | report complete; do not invent more work |
+
+When there is no active change, derive a single baseline route from tasks and reports.
+If several changes are active or blocked, report ambiguity and require an explicit
+change id instead of guessing.
+
+## Output
+
+Keep the answer compact:
+
+```text
+Ultra: <healthy|degraded> · <branch>@<head> · worktree <clean|dirty>
+Position: change=<id|none> task=<id|none> role=<role> gate=<gate>
+Readiness: <ready|blocked|stale> — <blockers or none>
+Progress: <completed>/<total>; sessions=<active count>
+Evidence: tests=<fresh|stale|missing>; delivery=<fresh|stale|missing>
+Next: <exactly one action, including the task/change id when known>
 ```
-Display: title, status, priority, complexity, deps, files_modified (if set),
-session_id (if active), `context_file`, `trace_to`, stale flag, update history.
-
-## MCP and CLI matrix
-
-| Purpose | MCP tool | CLI fallback |
-|---------|----------|--------------|
-| List tasks | `task.list` | none; fail closed |
-| Single task detail | `task.get` | none; fail closed |
-| Change lane | `change.list` | none; fail closed |
-| Runtime health | `system.doctor { repair:false }` | `ultra-tools system doctor` |
-| Cost panel (Phase 6.3) | — | `ultra-tools status --cost --json --since 7d` |
 
-## Cost panel (Phase 6.3)
+Separate verified facts from unavailable panels. Do not hide a stale context or stale
+test report behind an overall “healthy” label.
 
-`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.
+## Boundaries
 
-## What this skill DOES NOT do
-
-- Does NOT modify or repair state
-- Does NOT run tests / build / deploy
-- Does NOT require all artifacts (partial reports are tolerated)
-
-## Integration
-
-| | |
-|---|---|
-| **Input** | state.db via task/change/session/system reads, test/delivery reports, git HEAD |
-| **Output** | console report (Chinese per project rule) |
-| **When** | anytime — idempotent read-only |
+- Read-only: this workflow does not repair, compile context, update tasks, or release.
+- Cost data may use the declared CLI fallback, but task/change authority may not.
+- External memory and code graph providers are optional metadata references; their
+  absence does not change Ultra authority.

package/skills/ultra-test/SKILL.md

@@ -1,213 +1,94 @@
 ---
 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."
+description: "Run the pre-delivery check gate from a fresh role context and record exact feedback-loop, wiring, recovery, and acceptance evidence."
+user-invocable: true
 runtime: all
 mcp_tools_required:
   - task.list
   - change.list
+  - change.context
+  - change.breadcrumb
 ---
 
-# ultra-test — Phase 3.5
+# ultra-test — Independent Check Context
 
-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.
+This is the project/change pre-delivery gate, not a replacement for the task-level TDD
+loop. It produces `.ultra/test-report.json`; task and change authority remain in
+`.ultra/state.db`.
 
-## Authority failure boundary
+## Entry gate
 
-The completed-task precheck requires MCP `task.list`. If it is unavailable or
-returns an authority error, stop the audit. Never fall back to
-`.ultra/tasks/tasks.json`. For `LEGACY_STATE_MIGRATION_REQUIRED`, instruct
-`ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>`.
+1. Call `task.list`; require at least one completed task in scope.
+2. Call `change.list` and bind to exactly one relevant active/blocked/ready change, or
+   explicitly record `change_id: null` for an initial baseline.
+3. For a change, compile `change.context` with `role=check`, `gate=verification`, only
+   the tests/specs/source seams needed to verify it, and the same execution contract.
+4. Call `change.breadcrumb`; stop when context is stale or readiness is blocked.
 
-## Prerequisites
+Never fall back to `.ultra/tasks/tasks.json`. Do not reuse the implementer's full
+conversation as test context.
 
-- `task.list` returns ≥1 task with `status=completed`
-- Repo has test files (Step 0 pre-check)
+## Verification matrix
 
-## Workflow
+Build a matrix from acceptance claims to observable evidence:
 
-### Step 0 — Pre-Execution
+| Check | Required evidence | Blocking condition |
+|---|---|---|
+| Feedback loop | exact command and observed green | command fails or no prior red for fix/incident |
+| Public seam | reachable entry-to-consumer path | orphan/stub/unwired behavior |
+| Regression | focused and adjacent suites | failure or meaningful skipped assertion |
+| Build/static | typecheck/lint/build as applicable | non-zero result |
+| Error/recovery | failure mode and recovery path | silent/swallowed/unrecoverable critical path |
+| Security | input/auth/secrets/dependency checks in scope | high-severity issue |
+| Docs/spec | delivered behavior matches declared delta | drift or unknown impact |
 
-1. Detect project type from config (`package.json` / `Cargo.toml` / `go.mod` / `pyproject.toml` / …)
-2. `task.list { status: "completed" }` → confirm ≥1 task delivered
-3. `change.list` → identify the active/blocked change, if any; filter linked
-   tasks locally by `change_id`
-4. Find test files (suffix `.test.*`, `.spec.*`, `test_*.py`, `*_test.go`)
+Use repository-native commands and real boundaries where practical. Test doubles are
+acceptable only at costly or nondeterministic external boundaries and must be named.
 
-Block with instructive error if any precheck fails.
+## Quality checks
 
-### Step 1 — Anti-Pattern Detection
+- Detect tautologies, empty tests, weakened assertions, and core-domain over-mocking.
+- Find changed exports without meaningful test coverage.
+- Trace changed source into non-test consumers; flag orphan modules and placeholder
+  handlers/components.
+- Exercise key API/UI/CLI flows when the project exposes them.
+- Inspect error handling, authorization, migrations, idempotency, and rollback in the
+  affected risk surface.
+- Compare current HEAD and context digests with the implementation evidence.
 
-Detect fake / meaningless tests that waste CI time.
+Do not mechanically require every possible test category. Mark a check
+`not_applicable` only with a concrete scope reason.
 
-| 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 |
+## Report contract
 
-Use Grep with language-appropriate regex; count matches per file.
+Write `.ultra/test-report.json` atomically with at least:
 
-**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
+```json
 {
-  "timestamp": "<ISO8601>",
-  "git_commit": "<HEAD>",
-  "change_id": "<active-change-id-or-null>",
+  "schema_version": "2.0",
+  "change_id": "<id-or-null>",
+  "git_commit": "<full-head>",
+  "context_manifest_hash": "<hash-or-null>",
   "passed": true,
-  "run_count": 1,
-  "commands": [
-    { "command": "<exact command>", "exit_code": 0, "scope": "unit/integration/e2e/build" }
-  ],
-  "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 }
+  "feedback_loop": {
+    "command": "<exact command>",
+    "expected_red": "<failure contract or not-applicable reason>",
+    "observed_red": true,
+    "observed_green": true,
+    "deterministic": true
   },
-  "blocking_issues": []
+  "public_seams": ["<verified seam>"],
+  "checks": [],
+  "blocking_issues": [],
+  "commands": []
 }
 ```
 
-Rules:
-- File exists → increment `run_count`
-- `passed = true` iff all gates `.passed === true`
-- `blocking_issues` lists human-readable strings for any fail
-- `commands` records exact executable evidence; prose such as “tests look good”
-  is not convergence evidence
-- when a continuous change is active, `change_id` must match it; never reuse a
-  report from another change
-
-### 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 failure matrix
-
-| Purpose | MCP tool | CLI fallback |
-|---------|----------|--------------|
-| Confirm ≥1 completed task | `task.list { status: "completed" }` | none; fail closed |
-| Identify active change | `change.list` | none; omit only for initial baseline delivery |
-| 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`)
+Set `passed=true` only when every required check passes, the report HEAD is current,
+and at least one public seam is verified. Preserve exact commands, exit results, and
+concise failure excerpts; do not paste full logs.
 
-## Integration
+## Exit
 
-| | |
-|---|---|
-| **Input** | Source + test files, state.db (read-only) |
-| **Output** | `.ultra/test-report.json` with exact commands/change id, `.ultra/docs/test-coverage-gaps.md` |
-| **Next** | `/ultra-deliver` (only when `passed=true`) |
+Call `change.breadcrumb` and route one next action: fix a named blocker, run
+`/ultra-review all`, or run `/ultra-deliver`. A stale report never routes to delivery.

package/skills/ultra-think/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: ultra-think
 description: "Deep analysis with adversarial reasoning — Evidence-First + Multi-Perspective + Steel-Man + Pre-Mortem + Sensitivity. Produces a recommendation with confidence bounds."
+user-invocable: true
 runtime: all
 cli_fallback: "direct user interaction"
 ---

package/spec/cli-protocol.md

@@ -105,6 +105,9 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `change.get`              | `change get`                | 9     | any     |
 | `change.list`             | `change list`               | 9     | any     |
 | `change.context`          | `change context`            | 9     | mcp     |
+| `change.breadcrumb`       | `change breadcrumb`         | 10    | any     |
+| `change.learning_propose` | `change learning-propose`   | 10    | mcp     |
+| `change.learning_resolve` | `change learning-resolve`   | 10    | mcp     |
 | `change.converge`         | `change converge`           | 9     | mcp     |
 | `change.archive`          | `change archive`            | 9     | mcp     |
 | `system.doctor`           | `system doctor`             | 9     | mcp     |