ultra-builder-pro-cli 0.10.0 → 0.11.0

package/skills/ultra-deliver/SKILL.md

@@ -1,111 +1,73 @@
 ---
 name: ultra-deliver
-description: "Converge an implementation, approved specification learning, independent review axes, and release evidence into one recoverable baseline."
-user-invocable: true
-runtime: all
-mcp_tools_required:
-  - change.list
-  - change.get
-  - change.context
-  - change.breadcrumb
-  - change.learning_resolve
-  - change.converge
-  - change.archive
-cli_fallback: "direct user interaction"
+description: Converge verified implementation, specification learning, review evidence, and release artifacts into a recoverable baseline. Use when an initial baseline or active change has current passing evidence and is ready to archive or release.
 ---
 
-# ultra-deliver — Converge, Archive, Release
+# Converge and deliver
 
-Deliver the current baseline or one continuous-change packet. Change lifecycle writes
-use MCP only; `.ultra/test-report.json`, review sessions, and delivery reports are
-evidence artifacts.
+Deliver one baseline or continuous change. Change lifecycle writes use MCP; test,
+review, and delivery reports are evidence artifacts.
 
-## 1. Bind the delivery
+## Bind current evidence
 
-1. Call `change.list` for active, blocked, and ready changes.
-2. Bind exactly one relevant change; require an id when ambiguous. Initial baseline
-   delivery may use `change_id: null`.
-3. Call `change.breadcrumb`. A stale/blocked context or incomplete linked task blocks.
-4. Verify `.ultra/test-report.json` exists, passed, matches the change, and records the
-   current full HEAD plus at least one public seam.
-5. Verify the latest review session matches the same HEAD and has passing independent
-   `spec_fidelity` and `engineering_standards` axes.
+1. Call `change.list` and bind exactly one relevant change, or a null change id for an
+   initial baseline.
+2. Call `change.breadcrumb`. Block on stale context, incomplete linked tasks, or
+   unresolved readiness.
+3. Require a passing test report for the current full HEAD and at least one declared
+   public seam.
+4. Require current independent `spec_fidelity` and `engineering_standards` review
+   verdicts. Evidence from another checkout, commit, task set, or change is invalid.
 
-Do not reuse evidence from another checkout, commit, task set, or change.
+## Reconcile the baseline
 
-## 2. Reconcile specification learning
+Call `change.get` for authoritative learning candidates.
 
-Call `change.get` for authoritative `learning_candidates`; use the packet's
-`spec-learning.json` only as the inspectable projection.
+- Resolve every proposed item as approved or rejected.
+- Apply each approved item to its declared baseline target, verify the edit, then mark
+  it applied.
+- Preserve rejection reasons as decision evidence.
+- Confirm previously applied items remain represented in the target document.
 
-- `proposed`: require approve or reject through `change.learning_resolve`.
-- `approved`: update the declared baseline target, verify the edit, then mark `apply`.
-- `rejected`: preserve the reason as decision evidence.
-- `applied`: verify the target still contains the accepted behavior.
+Reconcile accepted delta content and documentation impact into baseline documents.
+Record updated paths or a specific no-change reason. Unknown documentation impact,
+unresolved placeholders, and behavior that exists only in the delta block convergence.
 
-Any proposed or approved candidate blocks convergence. This is the mandatory path that
-keeps baseline specs alive after daily changes; it is not cross-session memory.
+## Verify the release candidate
 
-Reconcile accepted `delta/` content and declared documentation impact into baseline
-documents. Record `baseline_updates`, or a specific no-change reason. No unresolved
-placeholder, unknown docs impact, or delivered-only-in-delta behavior may remain.
+Use a clean, reviewed release commit. Show any remaining diff and obtain explicit
+authorization before staging or committing. Never stage unrelated user changes.
 
-## 3. Verify the release candidate
+Run the exact repository commands needed for focused regression, relevant full tests,
+static checks, production build, package/install/doctor smoke when distributed, the
+public seam, and rollback or recovery sanity. Any post-verification edit invalidates
+the affected evidence.
 
-Require a clean, reviewed release commit. If changes remain, show the diff and obtain
-explicit approval before committing. Never auto-stage unrelated user changes.
+Compile final change context at the release commit with the convergence gate. It must
+be ready before calling `change.converge`.
 
