ultra-builder-pro-cli 0.15.0 → 0.17.0

package/skills/ultra-deliver/SKILL.md

@@ -1,77 +1,56 @@
 ---
 name: ultra-deliver
-description: Converge one verified Ultra change, reconcile specification learning and baseline authority, archive recoverably, and optionally release when explicitly authorized. Use when current test and independent review evidence are ready for delivery.
+description: Converge a verified Ultra change, reconcile baseline specifications, and archive it with recoverable local evidence. Use when implementation, testing, and review are current.
 ---
 
-# Converge and deliver one change
+# Converge and archive local authority
 
-Use host judgment for release scope and authorization. Use Ultra MCP for evidence
-binding, workflow state, convergence, baseline reconciliation, archive recovery, and
-output digests.
+Delivery closes Ultra's local change authority. It does not grant or perform commit,
+push, tag, registry publication, deployment, or another external effect.
 
 ## Bind current evidence
 
-1. Read `system.doctor`, `baseline.get`, `change.get`, `change.breadcrumb`, linked
-   tasks, and current test/review workflows and artifacts.
-2. Resume or start a `deliver` workflow linked to the change and baseline.
-3. Require completed tasks, current context, a passing test report at full HEAD with a
-   verified public seam, and current independent `spec_fidelity` and
-   `engineering_standards` verdicts. Record `bind-evidence`.
+1. Read doctor, baseline, change, breadcrumb, decisions, tasks, test, review, learning,
+   and current checkout.
+2. Resume or start a deliver workflow bound to the change and baseline.
+3. Require complete task evidence, a current test report, both review axes, current
+   context, and resolved material decisions. Record `bind-evidence`.
 
-Evidence from another revision, task set, change, or stale output is invalid. An
-approved break-glass incident follows only its recorded recovery contract.
+Evidence from another revision, task set, or change is invalid.
 
-## Reconcile and verify
+## Reconcile specifications
 
-Resolve every specification-learning proposal. Apply an approved item to its declared
-target and verify it before marking it applied; preserve rejection reasons. Reconcile
-accepted delta and documentation impact into baseline documents, or record an exact
-no-change reason. Record `reconcile-specifications`.
+Resolve every specification-learning candidate. Apply approved learning to its target
+with before/after digests and verification; preserve rejection reasons.
 
-Read `references/baseline-reconciliation.md` and write the bound reconciliation
-manifest inside the active change directory. It must record every baseline update as a
-semantic add or update with a real source anchor, before/after digests, verification,
-resolved gap ids, and resolved unknowns. A no-update delivery records one evidenced
-semantic no-change reason.
+Read `references/baseline-reconciliation.md` and write the reconciliation manifest
+inside the active change directory. Record semantic additions or updates, resolved
+gaps and unknowns, and verification. If baseline semantics did not change, record an
+evidenced no-change reason. Record `reconcile-specifications`.
 
-Verify the release candidate with repository-native focused/regression checks,
-type/lint/build where applicable, install/doctor smoke for distributed packages,
-public seams, and rollback or recovery sanity. Compile final convergence context and
-record its immutable manifest as the `verify-candidate` output. Any edit invalidates
-affected evidence.
+Compile final convergence context and run the risk-selected candidate checks, install
+or doctor smoke when this change modifies distributed assets, public-seam verification,
+and recovery sanity. Record the immutable context under `verify-candidate`.
 
-Call `change.converge` with only the change id. Do not submit verdicts or evidence
-summaries: MCP derives development, test report, public seam, specification,
-documentation, both review axes, and incident diagnosis evidence from DB-backed
-workflows and current artifacts. Resolve named blockers and rerun invalidated gates. Record
-`converge-authority` only when the change is ready.
+Call `change.converge`; MCP derives readiness from durable dev, test, review,
+specification, docs, diagnosis, and current checkout evidence. Record
+`converge-authority` only when ready.
 
-Call `change.archive` with the summary, `reconciliation_path`, and baseline updates or
-exact no-change reason.
-Ordinary archive refreshes baseline revision and digests atomically and rolls back on
-incomplete reconciliation. Record `archive-change`. For break-glass delivery, verify
-the returned bypass and blocking reconciliation gap.
+Call `change.archive` with the reconciliation manifest and summary. Verify the refreshed
+baseline and archived packet, then record `archive-change`.
 
