ultra-builder-pro-cli 0.19.1 → 0.20.0

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;