ultra-builder-pro-cli 0.15.0 → 0.16.0

package/skills/ultra-review/SKILL.md

@@ -18,8 +18,9 @@ One axis cannot compensate for the other.
 1. Read `references/review-modes.md`. Select exactly one review mode: `task` for one
    implementation slice, `change` for aggregate delivery readiness, or `plan` for an
    approved plan before implementation. Bind only the evidence defined by that mode.
-2. Resolve one explicit diff range, current full HEAD, change, task set, and accepted
-   evidence. Stop on an empty or ambiguous scope.
+2. Resolve one explicit diff range, current full HEAD, change, task set, accepted
+   evidence, and decision checkpoint state. Stop on an empty or ambiguous scope or an
+   unconfirmed alignment checkpoint.
 3. Resume or start a `review` workflow. Record `bind-diff` with revision, paths, mode,
    and task set.
 4. Compile `change.context` for `review` using only accepted intent, delta, task
@@ -50,6 +51,8 @@ Record:
 The coordinator preserves every specialist finding unchanged in `SUMMARY.json`.
 Duplicate root causes may be grouped only in the human-readable summary. Review is
 read-only except for review artifacts; implementation fixes are a separate dev action.
+If a finding exposes a new owner choice, preserve it as a finding and route the primary
+agent to `ultra-think`; a review worker must not open, answer, or hide that decision.
 
 ## Verify and complete
 
@@ -62,4 +65,7 @@ coordinator summary cannot replace either axis. Any code, test, spec, or contrac
 invalidates affected review evidence and requires a new or resumed run.
 
 Return both axis verdicts first, blocking findings, reviewed revision and paths,
-artifact digests, workflow id, skipped-role rationale, and one exact next route.
+artifact digests, workflow id, skipped-role rationale, and one exact next route. A
+blocking implementation finding returns to `ultra-dev`; stale verification returns to
+`ultra-test`; a new owner choice returns to `ultra-think`; an approved current change
+review routes to `ultra-deliver`.

package/skills/ultra-status/SKILL.md

@@ -13,10 +13,12 @@ projections.
 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;
+3. Call `decision.list`, then `decision.get` for the current active or checkpoint-ready
+   thread. Expose only its current question or checkpoint, not the hidden history.
+4. Call `workflow.list`, then `workflow.get` for every active, blocked, or ready run.
+5. Call `change.breadcrumb`, `change.list`, `task.list`, and `session.list`.
+6. Inspect current Git branch, full HEAD, and worktree without mutation.
+7. Read test, review, and delivery artifacts only when referenced by DB workflow state;
    compare their recorded digest and revision with current authority.
 
 If state is unreadable, report that panel unavailable and route to `ultra-doctor`.
@@ -27,6 +29,7 @@ Never fall back to generated task JSON, raw SQLite queries, or context frontmatt
 Prefer the breadcrumb and durable workflow position:
 
 - state integrity, schema, projection, or installed-asset failure: `ultra-doctor`;
+- open decision or checkpoint: `ultra-think` with its exact decision id;
 - 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
@@ -49,6 +52,7 @@ Report:
 Ultra: <healthy|degraded> · <branch>@<head> · worktree <clean|dirty>
 Baseline: <mode>/<status> · research=<run/status> · gaps=<open>/<blocking>
 Workflow: <kind/id/status> · step=<current|finalize> · outputs=<fresh|stale>
+Decision: <id/phase|checkpoint|none> · thread=<id/status>
 Change: <id/status|none> · Task: <id/status|none> · Sessions: <active>
 Evidence: test=<state> · review=<two axes> · delivery=<state>
 Blockers: <specific codes or none>

package/skills/ultra-test/SKILL.md

@@ -10,8 +10,10 @@ 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.
+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
@@ -26,6 +28,8 @@ or use generated task JSON as authority.
 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
 