-## Release only with authority
+Write `.ultra/reports/delivery/<workflow-id>.json` with
+`ultra-delivery-report-v1`: archived change, baseline, HEAD, worktree and context
+digests, local checks, rollback notes, and timestamp. The report must not contain a
+release decision. Record it under `verify-delivery` and complete the workflow.
 
-The `release-if-authorized` step is not permission. When publication is outside the
-user's request, complete it with exactly one `release_authorization` decision containing
-`authorized: false` and the reason. When explicitly authorized, record
-`authorized: true`, `approved_by`, the exact release `scope`, and the reason; then
-determine compatibility impact, update version and
-changelog, rerun invalidated checks, create a non-force commit/tag, push, publish, and
-verify remote commit, tag, release, and registry version independently.
+## External effects
 
-Write `.ultra/reports/delivery/<workflow-id>.json` atomically using
-`ultra-delivery-report-v1`, with change/archive state, baseline id/status, full HEAD,
-worktree digest, convergence-context digest, exact passing
-checks, the explicit release authorization/performed decision, release identifiers
-when applicable, structured evidence for every performed commit/push/tag/registry/
-deployment action, rollback notes, and timestamp. The report authorization must match
-the DB-recorded decision. Record `verify-delivery` with that
-output and call `workflow.complete` only after the change is archived and local and
-remote evidence agree for every authorized action. MCP derives the delivery summary
-from this report rather than a Prompt claim.
+If the user separately requests commit, push, tag, publish, or deploy, handle that as a
+host-owned effect after Ultra delivery. Confirm only missing material authority, run
+the repository's release checks, and report remote evidence separately. Never infer an
+external effect from `ultra-deliver`, and never encode it as completed Ultra delivery
+state.
 
-Return workflow id, archive and baseline state, evidence digests, commit/release facts,
-recovery notes, residual risks, and one next route.
+Return archive and baseline state, evidence digests, recovery notes, residual risks,
+and allowed transitions.

package/skills/ultra-dev/SKILL.md

@@ -1,58 +1,64 @@
 ---
 name: ultra-dev
-description: Execute one authoritative Ultra task through a fresh-context, test-driven, review-backed live-path slice with resumable DB state. Use when a planned task is ready to implement, resume, or recover after a blocker or interrupted session.
+description: Implement one authoritative Ultra task through a fresh-context, test-driven, review-backed live path. Use when a planned task is executable, interrupted, or ready for focused recovery.
 ---
 
