ultra-builder-pro-cli 0.13.0 → 0.15.0

package/skills/ultra-change/SKILL.md

@@ -1,84 +1,69 @@
 ---
 name: ultra-change
-description: Open or resume a bounded continuous change and connect its intent, delta, decisions, context, and executable tasks. Use when maintaining or extending an Ultra project after its baseline exists.
+description: Open or resume one bounded post-baseline change and connect its intent, delta, task plan, fresh context, and convergence evidence. Use when handling daily feature work, fixes, redesigns, or incidents after an Ultra baseline exists.
 ---
 
-# Open or resume a continuous change
+# Maintain one continuous change
 
-Keep post-delivery work aligned through a delta, implementation, learning, and
-convergence loop.
+Use Ultra MCP for lifecycle writes. Keep external memory and code-graph content in
+their providers; Ultra stores references only.
 
-## Authority boundary
+## Bind or create
 
-Use Ultra MCP tools for change and task lifecycle writes. Do not write raw SQLite or
-mutate generated task and context projections. External memory or code-graph systems
-own their payloads; Ultra stores only provider references supplied by the user or host.
+1. Read `system.doctor`, `baseline.get`, `change.list`, and `change.breadcrumb`.
+2. Resume the change matching the requested outcome. Require an id when several could
+   match; do not create a duplicate packet.
+3. New ordinary work requires a ready baseline. An incident on unhealthy authority
+   requires an explicit `baseline_bypass` reason and approver. Never infer approval
+   from urgency.
+4. Read `references/change-contract.md`. Persist the complete outcome, executable
+   acceptance, non-goals, public seams, recovery contract, unresolved decisions,
+   documentation impact, profile rationale, material risk flags, and research
+   disposition. Do not derive these fields from a title or free-form intent later.
+5. Select `quick`, `standard`, `major`, or `incident` from current scope and risk.
+   Escalate a proposed quick change when its contract carries material risk or research.
+   Then call `change.create` or `change.update` and read the normalized record back.
+6. Resume or start the linked `change` workflow with `workflow.list`/`workflow.start`.
 
-## Workflow
+## Record the change workflow
 
-1. Call `baseline.get`. State integrity failure routes to `ultra-doctor`.
-   - Create ordinary work only when the baseline is healthy and `ready`.
-   - Resume a change that was already active when baseline drift appears; record the
-     condition as a warning and restore baseline readiness before ordinary convergence.
-   - Create an `incident` on an unhealthy baseline only with an explicit
-     `baseline_bypass` containing the reason and approver.
-   - Route every other missing, migrated, incomplete, or stale baseline to `ultra-init`.
-2. Call `change.list` and `change.breadcrumb`.
-   - Resume the single change that matches the requested outcome.
-   - Require an explicit id when several changes could match.
-   - Create a new change only when no existing packet represents the same outcome.
-3. Capture the observable outcome, acceptance, non-goals, affected public seam,
-   documentation impact, and unresolved decisions.
-4. Classify the change as `quick`, `standard`, `major`, or `incident`. Ask only for a
-   material product, risk, or recovery decision that repository evidence cannot answer.
-5. Call `change.create` with a stable kebab-case id, or `change.update` when resuming.
-   For incident break-glass, persist the approved reason in `baseline_bypass`; never
-   infer approval from urgency.
-6. Write the minimum artifact set required by the classification:
+Use `workflow.step` as evidence becomes durable:
 
-   ```text
-   .ultra/changes/active/<change-id>/
-     intent.md
-     delta/                 # standard and major
-     plan.md                # standard and major
-     diagnosis.md           # incident
-     context-manifest.json  # generated projection
-     spec-learning.json     # generated projection
-     verification.md        # generated projection
-   ```
+- `bind-baseline`: current baseline id, revision, branch, and worktree evidence;
+- `classify-change`: kind and rationale;
+- `record-intent`: intent artifact, acceptance, scope, and resolved docs impact;
+- `plan-change`: completed plan workflow and authoritative task ids;
+- `compile-context`: current task-bound `change.context` manifest and digest;
+- `verify-readiness`: ready breadcrumb with one executable next action.
 