@@ -49,4 +53,6 @@ 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`.
+`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`.

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/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,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=15.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

package/spec/mcp-tools.yaml

@@ -3,7 +3,7 @@
 # Validated by spec/schemas/mcp-tools.schema.json (run `npm run test:spec`).
 # Trace: PLAN §7.3, decisions D12 / D29 / D31-D34.
 
-version: '1.2'
+version: '1.3'
 
 info:
   title: Ultra Builder Pro MCP tool contracts
@@ -25,6 +25,7 @@ families:
   - { name: plan,    description: 'execution-plan artifact export and query (D34)', phase: '8a' }
   - { name: baseline, description: 'project adoption, baseline evidence, convergence, and drift authority', phase: '11' }
   - { name: change,  description: 'continuous post-delivery change lifecycle and convergence', phase: '9' }
+  - { name: decision, description: 'durable owner-agent alignment, one-question presentation, and approved checkpoints', phase: '16' }
   - { name: workflow, description: 'durable cross-stage run position, evidence, outputs, blockers, and recovery', phase: '13' }
   - { name: system,  description: 'read-only diagnostics and explicit backup-first repair', phase: '9' }
 
@@ -1064,6 +1065,7 @@ tools:
             mode: { type: ['string', 'null'], enum: [product, feature, architecture, custom, null] }
             selected_steps: { type: array, uniqueItems: true, items: { type: string, minLength: 1 } }
             rationale: { type: string, minLength: 1 }
+        alignment_thread_id: { type: string, description: 'confirmed decision checkpoint that produced this change contract' }
         base_commit: { type: string, pattern: '^[0-9a-f]{7,40}$' }
         baseline_bypass:
           type: object
@@ -1125,6 +1127,7 @@ tools:
       - { code: CHANGE_CLASSIFICATION_REQUIRED, description: 'classification rationale or risk flags are incomplete' }
       - { code: CHANGE_RESEARCH_DISPOSITION_REQUIRED, description: 'research routing is incomplete or inconsistent' }
       - { code: CHANGE_PROFILE_ESCALATION_REQUIRED, description: 'quick profile conflicts with material risk or research' }
+      - { code: CHANGE_ALIGNMENT_REQUIRED, description: 'declared alignment thread is missing, unconfirmed, stale, not artifact-bound, bound to another authority, or not scoped to the current baseline' }
     cli_subcommand: change create
     emits_events: [change_created, context_updated, workflow_started, workflow_step_updated]
 
@@ -1476,6 +1479,299 @@ tools:
     cli_subcommand: change archive
     emits_events: [change_archived]
 
+  # ────────────────────────── decision family ────────────────────────────
+  - name: decision.thread_start
+    family: decision
+    description: Start one durable owner-agent alignment thread bound to baseline, change, or workflow authority.
+    phase: '16'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, purpose]
+      additionalProperties: false
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        purpose: { type: string, minLength: 3 }
+        mode: { type: string, enum: [guided, fast, autonomous, diagnostic], default: guided }
+        baseline_id: { type: string }
+        change_id: { type: string }
+        workflow_run_id: { type: string }
+    output_schema:
+      type: object
+      required: [thread]
+      additionalProperties: false
+      properties:
+        thread: { type: object }
+    errors:
+      - { code: DECISION_AUTHORITY_REQUIRED, description: 'thread has no baseline, change, or workflow authority' }
+      - { code: DECISION_AUTHORITY_MISMATCH, description: 'thread authority differs from its workflow binding' }
+      - { code: DECISION_THREAD_IN_PROGRESS, description: 'the same authority and purpose already has an active thread' }
+      - { code: DUPLICATE_DECISION_THREAD, description: 'decision thread id already exists' }
+      - { code: VALIDATION_ERROR, description: 'thread input is incomplete or invalid' }
+    cli_subcommand: decision thread-start
+    emits_events: [decision_thread_started]
+
+  - name: decision.get
+    family: decision
+    description: Read one decision thread with its current question, normalized decisions, and checkpoint authority.
+    phase: '16'
+    readonly: true
+    input_schema:
+      type: object
+      required: [id]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+    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' }
+    cli_subcommand: decision get
+    emits_events: []
+
+  - name: decision.list
+    family: decision
+    description: List durable decision threads by authority, mode, or lifecycle state for recovery and status reporting.
+    phase: '16'
+    readonly: true
+    input_schema:
+      type: object
+      additionalProperties: false
+      properties:
+        status: { type: string, enum: [active, checkpoint_ready, confirmed, cancelled] }
+        mode: { type: string, enum: [guided, fast, autonomous, diagnostic] }
+        baseline_id: { type: string }
+        change_id: { type: string }
+        workflow_run_id: { type: string }
+        limit: { type: integer, minimum: 1, maximum: 500, default: 100 }
+    output_schema:
+      type: object
+      required: [threads, count]
+      additionalProperties: false
+      properties:
+        threads: { type: array, items: { type: object } }
+        count: { type: integer, minimum: 0 }
+    errors:
+      - { code: STATE_DB_ERROR, description: 'decision thread state could not be read' }
+    cli_subcommand: decision list
+    emits_events: []
+
+  - name: decision.open
+    family: decision
+    description: Open the sole user-facing decision in a thread with evidence, recommendation, credible alternatives, and durable effects.
+    phase: '16'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, thread_id, phase, question, why_now, recommendation, effects]
+      additionalProperties: false
+      properties:
+        id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+        thread_id: { type: string }
+        phase: { type: string, minLength: 1 }
+        question: { type: string, minLength: 1 }
+        why_now: { type: string, minLength: 1 }
+        recommendation: { type: string, minLength: 1 }
+        options:
+          type: array
+          maxItems: 3
+          items: &decision_option
+            type: object
+            required: [id, label, tradeoff]
+            additionalProperties: false
+            properties:
+              id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+              label: { type: string, minLength: 1 }
+              tradeoff: { type: string, minLength: 1 }
+        evidence_refs: { type: array, uniqueItems: true, items: { type: string, minLength: 1 } }
+        dependency_ids: { type: array, uniqueItems: true, items: { type: string, minLength: 1 } }
+        effects: { type: object, minProperties: 1 }
+        blocking: { type: boolean, default: true }
+    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_ALREADY_OPEN, description: 'another decision is already awaiting an answer' }
+      - { code: DECISION_CHECKPOINT_PENDING, description: 'the prepared checkpoint must be confirmed or revised first' }
+      - { code: DECISION_DEPENDENCY_UNRESOLVED, description: 'a declared decision dependency is unresolved' }
+      - { code: DUPLICATE_DECISION_ID, description: 'decision item id already exists' }
+      - { code: VALIDATION_ERROR, description: 'question, recommendation, options, evidence, or effects are invalid' }
+    cli_subcommand: decision open
+    emits_events: [decision_opened]
+
+  - name: decision.resolve
+    family: decision
+    description: Resolve the current question as an explicit normalized owner decision without storing the conversation transcript.
+    phase: '16'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, decision, rationale, decided_by]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        decision: { type: string, minLength: 1 }
+        rationale: { type: string, minLength: 1 }
+        decided_by: { type: string, minLength: 1 }
+    output_schema:
+      type: object
+      required: [thread]
+      additionalProperties: false
+      properties:
+        thread: { type: object }
+    errors:
+      - { code: DECISION_NOT_FOUND, description: 'decision item id does not exist' }
+      - { code: DECISION_NOT_OPEN, description: 'decision item is no longer awaiting an answer' }
+      - { code: VALIDATION_ERROR, description: 'normalized owner decision is incomplete' }
+    cli_subcommand: decision resolve
+    emits_events: [decision_resolved]
+
+  - name: decision.delegate
+    family: decision
+    description: Record explicit owner delegation for a reversible decision, including the selected result and non-negotiable guardrails.
+    phase: '16'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, delegated_to, decision, rationale, guardrails]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        delegated_to: { type: string, minLength: 1 }
+        decision: { type: string, minLength: 1 }
+        rationale: { type: string, minLength: 1 }
+        guardrails: { type: array, minItems: 1, uniqueItems: true, items: { type: string, minLength: 1 } }
+    output_schema:
+      type: object
+      required: [thread]
+      additionalProperties: false
+      properties:
+        thread: { type: object }
+    errors:
+      - { code: DECISION_NOT_FOUND, description: 'decision item id does not exist' }
+      - { code: DECISION_NOT_OPEN, description: 'decision item is no longer awaiting an answer' }
+      - { code: VALIDATION_ERROR, description: 'delegation result or guardrails are incomplete' }
+    cli_subcommand: decision delegate
+    emits_events: [decision_resolved]
+
+  - name: decision.defer
+    family: decision
+    description: Defer the current decision with explicit consequences and a deterministic condition for revisiting it.
+    phase: '16'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, reason, consequences, revisit_condition]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        reason: { type: string, minLength: 1 }
+        consequences: { type: string, minLength: 1 }
+        revisit_condition: { type: string, minLength: 1 }
+    output_schema:
+      type: object
+      required: [thread]
+      additionalProperties: false
+      properties:
+        thread: { type: object }
+    errors:
+      - { code: DECISION_NOT_FOUND, description: 'decision item id does not exist' }
+      - { code: DECISION_NOT_OPEN, description: 'decision item is no longer awaiting an answer' }
+      - { code: VALIDATION_ERROR, description: 'deferral consequence or revisit condition is incomplete' }
+    cli_subcommand: decision defer
+    emits_events: [decision_resolved]
+
+  - name: decision.supersede
+    family: decision
+    description: Preserve a prior resolved decision and reopen alignment with one replacement question when evidence or owner intent changes.
+    phase: '16'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, reason, replacement]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        reason: { type: string, minLength: 1 }
+        replacement:
+          type: object
+          required: [id, phase, question, why_now, recommendation, effects]
+          additionalProperties: false
+          properties:
+            id: { type: string, pattern: '^[a-zA-Z0-9_\-]+$' }
+            phase: { type: string, minLength: 1 }
+            question: { type: string, minLength: 1 }
+            why_now: { type: string, minLength: 1 }
+            recommendation: { type: string, minLength: 1 }
+            options: { type: array, maxItems: 3, items: *decision_option }
+            evidence_refs: { type: array, uniqueItems: true, items: { type: string, minLength: 1 } }
+            dependency_ids: { type: array, uniqueItems: true, items: { type: string, minLength: 1 } }
+            effects: { type: object, minProperties: 1 }
+            blocking: { type: boolean, default: true }
+    output_schema:
+      type: object
+      required: [thread]
+      additionalProperties: false
+      properties:
+        thread: { type: object }
+    errors:
+      - { code: DECISION_NOT_FOUND, description: 'decision item id does not exist' }
+      - { code: DECISION_NOT_SUPERSEDEABLE, description: 'decision item cannot be revised from its current state' }
+      - { code: DECISION_ALREADY_OPEN, description: 'another decision is already awaiting an answer' }
+      - { code: VALIDATION_ERROR, description: 'replacement question or revision reason is invalid' }
+    cli_subcommand: decision supersede
+    emits_events: [decision_opened]
+
+  - 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.
+    phase: '16'
+    writer_role: mcp
+    input_schema:
+      type: object
+      required: [id, action]
+      additionalProperties: false
+      properties:
+        id: { type: string }
+        action: { type: string, enum: [prepare, confirm] }
+        summary: { type: string, minLength: 1 }
+        approved_by: { type: string, minLength: 1 }
+        approval_note: { type: string, minLength: 3 }
+        artifacts:
+          type: array
+          items:
+            type: object
+            required: [path, kind]
+            additionalProperties: false
+            properties:
+              path: { type: string, minLength: 1 }
+              kind: { type: string, minLength: 1 }
+        no_artifact_reason: { type: string, minLength: 3 }
+    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: 'cancelled decision thread cannot be checkpointed' }
+      - { code: DECISION_ALIGNMENT_BLOCKING, description: 'an open or deferred blocking decision prevents checkpointing' }
+      - { code: DECISION_CHECKPOINT_STALE, description: 'prepared decision digest no longer matches current authority' }
+      - { code: DECISION_ARTIFACT_REQUIRED, description: 'confirmation lacks required artifact bindings; no-artifact reasons are allowed only for standalone baseline thinking' }
+      - { code: DECISION_ARTIFACT_MISSING, description: 'a declared checkpoint artifact does not exist' }
+      - { code: VALIDATION_ERROR, description: 'checkpoint action, approval, or artifact input is invalid' }
+    cli_subcommand: decision checkpoint
+    emits_events: [decision_checkpoint_prepared, decision_checkpoint_confirmed]
+
   # ────────────────────────── workflow family ────────────────────────────
   - name: workflow.start
     family: workflow
@@ -1647,6 +1943,7 @@ tools:
       - { code: WORKFLOW_CONTEXT_AUTHORITY_MISMATCH, description: 'the context artifact does not match its DB snapshot row' }
       - { code: WORKFLOW_CONTEXT_STALE, description: 'the context artifact no longer matches the current checkout' }
       - { code: WORKFLOW_RELEASE_AUTHORIZATION_INVALID, description: 'release-if-authorized requires one complete durable owner decision' }
+      - { code: DECISION_ALIGNMENT_BLOCKING, description: 'matching owner decisions or artifact checkpoints are not current' }
     cli_subcommand: workflow step
     emits_events: [workflow_step_updated, workflow_blocked]
 
@@ -1697,6 +1994,7 @@ tools:
       - { code: WORKFLOW_TEST_NOT_PASSED, description: 'the current change-level test gate did not pass' }
       - { code: WORKFLOW_CHANGE_NOT_ARCHIVED, description: 'delivery completion requires an archived change' }
       - { code: WORKFLOW_RELEASE_AUTHORITY_MISMATCH, description: 'delivery release claims differ from the durable owner authorization decision' }
+      - { code: DECISION_ALIGNMENT_BLOCKING, description: 'matching owner decisions or artifact checkpoints are not current' }
     cli_subcommand: workflow complete
     emits_events: [workflow_completed, plan_approved]