-# Implement one executable task
-
-Bind exactly one task and change. Use the host for code reasoning and edits; use Ultra
-MCP for workflow state, context authority, task/session transitions, evidence, and
-recovery.
-
-## Start or resume
-
-1. Read `system.doctor`, `change.breadcrumb`, `task.get`, workflow state, dependencies,
-   active sessions, Git HEAD, and worktree scope.
-2. Resume an existing `dev` workflow or call `workflow.start` with `change_id` and
-   `task_id`. Startup fails when the DB-backed task execution contract is incomplete or
-   owned by another change.
-3. Record `bind-task` with task, dependency, branch, and worktree evidence.
-4. Compile `change.context` for `implement`. It derives public seam, verification, and
-   required refs from the task row. Record its immutable manifest as the
-   `compile-context` output only when ready. That starting snapshot remains historical
-   task evidence; later task commits do not invalidate it when its commit stays on the
-   current ancestry and the task contract is unchanged.
-5. Run session admission before spawning an isolated session. Do not open a second
-   active lease without the documented resume, takeover, or abandon decision.
-
-## Red, green, verify
-
-1. Reproduce the behavior or establish a characterization signal before logic edits.
-   Record `establish-feedback-loop` with the exact failing command and observed result.
-2. Set the task `in_progress`; implement the smallest complete vertical slice through
-   the declared public seam. Preserve unrelated worktree changes.
-3. Keep application judgment and edits in the host. Do not write projections, raw DB,
-   workflow output digests, or evidence state by hand.
-4. Refactor only inside the accepted slice while the focused signal stays green.
-5. Record `implement-slice`, then run focused, adjacent, static/build, public-seam,
-   error, and recovery checks proportional to risk. Record exact evidence under
-   `verify-slice`.
-6. Run `ultra-review` at the current diff. Record both independent verdict axes under
-   `review-slice`; unresolved blocking findings return to implementation.
+# Implement one task
+
+The host model owns code reasoning and edits. Ultra owns the task and workflow state,
+fresh context contract, session lease, evidence references, and recovery.
+
+## Bind and resume
+
+1. Read doctor, breadcrumb, active decisions, task contract, dependencies, dev runs,
+   sessions, HEAD, and worktree.
+2. Resume the matching dev run or start one with `change_id` and `task_id`.
+3. Record `bind-task` with current authority and dependency evidence.
+4. Compile `change.context` for `implement` using DB-backed public seam, verification
+   command, and refs. Context budgets are advisory; missing required evidence is
+   blocking. Record the immutable manifest as `compile-context`.
+5. Reuse an existing valid session. Otherwise pass admission and call `session.spawn`.
+   Work only in the returned worktree and preserve unrelated changes.
+
+Do not spawn recursively from a parent-owned worker session. Process exit is transport
+evidence, never task completion.
+
+## Focused inner loop
+
+1. Reproduce the bug, write a failing test, or establish a characterization signal
+   before a logic change. Record `establish-feedback-loop`.
+2. Mark the task `in_progress` and implement the smallest complete slice through the
+   declared public seam.
+3. Keep the loop adaptive. The model may choose implementation details inside the
+   accepted contract. If new evidence changes product intent, compatibility, security,
+   material cost, external effects, or recovery, use the host's native question UI and
+   the decision protocol; do not ask about ordinary reversible details.
+4. Record `implement-slice`, then run focused tests plus the adjacent checks justified
+   by the task risk. Record exact results under `verify-slice`.
+5. Run a task-scoped independent review on specification fidelity and relevant
+   engineering risks. Record `review-slice`. Fix blocking findings and refresh affected
+   evidence.
+6. Create the authorized local task commit. Do not push, publish, tag, or deploy unless
+   the user separately authorized that external effect.
+
+Task-level tests and review belong to this inner loop. They do not replace aggregate
+change testing or review when multiple slices, integrations, or broader risks require
+those capabilities.
 
 ## Complete or recover
 
-Close the admitted session with `session.close` after its final heartbeat and verify
-that no running lease remains for the task. Then update the task to `completed` only
-after acceptance, verification, documentation, and review are current. Record
-`record-completion` with commands, results, changed paths, commit when authorized, and
-context/review references; then call `workflow.complete`. The MCP refuses dev
-convergence while the task is incomplete or a session is still running.
+In direct mode, integrate the task commit through the repository's accepted path,
+verify ancestry and the public seam, close the session, update the task to `completed`,
+record `record-completion`, and complete the dev workflow.
+
+In a parent-supervised worker, record completion evidence and exit without closing the
+parent-owned lease. The primary host verifies the exact session commit, performs any
+integration, refreshes review if the reviewed checkout changed, settles the lease, and
+completes the workflow.
 
-On interruption or an external blocker, record the current step as `blocked`, update
-the task consistently, and preserve the session and evidence. Resume the same run;
-completed steps remain durable. Any code or contract change invalidates affected test,
-review, or context evidence.
+Preserve worktrees by default. Remove one only when Git proves it is clean and
+integrated. On interruption, record the current step and task as blocked, preserve
+worktree and evidence, and resume the same run later.
 
-Return the task outcome, public seam, changed paths, exact checks, review results,
-workflow id, session state, residual risks, and one next route.
+Return outcome, changed paths, public seam, exact checks, review axes, commit and
+session state, residual risk, and allowed transitions.

package/skills/ultra-doctor/SKILL.md

@@ -1,55 +1,50 @@
 ---
 name: ultra-doctor
-description: Diagnose and recover Ultra DB schema, workflow outputs, projections, sessions, incidents, change artifacts, archives, hooks, and installed host assets. Use when authority is degraded, workflow state disagrees with prompts, outputs are stale, hooks fail, or MCP operations cannot proceed.
+description: Diagnose and mechanically recover Ultra schema, workflow, projection, session, archive, hook, and installed-asset faults. Use when authority is degraded, stale, contradictory, or unavailable.
 ---
 
 # Diagnose before repair
 
