ultra-builder-pro-cli 0.18.0 → 0.20.0

package/skills/ultra-change/SKILL.md

@@ -29,13 +29,18 @@ Read `../ultra-think/references/decision-dialogue.md` before asking a material q
    - change kind and evidence-backed risk flags;
    - research disposition.
 
-Select `quick`, `standard`, `major`, or `incident` from actual scope and risk. A quick
-change may have no material risk, research obligation, or more than one task.
+Recommend `quick`, `standard`, `major`, or `incident` from actual scope and risk,
+together with the research disposition. A quick change may have no material risk,
+research obligation, or more than one task. MCP may reject a profile that contradicts
+hard risk invariants; it does not choose a replacement.
 
 Ask only when a choice changes accepted product intent, scope, public behavior,
 compatibility, security, material cost, external effects, or recovery. Use the host's
 native question UI when available. Normalize clear choices already in the user's
-request. The model owns reversible implementation detail inside the accepted contract.
+request. When profile or research posture remains unresolved, present the recommended
+route and credible alternatives through that same UI, then stop. The user selects,
+modifies, delegates, or defers the semantic route. The model owns reversible
+implementation detail inside the accepted contract.
 
 ## Persist the contract
 
@@ -60,14 +65,17 @@ meaning is coupled. Downstream task, context, test, or review evidence affected
 change must become stale and be regenerated; never keep old evidence green by prompt
 assertion.
 
-If research is required, invoke `ultra-research` with the recorded disposition. If the
-contract is sufficiently evidenced, the host may recommend `ultra-plan`. `change.context`
-is compiled only for an actual plan, implementation, test, or review consumer.
+If research is required, recommend `ultra-research` with the recorded disposition. If
+the contract is sufficiently evidenced, recommend `ultra-plan`. Return and wait for an
+explicit user invocation; do not start either workflow. `change.context` is compiled
+only for an actual plan, implementation, test, or review consumer.
 
 Stable implementation discoveries use the approval-gated specification-learning
 transitions. External memory and graph providers retain their own content; Ultra stores
 metadata references only.
 
 Return the normalized contract, change id and kind, research disposition, blockers,
-and `allowed_transitions`. The host selects a recommendation from those transitions;
-MCP does not encode a semantic next action.
+and `allowed_transitions`. Recommend a semantic next action from those transitions.
+If current intent does not already select it, present the recommendation and credible
+alternatives through the interaction protocol, then wait. MCP does not encode a
+semantic next action.

package/skills/ultra-init/SKILL.md

@@ -75,7 +75,8 @@ Read the returned `allowed_transitions` and `required_transition`:
 - a required transition represents a hard recovery invariant and must be followed;
 - otherwise the host model recommends among the allowed capabilities using the user's
   goal and current evidence;
-- start `ultra-research` only when the user invoked it or the host selects it after init.
+- never invoke another public Ultra workflow automatically; recommend the best allowed
+  capability and wait for an explicit user invocation.
 
 Report classification, scope, schema and backup result, Git state, init workflow id,
 baseline state, and allowed transitions. Do not claim that a baseline is ready until a

package/skills/ultra-plan/SKILL.md

@@ -15,17 +15,34 @@ accepted Change Contract without adding ceremonial approval.
    checkout.
 2. Require one mutable change with a healthy baseline or recorded incident bypass.
 3. Complete the exact change-bound research disposition before planning.
-4. Resume the matching plan run or start one bound to the change and baseline.
+4. Resume the matching plan run. Do not start a new run until planning posture is
+   accepted.
 
 Read `references/semantic-preflight.md` and inspect requirements, real consumers,
 state, tests, deployment, and recovery paths.
 
+## Align planning posture
+
+Use the interaction protocol in `../ultra-think/references/decision-dialogue.md`.
+Normalize a posture already explicit in current intent. Otherwise recommend one based
+on the Change Contract, explain its scope effect, and use the host's native question
+surface:
+
+- `EXPAND`: surface evidence-backed opportunities beyond accepted scope;
+- `SELECTIVE`: hold accepted scope and offer optional expansions individually;
+- `HOLD`: preserve scope and strengthen completeness, failure handling, and recovery;
+- `REDUCE`: propose the smallest outcome that still satisfies revised acceptance.
+
+The user may select, modify, delegate, or defer the posture. Stop on an unanswered
+choice. Start `workflow.start` only after alignment and store `planning_posture` plus
+its rationale in workflow metadata. This is a scope boundary, not approval of the
+eventual technical design.
+
 ## Design with model autonomy
 
 Build a candidate plan privately. Ask the user only if the plan would change accepted
 scope, public behavior, compatibility, security, material cost, external effects, or
