ultra-builder-pro-cli 0.14.0 → 0.15.0

package/skills/ultra-deliver/SKILL.md

@@ -1,87 +1,77 @@
 ---
 name: ultra-deliver
-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.
+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.
 ---
 
-# Converge and deliver
+# Converge and deliver one change
 
-Deliver one baseline or continuous change. Change lifecycle writes use MCP; test,
-review, and delivery reports are evidence artifacts.
+Use host judgment for release scope and authorization. Use Ultra MCP for evidence
+binding, workflow state, convergence, baseline reconciliation, archive recovery, and
+output digests.
 
 ## Bind current evidence
 
-1. Call `baseline.get`, then `change.list`. Bind exactly one relevant change, or the
-   current draft/adopting baseline when this is the initial delivery.
-2. Call `change.breadcrumb`. Context-size warnings are advisory. Ordinary delivery
-   blocks on incomplete baseline adoption, stale execution context, incomplete linked
-   tasks, or unresolved readiness. An explicitly approved break-glass incident may
-   continue while baseline adoption is incomplete.
-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.
-
-## Reconcile the baseline
-
-Call `change.get` for authoritative learning candidates.
-
-- 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.
-
-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.
-
-For an initial baseline without a change, call `baseline.record`, obtain explicit owner
-approval, and call `baseline.converge`. Do not simulate initial delivery through a null
-change record.
-
-## Verify the release candidate
-
-Use a clean, reviewed release commit. Show any remaining diff and obtain explicit
-authorization before staging or committing. Never stage unrelated user changes.
-
-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.
-
-Compile final change context at the release commit with the convergence gate. It must
-be ready before calling `change.converge`.
-
-## Converge and archive
-
-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.
-
-Resolve named blockers, rerun invalidated gates, then call `change.archive` with the
-summary and baseline updates or an exact no-change reason. Ordinary archive
-reconciliation refreshes the authoritative baseline revision and digests, rechecks
-health, and rolls back state and artifacts when any tracked digest or revision remains
-stale.
-
-For a break-glass incident, verify that archive returned `baseline_bypass: true` and
-created the open reconciliation gap on the current baseline. Report incident delivery
-separately from project baseline readiness. Resolve that gap through `ultra-init`
-before starting ordinary work.
-
-## Optional release
-
-Only when release authorization is in scope:
-
-1. determine the semantic version from compatibility impact;
-2. update version and changelog;
-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.
-
-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 local and remote evidence agree and the worktree has no
-unexplained scope. A local version bump is not publication 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`.
+
+Evidence from another revision, task set, change, or stale output is invalid. An
+approved break-glass incident follows only its recorded recovery contract.
+
+## Reconcile and verify
+
+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`.
+
+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.
+
+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.
+
+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.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.
+
+## Release only with authority
+
+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.
+
+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.
+
+Return workflow id, archive and baseline state, evidence digests, commit/release facts,
+recovery notes, residual risks, and one next route.

package/skills/ultra-deliver/references/baseline-reconciliation.md

@@ -0,0 +1,20 @@
+# Baseline reconciliation manifest
+
+Write a JSON file inside `.ultra/changes/active/<change-id>/` with
+`$schema: "ultra-baseline-reconciliation-v1"`.
+
+Bind `change_id`, `baseline_id`, and `baseline_updates` exactly to the archive request.
+Include:
+
+- `semantic_changes`: stable id, `add` or `update`, project-relative `source_ref` using
+  `path#anchor`, the prior baseline digest or `null`, and the current file digest;
+- `resolved_gap_ids`: existing baseline gaps closed by this delivery;
+- `resolved_unknowns`: exact existing unknown summaries closed by this delivery;
+- `verification`: named checks with exact commands, `pass`, and bounded evidence;
+- `semantic_no_change_reason`: an evidence-backed reason when `baseline_updates` is
+  empty.
+
+Every updated file needs a semantic change record and current anchor. The before digest
+must match baseline authority and the after digest must match the file. Keep the
+manifest with the change so archive recovery can replay the same transaction after an
+interrupted filesystem move.

package/skills/ultra-dev/SKILL.md

@@ -1,63 +1,58 @@
 ---
 name: ultra-dev