-Default to read-only diagnosis. Call `system.doctor` with repair disabled and inspect:
-
-- SQLite integrity, schema version, required tables, and migration provenance;
-- baseline classification/readiness, research provenance, spec/evidence digests, gaps,
-  and revision/worktree drift;
-- active, blocked, and ready workflow runs, current steps, blockers, and output health;
-- event/projection cursor lag and failed or interrupted projection jobs;
-- sessions, incidents, circuit state, active-change artifacts, and archive journals;
-- external provider ownership boundaries.
-
-An expected blocked workflow is a workflow warning, not DB corruption. A stale or
-missing recorded output is an authority failure for that run. Doctor cannot invent
-evidence, complete a step, accept a failure, approve a baseline, or change product
-scope.
-
-## Route failures
-
-- Missing or migrated baseline evidence: `ultra-init` and the exact research step.
-- Stale workflow output: restore or regenerate the artifact from accepted evidence,
-  then record the affected step again and re-run completion.
-- Projection lag with healthy authority: eligible for mechanical regeneration.
-- Orphan session: reconcile the recorded lease; do not kill unrelated processes.
-- Missing change artifact: recover from version control, backup, or explicit owner
-  decision rather than silently recreating it.
-- Corrupt SQLite: preserve DB/WAL/SHM and obtain a restore-or-rebaseline decision.
-
-## Explicit project repair
-
-After authorization, call `system.doctor` with repair enabled. Repair is limited to
-supported schema upgrades, backup-first archive recovery, orphan reconciliation,
-staleness consumption, projection requeue, and projection regeneration. Verify the
-pre-migration and repair backup paths and rerun the read-only report. A completed repair
-action does not imply healthy workflow evidence.
-
-When integrity prevents opening the DB, use only the documented restore or rebaseline
-command with its explicit confirmation token. Both must quarantine or back up prior
-authority and roll back on failure.
-
-## Installed host failures
-
-For a missing hook adapter or stale plugin path, capture the manifest and missing
-target, run `ubp --doctor` for the actual host, reinstall through the adapter rather
-than patching cache contents, and verify provenance, hashes, entry points, MCP startup,
-and a hook smoke test. Project doctor and installer doctor are separate authorities.
-
-Return health first, failing authority checks, workflow warnings, backup/recovery
-paths, whether repair ran, unresolved owners, and one exact next action. Do not edit
-application code or external memory/graph providers through this Skill.
+Doctor owns deterministic health and supported recovery. It cannot decide product
+scope, invent evidence, approve a baseline, answer a user decision, or mark semantic
+work complete.
+
+## Read-only diagnosis
+
+Run `system.doctor` without repair and inspect:
+
+- SQLite integrity, schema 18 migration, required tables, and backups;
+- baseline and research provenance, gaps, digests, and Git/worktree drift;
+- workflow status, obsolete-step migration, blockers, and output freshness;
+- decisions and checkpoint artifact freshness;
+- projection jobs and event cursors;
+- sessions, preserved worktrees, incidents, circuit state, and archive journals;
+- external provider boundaries.
+
+An expected workflow pause or awaiting user decision is a warning, not corruption.
+Missing or changed required evidence is an authority failure but cannot be reconstructed
+by doctor.
+
+## Recovery boundary
+
+With explicit repair authorization, `system.doctor` may:
+
+- apply backup-first supported schema migrations;
+- migrate active pre-18 rigid workflows into recoverable adaptive state;
+- requeue or regenerate projections from healthy DB authority;
+- reconcile orphan sessions without deleting unrelated or dirty worktrees;
+- resume supported archive journals;
+- recover missing workflow provenance as a blocked run requiring real evidence.
+
+It may not create a Git checkpoint, replace a healthy baseline, accept known failures,
+resolve decisions, regenerate semantic content, or edit application code.
+
+Corrupt SQLite requires preservation of DB, WAL, and SHM followed by an explicit
+restore-or-rebaseline choice. Missing hook adapters or stale cache paths require
+`ubp --doctor` and adapter reinstall; never patch plugin cache contents by hand.
+
+After repair, rerun doctor read-only and verify backup paths, schema, installed hashes,
+entry points, MCP startup, and hook smoke tests as applicable.
+
+Return health first, failed checks, mechanical repairs performed, preserved recovery
+paths, unresolved owners, and allowed transitions plus any unique required transition.

