ultra-builder-pro-cli 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] — 2026-07-30
+
+### Added
+
+- Added a seven-tool public MCP kernel: `ultra.context`, `ultra.record`,
+  `ultra.checkpoint`, `ultra.sync`, `ultra.session`, `ultra.archive`, and
+  `ultra.doctor`.
+- Added idempotent batched recording, content-addressed Context snapshots, and
+  semantic checkpoints that commit accepted workflow authority in one model
+  round trip.
+- Added mutable diagnostic envelopes for rejected draft checkpoints and
+  archive preflights so the host model can correct or abandon the same draft.
+
+### Changed
+
+- Moved workflow sequencing and semantic judgment back into the eleven public
+  Skills. MCP now owns persistence, schema, transaction, concurrency, path,
+  recovery, and irreversible-effect boundaries instead of directing the model.
+- Reduced the unconditional `tools/list` surface from 60 fine-grained tools to
+  seven high-level tools. The 0.22 fine-grained contracts remain callable but
+  hidden for one compatibility release.
+- Made draft Changes and nonterminal workflows reversible while keeping
+  accepted revisions immutable and replaceable through a new draft.
+- Updated Claude Code, Codex, OpenCode, and Kimi assets to use the same narrow
+  capability graph while preserving each host's native question and bounded
+  worker surfaces.
+
+### Fixed
+
+- Fixed Plan drafts becoming permanently self-locked when a task or exported
+  artifact changed after validation.
+- Fixed semantic validation failures surfacing as MCP transport errors and
+  forcing models into repeated repair calls.
+- Fixed duplicate Context compilation creating competing snapshots for the
+  same semantic inputs.
+- Fixed `ultra.context` creating `.ultra` state merely by inspecting an
+  uninitialized project.
+
 ## [0.22.0] — 2026-07-30
 
 ### Added

package/README.md

@@ -71,7 +71,7 @@ flowchart TB
     end
 
     SKILLS["Eleven explicit Ultra Skills<br/>init / research / think / change / plan / dev<br/>test / review / deliver / status / doctor"]
-    MCP["Ultra MCP<br/>60 typed tools across nine families"]
+    MCP["Ultra MCP safety kernel<br/>7 public tools; 60 hidden compatibility operations"]
     DB[(".ultra/.runtime/state.db<br/>SQLite lifecycle and index authority")]
     LEDGER[".ultra/tasks/tasks.json<br/>Git team checkpoint for portable baseline, Change, and task state"]
     VIEWS[".ultra/.runtime/projections<br/>checkout-local generated views"]
@@ -103,13 +103,42 @@ The responsibility split is deliberate:
 |---|---|
 | **User** | Product intent, semantic route selection, material scope and trade-offs, risk acceptance, destructive actions, publishing and deployment authorization |
 | **Host model** | Fact-finding, synthesis, research-coverage and route recommendations, reversible implementation decisions |
-| **Ultra MCP** | Checkout-local state, evidence references, digests, freshness, locks, valid transitions, hard recovery, and Git checkpoint publish/import |
+| **Ultra MCP** | Durable checkpoints, evidence references, digests, team sync, leases, archive transactions, and mechanical recovery |
 | **Host adapter** | Native Skill discovery, user questions, tool invocation, installation, and runtime wiring |
 | **Hooks** | Fast lifecycle observation, current breadcrumb injection, and protection of MCP-owned checkpoint and generated projection paths |
 