-Run exact project commands for:
+## Converge and archive
 
-1. focused regression/acceptance feedback loop;
-2. full relevant tests;
-3. static checks and production build;
-4. package/install/doctor smoke where the product is distributed;
-5. public-seam acceptance and rollback/recovery sanity.
+Submit structured evidence for the reviewed diff and seam, test signals, baseline and
+delta, documentation, both independent review axes, and incident diagnosis when
+applicable. Do not collapse review axes or replace exact signal fields with prose.
 
-Record commands, exit results, and current HEAD. Any post-test edit invalidates the
-test and review gates.
+Resolve named blockers, rerun invalidated gates, then call `change.archive` with the
+summary and baseline updates.
 
-## 4. Compile final role context
+## Optional release
 
-Call `change.context` at the release commit with `role=review`, `gate=convergence`,
-current required refs/digests, the public seam, exact verification command, and the
-single next action `Archive the converged change`. Readiness must be `ready`.
+Only when release authorization is in scope:
 
-## 5. Converge
-
-Call `change.converge` with evidence rows for:
-
-- `diff`: reviewed release diff and public seam;
-- `tests`: exact signal object (`command`, expected/observed red, observed green,
-  deterministic, duration when known) and seam;
-- `spec`: baseline/delta and applied learning evidence;
-- `docs`: updated paths or explicit non-applicability;
-- `review`, `axis=spec_fidelity`;
-- `review`, `axis=engineering_standards`;
-- `diagnosis` for incidents.
-
-Do not collapse the two review axes or substitute prose for the signal fields. If
-convergence returns blockers, fix the named source and rerun the invalidated gates.
-
-## 6. Archive and release
-
-After `ready=true`, call `change.archive` with summary and `baseline_updates` (or the
-validated no-change reason). Then:
-
-1. determine the semantic version from user-visible compatibility;
+1. determine the semantic version from compatibility impact;
 2. update version and changelog;
-3. rerun release verification if version files changed;
-4. create a non-force commit/tag and push only with explicit release authorization;
-5. publish the package/release through the repository's authenticated workflow;
-6. verify the remote tag/release and registry version independently.
-
-Write `.ultra/delivery-report.json` with change id, archived status, commit, version,
-commands, package/release identifiers, baseline updates, rollback notes, and timestamp.
+3. rerun checks invalidated by version changes;
+4. create a non-force commit and tag;
+5. push and publish through the repository's authenticated workflow;
+6. independently verify the remote commit, tag, release, and registry version.
 
-## Completion gate
+Write the delivery report with the change id, archive status, commit, version, exact
+commands, release identifiers, baseline updates, rollback notes, and timestamp.
 
-Delivery is complete only when the change is archived, local and remote commit/tag
-agree, registry/release verification is current, and the worktree contains no
-unexplained scope. Report the outcome first, exact evidence next, and residual risks
-last. Never say “published” based only on a local version bump.
+Delivery is complete only when local and remote evidence agree and the worktree has no
+unexplained scope. A local version bump is not publication evidence.

package/skills/ultra-dev/SKILL.md

@@ -1,120 +1,57 @@
 ---
 name: ultra-dev
-description: "Execute one fresh-context vertical slice through a public seam with strict red-green evidence, bounded recovery, and specification learning."
-user-invocable: true
-runtime: all
-mcp_tools_required:
-  - task.update
-  - task.get
-  - task.list
-  - change.get
-  - change.context
-  - change.breadcrumb
-  - change.learning_propose
+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 — One Slice, One Feedback Loop
+# Execute one vertical slice
 
-Drive one task from `pending` to `completed`. Task status lives in
-`.ultra/state.db`; generated task JSON and context frontmatter are read-only.
+Drive one task from `pending` to `completed` without widening its contract silently.
 
 ## Authority and recovery
 
