ultra-builder-pro-cli 0.15.0 → 0.17.0

package/skills/ultra-status/SKILL.md

@@ -1,60 +1,54 @@
 ---
 name: ultra-status
-description: Report authoritative Ultra project health, baseline, workflow position, task/session progress, evidence freshness, blockers, and one deterministic next action. Use when the user asks what is complete, blocked, stale, or next in an Ultra project.
+description: Read authoritative Ultra health, workflows, decisions, changes, tasks, evidence freshness, and valid transitions. Use when the user asks what is complete, blocked, stale, or currently possible.
 ---
 
-# Route from authoritative state
+# Report authoritative state
 
-This workflow is read-only. Never reconstruct status from prose or generated task
-projections.
+This Skill is read-only. Never fall back to generated task JSON, prose, or context
+frontmatter when DB authority is missing or degraded.
 
-## Read order
+## Read
 
-1. Call `system.doctor` with repair disabled.
-2. Call `baseline.get` for classification, readiness, revision, worktree, spec digests,
-   research provenance, gaps, and blockers.
-3. Call `workflow.list`, then `workflow.get` for every active, blocked, or ready run.
-4. Call `change.breadcrumb`, `change.list`, `task.list`, and `session.list`.
-5. Inspect current Git branch, full HEAD, and worktree without mutation.
-6. Read test, review, and delivery artifacts only when referenced by DB workflow state;
-   compare their recorded digest and revision with current authority.
+1. Run `system.doctor` without repair.
+2. Read baseline classification, revision, worktree, research provenance, gaps, and
+   health.
+3. Read current decision state without exposing hidden future questions.
+4. Read active, blocked, and ready workflows and their current steps.
+5. Read breadcrumb, changes, tasks, sessions, and current Git state.
+6. Read test, review, and delivery artifacts only through DB references and verify
+   their digests and revisions.
 
-If state is unreadable, report that panel unavailable and route to `ultra-doctor`.
-Never fall back to generated task JSON, raw SQLite queries, or context frontmatter.
+If authority is unreadable, report the unavailable panel and the required doctor or
+init transition. Do not mutate, compile context, repair, or release.
 
-## Choose one route
+## Interpret transitions
 
-Prefer the breadcrumb and durable workflow position:
+MCP reports:
 
-- state integrity, schema, projection, or installed-asset failure: `ultra-doctor`;
-- missing project or migrated compatibility authority: `ultra-init`;
-- active/blocked research: `ultra-research` at its exact `current_step`;
-- ready research with unconverged baseline: finalize research, record, approve, and
-  converge through `ultra-research`;
-- active plan/change/dev/test/review/deliver run: its matching workflow at the exact
-  step or blocker;
-- ready baseline with no change: `ultra-change` to persist the requested outcome before
-  any planning;
-- archived change with fresh evidence: report completion without inventing more work.
+- `allowed_transitions`: mechanically valid capabilities;
+- `required_transition`: the sole recovery route only when a hard invariant permits no
+  safe alternative.
 
-Context-size warnings are advisory. Missing authority, stale required refs or outputs,
-incomplete task contracts, failed evidence, unresolved learning, and missing approval
-are blockers.
-
-## Output
+The host model recommends among allowed transitions using the user's current goal,
+workflow evidence, and cost of interruption. Do not present the recommendation as DB
+authority. A healthy project may validly allow research, change, thinking, or status at
+the same time.
 
 Report:
 
 ```text
-Ultra: <healthy|degraded> · <branch>@<head> · worktree <clean|dirty>
+Ultra: <healthy|degraded> · <branch>@<head|unborn|non-git> · worktree <state>
 Baseline: <mode>/<status> · research=<run/status> · gaps=<open>/<blocking>
-Workflow: <kind/id/status> · step=<current|finalize> · outputs=<fresh|stale>
+Workflow: <kind/id/status> · step=<current|complete> · outputs=<fresh|stale>
+Decision: <current|checkpoint|none>
 Change: <id/status|none> · Task: <id/status|none> · Sessions: <active>
-Evidence: test=<state> · review=<two axes> · delivery=<state>
-Blockers: <specific codes or none>
-Warnings: <advisory codes or none>
-Next: <one exact action>
+Evidence: test=<state> · review=<axes> · delivery=<state>
+Blockers: <codes or none>
+Warnings: <codes or none>
+Allowed transitions: <capabilities>
+Required transition: <capability or none>
+Host recommendation: <capability and concise rationale>
 ```
 
-Separate verified facts, inferences, and unavailable evidence. Do not modify state,
-compile context, repair, or release from this Skill.
+Separate verified facts, host inference, and unavailable evidence.