-The MCP does not replace the model's judgment. A hook does not decide product
-strategy. A prompt does not become durable authority merely because it appeared
-in a conversation.
+The MCP does not replace the model's judgment or pre-authorize a semantic route. It
+reports draft diagnostics and commits accepted checkpoints. A hook does not decide
+product strategy. A prompt does not become durable authority merely because it
+appeared in a conversation.
+
+### The seven-tool MCP kernel
+
+The public model-facing surface is intentionally small:
+
+| Tool | Responsibility |
+|---|---|
+| `ultra.context` | Read the complete current spine without side effects |
+| `ultra.record` | Batch typed draft facts and events with idempotency |
+| `ultra.checkpoint` | Attempt one semantic stage checkpoint; rejection leaves the draft editable |
+| `ultra.sync` | Inspect, import, or publish the Git team checkpoint |
+| `ultra.session` | Own the transactional execution lease |
+| `ultra.archive` | Converge and archive through the recoverable filesystem/DB boundary |
+| `ultra.doctor` | Inspect or repair mechanical health, backup first |
+
+The 0.22 fine-grained tools remain callable but undiscoverable for one compatibility
+release. Skills and new sessions use only the seven tools above. Workflow prose stays
+in Skills, model judgment stays with the host, and SQLite records what happened rather
+than deciding what the model is allowed to think next.
+
+The enforcement gradient is:
+
+```text
+exploration and iteration: advisory
+durable semantic checkpoint: validated and recoverable
+corruption / unsafe path / real concurrency / permission: fail closed
+irreversible external effect: explicit owner authority plus fail closed
+```
 
 ### How owner intent becomes durable authority
 
@@ -121,9 +150,9 @@ flowchart TD
     CLEAR -->|"Yes"| NORMALIZE["Normalize the accepted intent"]
     CLEAR -->|"No: a material choice remains"| ASK["Ask one dependent question through the host-native question tool"]
     ASK --> NORMALIZE
-    NORMALIZE --> DECISION["Persist the normalized result through decision.*"]
-    DECISION --> APPLY["Apply it through the owning MCP operation or digest-bound artifact"]
-    APPLY --> AUTHORITY["Bind state, artifact digest, provenance, and downstream effects"]
+    NORMALIZE --> RECORD["Batch the normalized result through ultra.record"]
+    RECORD --> CHECKPOINT["Attempt the owning ultra.checkpoint when authority is ready"]
+    CHECKPOINT --> AUTHORITY["Bind state, artifact digest, provenance, and downstream effects"]
     AUTHORITY --> READBACK["Read back the authoritative result"]
     READBACK --> RESUME["Resume the exact workflow step and recommend the next explicit capability"]
 ```
@@ -299,9 +328,9 @@ already resolves the route. The normalized accepted coverage is then stored in
 - `deferred` — record the consequence and accepted owner.
 
 The catalog is not a mandatory document set or questionnaire. Omitted areas
-create no workflow rows; an explicit exclusion is recorded only when retaining
-that rationale is useful. MCP validates state, evidence, and transitions; it
-does not store or prove the preceding UI interaction.
+   create no workflow rows; an explicit exclusion is recorded only when retaining
+   that rationale is useful. MCP validates accepted checkpoints and mechanical
+   integrity; it does not store or prove the preceding UI interaction.
 
 Older projection-only Ultra projects are preserved and routed through a
 backup-first migration or rebaseline. The first supported checkpoint publication
@@ -358,19 +387,19 @@ The next piece of daily work starts with a new `ultra-change`.
 | `ultra-test` | Run the risk-selected verification profile and persist the gate result |
 | `ultra-review` | Coordinate independent specification-fidelity and engineering review |
 | `ultra-deliver` | Reconcile specifications, close local authority, and archive the change |
-| `ultra-status` | Read the current breadcrumb, blockers, evidence, and allowed transitions |
+| `ultra-status` | Read the current context, warnings, blockers, and evidence |
 | `ultra-doctor` | Diagnose installation or project-state faults and expose safe recovery |
 
-These eleven capabilities are the complete public Ultra command graph. Each capability
-returns current `allowed_transitions`; the host may recommend one, but another public
-capability starts only after an explicit user command or skill invocation.
+These eleven capabilities are the complete public Ultra command graph. The host model
+recommends the next capability from current context and owner intent; SQLite does not
+encode the semantic route. Another public capability starts only after an explicit
+user command or skill invocation.
 
 ### Command interaction graph
 
-Every solid handoff below means: the current capability returns
-`allowed_transitions`, the model recommends a route, and the owner explicitly
-invokes the next public capability. It does not mean that one public command
-silently launches another.
+Every solid handoff below means: the current capability returns context and checkpoint
+diagnostics, the model recommends a route, and the owner explicitly invokes the next
+public capability. It does not mean that one public command silently launches another.
 
 ```mermaid
 flowchart TD
