ultra-builder-pro-cli 0.14.0 → 0.16.0

package/skills/ultra-think/SKILL.md

@@ -1,18 +1,18 @@
 ---
 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 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.
 ---
 
-# Analyze a consequential question
+# Align on 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.
+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.
 
-## Workflow
+## Establish evidence
 
 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.
+   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;
@@ -31,8 +31,19 @@ simple questions directly; do not turn every request into a framework exercise.
    - 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.
+7. Decide whether the question is now answerable or still requires owner authority.
+
+## Route the result
+
+- 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.
 
 ## Output
 
@@ -46,6 +57,9 @@ Adapt the response to the question. Include:
 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.
+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.

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

@@ -0,0 +1,130 @@
+# Decision dialogue protocol
+
+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.
+
+## Select the interaction depth
+
+- `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.
+
+Do not ask a meta-question about mode when the user's request or current change profile
+already determines the appropriate depth.
+
+## Separate evidence from decisions
+
+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.
+
+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.
+
+## Bind durable authority
+
+For a project-bound dialogue:
+
+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.
+
+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.
+
+## Present one decision and stop
+
+Use a compact shape adapted to the user's language:
+
+```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>
+```
+
+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.

package/skills/ultra-verify/SKILL.md

@@ -36,7 +36,7 @@ never recurse into the current host or treat advisor output as authority.
 7. Write `metadata.json` and `synthesis.md`, then return one host-owned conclusion.
 
 Read `references/cross-verify-modes.md` for mode-specific evidence and
-`references/confidence-system.md` when confidence language is useful. Model agreement
+`references/evidence-status.md` when the synthesis needs an evidence status. Model agreement
 never overrides failing tests or authoritative runtime evidence.
 
 Advisor failure degrades to the primary analysis with a single-source warning. It

package/skills/ultra-verify/references/{confidence-system.md → evidence-status.md}

@@ -1,7 +1,7 @@
-# Evidence-Based Confidence
+# Evidence Status
 
-Cross-model agreement is a signal, not an authority. Assign confidence only after checking claims
-against source code, tests, runtime output, or primary documentation.
+Cross-model agreement is a signal, not an authority. Classify the synthesis only after checking
+consequential claims against source code, tests, runtime output, or primary documentation.
 
 ## Levels
 

package/spec/cli-protocol.md

@@ -91,7 +91,7 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `task.expand`             | `task expand`               | 8a    | mcp     |
 | `task.parse_prd`          | `task parse-prd`            | 8a    | mcp     |
 | `task.dependency_topo`    | `task topo`                 | 8a    | mcp     |
-| `task.append_event`       | `task append-event`         | 2     | any     |
+| `task.append_event`       | `task append-event`         | 2     | any (allowlisted observations only) |
 | `task.subscribe_events`   | `task subscribe`            | 2     | any     |
 | `session.spawn`           | `session spawn`             | 4.5   | mcp     |
 | `session.close`           | `session close`             | 4.5   | mcp     |
@@ -114,6 +114,20 @@ 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     |
+| `workflow.step`           | `workflow step`             | 13    | mcp     |
+| `workflow.complete`       | `workflow complete`         | 13    | mcp     |
 | `system.doctor`           | `system doctor`             | 9     | mcp     |
 | `plan.export`             | `plan export`               | 8a    | mcp     |
 | `plan.get`                | `plan get`                  | 8a    | any     |
@@ -121,12 +135,12 @@ 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=12.0` transition before resume.
+`migrate --from=4.4 --to=4.5` or the current supported state-schema transition before resume.
 `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