ultra-builder-pro-cli 0.9.0 → 0.11.0

package/skills/ultra-dev/SKILL.md

@@ -1,349 +1,57 @@
 ---
 name: ultra-dev
-description: "Agile development execution with TDD workflow. Writes state through live task MCP tools, reviews through native host subagents, and checkpoints through workflow-state plus lifecycle hooks."
-runtime: all
-mcp_tools_required:
-  - task.update
-  - task.get
-  - task.list
-  - change.get
-  - change.context
+description: Execute one authoritative Ultra task through a bounded fresh context, a red-green feedback loop, live-path verification, and review. Use when a dependency-ready planned slice is ready for implementation.
 ---
 
-# ultra-dev — Phase 3.4
+# Execute one vertical slice
 
-Drive one task from `pending → completed` using a strict TDD loop, gated by
-`/ultra-review`. **state.db is the authority**: status transitions go through
-MCP `task.update`; the projector regenerates `tasks.json` and context-md
-frontmatter. For a task linked by `change_id`, requirement discoveries go to
-the active change delta first; baseline reconciliation happens in
-`/ultra-deliver`.
+Drive one task from `pending` to `completed` without widening its contract silently.
 
-## Authority failure boundary
+## Authority and recovery
 
-All task selection and transitions require the live MCP state tools. If they
-are unavailable or return an authority error, stop. For
-`LEGACY_STATE_MIGRATION_REQUIRED`, instruct:
+Task state changes use `task.update`. Never write raw SQLite, generated task JSON, or
+projected status fields. If task MCP access fails, stop and route state health to
+`ultra-doctor`.
 
-```bash
-ultra-tools migrate --from=4.4 --to=4.5 --source-dir <project-root>
-```
-
-Never fall back to `.ultra/tasks/tasks.json`, direct SQLite writes, or a task
-CLI. The JSON file is only a projector-owned view.
-
-## Design decisions vs pre-Phase-3
-
-- **Single-write status**: Step 1.5 / Step 5 stop touching `contexts/task-{id}.md`
-  frontmatter or the "`> **Status**: xxx`" line. Only MCP `task.update` fires;
-  projector rewrites frontmatter; humans read body for history.
-- **Native review path**: `/ultra-review all` delegates bounded review work to
-  the current Host's installed review agents. Review is not an MCP service.
-- **No `/compact` dependency**: Step 4.4 writes `.ultra/workflow-state.json`;
-  trusted lifecycle hooks preserve and restore it around compaction when the
-  Host exposes those events.
-
-## Prerequisites
-
-- `task.list` succeeds against state.db and returns at least one `pending` task
-
-## Arguments
-
-- `$1`: task id (optional; default = first `pending` task in topological order)
+Read `change.breadcrumb` when a change is active. Stale context, blocked readiness,
+unknown documentation impact, or a HEAD mismatch blocks implementation.
 
 ## Workflow
 