@@ -459,8 +488,8 @@ health without selecting product intent.
 
 Together, `.ultra/` is Ultra's project-local cross-session workflow memory. The
 host model writes semantic specifications and evidence through the active
-workflow. MCP records lifecycle state, references, digests, provenance, and
-accepted intent, then rejects stale or illegal transitions. The DB is the
+capability. MCP records lifecycle state, references, digests, provenance, and
+accepted intent, then validates durable checkpoints and mechanical integrity. The DB is the
 lifecycle and index authority for one checkout; registered digest-bound files carry
 the semantic or evidence bodies that the DB references. The Git checkpoint is a
 portable, digest-chained handoff of baseline, Change, and durable task records. It is
@@ -551,12 +580,13 @@ host's existing model session.
 - **Project state is unhealthy:** invoke `ultra-doctor` or run
   `ultra-tools system doctor`. Repairs and schema migrations are backup-first.
 - **The team checkpoint disagrees with local state:** run `ultra-status`, inspect the
-  typed ledger condition, then use the recommended `task.ledger_import` or
-  `task.ledger_publish` path. Never edit `.ultra/tasks/tasks.json` by hand.
+  typed ledger condition, then use `ultra.sync` to import or publish after reviewing
+  any real conflict. Never edit `.ultra/tasks/tasks.json` by hand.
 - **A generated view disagrees with MCP:** trust `.ultra/.runtime/state.db`; never edit
   `.ultra/.runtime/projections/` by hand.
-- **A workflow appears blocked:** use `ultra-status` to read the exact current
-  workflow, blocker, owner decision, and mechanically valid transitions.
+- **A draft checkpoint is rejected:** use `ultra-status` to read the exact warnings
+  and blockers, fix the same mutable draft, and retry. Use `workflow.abandon` through
+  `ultra.record` only when intentionally cancelling the attempt.
 - **Kimi reports a native-module ABI error:** ensure an external Node.js 22+
   executable is available on `PATH`; the generated Kimi MCP launcher uses
   `env node`.

package/adapters/_shared/codex-assets.cjs