package/skills/ultra-test/SKILL.md

@@ -1,52 +1,65 @@
 ---
 name: ultra-test
-description: Verify completed Ultra tasks and one current change through independent acceptance, regression, build, public-seam, failure, and recovery evidence. Use when implementation needs a current test gate before review, convergence, or delivery.
+description: Independently verify an Ultra task set or change with an evidence-backed, risk-selected test profile. Use when implementation or current acceptance and recovery evidence needs independent verification.
 ---
 
-# Verify the current change
-
-Testing is independent checking. Do not reuse the implementer's conclusions as proof
-or use generated task JSON as authority.
-
-## Bind and execute
-
-1. Read `system.doctor`, `change.breadcrumb`, authoritative tasks, completed dev runs,
-   current HEAD/diff, and prior test report freshness.
-2. Resume or start a `test` workflow linked to the change and optional task. Record
-   `bind-scope` with the exact revision, task set, and acceptance ids.
-3. Compile `change.context` for `check`; record `compile-context` only when required
-   refs and DB-backed execution contracts are ready, with the immutable context
-   manifest as the step output.
-4. Map each accepted claim to an executable command or a specific bounded manual
-   observation. Record `map-acceptance`.
-5. Run repository-native focused and regression tests, applicable type/lint/build
-   checks, public-seam acceptance, and material error/recovery/security checks. Record
-   `execute-checks` and `verify-public-seam` with commands and observed results.
-
-Use real boundaries where practical. A test double is acceptable at a costly or
-nondeterministic external boundary only when the report explains why it preserves the
-contract. Reject tautologies, hidden skips, weakened assertions, and unconsumed code.
-
-## Report and converge
-
-Write `.ultra/reports/tests/<workflow-id>.json` atomically using
-`ultra-test-report-v1`: bind the full HEAD and worktree digest, change and exact task
-ids, the recorded checking-context digest, acceptance
-mapping, exact command results, public seams, failures, recovery evidence, run count,
-timestamp, and blocking issues. Populate every `verification_dimensions` entry:
-acceptance, regression, integration, static analysis, build, performance, security,
-and recovery. Use `not_applicable` only with a concrete rationale; `not_run` cannot
-support a passing gate. For an incident or any bugfix task, also record one
-deterministic `regression_signal` with the exact command, expected red symptom,
-observed red and green results, duration when known, and evidence. `passed` is true only when every recorded command and
-required public seam passes with no blocking issue at that exact checkout.
-
-Record `write-report` with the report output so MCP stores its digest. Re-read the file,
-HEAD, task set, and breadcrumb; record `verify-test-gate`, then call
-`workflow.complete`. MCP derives the durable test summary from the report rather than
-trusting a Prompt claim. A malformed, mismatched, changed, or stale report blocks
-completion.
-
-Return the workflow id, revision, pass/fail result, exact checks, verified seams,
-blocking failures, report path/digest, and one route to fix, `ultra-review`, or
-`ultra-deliver`.
+# Verify current behavior
+
+Testing is independent checking. Do not reuse implementation conclusions or generated
+projections as proof.
+
+## Bind scope
+
+1. Read doctor, change, breadcrumb, decisions, task and dev evidence, current checkout,
+   and prior report freshness.
+2. Resume or start a test workflow bound to the exact change and optional task.
+3. Record `bind-scope`, then compile `change.context` for `check` and record its
+   immutable manifest under `compile-context`.
+4. Record `map-acceptance` after mapping every accepted claim to an executable check
+   or bounded observable seam.
+
+## Select verification by risk
+
+The model selects from:
+
+- acceptance;
+- regression;
+- integration;
+- static analysis;
+- build;
+- performance;
+- security;
+- recovery.
+
+Acceptance is always selected. Select other dimensions when the change, repository, or
+failure mode makes them material. Record excluded dimensions and concrete rationales in
+`verification_profile`; omission without a rationale is invalid. A selected dimension
+must be `pass`, `fail`, or `not_run`; `not_run` cannot support a passing gate.
+
+Run repository-native commands and real boundaries where practical. Test doubles are
+acceptable only at costly or nondeterministic external boundaries when the report
+explains the preserved contract. Do not weaken assertions, hide skips, or validate
+unconsumed code.
+
+For an incident or bugfix, record one deterministic red-to-green `regression_signal`.
+When evidence reveals a material product or recovery choice, use the host's native
+question UI and decision protocol; testing must not choose the desired outcome.
+
+## Report
+
+Write `.ultra/reports/tests/<workflow-id>.json` with
+`ultra-test-report-v1`, binding:
+
+- change, exact task ids, HEAD, worktree digest, and checking-context digest;
+- acceptance mapping, commands, public seams, failures, and recovery evidence;
+- `verification_profile` and the selected `verification_dimensions`;
+- regression signal when required;
+- run count, timestamp, blockers, and evidence-derived `passed`.
+
+Record `execute-checks`, `verify-public-seam`, and `write-report`, then re-read the
+report and current checkout before `verify-test-gate`. `workflow.complete` derives its
+summary from the report and rejects stale, malformed, or contradictory evidence.
+
+Return the profile, exact results, verified seams, blockers, report digest, workflow
+state, and allowed transitions. The host decides whether a broader review, more
+implementation, or delivery is appropriate.