-### Step 0 — Workflow Resume Check
-
-Read `.ultra/workflow-state.json` if present.
-- If `branch` matches current `git branch --show-current` → resume from the
-  step after `status`
-- If `review_session` is set → skip re-running review
-- Otherwise → proceed to Step 0.5
-
-### Step 0.5 — Design Approval Gate (first run only)
-
-Fires when `.ultra/workflow-state.json` does NOT exist.
-
-1. `task.list` → confirm plan present; if empty, instruct `/ultra-plan` and **EXIT**
-2. If ANY task has `status` in (`in_progress`, `completed`) → plan was already
-   approved → skip this gate
-3. Present plan overview (totals, P0/P1/P2, Walking-Skeleton position)
-4. Ask through the current Host's native user-interaction surface:
-   - A: "Confirm, start implementation" → continue to Step 1
-   - B: "Revise plan first" → suggest `/ultra-plan` → **EXIT**
-5. On approval, write workflow-state:
-   ```jsonc
-   {"command":"ultra-dev","task_id":0,"branch":"","step":"0.5","status":"design_approved","ts":"<ISO8601>"}
-   ```
-
-### Step 1 — Task Selection
-
-```jsonc
-// MCP: task.list (or runtime args supply id)
-{ "status": "pending" }
-```
-
-Pick the first result (dependency-resolved) or the one matching `$1`.
-Read `.ultra/tasks/contexts/task-{id}.md` body for the Implementation /
-Acceptance sections. Use the Acceptance list as the initial todo set.
-
-If the task has `change_id`, call `change.get` and inspect its
-`context-manifest.json`. The task id, git head, allowed paths, spec refs, and
-external provider metadata must match the current slice. Call `change.context`
-before editing whenever they are stale. Provider content remains external.
-
-### Step 1.5 — Status → in_progress (single-write)
-
-```jsonc
-// MCP: task.update  (R: do NOT touch context-md frontmatter or "> **Status**" line)
-{ "id": "<id>", "patch": { "status": "in_progress" } }
-```
-
-Projector runs after the write → `tasks.json` + `contexts/task-{id}.md`
-frontmatter re-generated with `status: in_progress`. **Do not hand-edit either.**
-
-### Step 2 — Environment Setup
-
-**Unmerged-completed recovery**: `git branch --list 'feat/task-*'`; for each,
-extract task id, look up status via `task.get`. If any completed task has an
-unmerged branch → ask the user:
-- "Merge task-{id} to main first" (recommended)
-- "Delete branch (abandoned)"
-- "Skip, continue with new task"
-
-**Branch setup**:
-
-| Current branch | Action |
-|----------------|--------|
-| `main` / `master` | `git pull origin main && git checkout -b feat/task-{id}-{slug}` |
-| `feat/task-{id}-*` (same task) | continue (resume checkpoint) |
-| other | ask the user: switch to main + new branch / continue current |
-
-**Dependencies**: soft-warn only; parallel work is allowed.
-
-### Step 3 — TDD Cycle
-
-**Subagent isolation (complexity ≥ 7)**: optional — delegate a bounded TDD
-cycle through the current Host's native subagent surface; the subagent returns
-a summary and the primary agent owns verification.
-
-**Mid-TDD checkpoint (complexity ≥ 6)**: after GREEN phase, write a
-checkpoint. See Step 4.4 for the preferred MCP route.
-
-**RED** — write failing tests:
-- Mine Acceptance list for test specs
-- Cover 5 dimensions: functional / boundary / exception / security / integration
-- At least one integration test per boundary-crossing module
-- Run; confirm failure
-
-**GREEN** — minimum code to pass:
-- Production-ready (no TODO / placeholder)
-- Run; confirm pass
-
-**REFACTOR** — SOLID / DRY / KISS / YAGNI; tests stay green.
-
-**Checkpoint after Step 3.3**:
-```jsonc
-{"command":"ultra-dev","task_id":<id>,"branch":"<branch>","step":"3.3","status":"tdd_complete","ts":"<iso>"}
-```
-→ `.ultra/workflow-state.json`
-
-### Step 4 — Quality Gates
-
-| Gate | Requirement |
-|------|-------------|
-| Tests green | 0 failures |
-| Coverage | ≥80% overall; 100% functional-core; critical paths for shell |
-| Mock policy | Core logic: no mocks; external: testcontainers/stub OK |
-| No degradation | Zero fallback or demo code |
-| Integration test | Boundary-crossing code has ≥1 real integration test |
-| Entry-point reachable | New modules trace to a handler/listener/cron |
-| Spec compliance | Each Acceptance criterion implemented AND tested |
-
-Checkpoint `step="4"`, `status="gates_passed"`.
-
-### Step 4.4 — Pre-Review Checkpoint
-
-1. Write `.ultra/workflow-state.json` with `step=4.5, status=pre_review`.
-2. Let trusted Host lifecycle hooks preserve and restore that state when
-   compaction events exist.
-3. On Hosts without compaction hooks, resume directly from the same file.
-
-**Gate**: the skill MUST NOT require `/compact`; it MUST work when the
-runtime cannot compact.
-
-### Step 4.5 — Ultra Review (MANDATORY)
-
-Invoke `/ultra-review all`. The workflow uses the current Host's installed
-review agents and writes the unified review artifact. The primary agent owns
-the final verdict and re-runs relevant tests after fixes.
-
-**MAX_REVIEW_ITERATIONS = 2**
-
-| Verdict | Iter | Action |
-|---------|------|--------|
-| APPROVE | any | → Step 5 |
-| COMMENT | any | review P1s, fix if warranted, → Step 5 |
-| REQUEST_CHANGES | 1 | fix ALL P0, re-run tests, `/ultra-review recheck` |
-| REQUEST_CHANGES | 2 | stall check → escalate or fix |
-
-**Stall detection before iter 2**: if `curr_count >= prev_count` (P0+P1 not
-shrinking) → write `UNRESOLVED.md`, WARN user, proceed to Step 5.
-
-**Verification gate before Step 5**:
-- SUMMARY.json verdict ≠ `REQUEST_CHANGES`
-- All P0 resolved
-- Tests still green
-
-Checkpoint `step="4.5", status="review_done", review_session=<id>, review_iteration=<N>`.
-
-### Step 5 — Status → completed (single-write)
-
-**Prerequisites**: Step 4 + Step 4.5 green.
-
-```jsonc
-// MCP: task.update
-{
-  "id": "<id>",
-  "patch": {
-    "status": "completed"
-  }
-}
-```
-
-Projector regenerates frontmatter. **Then** write the context-md **body**
-Completion section (skill responsibility, not projector):
-
-```markdown
-## Completion
-- **Completed**: <YYYY-MM-DD>
-- **Commit**: _pending_   # filled in Step 6
-- **Summary**: <one-line delivery summary>
-```
-
-**Do not** hand-edit `> **Status**` anywhere in the body — frontmatter owns it.
-
-### Step 5.5 — Pre-Commit Checklist (BLOCKING)
-
-Before `git commit`, verify every item:
-
-- [ ] `task.get` confirms `status="completed"`
-- [ ] context-md body has updated Completion section
-- [ ] All tests pass
-- [ ] Ultra Review verdict ≠ `REQUEST_CHANGES`
-- [ ] New modules reach a live entry point (no orphan)
-- [ ] Boundary-crossing code has integration test
-
-Any unchecked → fix; do NOT commit.
-
-### Step 6 — Commit + Merge
-
-1. `git status` → show diff
-2. Ask through the current Host's native user-interaction surface:
-   - A: "Commit + Merge to main" (recommended)
-   - B: "Commit only, create PR later"
-   - C: "Review diff first" → `git diff --stat` → re-ask
-
-3. On approval:
-   ```bash
-   git add -A
-   git commit -m "feat(scope): description"
-   ```
-
-4. Record commit hash via MCP:
-   ```jsonc
-   { "id": "<id>", "patch": { "completion_commit": "<sha>" } }
-   ```
-   Update context-md body Completion line to the real hash; amend:
-   ```bash
-   git add .ultra/tasks/contexts/task-<id>.md
-   git commit --amend --no-edit
-   ```
-   (The amend is OK here — the first commit is a local, not-yet-pushed commit
-   in the feature branch. Never amend pushed commits.)
-
-5. `git fetch origin && git rebase origin/main`; resolve any conflicts.
-
-6. Re-run tests after rebase. Fail → fix → amend → repeat 5-6.
-
-7. If Option A chosen:
-   ```bash
-   git checkout main && git pull origin main
-   git merge --no-ff feat/task-<id>-<slug>
-   git push origin main && git branch -d feat/task-<id>-<slug>
-   ```
-
-8. For a task with `change_id`, call `change.context` after the final commit,
-   rebase, and verification so the manifest records the actual HEAD and task
-   set used for convergence.
-
-Checkpoint `step="6", status="committed", commit=<sha>`.
-
-### Step 7 — Report
-
-- Commit hash
-- Project progress (`task.list` → `completed/total`)
-- Next task suggestion (first remaining `pending` in topological order)
-
-## Delta-First Specification Mode
-
-Triggered when implementation reveals specification gaps or requirement changes.
-
-**Classification (mandatory before updating specs)**:
-
-| Kind | Meaning | Action |
-|------|---------|--------|
-| **EXPANSION** | new requirement surfaced | update active change delta + Change Log |
-| **CORRECTION** | spec error/ambiguity | update active change delta + Change Log |
-| **REDUCTION** | removing/weakening scope | **STOP** → ask the user for approval |
-
-**REDUCTION gate** — options:
-- A: "Approve reduction, update spec"
-- B: "Keep original scope, find alternative implementation"
-- C: "Split into separate task, defer to next cycle"
-
-For a task with `change_id`, update
-`.ultra/changes/active/<change-id>/delta/` immediately, then recompile
-`change.context`. Do not silently rewrite the baseline while parallel tasks are
-still executing. `/ultra-deliver` must reconcile the approved delta into the
-declared baseline files before archive.
-
-For an initial-baseline task with no `change_id`, update `.ultra/specs/`
-directly because no continuous-change packet exists yet. In both cases log the
-decision in the context-md body Change Log:
-
-```markdown
-| <date> | <KIND> | <change desc> | specs/<file>#<section> | <reason> |
-```
-
-**Principle**: the baseline specs describe accepted product truth; the active
-delta describes proposed change; task contexts record implementation history.
-No layer may silently shrink scope without the REDUCTION gate.
-
-## MCP failure matrix
-
-| Purpose | MCP tool (phase) | Failure behavior |
-|---------|------------------|------------------|
-| Select pending task | `task.list` (2) / `task.get` (2) | stop and surface the MCP error |
-| Status → in_progress | `task.update` (2) | stop; do not edit a projection |
-| Pre-review checkpoint | none | write `.ultra/workflow-state.json`; lifecycle hooks restore it |
-| Run review | none | `/ultra-review all` + Host-native review agents |
-| Status → completed | `task.update` (2) | stop; do not claim completion |
-| Refresh linked context | `change.context` (9) | stop; do not claim the change packet is current |
-| Ask user | none | current Host's native user-interaction surface |
-
-## What this skill DOES NOT do
-
-- Does NOT write `tasks.json` directly (projector owns it)
-- Does NOT edit context-md frontmatter (projector owns it)
-- Does NOT require the runtime to support `/compact`
-- Does NOT advertise review or checkpoint operations as MCP tools
-
-## Integration
-
-| | |
-|---|---|
-| **Input** | state.db via MCP, plus the `context_file` body returned for the selected task |
-| **Writes** | state.db (via `task.update`/`change.context`), active delta or baseline spec as classified, context-md body, workflow-state checkpoints |
-| **Next** | `/ultra-dev <next-id>` or `/ultra-test` when all Walking Skeleton + critical-path tasks complete |
+1. Select the requested task, otherwise the first dependency-ready pending task.
+2. Call `task.get` and verify acceptance, dependencies, ownership, public seam, and
+   exact verification command.
+3. For a linked change, call `change.get`, then compile `change.context` for the
+   implementation role and gate with the smallest required references.
+4. Mark the task `in_progress` only after the context is ready.
+5. Establish the feedback-loop baseline before changing production logic:
+   - reproduce the smallest observable symptom at the declared seam;
+   - add or identify the contract or regression test;
+   - record the exact command, expected signal, and observed result.
+
+   A feature starts with an assertion for missing behavior. A refactor starts from a
+   green characterization baseline. Documentation or configuration work may use a
+   structural validator when no logic test applies.
+6. Implement the minimum complete path from entry point to public seam. Reuse existing
+   utilities, keep IO at boundaries, include required errors and recovery, and preserve
+   unrelated worktree changes.
+7. If the work reveals a stable requirement or public behavior absent from the
+   baseline, call `change.learning_propose`. Do not edit the baseline silently or store
+   the discovery as private Ultra memory.
+8. Verify in this order:
+   - the original feedback-loop command;
+   - adjacent focused tests;
+   - proportionate static checks and build;
+   - the live public-seam acceptance path;
+   - final diff and worktree scope.
+9. Run `ultra-review` against the current diff. Fix blocking findings, rerun invalidated
+   checks, and require independent specification-fidelity and engineering verdicts.
+10. Call `task.update` with `status=completed` and exact evidence. For a linked change,
+    recompile the verification context at the final HEAD, then call
+    `change.breadcrumb`.
+
+## Completion evidence
+
+Report the task and change ids, changed paths, baseline signal, passing commands,
+public-seam result, review session, specification-learning candidates, and one next
+action. Leave the task in progress or blocked when required evidence is missing.