package/skills/ultra-init/SKILL.md

@@ -1,104 +1,82 @@
 ---
 name: ultra-init
-description: Initialize a new repository, adopt an existing codebase, or migrate prior Ultra authority into a verified project baseline. Use when `.ultra` is absent, initialization is incomplete, baseline readiness is blocked, or a legacy Ultra project must be resumed.
+description: Create or recover Ultra project authority for a new repository, an existing codebase, or an older Ultra installation. Use when `.ultra` is absent, initialization is incomplete, or doctor reports a migration or initialization fault.
 ---
 
-# Establish project authority
-
-Use host reasoning to inspect repository evidence and prepare baseline content. Use
-Ultra MCP for classification records, schema migration, workflow state, evidence
-digests, approval, and convergence. Never treat generated Markdown or JSON as state.
-
-## Classify without guessing product scope
-
-Run `system.doctor` read-only when `.ultra/state.db` exists. Otherwise call
-`task.init_project` with `mode: "auto"`, the repository root, project name, and an
-owner-selected monorepo scope when applicable.
-
-Interpret classification independently from readiness:
-
-- `greenfield`: no meaningful delivered application behavior exists outside docs,
-  generated output, or a starter skeleton;
-- `brownfield`: source, runtime, deployment, API, schema, or test evidence shows an
-  existing maintained system;
-- `migrated`: older DB or projection-only authority was preserved and must be
-  replaced by an evidence-backed brownfield baseline.
-
-The presence of `.ultra/`, a manifest, or a Git repository does not make a baseline
-ready. Classification never chooses an MVP, reduced scope, or delivery posture.
-Report the detected project type, technology signals, verification commands, and
-monorepo roots. Pass an explicit `project_type` or `stack` only when repository evidence
-or an owner decision supports the override; MCP preserves both detection and selection.
-
-## Resume safely
-
-When `.ultra/` exists, call `task.init_project` with `resume: true`. It must preserve
-existing artifacts, create a pre-migration backup when needed, upgrade the schema,
-install only missing assets, and return the durable workflow ids and exact route.
-
-For projection-only state, execute only the backup-first migration command returned by
-the structured error. For a `migrated` compatibility row, call `baseline.start` with a
-new brownfield id and `replace_migrated: true`; never treat migration as owner approval.
-
-Replacing a healthy baseline requires a new id plus `replace_ready: true` and explicit
-`replacement_authorization`. Preserve corrupt DB, WAL, SHM, and backups; use the
-documented restore or rebaseline command only after the owner selects that destructive
-recovery path.
-
-## Follow durable initialization state
-
-Read the returned init and research runs with `workflow.get`.
-
-- `inspect-authority`: `task.init_project` records the bounded repository and existing
-  Ultra evidence it inspected.
-- `classify-repository`: `task.init_project` records classification, detected signals,
-  selected scope, and supported overrides.
-- `scaffold-authority`: `task.init_project` creates or resumes DB authority and installs
-  only missing scaffold assets.
-- `establish-baseline`: research completion, `baseline.record`, and owner-approved
-  `baseline.converge` establish the evidence-backed authority.
-- `verify-initialization`: convergence re-reads baseline, init, research, repository,
-  verification, and output health before completing initialization.
-
-The first three steps are deterministic writes owned by `task.init_project`; the final
-two are completed atomically by successful baseline convergence. Do not mark or emulate
-these transitions in Prompt text or projection files.
-
-- Greenfield starts a `full` research run.
-- Brownfield starts an `adoption` research run.
-- Both modes require all seventeen research steps before baseline convergence.
-- A migrated project remains routed to re-adoption before research can authorize work.
-
-Continue through `ultra-research`. Research completion records output digests; then
-`baseline.record` captures current scope, revision, discovery/product/architecture
-specs, source and runtime evidence, actual verification, unknowns, gaps,
-classification, and external provider metadata references.
-
-Call `baseline.converge` only after explicit owner approval. The MCP rejects missing
-research, missing discovery/product/architecture refs, stale evidence, revision or
-worktree drift, unaccepted known failures, blocking unknowns, and blocking gaps. A
-successful convergence atomically marks the baseline ready and completes the init run.
-
-## Recovery
-
-- Record deterministic blockers on the current workflow; never create a parallel run.
-- Use `system.doctor` repair only for supported schema, projection, session, incident,
-  archive, or legacy workflow-provenance recovery. A recovered legacy change workflow
-  remains blocked for real baseline evidence; repair cannot invent research or approve
-  a baseline.
-- Treat context budgets as advisory. Missing authority, evidence, output, or approval
-  is blocking.
-- Store only references to external memory and code-graph providers.
-
-## Completion
-
-Read `baseline.get`, `workflow.get`, and `system.doctor` after convergence. Report
-classification evidence, scope, revision, worktree snapshot, migration backups,
-research run and output health, verification, gaps, approval, and one route.
-
-Initialization is complete only when the baseline is `ready`, the init workflow is
-`completed`, the research workflow is `completed`, and
-`baseline.research_run_id` names that exact research run with healthy outputs. Route
-every newly converged or already initialized baseline through `ultra-change`; planning
-starts only after that command persists a complete Change Contract, profile, and
-research disposition. Otherwise return the exact current workflow step or blocker.
+# Initialize project authority
+
+Initialization is a bounded setup capability. It creates or repairs the repository and
+Ultra authority; it does not perform product research, approve a baseline, or choose
+the next semantic workflow.
+
+## Inspect before mutation
+
+1. Identify the repository root, existing `.ultra` state, Git state, meaningful source,
+   monorepo boundaries, and current owner request.
+2. If `.ultra/state.db` exists, run `system.doctor` read-only and resume with
+   `task.init_project` only when its report permits it.
+3. Otherwise call `task.init_project` with `mode: "auto"`, the project name, and an
+   explicit scope only when the repository contains multiple plausible roots.
+4. Leave `git_mode` as `auto` unless the user explicitly requires a non-Git workspace.
+
+Use repository evidence to classify:
+
+- `greenfield`: no meaningful delivered application behavior is present;
+- `brownfield`: source, runtime, API, data, deployment, or tests describe an existing
+  maintained system;
+- `migrated`: older Ultra authority was preserved but is not a trusted baseline.
+
+The model may override an automatic classification only with evidence or an explicit
+user decision. Classification must not infer product scope, an MVP, or a release plan.
+
+## Interaction boundary
+
+Read `../ultra-think/references/decision-dialogue.md` before asking a material question.
+Inspect observable facts yourself. Use the host's native question UI when available and
+plain direct interaction otherwise. Ask only when repository scope, replacement of
+healthy authority, destructive recovery, or another material owner decision is truly
+unresolved. Normalize clear intent already present in the request without asking again.
+
+## Deterministic initialization contract
+
+`task.init_project` owns these steps:
+
+1. `inspect-authority`
+2. `classify-repository`
+3. `scaffold-authority`
+4. `verify-initialization`
+
+The operation must:
+
+- create or migrate `.ultra/state.db` with a backup before schema migration;
+- install only missing scaffold assets on resume;
+- preserve existing artifacts and unrelated work;
+- preserve an existing Git repository and HEAD;
+- initialize Git and a safe `.gitignore` entry when Git is absent;
+- report an unborn repository as `initial_commit_required` without manufacturing a
+  commit, remote, tag, or push;
+- read back the created DB, classification, projection, and Git result before
+  completing the init workflow.
+
+Projection-only projects must use the exact backup-first migration command returned by
+the runtime. A migrated compatibility baseline requires a new brownfield adoption with
+`replace_migrated: true`. Replacing a healthy baseline requires explicit replacement
+authority. Corrupt DB, WAL, SHM, and backups must be preserved until the user chooses a
+documented recovery operation.
+
+## Completion and handoff
+
+Initialization is complete when the init workflow is `completed`, the current schema is
+healthy, the scaffold is readable, and repository classification and Git state are
+durable. Research status may still be `not_started`; that is not incomplete init.
+
+Read the returned `allowed_transitions` and `required_transition`:
+
+- a required transition represents a hard recovery invariant and must be followed;
+- otherwise the host model recommends among the allowed capabilities using the user's
+  goal and current evidence;
+- start `ultra-research` only when the user invoked it or the host selects it after init.
+
+Report classification, scope, schema and backup result, Git state, init workflow id,
+baseline state, and allowed transitions. Do not claim that a baseline is ready until a
+separate research/adoption workflow has recorded and converged it.