-recovery. Use the host's native question UI when available and the interaction protocol
-in `../ultra-think/references/decision-dialogue.md`.
+recovery. Use the same host-native interaction protocol.
 
 When the candidate remains inside the accepted Change Contract, proceed without a
 second approval. A user may still request a plan review before persistence; that is an

package/skills/ultra-research/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: ultra-research
-description: Build or refresh an evidence-backed product and architecture baseline with model-selected semantic coverage and low-load user alignment. Use when initialization, brownfield adoption, or an active change has a real evidence gap.
+description: Build or refresh an evidence-backed product and architecture baseline through recommended, user-selected semantic coverage and low-load alignment. Use when initialization, brownfield adoption, or an active change has a real evidence gap.
 ---
 
 # Research with adaptive coverage
 
-The host model owns investigation, synthesis, and coverage judgment. Ultra MCP owns the
-run, evidence references, semantic records, artifact digests, freshness, and
-convergence. The reference areas are an optional coverage catalog, not a mandatory
-questionnaire or a fixed sequence of user conversations.
+The model owns investigation, synthesis, and coverage recommendations. The user owns
+the accepted semantic route and material deferrals. Ultra MCP owns the run, evidence
+references, semantic records, artifact digests, freshness, and convergence. The
+reference areas are an optional catalog, not a mandatory questionnaire or fixed
+sequence of user conversations.
 
 Read `../ultra-think/references/decision-dialogue.md` before asking a material question.
 
@@ -16,20 +17,27 @@ Read `../ultra-think/references/decision-dialogue.md` before asking a material q
 
 1. Read `system.doctor`, `baseline.get`, active decisions, and existing research runs.
 2. Resume the matching active, blocked, or ready run. Do not create parallel authority.
-3. If none exists, select:
+3. If none exists, determine the authority-bound mode:
    - `full` for a greenfield baseline;
    - `adoption` for a brownfield baseline;
    - a bounded mode only for a recorded active-change research disposition.
+   Focused baseline coverage retains `full` or `adoption`; `custom` is only
+   change-bound and narrows coverage inside an active Change.
 4. Before `workflow.start`, inspect current code, docs, tests, runtime, and prior
-   artifacts. Select the smallest sufficient set of applicable catalog areas. Include
-   only areas that need work or whose exclusion must remain auditable:
+   artifacts. Recommend the smallest sufficient set of applicable catalog areas.
+   Explain the net effect without dumping all 17 areas. Offer at most three credible
+   routes: the recommended adaptive set, the full catalog, and a focused or custom set.
+5. If current user intent does not already select a route, use the host's native
+   structured question surface. The user selects, modifies, delegates, or defers.
+   Treat a dismissal as unanswered, stop, and perform no route-dependent write.
+6. Normalize the answer and persist the accepted coverage through `workflow.start`:
    - `execute`: produce fresh evidence;
    - `verify_existing`: verify a current artifact against its source;
    - `reuse`: reuse evidence that is still current;
    - `not_applicable`: exclude with an evidence reference and rationale;
    - `deferred`: record the consequence and owner acceptance when deferral changes the
      accepted scope or leaves material risk.
-5. Pass the evidence-based coverage rationale as `metadata.selection_reason`. Omitted
+7. Pass the evidence-based coverage rationale as `metadata.selection_reason`. Omitted
    catalog areas create no DB step and need no ceremonial disposition.
 
 `99-synthesis` must execute, verify, or reuse. A missing disposition is a coverage
@@ -96,11 +104,13 @@ known failures, blocking gaps, and scope. Reuse an unambiguous current approval;
 ask twice. MCP must reject stale research, drift, missing evidence, and unaccepted
 failures.
 
-Reuse the final research checkpoint approval during baseline convergence; do not ask
-for an equivalent approval again. After initial or adoption convergence,
-`ultra-change` becomes an available transition. Bounded change research returns to
-its owning Change authority.
+Reuse the final research acceptance or current artifact checkpoint during baseline
+convergence; do not ask for an equivalent approval again. After initial or adoption
+convergence, `ultra-change` becomes an available transition. Bounded change research
+returns to its owning Change authority.
 
 Return a compact coverage summary by disposition, current evidence or decision