package/skills/ultra-doctor/SKILL.md

@@ -1,97 +1,65 @@
 ---
 name: ultra-doctor
-description: "Inspect Ultra state, projection, session, incident, and active-change health; optionally run explicit backup-first mechanical recovery."
-runtime: all
-mcp_tools_required:
-  - system.doctor
-cli_fallback: "system doctor"
+description: Diagnose Ultra state, projection, session, incident, change-artifact, and installed-plugin health with bounded recovery. Use when Ultra state appears missing, projections disagree, hooks fail, or MCP operations report degraded health.
 ---
 
-# ultra-doctor — Runtime Diagnostics and Recovery
+# Diagnose and recover the Ultra runtime
 
-Use this workflow when Ultra state appears empty, projections disagree with
-`state.db`, a hook reports a missing adapter, sessions are orphaned, a change
-artifact is missing, or MCP operations return degraded projection metadata.
+Default to read-only diagnosis. Repair only after the user explicitly authorizes it.
 
-## Default is read-only
+## Project-state diagnosis
 
-Call `system.doctor` with `{ "repair": false }` unless the user explicitly
-requests repair. Read-only diagnosis reports:
+Call `system.doctor` with `{ "repair": false }` and inspect:
 
 - SQLite integrity and required tables;
 - open structured incidents;