-   Delta files describe differences from the baseline, not a second copy of it.
-   Incident diagnosis records the symptom, earliest bad state, falsifiable
-   hypotheses, evidence, root cause, and recovery boundary.
-7. Create the smallest executable vertical slice with `task.create`. Each task needs
-   one outcome, bounded ownership, dependencies, a live public seam, an exact
-   verification command, and documentation impact.
-8. Compile `change.context` for the next role and gate. Include only required
-   references and the task execution contract. Missing required references, digest or
-   HEAD drift, an absent public seam or verification command, and unknown
-   documentation impact are blockers. File count, token estimate, and context-share
-   thresholds are advisory warnings: narrow reads or split the slice when useful, but
-   never raise a threshold merely to make the warning disappear or refuse necessary
-   incident context.
-9. Call `change.breadcrumb` and return its single next action.
+Standard and major changes keep deltas under
+`.ultra/changes/active/<id>/delta/` and an evidence-linked `plan.md`. Deltas describe
+differences from the baseline; they are not a second baseline. Incidents maintain the
+structured diagnosis artifact and recovery evidence.
 
-## Specification learning
+When `research_disposition.status` is `bounded` or `required`, run `ultra-research`
+with the exact recorded mode and selected steps before planning. Planning is blocked
+until that change-bound research run is complete, current, and selection-equivalent.
+Use `none` only when the Change Contract already has sufficient evidence.
 
-When implementation uncovers a stable requirement, invariant, or public behavior
-missing from the baseline, call `change.learning_propose` with evidence and a target
-document. The proposal does not edit the baseline. It must be approved or rejected,
-and an approved item is marked applied only after the target document is updated and
-verified.
+Use `ultra-plan` to create complete DB-backed task contracts. Recompile
+`change.context` after any task, HEAD, specification, or decision change. The task's DB
+contract is authoritative; Prompt input may not override its seam or verification.
+Required missing or stale refs block. Budget warnings guide narrower context but never
+justify dropping necessary evidence or refusing legitimate work.
 
-## Completion gate
+An ordinary active change remains executable only while its durable `bind-baseline`
+evidence still names the current approved-ready baseline. HEAD, worktree, specification,
+or source-evidence drift created after that binding is advisory until delivery
+reconciliation. Adoption/migration state, missing approval or evidence, blocking gaps,
+and any other structural baseline failure block tasks, context, and later stages. Only
+the recorded incident break-glass authority can bypass that gate.
 
-Do not claim alignment while a material decision is unresolved, documentation impact
-is unknown, context is stale, or the next task is not executable. Ordinary change
-convergence requires a non-migrated `ready` baseline. Normal HEAD or tracked-spec drift
-caused by the active change is reconciled at archive.
+Call `workflow.complete` only after all change workflow steps are current. Return the
+change id, kind, task set, context digest, blockers or warnings, workflow state, and the
+breadcrumb's one route.
 
-An approved break-glass incident may converge and archive while baseline adoption is
-incomplete. Its archive must add an open `baseline_blocker` reconciliation gap owned by
-the recorded approver. Report the incident as closed and the project baseline as not
-ready until that gap is resolved. Every archive declares baseline updates or an exact
-no-change reason; failed ordinary reconciliation rolls back state and artifacts.
+When implementation reveals a stable missing invariant, use
+`change.learning_propose` and the approval/reject/apply transition. Unresolved learning
+blocks delivery. An approved application must bind the declared target anchor, its
+before and after digests, and current evidence before the proposal becomes `applied`.

package/skills/ultra-change/references/change-contract.md

@@ -0,0 +1,36 @@
+# Change Contract and profile
+
+Create one contract before planning. Keep every field specific enough to verify and
+stable enough to survive a fresh session.
+
+## Contract
+
+- `outcome`: one externally observable result.
+- `acceptance`: stable ids with a criterion and exact verification for each accepted
+  behavior.
+- `non_goals`: explicit boundaries that prevent accidental scope growth.
+- `public_seams`: entry points or outputs through which acceptance is observed.
+- `recovery`: a bounded reversal or recovery strategy and its verification.
+- `unresolved_decisions`: stable ids, summary, blocking state, and owner when known.
+
+Resolve every blocking decision before planning. Keep non-blocking uncertainty visible
+in the task and verification contracts.
+
+## Profile
+
+- `quick`: one low-risk task, no material risk flags, and no research dependency.
+- `standard`: a bounded change with multiple tasks or ordinary integration risk.
+- `major`: a broad or consequential change with material contract, migration,
+  authorization, security, multi-module, external-integration, or release impact.
+- `incident`: urgent diagnosis and recovery with a reproducible symptom. Baseline
+  break-glass still requires a recorded approver and recovery contract.
+
+Record a profile rationale and every applicable risk flag. Select the smallest profile
+whose guarantees cover the real blast radius; never use profile labels as estimates.
+
+## Research disposition
+
+Use `none` with a rationale when accepted evidence is sufficient. Use `bounded` or
+`required` with a supported mode and the exact selected semantic steps when product,
+behavior, architecture, deployment, or risk facts remain load-bearing. The recorded
+selection is the planning gate.

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.