-blocker, baseline state, gaps, and allowed transitions. The host chooses the semantic
-recommendation; MCP supplies only valid and required transitions.
+blocker, baseline state, gaps, and allowed transitions. Recommend a semantic next
+action from those transitions. If current intent does not already select it, present
+the recommendation and credible alternatives through the interaction protocol, then
+wait. MCP supplies only valid and required transitions.

package/skills/ultra-test/SKILL.md

@@ -61,5 +61,8 @@ report and current checkout before `verify-test-gate`. `workflow.complete` deriv
 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.
+state, and allowed transitions. Recommend broader review, more implementation, or
+delivery from those transitions. If current intent does not already select the
+semantic next action, use
+`../ultra-think/references/decision-dialogue.md` and wait for the user to select,
+modify, delegate, or defer it.

package/skills/ultra-think/SKILL.md

@@ -37,6 +37,8 @@ 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.
+Call `decision.complete` when normalized state is settled and no artifact-bound
+checkpoint is needed; completion is not another owner approval.
 
 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

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

@@ -10,6 +10,7 @@ The user owns:
 
 - product intent and accepted outcomes;
 - material scope, compatibility, security, cost, and recovery tradeoffs;
+- semantic route selection and risk acceptance;
 - authorization for destructive or external effects.
 
 The model owns:
@@ -22,15 +23,36 @@ The model owns:
 MCP owns durable state, evidence references, digests, freshness, locks, valid
 transitions, and hard invariants. It does not choose semantic intent.
 
+## Follow the common selection flow
+
+1. **Inspect** repository authority, source, runtime, tests, and relevant primary
+   sources.
+2. **Suggest** one recommendation and only credible alternatives, with their effects.
+3. **Ask** through the host-native structured question surface only when current user
+   intent does not already resolve the material choice.
+4. **Normalize** a direct choice, modified route, delegation, or deferral. Treat a
+   dismissed question as unanswered.
+5. **Persist** the normalized result through MCP, then trust the DB record as current
+   authority across sessions.
+
+The DB treats normalized intent as current authority. It does not prove that the user
+selected it, store a host interaction receipt, or judge whether the choice was wise.
+The host interaction is the semantic gate; MCP validates state shape, bindings,
+freshness, and legal transitions.
+
+When an unanswered material question must survive interruption, `decision.open` stores
+that pending question before the host presents it. A pending question is recovery
+state, not accepted user intent. Only the normalized resolution becomes intent
+authority.
+
 ## 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,
+1. Separate `Observed`, `Verified`, `Decided`, `Delegated`, and `Unknown`.
+2. Resolve evidence-answerable unknowns autonomously.
+3. Normalize clear decisions already present in the user's current request.
+4. 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.
@@ -50,8 +72,11 @@ 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.
+contract when it exists. If that surface is unavailable but normal conversation is
+permitted, ask one concise direct question instead of inventing a tool or foreign-host
+syntax. If the host mode forbids interaction entirely, keep the choice unanswered and
+stop before any route-dependent write. Do not convert host unavailability into
+delegated authority.
 
 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.
@@ -70,6 +95,7 @@ low-cognitive-load facts when seeing them together improves consistency. Never d
 questionnaire, hidden queue, or every research area.
 
 The question tool or direct question ends the current interaction naturally.
+A dismissed or unavailable response is not acceptance of the recommendation.
 
 ## Persist only when recovery needs it
 
@@ -77,20 +103,25 @@ 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.
+2. Use `decision.open` before presenting only the current decision, with evidence refs,
+   recommendation, credible alternatives, effects, and its real blocking consequence.
+   A non-blocking follow-up must not become a global workflow gate.
 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.
+4. Call `decision.complete` when normalized state is settled and no artifact checkpoint
+   is needed. This closes lifecycle state; it is not another user approval.
+5. Use `decision.checkpoint` instead 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.
+An answered thread with no open or blocking deferred decision does not require a
+checkpoint merely to prove intent.
 
 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
@@ -98,6 +129,11 @@ compact effect once, obtain any missing approval, update the artifact, and confi
 digest. Do not create ceremonial checkpoints for routine implementation detail or an
 already explicit current instruction.
 