-- projection queue failures and event/projection cursor lag;
+- event and projection cursor lag;
+- failed or interrupted projection jobs;
 - orphan sessions;
 - missing active-change artifact roots;
-- the external ownership boundary for Memory and code graph.
+- the boundary to separately installed memory and code-graph providers.
 
-Do not infer health from `tasks.json`. Do not mutate provider state, delete
-artifacts, rebuild a graph, or collect memory during diagnosis.
+Do not infer health from generated task JSON. Do not mutate external provider state,
+delete artifacts, or collect memory during diagnosis.
 
-## Interpret the report
+## Interpret failures
 
-| Check | Meaning | Next action |
-|---|---|---|
-| `state_db` fail | schema/integrity problem | stop ordinary workflow; preserve DB evidence |
-| `incidents` fail | a structured runtime failure remains open | report code, source, retryability, and evidence |
-| `projections` fail | state commit is ahead of generated views or a projector failed | explicit repair is appropriate when authorized |
-| `sessions` fail | an orphan execution lease exists | repair may mark/reconcile it; never kill unrelated processes blindly |
-| `change_artifacts` fail | DB points to a missing active packet | recover from version control/backup or recreate deliberately |
-| `external_providers` pass | ownership is correctly external | provider availability must be checked with its own plugin/tool |
+- State integrity failure blocks ordinary workflows and requires preserving database
+  evidence before recovery.
+- An open incident requires its code, source, retryability, and evidence.
+- Projection lag may be mechanically repairable when authority is healthy.
+- An orphan session may be reconciled; never kill unrelated processes blindly.
+- A missing change artifact requires version-control, backup, or deliberate recreation
+  evidence rather than silent regeneration.
 