package/skills/ultra-think/SKILL.md

@@ -1,51 +1,51 @@
 ---
 name: ultra-think
-description: Produce an evidence-bounded recommendation or diagnosis for a consequential technical or product question. Use when the decision has material tradeoffs, uncertainty, or failure risk that benefits from explicit stress testing.
+description: Resolve a consequential product, architecture, or recovery question through evidence-first reasoning and adaptive user alignment. Use when a material decision cannot be derived safely from accepted intent and current evidence.
 ---
 
-# Analyze a consequential question
-
-Use the smallest reasoning structure that resolves the user's actual decision. Answer
-simple questions directly; do not turn every request into a framework exercise.
-
-## Workflow
-
-1. State the decision, observed symptom, or disputed claim and the constraints that
-   could change the answer. Ask only for missing information that materially affects
-   the result.
-2. Gather evidence from the most authoritative available source:
-   - current checkout and runtime for repository claims;
-   - official primary documentation for product or API behavior;
-   - current web sources for unstable external facts.
-3. Separate verified facts, evidence-backed inferences, and unresolved assumptions.
-   Cite the supporting file, command, runtime result, or source near each consequential
-   claim.
-4. For a decision, compare only credible alternatives. Do not invent a fixed number of
-   options or assign arbitrary numeric scores. Name the criteria that actually drive
-   the choice and explain the tradeoffs.
-5. For a diagnosis, form falsifiable hypotheses and identify the smallest observation
-   that distinguishes them. Do not recommend implementation before the earliest
-   incorrect state is supported by evidence.
-6. Stress-test the leading conclusion with the techniques that fit the problem:
-   - strongest counterargument;
-   - likely failure scenario and recovery;
-   - load-bearing assumption;
-   - meaningful second-order effect.
-7. Return the recommendation or diagnosis, evidence, uncertainty, what would change
-   the conclusion, and the smallest verification step.
-
-## Output
-
-Adapt the response to the question. Include:
-
-- the conclusion first;
-- the decisive evidence and tradeoffs;
-- unresolved uncertainty without false precision;
-- one concrete verification or follow-up action.
-
-Use a comparison table only when several alternatives share the same decision
-criteria. Comparisons are an analysis tool, not a required output section.
-
-This skill is read-only unless the user separately authorizes writing an analysis
-artifact. It does not update Ultra state, implement the recommendation, or replace an
-independent review.
+# Align without suppressing model judgment
+
+Thinking is an optional reasoning capability, not a mandatory stage. Answer
+self-contained questions directly. Use durable decision state only when a
+project-bound choice must survive interruption or gate later work.
+
+## Reason first
+
+1. Define the actual decision or disputed claim and the constraints that can change
+   its answer.
+2. Inspect current authority, source, runtime, tests, and primary documentation before
+   asking the user for facts.
+3. Separate verified fact, evidence-backed inference, accepted intent, delegated
+   implementation judgment, and unresolved owner choice.
+4. Form credible alternatives only when alternatives materially help the decision.
+   Evaluate them against the real constraints; do not impose a fixed option count,
+   scoring system, or confidence percentage.
+5. Stress-test the leading answer with its strongest counterexample, likely failure
+   path, recovery, and load-bearing assumption.
+
+## Interact adaptively
+
+Read `references/decision-dialogue.md`. If the user already gave a clear decision,
+normalize and use it without asking for confirmation. If the decision is reversible
+and delegated by the accepted contract, decide it and explain the reasoning.
+
+When owner authority is required, use the host's native question UI when available.
+Ask the earliest dependent decision with a recommendation, decisive evidence, and the
+effect of the answer. Keep cognitive load small; group only independent, simple facts.
+Do not expose the hidden decision queue.
+
+For durable project decisions, use `decision.thread_start`, `decision.open`, and the
+appropriate resolve, delegate, defer, or supersede transition. Store normalized
+decisions and artifact references, never transcripts or internal reasoning.
+
+Prepare and confirm a checkpoint only when the decision changes a durable contract or
+artifact and a checkpoint is needed for recovery. Do not add a ceremonial approval
+gate to an already explicit user instruction or a reversible implementation detail.
+
+## Return control
+
+Return the conclusion, decisive evidence, material uncertainty, and affected
+contracts. Re-read the invoking workflow or breadcrumb and recommend one of its
+`allowed_transitions`; follow `required_transition` only when a hard invariant leaves
+no alternative. Thinking does not implement code, mutate unrelated state, or invent a
+canonical next action.