-If `task.list`, `task.get`, or `task.update` fails, stop. Never write raw SQLite,
-`.ultra/tasks/tasks.json`, or projected status fields. On
-`LEGACY_STATE_MIGRATION_REQUIRED`, use the documented migration command before work.
+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`.
 
-At entry, read `change.breadcrumb` when a change is active. A blocked or stale
-breadcrumb is an implementation blocker, not an advisory warning.
+Read `change.breadcrumb` when a change is active. Stale context, blocked readiness,
+unknown documentation impact, or a HEAD mismatch blocks implementation.
 
-`.ultra/workflow-state.json` is a compact recovery checkpoint only. Record command,
-task, branch, current step, status, and timestamp; do not copy prompts, codebase
-summaries, or provider memory into it.
-
-## 1. Select and compile the slice
+## Workflow
 
 1. Select the requested task, otherwise the first dependency-ready pending task.
-2. Call `task.get`; verify dependencies, ownership, acceptance, public seam, and exact
-   verification command.
-3. If linked to a change, call `change.get`, then compile `change.context` with:
-   `role=implement`, `gate=implementation`, the smallest required references, and the
-   task's execution contract.
-4. Stop on missing/stale references, budget overflow, unknown documentation impact,
-   or a HEAD mismatch. Do not compensate by loading the whole repository.
-5. Mark the task `in_progress` with `task.update` and checkpoint the step.
-
-The default slice is a `tracer_bullet`. An `expand_contract` must already be approved;
-implementation does not widen its own contract silently.
-
-## 2. Establish red
-
-Before production logic changes:
-
-1. Reproduce the smallest observable symptom at the declared public seam.
-2. Add or identify the regression/contract test.
-3. Run the exact command and record:
-   - command;
-   - expected failure;
-   - observed red result;
-   - deterministic/non-deterministic classification;
-   - duration when useful.
-
-For a new feature, red means an assertion expressing missing behavior. For a refactor,
-establish a green characterization baseline first. Documentation/config-only tasks may
-use a structural validator instead of a failing test, but must state why.
-
-If red cannot be observed, stop and correct the task contract; do not implement against
-an unproven hypothesis.
-
-## 3. Implement the minimum complete path
-
-- Trace entry point → domain rule → side effect → public seam.
-- Search for existing utilities and dependencies before adding helpers.
-- Keep IO at boundaries and domain behavior testable.
-- Include required validation, errors, observability, recovery, and documentation.
-- Preserve unrelated dirty worktree changes and stay within allowed paths.
-- Verify each meaningful increment through the same feedback loop.
-
-If implementation reveals a stable invariant or public behavior absent from the
-baseline, call `change.learning_propose` with its evidence and target document. Do not
-edit the baseline silently and do not store the discovery as Ultra memory.
-
-## 4. Establish green and inspect reachability
-
-Run, in order:
-
-1. the exact red command until the observed failure becomes green;
-2. adjacent focused tests;
-3. type check/lint/build proportionate to the change;
-4. the live public-seam acceptance path;
-5. final diff and worktree scope inspection.
-
-Record exact commands and zero-failure results. “Compiled” or “unit tests pass” is not
-enough when the new module is not connected to a consumer.
-
-## 5. Review gate
-
-Checkpoint `status=pre_review`, then invoke `/ultra-review all`. The review must produce
-independent `spec_fidelity` and `engineering_standards` verdicts. Fix all P0/P1 issues,
-rerun affected tests, and recheck until both axes pass. The primary host owns final
-verification; review workers never mutate durable Ultra state.
-
-## 6. Complete the task
-
-First call `task.update` with `status=completed` and completion commit/evidence
-supported by the task contract. Then, for a linked change, recompile
-`change.context` at the final HEAD with:
-
-- `role=implement`, `gate=verification`;
-- exact required references and current digests;
-- the public seam and verification command;
-- a single next action, normally `Run ultra-test for this change`.
-
-This ordering ensures the snapshot records the completed task state. Clear the active
-workflow checkpoint, call `change.breadcrumb`, and report exactly one next action.
+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 task/change id, changed paths, red signal, green commands, public-seam result,
-review session, spec-learning candidates, and remaining blockers. If any item is
-missing, leave the task in progress or blocked rather than claiming completion.
+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,98 +1,65 @@
 ---
 name: ultra-doctor
-description: "Inspect Ultra state, projection, session, incident, and active-change health; optionally run explicit backup-first mechanical recovery."
-user-invocable: true
-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.