+Every checkpoint binds the normalized decision digest. Change- and workflow-bound
+checkpoints also require at least one current artifact digest. A standalone baseline
+thread may instead record a specific `no_artifact_reason` when no durable artifact
+exists; that exception does not create interaction proof.
+
 ## Return to the capability graph
 
 After alignment, re-read the invoking workflow and breadcrumb. A

package/spec/cli-protocol.md

@@ -122,6 +122,7 @@ as a fallback unless `ultra-tools <family> --help` lists it.
 | `decision.delegate`       | `decision delegate`          | 16    | mcp     |
 | `decision.defer`          | `decision defer`             | 16    | mcp     |
 | `decision.supersede`      | `decision supersede`         | 16    | mcp     |
+| `decision.complete`       | `decision complete`          | 19    | mcp     |
 | `decision.checkpoint`     | `decision checkpoint`        | 16    | mcp     |
 | `workflow.start`          | `workflow start`            | 13    | mcp     |
 | `workflow.get`            | `workflow get`              | 13    | any     |

package/spec/mcp-tools.yaml

@@ -1600,7 +1600,7 @@ tools:
       type: object
       additionalProperties: false
       properties:
-        status: { type: string, enum: [active, checkpoint_ready, confirmed, cancelled] }
+        status: { type: string, enum: [active, checkpoint_ready, completed, confirmed, cancelled] }
         mode: { type: string, enum: [guided, fast, autonomous, diagnostic] }
         baseline_id: { type: string }
         change_id: { type: string }
@@ -1788,6 +1788,33 @@ tools:
     cli_subcommand: decision supersede
     emits_events: [decision_opened]
 
+  - name: decision.complete
+    family: decision
+    description: Complete a decision thread after its normalized state is settled, without creating an approval receipt or artifact checkpoint.
+    phase: '19'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, summary]
+      additionalProperties: false
+      properties:
+        id: { type: string, minLength: 1 }
+        summary: { type: string, minLength: 1 }
+    output_schema:
+      type: object
+      required: [thread]
+      additionalProperties: false
+      properties:
+        thread: { type: object }
+    errors:
+      - { code: DECISION_THREAD_NOT_FOUND, description: 'decision thread id does not exist' }
+      - { code: DECISION_THREAD_NOT_MUTABLE, description: 'the decision thread is already terminal' }
+      - { code: DECISION_CHECKPOINT_PENDING, description: 'a prepared artifact checkpoint must be confirmed or revised first' }
+      - { code: DECISION_ALIGNMENT_BLOCKING, description: 'an unanswered question or blocking deferral prevents completion' }
+      - { code: VALIDATION_ERROR, description: 'the completion summary is missing' }
+    cli_subcommand: decision complete
+    emits_events: [decision_thread_completed]
+
   - name: decision.checkpoint
     family: decision
     description: Prepare or confirm a decision checkpoint, including renewal of unchanged decisions against current artifacts; change- and workflow-bound threads require an artifact, while a standalone baseline thread may record an explicit no-artifact reason.
@@ -1833,7 +1860,7 @@ tools:
   # ────────────────────────── workflow family ────────────────────────────
   - name: workflow.start
     family: workflow
-    description: Start one durable Ultra workflow run. For research, the host model supplies only evidence-relevant semantic coverage; MCP records and validates the selection without choosing it.
+    description: Start one durable Ultra workflow run. For research, the host supplies normalized accepted semantic coverage after user-model alignment; MCP records and validates the state without choosing or proving user intent.
     phase: '13'
     writer_role: mcp
     input_schema:
@@ -1883,7 +1910,7 @@ tools:
       - { code: WORKFLOW_AUTHORITY_REQUIRED, description: 'the workflow is missing its required baseline, change, or task authority' }
       - { code: WORKFLOW_CHANGE_DECISION_BLOCKING, description: 'the change contains unresolved material owner decisions' }
       - { code: WORKFLOW_CHANGE_RESEARCH_INCOMPLETE, description: 'the change-bound research disposition is not current and complete' }
