ultra-builder-pro-cli 0.16.0 → 0.17.0

package/skills/ultra-test/SKILL.md

@@ -1,58 +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`, active decision state, authoritative
-   tasks, completed dev runs, current HEAD/diff, and prior test report freshness. An
-   open decision or unconfirmed checkpoint blocks testing claims and routes to
-   `ultra-think`.
-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.
-When evidence reveals an unresolved product decision, report the exact consequence and
-route it to the decision dialogue; testing must not silently select the desired result.
-
-## 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`. A failed implementation contract returns to `ultra-dev`; a new owner
-choice returns to `ultra-think`; a passing current change without current aggregate
-review routes to `ultra-review`.
+# 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,65 +1,51 @@
 ---
 name: ultra-think
-description: Resolve a consequential product or technical question through evidence-first analysis or a resumable one-decision-at-a-time owner dialogue. Use when tradeoffs, ambiguity, diagnosis, or failure risk require shared understanding before research, planning, or implementation proceeds.
+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.
 ---
 
-# Align on a consequential question
+# Align without suppressing model judgment
 
-Use the smallest reasoning structure that resolves the user's actual decision. Answer a
-simple self-contained question directly. For a project-bound or multi-turn decision,
-read `references/decision-dialogue.md` and use its durable protocol.
+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.
 
-## Establish evidence
+## Reason first
 
-1. State the decision, observed symptom, or disputed claim and the constraints that
-   could change the answer.
-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. Decide whether the question is now answerable or still requires owner authority.
+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.
 
-## Route the result
+## Interact adaptively
 
-- For an answerable read-only question, return the recommendation or diagnosis,
-  decisive evidence, uncertainty, what would change the conclusion, and one smallest
-  verification step.
-- For a load-bearing owner decision, bind or resume a decision thread, open the one
-  earliest decision, present it using the shared protocol, and STOP.
-- After an answer, normalize it through `decision.resolve`, `decision.delegate`, or
-  `decision.defer`; never store the conversation transcript.
-- At a phase boundary, prepare the checkpoint, obtain approval, bind current artifact
-  digests when project-bound, and only then return control to the invoking workflow.
+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.
 
-## Output
+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.
 
-Adapt the response to the question. Include:
+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.
 
-- the conclusion first;
-- the decisive evidence and tradeoffs;
-- unresolved uncertainty without false precision;
-- one concrete verification or follow-up action.
+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.
 
-Use a comparison table only when several alternatives share the same decision
-criteria. Comparisons are an analysis tool, not a required output section.
+## Return control
 
-Unbound analysis is read-only. A project-bound dialogue may write only decision state
-and explicitly approved checkpoint artifacts. It does not implement the decision or
-replace research, planning, testing, or independent review. After a confirmed
-checkpoint, return to the exact invoking `ultra-init`, `ultra-research`, `ultra-change`,
-`ultra-plan`, `ultra-dev`, `ultra-test`, `ultra-review`, or `ultra-deliver` run and
-current step; never choose a new route from conversation history.
+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

@@ -1,130 +1,106 @@
-# Decision dialogue protocol
+# User-agent interaction contract
 
-Use this protocol when an Ultra workflow reaches a load-bearing owner decision. Keep
-fact acquisition autonomous and decision authority explicit. Do not use it for facts
-that repository, runtime, tests, or primary sources can answer.
+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.
 
-## Select the interaction depth
+## Authority split
 
-- `guided`: ask every unresolved decision that changes accepted product intent, scope,
-  public behavior, security, material cost, compatibility, delivery semantics, or
-  recovery. Use for initial research and major changes.
-- `fast`: ask only unresolved one-way-door or materially expensive decisions. Decide
-  reversible implementation detail inside accepted constraints. Use for bounded daily
-  work.
-- `autonomous`: use only after the owner explicitly delegates reversible decisions.
-  Preserve the delegation, selected result, rationale, and guardrails.
-- `diagnostic`: acquire evidence and distinguish falsifiable hypotheses before asking
-  for a recovery or product decision.
+The user owns:
 
-Do not ask a meta-question about mode when the user's request or current change profile
-already determines the appropriate depth.
+- product intent and accepted outcomes;
+- material scope, compatibility, security, cost, and recovery tradeoffs;
+- authorization for destructive or external effects.
 
-## Separate evidence from decisions
+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 current authority, repository, runtime, tests, and relevant primary sources.
-2. Resolve factual unknowns yourself when evidence is obtainable.
-3. Separate `Observed`, `Verified`, `Decided`, and `Unknown`.
-4. Identify the earliest unresolved decision on which later decisions depend.
-5. Form a private candidate queue, but expose only its current item. Do not dump the
-   backlog, a questionnaire, or every research step.
+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.
 