package/skills/ultra-think/references/decision-dialogue.md

@@ -0,0 +1,106 @@
+# User-agent interaction contract
+
+Use this protocol only when evidence and accepted intent do not resolve a material
+choice. The goal is shared understanding with low cognitive load, not a mandatory
+interview.
+
+## Authority split
+
+The user owns:
+
+- product intent and accepted outcomes;
+- material scope, compatibility, security, cost, and recovery tradeoffs;
+- authorization for destructive or external effects.
+
+The model owns:
+
+- fact finding and synthesis;
+- reversible implementation detail inside accepted constraints;
+- research coverage and risk-profile recommendations;
+- technical decomposition, verification selection, and route recommendation.
+
+MCP owns durable state, evidence references, digests, freshness, locks, valid
+transitions, and hard invariants. It does not choose semantic intent.
+
+## Decide whether to ask
+
+Before asking:
+
+1. Inspect repository authority, source, runtime, tests, and relevant primary sources.
+2. Separate `Observed`, `Verified`, `Decided`, `Delegated`, and `Unknown`.
+3. Resolve evidence-answerable unknowns autonomously.
+4. Normalize clear decisions already present in the user's current request.
+5. Ask only if the remaining choice changes accepted intent, public behavior,
+   compatibility, security, material cost, external effects, or recovery.
+
+Do not ask about a reversible implementation detail already delegated by the contract.
+If the user does not know, recommend a bounded validation action instead of forcing a
+guess.
+
+## Choose interaction depth
+
+- `guided`: material initial product or major-change choices;
+- `fast`: only one-way-door or costly choices in routine work;
+- `autonomous`: reversible choices explicitly delegated by the user;
+- `diagnostic`: gather discriminating evidence before asking about recovery.
+
+Infer the depth from the request and risk. Do not ask a meta-question about mode unless
+that choice itself changes the outcome.
+
+## Present questions
+
+Use the host-native structured question surface declared by the installed interaction
+contract when it exists. If that surface is unavailable in the current mode, ask one
+concise direct question instead of inventing a tool or foreign-host syntax.
+
+Ask one question only for a dependent decision. STOP is mandatory after presenting
+that question: do not perform writes whose meaning depends on an unanswered choice.
+
+For one dependent decision, present:
+
+```text
+Decision: <question>
+Why now: <decision effect>
+Recommendation: <choice> — <decisive reason>
+Alternatives: <only credible alternatives and their net tradeoff>
+```
+
+Ask dependent decisions one at a time. A host may group up to three independent,
+low-cognitive-load facts when seeing them together improves consistency. Never dump a
+questionnaire, hidden queue, or every research area.
+
+The question tool or direct question ends the current interaction naturally.
+
+## Persist only when recovery needs it
+
+For a project-bound material decision:
+
+1. Call `decision.list` and resume a matching active decision thread, or use
+   `decision.thread_start` for one new baseline-, change-, or workflow-bound thread.
+2. Use `decision.open` for only the current decision with evidence refs, recommendation, credible
+   alternatives, effects, and blocking consequence.
+3. After the answer:
+   - `decision.resolve` for a direct user choice;
+   - `decision.delegate` for explicit model delegation;
+   - `decision.defer` with consequence and revisit condition;
+   - `decision.supersede` when accepted intent actually changed.
+4. Use `decision.checkpoint` only for the digest-bound recovery boundary described
+   below.
+
+Keep fact acquisition autonomous and decision authority explicit.
+Never store raw prompts or transcripts; store normalized decisions, not internal
+chain of thought.
+Do not require a redundant confirmation after an unambiguous answer.
+
+Use a checkpoint only when a coherent decision cluster changes a durable contract or
+artifact and interruption recovery requires a digest-bound boundary. Present the
+compact effect once, obtain any missing approval, update the artifact, and confirm its
+digest. Do not create ceremonial checkpoints for routine implementation detail or an
+already explicit current instruction.
+
+## Return to the capability graph
+
+After alignment, re-read the invoking workflow and breadcrumb. A
+`required_transition` is authoritative only for a hard invariant. Otherwise the host
+model recommends among `allowed_transitions` based on the user's goal and current
+evidence. Do not persist that semantic recommendation as MCP authority.