-## Explicit repair mode
+## Explicit repair
 
-Only after the user asks for repair, call `system.doctor` with
-`{ "repair": true }`, or use the fallback:
+After authorization, call `system.doctor` with `{ "repair": true }` or use the
+installed `ultra-tools system doctor --repair` fallback. The runtime must create a
+timestamped state database backup before any mechanical repair.
 
-```bash
-ultra-tools system doctor --repair
-```
+Repair is limited to documented recovery operations such as reconciling orphan
+sessions, consuming staleness events, requeueing interrupted or failed projections,
+and regenerating projections from authoritative state. If backup fails, stop. Always
+inspect the post-repair report; a completed repair action does not imply healthy state.
 
-The runtime must create `.ultra/backups/state-<timestamp>.db` before any
-mechanical repair. Repair is bounded to:
+## Installed-plugin failures
 
-- boot recovery for orphan sessions;
-- durable consumption of spec-staleness events;
-- requeueing projection jobs left `running` beyond the interruption cutoff;
-- requeueing failed projection jobs;
-- regenerating projections from authoritative state.
+When a hook points to a missing installed file:
 
-If backup fails, repair must stop with `BACKUP_FAILED`. A repair result is not
-automatically healthy; inspect the returned post-repair report and keep any
-remaining incident unresolved.
+1. Capture the hook manifest path and missing target.
+2. Run the installer doctor for the actual host and install scope.
+3. Preserve provenance, asset-hash, and host-contract findings.
+4. Reinstall through the host adapter rather than patching a cache directory.
+5. Rerun installer doctor, `system.doctor`, and a host hook smoke test.
 
-## Hook/path failures
-
-For an installed hook that points to a missing cached file:
-
-1. capture the exact hook config path and missing target;
-2. run the separate read-only installer boundary check:
-   `npx ultra-builder-pro-cli --<runtime> --local --doctor --json` (or use
-   `--global` when that is the actual install scope);
-3. preserve its provenance, asset-hash, and host-contract findings;
-4. reinstall or regenerate the host-native plugin through the adapter;
-5. rerun both installer doctor and `system.doctor`, then a host hook smoke test.
-
-`system.doctor` diagnoses project `.ultra/state.db` and workflow recovery.
-Installer `ubp --doctor` diagnoses the installed plugin files and host wiring.
-Neither report substitutes for the other.
-
-Do not bypass a broken hook by changing application implementation, and do not
-treat a hook failure as project-code evidence.
+Project doctor covers `.ultra/state.db`; installer doctor covers packaged files and
+host wiring. Neither substitutes for the other.
 
 ## Output
 
-Lead with `healthy` or `degraded`, list only failing checks, and include:
-
-- incident ids/codes and sources;
-- event vs projected cursor;
-- whether repair ran;
-- backup path when repair ran;
-- unresolved actions and their owner (`Ultra`, host plugin, or external provider).
-
-## What this skill does not do
+Lead with `healthy` or `degraded`. List failing checks, incident identifiers, cursor
+lag, whether repair ran, the backup path, and each unresolved action with its owner.
 
-- It does not fix project code or semantic specification conflicts.
-- It does not delete state, force-reset git, or close live healthy sessions.
-- It does not install, query, refresh, or repair external Memory/graph providers.
+Do not fix application code, delete state, reset Git, close healthy sessions, or
+install and repair external providers through this workflow.