-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.
+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.
 ---
 
-# Execute one vertical slice
-
-Drive one task from `pending` to `completed` without widening its contract silently.
-
-## Authority and recovery
-
-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`.
-
-Read `change.breadcrumb` when a change is active. Stale context, blocked readiness,
-unknown documentation impact, or a HEAD mismatch blocks implementation.
-Baseline-adoption and context-size warnings do not block an active slice. Address
-them when practical without dropping required evidence or arbitrarily changing a
-threshold. Ordinary convergence requires approved baseline availability; revision
-and tracked-spec health are reconciled and verified at archive. An approved
-break-glass incident may finish recovery first and must leave a blocking baseline
-reconciliation gap.
-
-## Workflow
-
-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 keep
-   the discovery only in transient conversation context.
-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.
+# 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.
+
+## 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.
+
+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.
+
+Return the task outcome, public seam, changed paths, exact checks, review results,
+workflow id, session state, residual risks, and one next route.

package/skills/ultra-doctor/SKILL.md

@@ -1,86 +1,55 @@
 ---
 name: ultra-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.
+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.
 ---
 
-# Diagnose and recover the Ultra runtime
+# Diagnose before repair
 
-Default to read-only diagnosis. Repair only after the user explicitly authorizes it.
+Default to read-only diagnosis. Call `system.doctor` with repair disabled and inspect:
 
-## Project-state diagnosis
+- 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.
 
-Call `system.doctor` with `{ "repair": false }` and inspect:
+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.
 
-- SQLite integrity and required tables;
-- open structured incidents;
-- event and projection cursor lag;
-- failed or interrupted projection jobs;
-- interrupted archive journals;
-- orphan sessions;
-- missing active-change artifact roots;
-- missing, incomplete, or stale project baseline readiness and specification digests;
-- the boundary to separately installed memory and code-graph providers.
+## Route failures
 
-Do not infer health from generated task JSON. Do not mutate external provider state,
-delete artifacts, or collect memory during diagnosis.
+- 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.
 
-## Interpret failures
+## Explicit project repair
 
-- 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.
-- Missing or incomplete baseline evidence routes to `ultra-init`. Doctor repair does
-  not approve a baseline, accept known-red verification, or invent adoption evidence.
-  Baseline readiness is an advisory workflow check, not state-database corruption and
-  not a reason for doctor repair.
-- A compatibility `migrated` baseline requires explicit brownfield re-adoption and
-  cannot authorize ordinary changes.
-- A corrupt SQLite file requires preserving the file, locating a verified backup, and
-  an explicit restore-or-rebaseline decision.
+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.
 
-## Explicit repair
+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.
 
-After authorization, call `system.doctor` with `{ "repair": true }` or use the
-installed `ultra-tools system doctor --repair` fallback. The CLI applies supported
-schema upgrades to the packaged current schema and reports a pre-migration backup path. Doctor then
-creates a second timestamped backup before runtime recovery.
+## Installed host failures
 
-Repair is limited to documented schema upgrades, archive-journal completion,
-reconciling orphan sessions, consuming staleness events, requeueing interrupted or
-failed projections, and regenerating projections from authoritative state. If either
-backup fails, stop. Always inspect the post-repair report; a completed repair action
-does not imply healthy state.
+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.
 
-If SQLite integrity prevents doctor from opening authority, preserve the original
-database, WAL, and SHM. After the owner chooses a recovery path, either run
-`ultra-tools system restore --backup <managed-backup> --confirm
-REPLACE_CORRUPT_ULTRA_STATE` or run `ultra-tools system rebaseline --project-name
-<name> [--scope <path>] --confirm REBASELINE_CORRUPT_ULTRA_STATE`. Both commands
-must report the recovery backup directory. A failed command must restore the
-original authority, sidecars, and task projection before returning an error.
-
-## Installed-plugin failures
-
-When a hook points to a missing installed file:
-
-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.
-
-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 failing authority checks separately from
-baseline warnings, incident identifiers, cursor lag, whether repair ran, the backup
-path, and each unresolved action with its owner.
-
-Do not fix application code, delete state, reset Git, close healthy sessions, or
-install and repair external providers through this workflow.
+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.