-      - { code: WORKFLOW_RESEARCH_COVERAGE_REQUIRED, description: 'research requires model-selected coverage with at least one applicable semantic area beyond synthesis' }
+      - { code: WORKFLOW_RESEARCH_COVERAGE_REQUIRED, description: 'research requires accepted coverage with at least one applicable semantic area beyond synthesis' }
       - { code: WORKFLOW_RESEARCH_COVERAGE_EVIDENCE_REQUIRED, description: 'reuse, verification, and not-applicable dispositions require evidence references' }
       - { code: WORKFLOW_RESEARCH_SYNTHESIS_REQUIRED, description: 'research synthesis must execute, verify, or reuse durable evidence' }
       - { code: WORKFLOW_RESEARCH_MODE_MISMATCH, description: 'the selected research mode does not match its authority or baseline mode' }

package/spec/schemas/state-db.sql

@@ -407,16 +407,16 @@ CREATE INDEX IF NOT EXISTS workflow_steps_status
   ON workflow_steps(run_id, status, position);
 
 -- ──────────────────────────── decision dialogue ─────────────────────────
--- The host owns reasoning and normalized decision content. MCP owns one-at-a-
--- time presentation, durable authority, checkpoints, and recovery. Raw prompts
--- and transcripts never belong in these tables.
+-- The host owns reasoning, presentation, and normalized decision content. MCP
+-- owns the one-open-item invariant, pending recovery state, durable authority,
+-- checkpoints, and recovery. Raw prompts and transcripts never belong here.
 CREATE TABLE IF NOT EXISTS decision_threads (
   id                 TEXT PRIMARY KEY,
   purpose            TEXT NOT NULL,
   mode               TEXT NOT NULL DEFAULT 'guided'
                        CHECK (mode IN ('guided', 'fast', 'autonomous', 'diagnostic')),
   status             TEXT NOT NULL DEFAULT 'active'
-                       CHECK (status IN ('active', 'checkpoint_ready', 'confirmed', 'cancelled')),
+                       CHECK (status IN ('active', 'checkpoint_ready', 'completed', 'confirmed', 'cancelled')),
   baseline_id        TEXT REFERENCES baselines(id) ON DELETE SET NULL,
   change_id          TEXT REFERENCES changes(id) ON DELETE CASCADE,
   workflow_run_id    TEXT REFERENCES workflow_runs(id) ON DELETE CASCADE,
@@ -424,6 +424,7 @@ CREATE TABLE IF NOT EXISTS decision_threads (
   checkpoint_json    TEXT NOT NULL DEFAULT '{}',
   started_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
   updated_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  completed_at       TEXT,
   confirmed_at       TEXT,
   CHECK (baseline_id IS NOT NULL OR change_id IS NOT NULL OR workflow_run_id IS NOT NULL)
 );
@@ -492,3 +493,5 @@ INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('17.0', 'Explicit unborn Git authority and owner-authorized baseline checkpoints');
 INSERT OR IGNORE INTO schema_version (version, description)
 VALUES ('18.0', 'Adaptive capability transitions, independent initialization, and recoverable workflow migration');
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES ('19.0', 'Non-ceremonial decision completion and host-neutral intent persistence');

package/ultra-tools/cli.cjs

@@ -38,7 +38,7 @@ SUBCOMMANDS:
   system    doctor [--repair] | restore | rebaseline
   status    [--cost] [--since <duration>] [--json]
   db        init | checkpoint | vacuum | integrity | backup (Phase 2)
-  migrate   --from=<4.4|4.5> --to=<4.5|18.0> [--dry|--rollback]
+  migrate   --from=<4.4|4.5> --to=<4.5|19.0> [--dry|--rollback]
   legacy-memory inspect | archive | prune --confirm DELETE_ULTRA_LEGACY_MEMORY
 
   --help / -h      show this message

package/ultra-tools/commands/status.cjs

@@ -171,7 +171,8 @@ function buildStatusPanel(db, { since = null, limit = 3, rootDir = process.cwd()
   const decisions = tables.has('decision_threads') && tables.has('decision_items')
     ? decisionDialogue.inspectDecisionHealth(db, { rootDir })
     : {
-      status: 'unavailable', active: 0, awaiting_owner: 0, checkpoint_ready: 0,
+      status: 'unavailable', active: 0, completed: 0, awaiting_owner: 0,
+      awaiting_blocking: 0, checkpoint_ready: 0,
       deferred_blocking: 0, stale_artifacts: [], current: null, current_thread_id: null,
     };
   let transitions;