-If more evidence can resolve the current uncertainty, perform that research first. If
-the user says they do not know, convert the gap into a bounded validation action rather
-than pressuring them to guess.
+## Choose interaction depth
 
-## Bind durable authority
+- `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.
 
-For a project-bound dialogue:
+Infer the depth from the request and risk. Do not ask a meta-question about mode unless
+that choice itself changes the outcome.
 
-1. Call `decision.list` and resume the matching `active` or `checkpoint_ready` thread.
-2. Otherwise call `decision.thread_start` with one baseline, change, or workflow
-   binding, a concise purpose, and the selected mode. Never store raw prompts or
-   transcripts.
-3. Call `decision.open` for exactly one decision. Include:
-   - why it must be decided now;
-   - the evidence-backed recommendation;
-   - zero to three credible alternatives with their net tradeoff;
-   - evidence references;
-   - the contract, artifact, gate, or task effects;
-   - whether deferral blocks progress.
+## Present questions
 
-Do not encode future questions as open decisions. Re-evaluate the next candidate after
-each answer so the dialogue adapts instead of following a static questionnaire.
+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.
 
-## Present one decision and stop
+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.
 
-Use a compact shape adapted to the user's language:
+For one dependent decision, present:
 
 ```text
-Decision <position when known>: <question>
-Why now: <one sentence>
-Recommendation: <choice or next validation> — <reason>
-Options: <only credible alternatives and their net tradeoff>
-Effect: <what this answer changes>
+Decision: <question>
+Why now: <decision effect>
+Recommendation: <choice> — <decisive reason>
+Alternatives: <only credible alternatives and their net tradeoff>
 ```
 
-Ask one question only. Do not combine dependent questions, append a second request, or
-continue into analysis, planning, edits, or another workflow step. End the turn and
-wait. This STOP is mandatory even when the likely answer seems obvious.
-
-## Normalize the answer
-
-On the next turn:
-
-- When the answer is unambiguous, briefly reflect the normalized decision and its
-  durable effect, then call `decision.resolve` with the decision, rationale, and owner.
-- When the user says "you decide", select the reversible result within stated bounds
-  and call `decision.delegate` with the explicit delegation, result, rationale, and
-  guardrails. Never represent delegation as a direct owner decision.
-- When the user defers, call `decision.defer` with the reason, consequence, and revisit
-  condition. A blocking deferral remains a gate.
-- When the answer is ambiguous, ask one clarification for the same decision; do not
-  infer a product choice from tone or partial wording.
-- When evidence or owner intent changes a resolved decision, call
-  `decision.supersede`. Preserve the prior record and open one replacement question.
-
-Do not require a redundant confirmation after a clear answer. The owner can correct
-the compact reflection; phase checkpoint approval is the durable confirmation.
-
-## Checkpoint before projection
-
-After a coherent cluster of decisions or a phase boundary:
-
-1. Call `decision.checkpoint` with `action: "prepare"` and a compact shared
-   understanding. Open or blocking-deferred decisions must prevent preparation.
-2. Present only accepted decisions, unresolved consequences, and the artifacts that
-   will change. Ask for one checkpoint approval and STOP.
-3. After approval, update the target specification, Change Contract, delta, or plan
-   from normalized decisions. Do not write conversation transcripts.
-4. Call `decision.checkpoint` with `action: "confirm"`, owner approval, and the current
-   artifact paths. MCP binds their digests. A change- or workflow-bound thread must
-   bind at least one artifact. When a shared specification will continue evolving,
-   bind a stable decision projection under `.ultra/docs/decisions/<thread-id>.md`
-   instead of a mutable draft that would immediately become stale. Only a standalone
-   baseline thinking thread may use an explicit no-artifact reason.
-5. Re-read the confirmed thread. Only then may the linked workflow complete the gated
-   step or move to another phase.
-
-If a bound artifact changes while the normalized decisions remain valid, prepare the
-same thread again, show the changed effect, obtain one new checkpoint approval, and
-confirm the current digest. Do not invent a replacement decision merely to refresh an
-artifact. If the decision itself changed, use supersession instead.
-
-Start a new thread for a new decision cluster. Supersede an old item only when the old
-decision itself changed.
-
-## Keep the user surface small
-
-At each turn show only:
-
-- the current decision or checkpoint;
-- the decisive evidence and recommendation;
-- the effect of the answer;
-- optionally the number of already resolved decisions.
-
-Provide the hidden evidence inventory, all semantic steps, or full report paths only
-when requested. Context and token budgets are advisory; they never justify omitting
-load-bearing evidence or refusing legitimate work.
+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

@@ -141,6 +141,9 @@ 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 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
@@ -157,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.