package/spec/cli-protocol.md

@@ -114,6 +114,15 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `change.learning_resolve` | `change learning-resolve`   | 10    | mcp     |
 | `change.converge`         | `change converge`           | 9     | mcp     |
 | `change.archive`          | `change archive`            | 9     | mcp     |
+| `decision.thread_start`   | `decision thread-start`      | 16    | mcp     |
+| `decision.get`            | `decision get`               | 16    | any     |
+| `decision.list`           | `decision list`              | 16    | any     |
+| `decision.open`           | `decision open`              | 16    | mcp     |
+| `decision.resolve`        | `decision resolve`           | 16    | mcp     |
+| `decision.delegate`       | `decision delegate`          | 16    | mcp     |
+| `decision.defer`          | `decision defer`             | 16    | mcp     |
+| `decision.supersede`      | `decision supersede`         | 16    | mcp     |
+| `decision.checkpoint`     | `decision checkpoint`        | 16    | mcp     |
 | `workflow.start`          | `workflow start`            | 13    | mcp     |
 | `workflow.get`            | `workflow get`              | 13    | any     |
 | `workflow.list`           | `workflow list`             | 13    | any     |
@@ -126,12 +135,15 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 Current executable maintenance surfaces are `task init-project`,
 `session close|get|list|admission|heartbeat|subscribe|reap`, `status`, `db`,
 `migrate`, `system doctor|restore|rebaseline`, and `legacy-memory`. In particular, `task create|update|list|get`
-and all `change` lifecycle verbs are not CLI fallbacks. Change state must use
+and all `change` and `decision` lifecycle verbs are not CLI fallbacks. Change and decision state must use
 the live MCP server; `system doctor` may additionally be exposed by the
 maintenance CLI because it is the recovery path when MCP startup is degraded.
 `task init-project --resume` preserves existing `.ultra` files and installs only
 missing current scaffold assets. Projection-only state uses the supported
-`migrate --from=4.4 --to=4.5` or `--from=4.5 --to=15.0` transition before resume.
+`migrate --from=4.4 --to=4.5` or the current supported state-schema transition before resume.
+`session close` preserves the worktree by default. `--remove-worktree` delegates to
+the same Git ancestry and dirty-state verifier as MCP and fails with
+`WORKTREE_NOT_INTEGRATED` instead of deleting uncommitted or unintegrated work.
 `system doctor --repair` applies supported schema upgrades with a pre-migration
 backup before mechanical recovery.
 `system restore` requires the exact `REPLACE_CORRUPT_ULTRA_STATE` confirmation and a
@@ -148,3 +160,35 @@ The CLI follows the `version` field of `spec/mcp-tools.yaml`. Adding a new
 flag is a minor bump; renaming or removing a flag, or changing exit-code
 semantics, is a major bump. Major bumps require an entry in
 `docs/PLAN.zh-CN.md §14 Decision log`.
+
+## 7. `ubp-orchestrator`
+
+`ubp-orchestrator execute-plan` consumes the completed and current
+`.ultra/execution-plan.json` and resumes from the first unfinished dependency wave.
+Before creating a session it rejects an empty, malformed, cyclic, duplicate-task, or
+cross-change plan. For change-owned tasks, the plan must exactly match the current DB
+task graph and a healthy completed `plan` workflow; an exported but incomplete or
+stale artifact is not executable. A separate owner approval is present only when a
+material planning decision required it.
+It returns `status: "paused"` when that wave still has non-terminal Ultra tasks and
+does not dispatch later waves. Worktrees are preserved unless `--auto-merge` is
+explicitly supplied and the corresponding change task has an exact completion commit,
+ready dev workflow, and current task review. `run` and `start` are optional queue daemons and additionally require
+`orchestrator.auto_dispatch: true`.
+
+Every execution mode requires a shell-free worker contract:
+
+```json
+{
+  "orchestrator": {
+    "command": "/absolute/path/to/ultra-worker",
+    "command_args": []
+  }
+}
+```
+
+`UBP_ORCH_COMMAND` and a JSON-array `UBP_ORCH_ARGS_JSON` may override that contract.
+The daemon refuses startup without a real executable. Worker exit zero is execution
+evidence only and leaves the Ultra task `in_progress`; failure blocks the task and
+records session-linked circuit-breaker evidence. Worker spawn errors follow the same
+failure path instead of leaving a running lease.