@@ -96,7 +96,7 @@ function adaptCodexPrimaryText(input, skillName) {
   let text = String(input);
   if (skillName === 'ultra-review') {
     text = text.replace(
-      /the current host's native bounded-worker\s+mechanism/g,
+      /(?:the current host's native|the host-native) bounded-worker\s+mechanism/g,
       'native Codex custom agents installed for the selected review workers',
     );
   }
@@ -470,7 +470,11 @@ main().catch((error) => {
 
   const sourceToolsFile = path.join(repoRoot, 'spec', 'mcp-tools.yaml');
   const upstreamManifest = yaml.load(fs.readFileSync(sourceToolsFile, 'utf8'));
-  const { REGISTERED_TOOLS } = require(path.join(repoRoot, 'mcp-server', 'server.cjs'));
+  const {
+    LEGACY_TOOLS,
+    PUBLIC_TOOLS,
+    REGISTERED_TOOLS,
+  } = require(path.join(repoRoot, 'mcp-server', 'server.cjs'));
   const registered = new Set(REGISTERED_TOOLS);
   const liveFamilies = new Set(
     upstreamManifest.tools.filter((tool) => registered.has(tool.name)).map((tool) => tool.family),
@@ -495,7 +499,8 @@ main().catch((error) => {
     fs.copyFileSync(sourceToolsFile, path.join(specRoot, 'upstream-mcp-tools.yaml'));
     writeAtomic(path.join(specRoot, 'codex-capability-map.json'), JSON.stringify({
       runtime: 'codex',
-      live_mcp_tools: REGISTERED_TOOLS,
+      live_mcp_tools: PUBLIC_TOOLS,
+      compatibility_mcp_tools: LEGACY_TOOLS,
       codex_native_replacements: CODEX_NATIVE_MCP_REPLACEMENTS,
     }, null, 2) + '\n');
   }

package/adapters/_shared/interaction-contract.cjs

@@ -32,7 +32,7 @@ function interactionContract(runtime) {
   const question = SURFACES[runtime];
   if (!question) throw new Error(`unsupported interaction runtime: ${runtime}`);
   return {
-    schema_version: '1.2',
+    schema_version: '1.3',
     runtime,
     public_capability_graph: PUBLIC_CAPABILITY_GRAPH,
     authority: {
@@ -50,9 +50,9 @@ function interactionContract(runtime) {
         'accepted_intent_normalization',
       ],
       ultra_mcp: [
-        'durable_state_and_evidence_refs',
-        'digests_freshness_locks_and_recovery',
-        'allowed_and_required_transitions',
+        'durable_checkpoints_and_evidence_refs',
+        'digests_freshness_leases_archives_and_recovery',
+        'mutable_semantic_diagnostics',
       ],
     },
     interaction: {
@@ -85,8 +85,15 @@ function interactionContract(runtime) {
     routing: {
       semantic_recommendation_owner: 'host_model',
       durable_recommendation_authority: false,
-      hard_invariant_field: 'required_transition',
-      valid_capabilities_field: 'allowed_transitions',
+      current_context_tool: 'ultra.context',
+      checkpoint_diagnostic_fields: ['warnings', 'blockers'],
+      hard_blocker_boundary: [
+        'corruption',
+        'unsafe_path',
+        'concurrency_conflict',
+        'permission',
+        'irreversible_external_effect',
+      ],
     },
   };
 }

package/adapters/_shared/runtime-assets.cjs

@@ -41,7 +41,7 @@ const PUBLIC_CAPABILITY_GRAPH = Object.freeze(Object.fromEntries(
     Object.freeze({
       mode: PUBLIC_CAPABILITY_MODES[name],
       activation: 'explicit_only',
-      next_capability_source: 'mcp_allowed_transitions',
+      next_capability_source: 'host_model_from_ultra_context',
       recommendation_owner: 'host_model',
       selection_owner: 'user',
       automatic_invocation: false,

package/adapters/claude.js

@@ -66,7 +66,7 @@ function copySkills(repoRoot, target, names) {
         let adaptedBody = adaptInteractionGuidance(body, 'claude');
         if (name === 'ultra-review') {
           adaptedBody = adaptedBody.replace(
-            /the current host's native bounded-worker\s+mechanism/g,
+            /(?:the current host's native|the host-native) bounded-worker\s+mechanism/g,
             'Claude Code Task workers using the installed review agent definitions',
           );
         }

package/adapters/kimi.js

@@ -96,7 +96,7 @@ function kimiTextTransform(input, assetName = '') {
   }
   if (assetName === 'ultra-review') {
     text = text.replace(
-      /the current host's native bounded-worker\s+mechanism/g,
+      /(?:the current host's native|the host-native) bounded-worker\s+mechanism/g,
       'Kimi `AgentSwarm` for parallel reviewers or one foreground Kimi `Agent` for a single reviewer, using the worker prompt files under `$KIMI_PLUGIN_ROOT/agents/`',
     );
   }

package/adapters/opencode.js

@@ -93,7 +93,7 @@ function openCodeTextTransform(input, assetName = '') {
   }
   if (assetName === 'ultra-review') {
     text = text.replace(
-      /the current host's native bounded-worker\s+mechanism/g,
+      /(?:the current host's native|the host-native) bounded-worker\s+mechanism/g,
       'the OpenCode `task` tool using the installed bounded review agents',
     );
   }

package/docs/AGENT-CONTEXT.md

@@ -25,18 +25,18 @@ not put it in a plugin until that allowlist classifies it.
 ## 2. Three-layer architecture
 
 ```text
-native command or skill -> MCP workflow-state operation -> .ultra/.runtime/state.db
+native command or skill -> 7-tool MCP safety kernel -> .ultra/.runtime/state.db
                                       | \
                                       |  -> .ultra/tasks/tasks.json (Git checkpoint)
                                       |  -> .ultra/.runtime/projections/ (local views)
                                       ^
-              selected CLI init / doctor / diagnostics / orchestration
+                         CLI diagnostics / orchestration
 ```
 
 | Layer | Artifact | Contract |
 |---|---|---|
 | Skill/command | `skills/*/SKILL.md`, `commands/*.md` | Model-facing workflow and host-native entry point |
-| MCP | `mcp-server/server.cjs` | Authoritative typed operations over `.ultra/.runtime/state.db` |
+| MCP | `mcp-server/server.cjs` | Persistence, semantic checkpoints, team sync, leases, archive transactions, and mechanical recovery |
 | CLI | `ultra-tools`, `ubp-orchestrator` | Selected initialization, backup-first recovery, automation, and diagnostics; not a change-state mirror |
 
 `.ultra/` is project-local cross-session workflow memory for normalized intent,
@@ -51,28 +51,29 @@ authority. Generated task views, runtime checkpoints, and collaboration scratch
 not independent authority. See
 [`ARTIFACT-AUTHORITY.md`](./ARTIFACT-AUTHORITY.md).
 
-## 3. Live MCP and declared contracts
+## 3. Public MCP kernel and compatibility layer
 
-`spec/mcp-tools.yaml` declares and the bundled server registers 60 tools across
-nine families:
+Every host discovers the same seven model-facing tools:
 
-| Family | Live tools |
+| Public tool | Contract |
 |---|---|
-| `baseline.*` | start, record, get, converge |
-| `task.*` | create, update, list, get, switch_tag, delete, init_project, expand, parse_prd, dependency_topo, append_event, subscribe_events, ledger_get, ledger_publish, ledger_import |
-| `session.*` | spawn, close, get, list, admission_check, heartbeat, subscribe_events |
-| `change.*` | create, update, delta, documentation_reconcile, get, list, context, breadcrumb, learning_propose, learning_resolve, converge, archive |
-| `decision.*` | thread_start, get, list, open, resolve, delegate, defer, supersede, complete, checkpoint |
-| `workflow.*` | start, get, list, step, revise, supersede, complete |
-| `artifact.*` | record, get |
-| `system.*` | doctor |
-| `plan.*` | export, get |
-
-Review, repository impact discovery, skill loading, and decision presentation remain
-host-native capabilities rather than fake MCP contracts. MCP stores only normalized
-decision authority, pending-question recovery state, lifecycle completion, and optional
-checkpoints; it never generates questions or retains prompts and transcripts. The
-generated Codex capability map documents host replacements.
+| `ultra.context` | side-effect-free current authority and evidence spine |
+| `ultra.record` | idempotent batch recording of typed draft facts and events |
+| `ultra.checkpoint` | one semantic stage commit; rejection keeps the draft mutable |
+| `ultra.sync` | Git team-checkpoint inspect/import/publish |
+| `ultra.session` | transactional execution lease |
+| `ultra.archive` | recoverable convergence and archive boundary |
+| `ultra.doctor` | mechanical diagnosis and backup-first repair |
+
+The public schemas stay below a 12KB discovery budget. The sixty 0.22 fine-grained
+task/session/baseline/change/decision/workflow/artifact/system/plan tools remain
+callable but undiscoverable for one compatibility release. They are implementation
+operations, not a second public API, and Skills must not call them directly.
+
+Semantic rejections return `accepted: false`, `mutable: true`, and diagnostics. Hard
+MCP errors are reserved for corruption, unsafe paths, real concurrency conflicts,
+permissions, or irreversible effects. Review, repository discovery, model reasoning,
+and owner interaction remain host-native.
 
 The complete write, transition, invalidation, and recovery contract lives in
 [`WORKFLOW-LIFECYCLE.md`](./WORKFLOW-LIFECYCLE.md).
@@ -91,23 +92,20 @@ review, and deliver route back to the same thread instead of deciding for the ow
 One partial unique index permits only one open item per thread. `decision.resolve`,
 `decision.delegate`, and `decision.defer` preserve the source of authority;
 `decision.supersede` preserves history when evidence or intent changes.
-After normalization, the host applies accepted intent through the owning MCP operation
-or digest-bound artifact, reads it back, and records typed `applied_refs` when another
-authority changed. Row-backed references require the exact field and canonical value;
-specification and artifact references require the exact file digest. Active proposals
-are never recalled as accepted intent. `decision.complete` then closes settled state without manufacturing
-an approval receipt. Prepare and confirm checkpointing remain optional and bind only a
-material accepted cluster to current artifact digests when interruption recovery needs
-that boundary. Status and breadcrumb return the current unresolved question, accepted
-intent relevant to the active authority, and allowed or mechanically required
-transitions, so recovery does not require replaying conversation history.
+After normalization, the host records accepted intent in one `ultra.record` batch,
+reads it back through `ultra.context`, and attempts an owning `ultra.checkpoint` only
+when durable authority is ready. Active proposals are never recalled as accepted
+intent. Status returns the current unresolved question, accepted intent, evidence,
+warnings, and hard blockers so recovery does not require replaying conversation
+history. The host model, not SQLite, recommends the next capability.
 
 ## 5. Context Spine contract
 
 Context Manifest v3 is an immutable DB-backed role handoff, not a static codebase summary.
-`change.context` compiles required references, digests, readiness, context budget,
-public seam, exact verification command, Change/task authority digests, and valid
-transitions for `plan`, `implement`, `check`, or `review`. Compilation never updates
+`ultra.checkpoint` compiles or reuses a content-addressed Context Manifest containing
+required references, digests, readiness, context budget, public seam, exact verification
+command, and Change/task authority digests for `plan`, `implement`, `check`, or
+`review`. Compilation never updates
 Change or provider authority; provider metadata changes through `change.update`.
 Snapshots are selected exactly by `change_id`, nullable `task_id`, `role`, and `gate`,
 so a review packet cannot satisfy implementation or planning evidence.
@@ -125,9 +123,9 @@ not block work or require raising a threshold. Prefer direct reads, bounded
 excerpts, or a smaller slice when they preserve correctness, and retain all
 necessary context when they do not.
 
-`change.breadcrumb` is the only compact router. Hooks may inject its change/task,
-role, gate, readiness, blockers, bounded normalized accepted intent,
-`allowed_transitions`, and `required_transition`. They must not inject raw prompts,
+The compact breadcrumb is a hook-only compatibility reader. Hooks may inject its
+change/task, role, gate, readiness, blockers, and bounded normalized accepted intent.
+They must not inject raw prompts,
 interaction transcripts, external-memory payloads, or graph payloads. Missing references,
 required digest drift, HEAD drift, or a missing execution seam blocks readiness. Context
 size and baseline drift are advisory for a change that is already active. New ordinary
@@ -176,7 +174,7 @@ the shared read-only `context_spine.py` breadcrumb helper:
   and types, never transcript paths or messages.
 
 `workflow_context.py`, `active_task_context.py`, `workflow_resume.py`, and the
-OpenCode plugin invoke the same bundled JavaScript `change.breadcrumb` reader
+OpenCode plugin invoke the same bundled JavaScript hook-only breadcrumb reader
 through the thin `context_spine.py` bridge. No hook reimplements the state query.
 `health_check.py` and
 `workflow_context.py` may inspect any initialized project;
@@ -185,7 +183,7 @@ projection but limits ordinary
 edit guidance to an active workflow. Compact/stop/subagent hooks remain
 active-workflow scoped. OpenCode natively injects baseline/change context and
 protects both managed task paths; full health inspection is available through
-`system.doctor` rather than a session-start health hook.
+`ultra.doctor` rather than a session-start health hook.
 Advisory baseline or context-budget warnings are presentation only and never
 reject an edit, stop, or tool call.
 Generic command blocking, post-edit governance, and unrelated user hooks are not

package/docs/ARCHITECTURE.md

@@ -55,14 +55,14 @@ memory under `.ultra/`.
 | Layer        | Role                                         | Form                                                  |
 |--------------|----------------------------------------------|-------------------------------------------------------|
 | **skill**    | knowledge carrier; tells the runtime *what to do* | `skills/<name>/SKILL.md` discovered natively by all supported runtimes |
-| **MCP**      | authoritative workflow-state, decision, artifact, and Context Spine API | stdio MCP server exposing 60 live tools across task/session/baseline/change/decision/workflow/artifact/system/plan families in [`spec/mcp-tools.yaml`](../spec/mcp-tools.yaml) |
+| **MCP**      | persistence and safety kernel for checkpoints, evidence, sync, leases, archive, and recovery | stdio MCP server exposing seven public `ultra.*` tools; sixty 0.22 fine-grained operations remain hidden for one compatibility release |
 | **CLI**      | explicit initialization, recovery, diagnostics, and orchestration | `ultra-tools` / `ubp-orchestrator`; only commands listed by `--help` are executable (see [`spec/cli-protocol.md`](../spec/cli-protocol.md)) |
 
-Why three: skills give us behavior portability across runtimes; MCP gives
-us a strongly-typed contract so we can refactor implementations without
-rewriting prompts; the CLI supplies bounded maintenance and recovery paths when
-the MCP cannot start. It is deliberately not a second change-state API:
-continuous change mutations remain MCP-only and fail closed (D12).
+Why three: skills preserve adaptable model behavior across runtimes; MCP gives durable
+checkpoint and safety primitives without supervising every reasoning step; the CLI
+supplies bounded maintenance and recovery when MCP cannot start. Semantic draft
+diagnostics are report-first. Corruption, unsafe paths, real concurrency, permissions,
+and irreversible effects remain fail-closed.
 
 The skill layer is **read-only by design** (D29) and is discovered directly by
 each host. Ultra exposes no `skill.*` MCP family: skills are documentation, not
@@ -222,15 +222,11 @@ current question per thread. The host ends that turn and waits.
 
 The next response becomes a normalized owner decision, explicit reversible delegation,
 or consequence-bearing deferral. Prompts and transcripts are never persisted. The host
-applies accepted intent through the owning MCP operation or digest-bound artifact,
-reads it back, and records typed `applied_refs` when another authority changed. Routine
-settled state then closes through `decision.complete`, which is lifecycle completion
-rather than another approval. The breadcrumb recalls normalized accepted intent after
-the thread closes. Only a coherent cluster that needs an artifact-bound recovery
-boundary moves through prepare/confirm checkpointing. Matching workflow steps fail
-closed while a blocking question, blocking deferral, prepared checkpoint, or stale
-checkpoint artifact remains. Supersession preserves prior history and reopens alignment
-instead of silently editing an old decision. The shared procedure lives in
+batches the normalized result and owning mutation through `ultra.record`, reads it back
+through `ultra.context`, and attempts a semantic checkpoint only when durable authority
+is ready. Failed semantic checks leave the draft editable. Accepted revisions remain
+immutable; a changed decision opens a replacement draft while preserving history. The
+shared procedure lives in
 `skills/ultra-think/references/decision-dialogue.md`; status, breadcrumb, and doctor expose
 only the current recovery surface.
 
@@ -262,9 +258,10 @@ consumer trace. Standard and major convergence requires both current authorities
 only after all writes and baseline reconciliation succeed does it rebind the complete
 Change root into the archive.
 
-Workflow revisions preserve prior accepted runs. A candidate becomes current only
-through `workflow.supersede`; the artifact graph then invalidates the prior run's true
-transitive consumers without staling unrelated tasks.
+Draft revisions remain editable and recoverable. A failed checkpoint can be repaired
+and retried in place or intentionally abandoned. Accepted runs are immutable; a later
+candidate supersedes them only after its own accepted checkpoint, and the artifact graph
+invalidates only true transitive consumers.
 
 ### Context Spine
 
@@ -277,25 +274,24 @@ implementation, checking, review, convergence, and recovery. Each snapshot recor
   execution contract;
 - advisory attention budgets (12 files / about 12k tokens / 40% by default);
 - a DB-derived execution contract (`slice_kind`, public seam, exact verification command);
-- mechanically valid `allowed_transitions` and a `required_transition` only when a
-  hard invariant leaves one recovery route;
+- warnings and hard mechanical blockers without a semantic next-action command;
 - a digest of the accepted Change authority so semantic updates invalidate the
   snapshot.
 
-Prompt input may identify the intended role/gate, add bounded reference candidates,
+Checkpoint input may identify the intended role/gate, add bounded reference candidates,
 and lower advisory budgets. It cannot supply or override the task seam, verification
 command, task context references, evidence digest, gate verdict, workflow summary, or
 machine transitions. A host may attach a clearly non-authoritative recommendation.
 Critical dev/test/review/deliver workflow steps record the matching
 snapshot as an output; test, review, and delivery reports carry its digest forward.
 
-`change.breadcrumb` derives the compact current position from state.db. Session,
+The hook-only breadcrumb derives the compact current position from state.db. Session,
 edit, resume, and OpenCode lifecycle hooks invoke one bundled read-only reader
 and inject it only while state.db proves an active, blocked, or ready workflow,
 never the intent body,
 provider content, or a conversation summary. A changed Git HEAD, task contract, or
-Change semantic authority marks the snapshot stale and permits recompilation through
-`change.context`.
+Change semantic authority marks the snapshot stale and permits content-addressed
+recompilation through the next `ultra.checkpoint`.
 
 PRD decomposition and complex-task subdivision use the active host model. The
 MCP accepts the resulting structured tasks, validates schema, topology,
@@ -305,9 +301,9 @@ model API credential.
 
 Plugin installation does not activate a semantic workflow and never edits the
 user's `CLAUDE.md`, `AGENTS.md`, or equivalent durable instructions. Public
-workflows require explicit user invocation. A completed workflow returns
-mechanically allowed transitions and a host-owned recommendation, then stops;
-it never launches the next public workflow. OpenCode realizes this boundary
+workflows require explicit user invocation. The host reads `ultra.context`, recommends
+the next capability from evidence and owner intent, then stops; SQLite never launches
+or semantically selects the next public workflow. OpenCode realizes this boundary
 with explicit commands backed by private plugin workflow assets, while Claude,
 Codex, and Kimi use their native implicit-invocation controls.
 
@@ -334,8 +330,8 @@ Mutating MCP calls enqueue durable `projection_jobs`. Success is exposed in MCP
 response metadata; failure becomes a retryable structured incident instead of a
 swallowed warning. These jobs regenerate only checkout-local views below
 `.ultra/.runtime/projections/`; they never rewrite the Git team checkpoint. Durable
-semantic operations publish the checkpoint directly at baseline, Change, plan, and
-task handoff boundaries. `system.doctor` is read-only by default. Explicit repair
+semantic checkpoints publish team state at baseline, Change, plan, and task handoff
+boundaries. `ultra.doctor` is read-only by default. Explicit repair
 performs backup-first schema upgrade, archive-journal recovery, session and local
 projection recovery, and regenerated local views. It cannot import or publish semantic
 team state, approve a baseline, or replace a corrupt SQLite file silently. `system
@@ -346,14 +342,14 @@ authority and the legacy task projection before creating a new brownfield adopti
 
 ### Git team checkpoint and checkout merge
 
-`task.ledger_publish` serializes the current portable baseline, all Change summaries,
-and durable task contracts to `.ultra/tasks/tasks.json`. Per-record digests and
+`ultra.sync { action: publish }` serializes the current portable baseline, all Change
+summaries, and durable task contracts to `.ultra/tasks/tasks.json`. Per-record digests and
 revisions make independent fast-forward possible; the document state digest, parent
 digest, and bounded ancestor list reject stale or unrelated histories. Local process
 ownership fields are deliberately absent.
 
 The MCP server imports the checkpoint once when it opens project authority. A
-long-running host explicitly calls `task.ledger_import` after receiving a newer Git
+long-running host explicitly calls `ultra.sync { action: import }` after receiving a newer Git
 version. Import is transactional: it validates every record first, preserves local-only
 fields, fast-forwards clean records, and rejects same-record concurrency or an active
 task collision. Re-reading an already imported checkpoint performs no write. A ready
@@ -451,7 +447,7 @@ repository commit.
 `ubp --all --global --doctor [--json]` is read-only: it recomputes hashes and
 validates those entry points, returning a non-zero degraded result for
 missing/corrupt provenance, content drift, or broken host wiring. A single host
-can be selected instead of `--all`. This is separate from `system.doctor`, which
+can be selected instead of `--all`. This is separate from `ultra.doctor`, which
 diagnoses project state, projection, incidents, sessions, and backup-first
 workflow recovery.